 |  |
| |
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.
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.confSince 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.
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:
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 to disable them.
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:
Here are the modules we commented out, and why:
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> ...
If you want to enable shared objects in this method, see the notes in the Configuration file. Essentially, you do the following:
Enable mod_so by uncommenting its line.
Change an existing AddModule <path>/<modulename>.o so it ends in .so rather than .o and, of course, making sure the path is correct.
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:
Any other value is ignored.
The Rule s are as follows:
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 apache-bugs@ apache.org. Currently, there is only one rule in this group:
Rule WANTSHREGEX=default
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/proxyThen 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.
|  | |
| 1.9. Installing Apache |  | 1.11. New Features in Apache v2 |
Copyright © 2003 O'Reilly & Associates. All rights reserved.