home | O'Reilly's CD bookshelfs | FreeBSD | Linux | Cisco | Cisco Exam  


Book HomeApache: The Definitive GuideSearch this book

1.8. Making Apache Under Unix

Download the most recent Apache source code from a suitable mirror site: a list can be found at http://www.apache.org/.[13] You can also load an older version from the enclosed CD-ROM. You will get a compressed file, with the extension .gz if it has been gzipped, or .Z if it has been compressed. Most Unix software available on the Web (including the Apache source code) is compressed using gzip, a GNU compression tool. If you don't have a copy, you will find one on our CD, or you can get it from the Web.

[13]It is best to download it, so you get the latest version with all its bug fixes and security patches.

When expanded, the Apache .tar file creates a tree of subdirectories. Each new release does the same, so you need to create a directory on your FreeBSD machine where all this can live sensibly. We put all our source directories in /usr/local/etc/apache. Go there, copy the <apachename>.tar.gz or <apachename>.tar.Z file, and uncompress the .Z version or gunzip (or gzip -d ) the .gz version:

uncompress <apachename>.tar.Z

or:

gzip -d <apachename>.tar.gz

Make sure that the resulting file is called <apachename>.tar, or tar may turn up its nose. If not, type:

mv <apachename> <apachename>.tar

Now unpack it: [14]

[14]If you are using GNU tar, it is possible to uncompress and unpack in one step: tar zxvf <apachename>.tar.gz.

% tar xvf <apachename>.tar

The file will make itself a subdirectory, such as apache_1.3.1. Keep the .tar file because you will need to start fresh to make the SSL version. Get into the .src directory. There are a number of files with names in capital letters, like README, that look as if you ought to read them. The KEYS file contains the PGP keys of various Apache Group members. It is more useful for checking future downloads of Apache than the current one (since a Bad Guy will obviously have replaced the KEYS file with his own). The distribution may have been signed by one or more Apache Group members.

1.8.1. Out of the Box

Until Apache 1.3, there was no real out-of-the-box batch-capable build and installation procedure for the complete Apache package. This is now provided by a top-level configure script and a corresponding top-level Makefile.tmpl file. The goal is to provide a GNU Autoconf-style front end that is capable of driving the old src/Configure stuff in batch and that additionally installs the package with a GNU- conforming directory layout.[15] Any options from the old configuration scheme are available, plus a lot of new options for flexibly customizing Apache. To run it, simply type:

[15]At least, some say it is conforming.

./configure
cd src
make

It has to be said that if we had read the apache/INSTALL file first, we would not have tried, because it gives an unjustified impression of the complexity involved. However, INSTALL does conceal at least one useful trick: because almost everything can be specified on the command line, you can create a shell script that configures your favorite flavor of Apache, and you never have to edit Configuration again. If you have to make a lot of different versions of Apache, this method has its advantages. However, the result, for some reason, produces an httpd that expects all the default directories to be different from those described in this book -- for instance, /usr/local/apache/etc/httpd.conf instead of /usr/local/apache/conf/httpd.conf. Until this is fixed, we would suggest running:

./configure  -- compat

or relying on the method in the next section.

1.8.2. Semimanual Method

Start off by reading README in the top directory. This tells you how to compile Apache. The first thing it wants you to do is to go to the src subdirectory and read INSTALL. To go further you must have an ANSI C-compliant compiler. A C++ compiler may not work.

If you have downloaded a beta test version, you first have to copy .../src/Configuration.tmpl to Configuration. We then have to edit Configuration to set things up properly. The whole file is in Appendix A of the installation kit. A script called Configure then uses Configuration and Makefile.tmpl to create your operational Makefile . (Don't attack Makefile directly; any editing you do will be lost as soon as you run Configure again.)

It is usually only necessary to edit the Configuration file to select the modules required (see the next section). Alternatively, you can specify them on the command line. The file will then automatically identify the version of Unix, the compiler to be used, the compiler flags, and so forth. It certainly all worked for us under FreeBSD without any trouble at all.

Configuration has five kinds of things in it:

  • Comment lines starting with "#"

  • Rules starting with the word Rule

  • Commands to be inserted into Makefile , starting with nothing

  • Module selection lines beginning with AddModule, which specify the modules you want compiled and enabled

  • Optional module selection lines beginning with %Module, which specify modules that you want compiled but not enabled until you issue the appropriate directive

For the moment, we will only be reading the comments and occasionally turning a comment into a command by removing the leading #, or vice versa. Most comments are in front of optional module inclusion lines.

1.8.3. Modules

These modules are self-contained sections of source code dealing with various functions of Apache that can be compiled in or left out. You can also write your own module if you want. Inclusion of modules is done by uncommenting (removing the leading #) lines in Configuration. The only drawback to including more modules is an increase in the size of your binary and an imperceptible degradation in performance.[16]

[16]Assuming the module has been carefully written, it does very little unless enabled in the httpd.conf files.

The default Configuration file includes the modules listed here, together with a lot of chat and comment that we have removed for clarity. Modules that are compiled into the Win32 core are marked with "W"; those that are supplied as a standard Win32 are marked DLL "WD." Our final list is as follows:

AddModule modules/standard/mod_env.o

Sets up environment variables to be passed to CGI scripts.

AddModule modules/standard/mod_log_config.o

Determines logging configuration.

AddModule modules/standard/mod_mime_magic.o

Determines the type of a file.

AddModule modules/standard/mod_mime.o

Maps file extensions to content types.

AddModule modules/standard/mod_negotiation.o

Allows content selection based on Accept headers.

AddModule modules/standard/mod_status.o (WD)

Gives access to server status information.

AddModule modules/standard/mod_info.o

Gives access to configuration information.

AddModule modules/standard/mod_include.o

Translates server-side include statements in CGI texts.

AddModule modules/standard/mod_autoindex.o

Indexes directories without an index file.

AddModule modules/standard/mod_dir.o

Handles requests on directories and directory index files.

AddModule modules/standard/mod_cgi.o

Executes CGI scripts.

AddModule modules/standard/mod_asis.o

Implements .asis file types.

AddModule modules/standard/mod_imap.o

Executes imagemaps.

AddModule modules/standard/mod_actions.o

Specifies CGI scripts to act as handlers for particular file types.

AddModule modules/standard/mod_speling.o

Corrects common spelling mistakes in requests.

AddModule modules/standard/mod_userdir.o

Selects resource directories by username and a common prefix.

AddModule modules/proxy/libproxy.o

Allows Apache to run as a proxy server; should be commented out if not needed.

AddModule modules/standard/mod_alias.o

Provides simple URL translation and redirection.

AddModule modules/standard/mod_rewrite.o (WD)

Rewrites requested URIs using specified rules.

AddModule modules/standard/mod_access.o

Provides access control.

AddModule modules/standard/mod_auth.o

Provides authorization control.

AddModule modules/standard/mod_auth_anon.o (WD)

Provides FTP-style anonymous username password authentication.

AddModule modules/standard/mod_auth_db.o

Manages a database of passwords; alternative to mod_auth_dbm.o.

AddModule modules/standard/mod_cern_meta.o (WD)

Implements metainformation files compatible with the CERN web server.

AddModule modules/standard/mod_digest.o (WD)

Implements HTTP digest authentication; more secure than the others.

AddModule modules/standard/mod_expires.o (WD)

Applies Expires headers to resources.

AddModule modules/standard/mod_headers.o (WD)

Sets arbitrary HTTP response headers.

AddModule modules/standard/mod_usertrack.o (WD)

Tracks users by means of cookies. It is not necessary to use cookies.

AddModule modules/standard/mod_unique_id.o

Generates an ID for each hit. May not work on all systems.

AddModule modules/standard/mod_so.o

Loads modules at runtime. Experimental.

AddModule modules/standard/mod_setenvif.o

Sets environment variables based on header fields in the request.

Here are the modules we commented out, and why:

# AddModule modules/standard/mod_log_agent.o

Not relevant here -- CERN holdover.

# AddModule modules/standard/mod_log_referer.o

Not relevant here -- CERN holdover.

# AddModule modules/standard/mod_auth_dbm.o

Can't have both this and mod_auth_db.o. Doesn't work with Win32.

# AddModule modules/example/mod_example.o

Only for testing APIs (see Chapter 14, "The Apache API").

These are the "standard" Apache modules, approved and supported by the Apache Group as a whole. There are a number of other modules available (see Chapter 12, "Extra Modules").

Although we've mentioned mod_auth_db.o and mod_auth_dbm.o above, they provide equivalent functionality and shouldn't be compiled together.

We have left out any modules described as experimental. Any disparity between the directives listed in this book and the list obtained by starting Apache with the -h flag is probably caused by the errant directive having moved out of experimental status since we went to press.

Later on, when we are writing Apache configuration scripts, we can make them adapt to the modules we include or exclude with the IfModule directive. This allows you to give out predefined Config files that always work (in the sense of Apache loading) whatever mix of modules is actually compiled. Thus, for instance, we can adapt to the absence of configurable logging with the following:

...
<IfModule mod_log_config.c>
LogFormat "customers: host %h, logname %l, user %u, time %t, request %r, status %s, bytes %b"
</IfModule>
...

The module directives are as follows (it will become clear later on how to use them, but they are printed here for convenience):

1.8.3.1. ClearModuleList

ClearModuleList
Server Config

Clears the list of active modules. Apache then has no modules until the AddModule directive is run. This should only concern the extreme seeker after performance.

1.8.3.2. AddModule

AddModule module module ...
Server Config

Makes the list of modules active. They must have been compiled in with the AddModule instruction in Configuration.

1.8.4. Configuration Settings and Rules

Most users of Apache will not have to bother with this section at all. However, you can specify extra compiler flags (for instance, optimization commands), libraries, or includes by giving values to :

EXTRA_CFLAGS=
EXTRA_LDFLAGS=
EXTRA_LIBS=
EXTRA_INCLUDES=

Configure will try to guess your operating system and compiler; therefore, unless things go wrong, you won't need to uncomment and give values to:

#CC=
#OPTIM=-02
#RANLIB=

The rules in the Configuration file allow you to adapt for a few exotic configuration problems. The syntax of a rule in Configuration is as follows:

Rule RULE =value

The possible values are as follows:

yes

Configure does what is required.

default

Configure makes a best guess.

Any other value is ignored.

The Rules are as follows:

STATUS

If yes, and Configure decides that you are using the status module, then full status information is enabled. If the status module is not included, yes has no effect. This is set to yes by default.

SOCKS4

SOCKS is a firewall traversal protocol that requires client-end processing. See ftp://ftp.nec.com/pub/security/socks.cstc. If set to yes, be sure to add the SOCKS library location to EXTRA_LIBS; otherwise, Configure assumes L/usr/local/lib-lsocks. This allows Apache to make outgoing SOCKS connections, which is not something it normally needs to do, unless it is configured as a proxy. Although the very latest version of SOCKS is SOCKS5, SOCKS4 clients work fine with it. This is set to no by default.

SOCKS5

If you want to use a SOCKS5 client library, you must use this rule rather than SOCKS4. This is set to no by default.

IRIXNIS

If Configure decides that you are running SGI IRIX, and you are using NIS, set this to yes. This is set to no by default.

IRIXN32

Make IRIX use the n32 libraries rather than the o32 ones. This is set to yes by default.

PARANOID

During Configure, modules can run shell commands. If PARANOID is set to yes, it will print out the code that the modules use. This is set to no by default.

There is a group of rules that Configure will try to set correctly, but that can be overridden. If you have to do this, please advise the Apache Group by filling out a problem report form at http://apache.org/bugdb.cgi or by sending an email to . Currently, there is only one rule in this group:

WANTHSREGEX:

Apache needs to be able to interpret regular expressions using POSIX methods. A good regex package is included with Apache, but you can use your OS version by setting WANTSHREGEX=no, or commenting out the rule. The default action depends on your OS:

Rule WANTSHREGEX=default

1.8.5. Making Apache

The INSTALL file in the src subdirectory says that all we have to do now is run the configuration script by typing:

% ./Configure

You should see something like this -- bearing in mind that we're using FreeBSD:

Using config file: Configuration
Creating Makefile
 + configured for FreeBSD platform
 + setting C compiler to gcc
 + Adding selected modules
    o status_module uses ConfigStart/End:
    o dbm_auth_module uses ConfigStart/End:
    o db_auth_module uses ConfigStart/End:
    o so_module uses ConfigStart/End:
 + doing sanity check on compiler and options
Creating Makefile in support
Creating Makefile in main
Creating Makefile in ap
Creating Makefile in regex
Creating Makefile in os/unix
Creating Makefile in modules/standard
Creating Makefile in modules/proxy

Then type:

% make

When you run make, the compiler is set in motion, and streams of reassuring messages appear on the screen. However, things may go wrong that you have to fix, although this situation can appear more alarming than it really is. For instance, in an earlier attempt to install Apache on an SCO machine, we received the following compile error:

Cannot open include file 'sys/socket.h'

Clearly (since sockets are very TCP/IPish things), this had to do with TCP/IP, which we had not installed: we did so. Not that this is any big deal, but it illustrates the sort of minor problem that arises. Not everything turns up where it ought to. If you find something that really is not working properly, it is sensible to make a bug report via the Bug Report link in the Apache Server Project main menu. But do read the notes there. Make sure that it is a real bug, not a configuration problem, and look through the known bug list first so as not to waste everyone's time.

The result of make was the executable httpd. If you run it with:

% ./httpd

it complains that it:

could not open document config file /usr/local/etc/httpd/conf/httpd.conf

This is not surprising because, at the moment, being where we are, the Config file doesn't exist. Before we are finished, we will become very familiar with this file. It is perhaps unfortunate that it has a name so similar to the Configuration file we have been dealing with here, because it is quite different. We hope that the difference will become apparent later on.

1.8.6. Unix Binary Releases

The fairly painless business of compiling Apache, which is described above, can now be circumvented by downloading a precompiled binary for the Unix of your choice from http://apache.org/dist/binaries. When we went to press, the following versions of Unix were supported, but check before you decide (see ftp://ftp.apache.org/httpd/binaries.html):

alpha-dec-osf3.0

hppa1.1-hp-hpux

i386-slackware-linux(a.out)

i386-sun-solaris2.5

i386-unixware-svr4

i386-unknown-bsdi2.0

i386-unknown-freebsd2.1

i386-unknown-linux(ELF)

i386-unknown-netBSD

i386-unknown-sco3

i386-unknown-sco5

m68k-apple-aux3.1.1

m88k-dg-dgux5.4R2.01

m88k-next-next

mips-sgi-irix5.3

mips-sni-svr4

rs6000-ibm-aix3.2.5

sparc-sun-solaris2.4

sparc-sun-solaris2.5

sparc-sun-sunos4.1.4

sparc-sun-sunos4.1.3_U1

mips-dec-ultirx4.4

Although this route is easier, you do forfeit the opportunity to configure the modules of your Apache, and you lose the chance to carry out quite a complex Unix operation, which is in itself interesting and confidence inspiring if you are not very familiar with this operating system.



Library Navigation Links

Copyright © 2001 O'Reilly & Associates. All rights reserved.