Apache The Definitive Guide, 3rd EditionApache: The Definitive GuideSearch this book

1.10. Building Apache 1.3.X Under Unix

There are two methods for building Apache: the "Semimanual Method" and "Out of the Box". They each involve the user in about the same amount of keyboard work: if you are happy with the defaults, you need do very little; if you want to do a custom build, you have to do more typing to specify what you want.

Both methods rely on a shell script that, when run, creates a Makefile. When you run make, this, in turn, builds the Apache executable with the side orders you asked for. Then you copy the executable to its home (Semimanual Method) or run make install (Out of the Box) and the various necessary files are moved to the appropriate places around the machine.

Between the two methods, there is not a tremendous amount to choose. We prefer the Semimanual Method because it is older[12] and more reliable. It is also nearer to the reality of what is happening and generates its own record of what you did last time so you can do it again without having to perform feats of memory. Out of the Box is easier if you want a default build. If you want a custom build and you want to be able to repeat it later, you would do the build from a script that can get quite large. On the other hand, you can create several different scripts to trigger different builds if you need to.

[12]New is a dirty four letter word in computing.

1.10.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 method is provided by a top-level configure script and a corresponding top-level Makefile.tmpl file. The goal is to provide a GNU Autoconf-style frontend that is capable of driving the old src/Configure stuff in batch.

Once you have extracted the sources (see earlier), the build process can be done in a minimum of three command lines — which is how most Unix software is built nowadays. Change yourself to root before you run ./configure; otherwise, if you use the default build configuration (which we suggest you do not), the server will be looking at port 8080 and will, confusingly, refuse requests to the default port, 80.

The result is, as you will be told during the process, probably not what you really want:

./configure
make
make install

This will build Apache and install it, but we suggest you read on before deciding to do it this way. If you do this — and then decide to do something different, do:

make clean 

afterwards, to tidy up. Don't forget to delete the files created with:

rm -R /usr/local/apache

Readers who have done some programming will recognize that configure is a shell script that creates a Makefile. The command make uses it to check a lot of stuff, sets compiler variables, and compiles Apache. The command make install puts the numerous components in their correct places around your machine, using, in this case, the default Apache layout, which we do not particularly like. So, we recommend a slightly more elaborate procedure, which uses the GNU layout.

The GNU layout is probably the best for users who don't have any preconcieved ideas. As Apache involves more and more third-party materials and this scheme tends to be used by more and more players, it also tends to simplify the business of bringing new packages into your installation.

A useful installation, bearing in mind what we said about modules earlier and assuming you want to use the mod_proxy DSO, is produced by:

make clean
./configure --with-layout=GNU \
    --enable-module=proxy --enable-shared=proxy
make
make install

( the \ character lets the arguments carry over to a new line). You can repeat the --enable- commands for as many shared objects as you like.

If you want to compile in hooks for all the DSOs, use:

./configure --with-layout=GNU --enable-shared=max 
make
make install

If you then repeat the ./configure... line with --show-layout > layout added on the end, you get a map of where everything is in the file layout. However, there is an nifty little gotcha here — if you use this line in the previous sequence, the --show-layout command turns off acutal configuration. You don't notice because the output is going to the file, and when you do make and make install, you are using whichever previous ./configure actually rewrote the Makefile — or if you haven't already done a ./configure, you are building the default, old Apache-style configuration. This can be a bit puzzling. So, be sure to run this command only after completeing the installation, as it will reset the configuration file.

If everything has gone well, you should look in /usr/local/sbin to find the new executables. Use the command ls -l to see the timestamps to make sure they came from the build you have just done (it is surprisingly easy to do several different builds in a row and get the files mixed up):

total 1054
-rwxr-xr-x  1 root  wheel   22972 Dec 31 14:04 ab
-rwxr-xr-x  1 root  wheel    7061 Dec 31 14:04 apachectl
-rwxr-xr-x  1 root  wheel   20422 Dec 31 14:04 apxs
-rwxr-xr-x  1 root  wheel  409371 Dec 31 14:04 httpd
-rwxr-xr-x  1 root  wheel    7000 Dec 31 14:04 logresolve
-rw-r--r--  1 root  wheel       0 Dec 31 14:17 peter
-rwxr-xr-x  1 root  wheel    4360 Dec 31 14:04 rotatelogs

Here is the file layout (remember that this output means that no configuration was done):

Configuring for Apache, Version 1.3.26
 + using installation path layout: GNU (config.layout)

Installation paths:
               prefix: /usr/local
          exec_prefix: /usr/local
               bindir: /usr/local/bin
              sbindir: /usr/local/sbin
           libexecdir: /usr/local/libexec

               mandir: /usr/local/man
           sysconfdir: /usr/local/etc/httpd
              datadir: /usr/local/share/httpd
             iconsdir: /usr/local/share/httpd/icons
            htdocsdir: /usr/local/share/httpd/htdocs
               cgidir: /usr/local/share/httpd/cgi-bin
           includedir: /usr/local/include/httpd
        localstatedir: /usr/local/var/httpd
           runtimedir: /usr/local/var/httpd/run
           logfiledir: /usr/local/var/httpd/log
        proxycachedir: /usr/local/var/httpd/proxy

Compilation paths:
           HTTPD_ROOT: /usr/local
      SHARED_CORE_DIR: /usr/local/libexec
       DEFAULT_PIDLOG: var/httpd/run/httpd.pid
   DEFAULT_SCOREBOARD: var/httpd/run/httpd.scoreboard
     DEFAULT_LOCKFILE: var/httpd/run/httpd.lock
      DEFAULT_XFERLOG: var/httpd/log/access_log
     DEFAULT_ERRORLOG: var/httpd/log/error_log
    TYPES_CONFIG_FILE: etc/httpd/mime.types
   SERVER_CONFIG_FILE: etc/httpd/httpd.conf
   ACCESS_CONFIG_FILE: etc/httpd/access.conf
 RESOURCE_CONFIG_FILE: etc/httpd/srm.conf

Since httpd should now be on your path, you can use it to find out what happened by running it, followed by one of a number of flags. Enter httpd -h. You see the following:

httpd: illegal option -- ?
Usage: httpd [-D name] [-d directory] [-f file]
             [-C "directive"] [-c "directive"]
             [-v] [-V] [-h] [-l] [-L] [-S] [-t] [-T]
Options:
  -D name          : define a name for use in <IfDefine name> directives
  -d directory     : specify an alternate initial ServerRoot
  -f file          : specify an alternate ServerConfigFile
  -C "directive"   : process directive before reading config files
  -c "directive"   : process directive after  reading config files
  -v               : show version number
  -V               : show compile settings
  -h               : list available command line options (this page)
  -l               : list compiled-in modules
  -L               : list available configuration directives
  -S               : show parsed settings (currently only vhost settings)
  -t               : run syntax check for config files (with docroot check)
  -T               : run syntax check for config files (without docroot check)

A useful flag is httpd -l, which gives a list of compiled-in modules:

Compiled-in modules:
  http_core.c
  mod_env.c
  mod_log_config.c
  mod_mime.c
  mod_negotiation.c
  mod_status.c
  mod_include.c
  mod_autoindex.c
  mod_dir.c
  mod_cgi.c
  mod_asis.c
  mod_imap.c
  mod_actions.c
  mod_userdir.c
  mod_alias.c
  mod_access.c
  mod_auth.c
  mod_so.c
  mod_setenvif.c

This list is the result of a build with only one DSO: mod_alias. All the other modules are compiled in, among which we find mod_so to handle the shared object. The compiled shared objects appear in /usr/local/libexec. as .so files.

You will notice that the file /usr/local/etc/httpd/httpd.conf.default has an amazing amount of information it it — an attempt, in fact, to explain the whole of Apache. Since the rest of this book is also an attempt to present the same information in an expanded and digestible form, we do not suggest that you try to read the file with any great attention. However, it has in it a useful list of the directives you will later need to invoke DSOs — if you want to use them.

In the /usr/src/apache/apache_XX directory you ought to read INSTALL and README.configure for background.

1.10.2. Semimanual Build Method

Go to the top directory of the unpacked download — we used /usr/src/apache/apache1_3.26. Start off by reading README. 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. Most Unices come with a suitable compiler; if not, GNU gcc works fine.

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 permanent 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:

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 to disable them.

1.10.3. Choosing Modules

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.[13]

[13]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 DLL are marked "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 20).

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 http://modules.apache.org).

Although we mentioned mod_auth_db.o and mod_auth_dbm.o earlier, 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), regardless of what 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>
...

1.10.4. Shared Objects

If you want to enable shared objects in this method, see the notes in the Configuration file. Essentially, you do the following:

  1. Enable mod_so by uncommenting its line.

  2. Change an existing AddModule <path>/<modulename>.o so it ends in .so rather than .o and, of course, making sure the path is correct.

1.10.5. Configuration Settings and Rules

Most Apache users won't 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 the following :

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 these:

#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 Rule s 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 http://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 interpret regular expressions using POSIX methods. A good regex package is included with Apache, but you can use your OS version by setting WANTHSREGEX=no or commenting out the rule. The default action depends on your OS:

Rule WANTSHREGEX=default

1.10.6. Making Apache

The INSTALL file in the src subdirectory says that all we have to do now is run the configuration script. Change yourself to root before you run ./configure; otherwise the server will be configured on port 8080 and will, confusingly, refuse requests to the default port, 80.

Then type:

% ./Configure

You should see something like this — bearing in mind that we're using FreeBSD and you may not be:

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 using the makefile built by Configure, 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/IP-intensive), this had to do with TCP/IP, which we had not installed: we did so. Not that this is a 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, httpd.conf, which we call 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. The last step is to copy httpd to a suitable storage directory that is on your path. We use /usr/local/bin or /usr/local/sbin.



Library Navigation Links

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