Getting Started with Apache

Learn the basic steps necessary to download, install, and configure a basic Apache server. This article is from chapter two of Pro Apache by Peter Wainwright. (Apress, 2004, ISBN: 1590593006).

APACHE IS BOTH powerful and highly configurable. As such, the range of configuration possibilities available can be daunting, and much of this book is dedicated to exploring them. Fortunately, installing, configuring, and testing a simple Apache setup is relatively straightforward.

In this chapter, I’ll outline the basic steps necessary to download, install, and configure a basic Apache server. Depending on your requirements, you may choose to install a precompiled Apache distribution, download the source code and build it yourself, or opt for a prebuilt package that both installs and sets up the initial configuration for you. Binary distributions are available for many platforms and are all installed in essentially the same way. Prebuilt packages vary from platform to platform, so you’ll look at the two most common choices—Linux RPM packages and Windows Installer files. You’ll also learn about upgrading the server and setting up Apache to run automatically, if it doesn’t already, on both Windows and Unix.

After installing the server, you’ll see the most essential of Apache’s configuration directives, the ones that Apache absolutely needs to set to start. Once this is done, you should have a running server. It might not do much at this point, but it’s enough to prove that the installation worked and that Apache is ready for the next stage of configuration. After setting up the basic configuration, you’ll examine the various ways in which Apache may be started, stopped, restarted, tested, and queried. You’ll then look at testing the server both with a browser and using the telnet command to see what the server is actually doing with the requests sent to it.

The chapter concludes with a quick overview of some of the most popular graphical configuration tools available for Apache. Perhaps surprisingly, Apache has no standard configuration tool, but you can choose from several independent GUIs.

NOTE This chapter contains a lot of information for the administrator who wants to learn the details of Apache installation, but for the most part, it’s not necessary to get down to this level. In the simplest and most common case, a basic Apache installation can take a matter of seconds. 

This chapter is from Pro Apache by Peter Wainwright. (Apress, 2004, ISBN: 1590593006). Check it out at your favorite bookstore today. Buy this book now.

{mospagebreak title=Installing Apache}

This section investigates the various options available for installing Apache. In many cases, you may be lucky enough to have it installed already, in which case you can skip straight to basic configuration. However, you’ll want to upgrade the installation from time to time to take advantage of new features or close the door on an old bug, so knowing how to install Apache will be a useful skill sooner or later.

Getting Apache

The primary source for downloading Apache is http://httpd.apache.org/, the ASF project page for the HTTP server. You can also reach this via the foundation’s home page at http://www.apache.org/. The Apache home page is understandably busy and provides links to several international mirrors where you have the option to download the software from a closer location.

Apache releases appear in two basic forms—binary and source—for several operating systems. The binary releases are prebuilt, ready to install. They also include a copy of the source code, so you can customize, rebuild, and then reinstall it. From Apache 2 onward, binary distributions also ship with all modules that are capable of being configured as external modules.

The source release contains only the source code, which you must build to create an installable Apache. Building from source can be very rewarding, both for the benefits conveyed by building Apache on your own hardware and for the satisfaction of knowing that you really do have complete control over the server. The source code comes with a configuration script (configure) that takes away most of the hard work of setting up Apache and also examines the system to determine the best way to build Apache for maximum performance. Chapter 3 covers this in detail.

In addition to releases from the Apache Web site, many operating systems provide prebuilt packages from their own Web sites. These are designed to set up Apache on the given platform in a more official file system location (on Unix systems, /etc/httpd or /opt/httpd rather than /usr/local/apache, for example). They usually also install startup and shutdown scripts, so Apache will automatically start and stop with the operating system. These packages also make upgrading the server easy and often integrate with other vendor-specific features such as online Help.

Most Linux- and BSD-based operating systems offer Apache as an easily installable package. Apache is also shipped, by default, with Apple’s MacOS X operating system, and aside from a customized layout, Apache on MacOS X/Darwin is the same as Apache on any other Unix operating system.

Though Windows doesn’t ship with Apache, installable packages for Windows are available directly from the Apache Web site and its mirrors. You can download all Apache installations from http://www.apache.org/dist/httpd/binaries/win32/. The installation file for the Windows version of Apache carries the extension .msi; this is a Microsoft installer file. The Apache source is available in a .zip file and may be downloaded and compiled using the Microsoft Visual C++ compiler.

A seemingly obvious place to find Apache is on magazine cover CDs and bundled with books. But these origins should be treated with some suspicion because there’s almost always a more recent release on the Apache Web site. For all practical purposes, it’s as easy to download a fresh and up-to-date copy as it is to extract one from a CD. Therefore, there’s rarely a good reason to install Apache from such a source; the number of people who need to install Apache but don’t have a network connection to download it is rather small.

At any given time, Apache is available as a stable release and as a development beta release. The status of both versions is available from the news page, along with any major updates or fixes that were dealt with in the most recent release.

You also have the choice of downloading either Apache 1.3 or Apache 2. Although Apache 2 has been available for a while now, Apache 1.3 can still be a good choice in some situations, particularly for administrators who are already running an existing Apache 1.3 server and don’t want to migrate to Apache 2 until it has been deployed more widely. Whichever version you choose, you should heed the warnings and download a beta release only if you’re willing to endure the possibility of unexpected bugs and unreliable behavior and need access to a feature not yet available in the stable release.

Up until Apache 2, source code for experimental features has been bundled together with source code for stable ones in each new release. Binary distributions are ordinarily built only from the stable features, with experimental ones added if you ask for them. From Apache 2.2 onward this will change: The 2.2 release will contain only the current stable release, with no experimental features even as options, but 2.3 will contain all developmental code. Ultimately, 2.4 will be released as the next stable release, with 2.5 becoming the next developmental release, in a similar manner to the Linux kernel, Perl, and other projects.

You can find a rundown of new Apache 2 features and upgrade tips for Apache 1.3 administrators at http://httpd.apache.org/docs-2.0/upgrading.html. This page is also distributed as part of the Apache package, which is under /manual/upgrading.html in a fresh local Apache installation. 

This chapter is from Pro Apache by Peter Wainwright. (Apress, 2004, ISBN: 1590593006). Check it out at your favorite bookstore today. Buy this book now.

{mospagebreak title=Installing Apache from Binary Distribution}

Binary distributions are archived copies of the compiled Apache source and contain a complete Apache server, all supporting scripts and configuration files, a complete copy of the source code, and an installation script to install the server into the desired location. They don’t, however, contain scripts to automatically start and stop Apache with the operating system.

Distributions are available for several variants of Unix, OS/2, Netware, BeOS, and MacOS X from the Apache home page at http://www.apache.org/dist/httpd/binaries/. Refer to the “Installing Apache from Prebuilt Packages” section for more information.

NOTE Linux administrators will find packages under the linux subdirectory, and you can find Solaris packages similarly under solaris.
MacOS X administrators
will also find distributions for MacOS X/Darwin—the darwin and macosx subdirectories have the same contents, so either will do—as well as MacOS X Server/Rhapsody, similarly in macosxserver or rhapsody .Windows packages for Windows 9x ,ME, NT, 2000, and XP are also available from this location. Both self-installing and Windows installer packages are available, but these aren’t basic binary distributions as described here.

On platforms for which binary distributions are available, you can download and install Apache with only a few steps.

Using Unix as an example, first download either the compress archive (suffix .Z) or the gzip archive (suffix .gz). For other platforms, such as OS/2, you may also find a ZIP archive available. Because gzipped archives are compressed more efficiently than compressed ones, you should get the gzip archive if you have gzip available to decompress it. If you don’t, this might be a good time to install it.

Once the archive is downloaded, unpack it:

$ gunzip apache_1.3.28-i686-whatever-linux22.tar.gz
$ tar xvf apache_1.3.28-i686-whatever-linux22.tar

This archive is for a Linux server, kernel version 2.2 or higher, running on a machine with at least an Intel Pentium II processor. Archives for other platforms are named appropriately in the relevant platform subdirectory. When a platform is available for more than one processor architecture, as Linux is, be careful to download the correct binary distribution—a Sparc or Alpha distribution is of little use to an Intel server, for example.

You can also extract the archive in one step, leaving the archive in a compressed state to conserve disk space:

$ gunzip -c apache_1.3.28-i686-whatever-linux22.tar.gz | tar xvf -

On systems with the GNU version of tar, which includes all Linux and BSD platforms, you can also extract the archive in one step (note the extra z in zxvf to signify that the archive is compressed):

$ tar zxvf apache_1.3.28-i686-whatever-linux22.tar.gz

On systems that don’t have gzip installed, download the .Z archive and use the standard Unix uncompress utility instead:

$ uncompress apache_1.3.28-i686-whatever-linux22.tar.Z

This is actually the most complex part of the process. Once the archive is unpacked, go into the newly created Apache directory:

$ cd apache_1.3.28

Then run the included installation script:

$ ./install-bindist.sh

If you want to install Apache somewhere other than /usr/local/apache, give the installation script the path you want to use, for example:

$ ./install-bindist.sh /home/httpd/

This should produce a working Apache installation in the desired location. If you’re installing on a Unix server and want to install into a standard system location, you’ll need to have root privileges to perform this step. After the installation is complete, you may remove both the archive and the unpacked archive directory. You’re now ready to configure Apache.

An interesting point of binary distributions is that you can create them yourself, using the source distribution. This allows you to create a fully customized server that matches your needs and then distribute it yourself. The created binary distribution is the same as the standard distribution in all respects except for the customizations you make.

NOTE Creating and installing your own binary distribution is covered in Chapter 3.

Installing Apache from Source

As mentioned, you can also download Apache source distributions from the official Apache site. They’re located in http://www.apache.org
/dist/httpd/
and come in either ZIP format (.zip) or gzip format (.gz).

Again, mirrors exist, and you should use the mirror closest to you—note that choosing the Download from a Mirror link from the main site should select a suitable mirror automatically. Once downloaded, the source can be compiled using Microsoft Visual C++ compiler on Windows and gcc on most other platforms. This is the major subject of Chapter 3, so I’ll not dwell on it further here. 

This chapter is from Pro Apache by Peter Wainwright. (Apress, 2004, ISBN: 1590593006). Check it out at your favorite bookstore today. Buy this book now.

{mospagebreak title=Installing Apache from Prebuilt Packages}

If you’re using an operating system for which a prebuilt Apache package is available, you can often save time by installing one package instead of installing individual files from a binary distribution. However, packages may lag behind the current Apache release—whether or not this is important depends on whether you need specific features or bug fixes only available only in the latest release.

Administrators interested in building Apache from source but who also want to retain the benefits of upgrading Apache as a package may be interested in the ability of more recent Apache 2 distributions to build an RPM package directly out of the source distribution, providing the best of both worlds.

Prebuilt Unix Packages

Most distributions of Linux and FreeBSD come with Apache as standard, so for these operating systems all of this has already been done for you. If not, you can locate an RPM package (Red Hat, Caldera, and SuSE all use this format) or deb (for Debian) from http://rpmfind.net/ or http://www.debian.org/, respectively.

The following example uses an Apache 1.3 RPM, but Apache 2.0 is just the same. First, if the RPM is signed, verify it with:

$rpm -verify apache-1.3.28-1.i386.rpm

This will carry out any possible MD5 or PGP checks, depending on the source of the package. Assuming it checks out, the installation command is typically of this form:

$ rpm -ivh apache-1.3.28-1.i386.rpm

Here the -i option is the only essential one—it means “install,” -v produces more verbose output, and -h generates a progress bar.

Note that you need to have root privileges to carry out this installation. To install into a different location, you can usually use the –relocate option, which takes the installation root in the package and remaps it to a new location. This may or may not work depending on the package. For example, for a package that normally installs Apache under /usr/local/apache, you would use something like this:

$ rpm -ivh apache-1.3.28-1.i386.rpm –relocate
/usr/local/apache=/home/highprogrammer/my_apache

If you expect to be building any third-party modules, you should also install the apache-devel package (or httpd-devel for Apache 2). This contains the include files and the apxs utility, among other files:

$ rpm -ivh apache-devel-1.3.28-1.i386.rpm

You can install both files at the same time simply by listing them both on the same command line.

To find out where Apache has been installed after the event, list the files using this:

$ rpm -qlp apache-1.3.28-1.i386.rpm

Here -q puts the rpm utility into query mode, -l tells it to list the files for a package, and -p tells it to use the file specified on the command line rather than look for a package with the same name already installed on the server.

Depending on how Apache has been packaged, you may also have supplementary packages to install. For example, the RPM build specification file included in recent Apache 2 distributions divides Apache into httpd, httpd-manual, and httpd-ssl packages.

If you’re upgrading an existing installation, use -U instead of -i. Existing configuration files will be preserved, usually by being renamed with an .rpmsave extension:

$ rpm -Uvh apache-1.3.28-1.i386.rpm

If you want to use tools such as apxs to build third-party modules, you need to install the apache-devel package. In some distributions—for example, Red Hat—the Apache manual is also packaged separately as apache-manual because if you have ready access to the Apache Web site, you can omit a locally installed manual. To install these, use this:

$ rpm -ivh apache-devel-1.3.28-1.i386.rpm
$ rpm -ivh apache-manual-1.3.28-1.i386.rpm

This is all you need to do to install Apache. Scripts will automatically be installed so Apache starts and stops with the operating system. In most cases, a new user and group will be created for Apache to run under as part of the installation process. In some cases, the server will even be started automatically, and you can point a browser at http://localhost/ to see your new Apache server running. To see where Apache was installed, including all the additional support files and startup scripts, use this:

$ rpm -ql apache

This tells rpm to list the files for the installed copy of Apache, so don’t use the complete package filename. For more information on RPM, including how to perform package integrity checks and force relocation, see the RPM manual page.

Prebuilt Windows Packages

You can find Windows self-installing packages at http://www.apache.org/dist/httpd/binaries/win32/. Microsoft Installer (MSI) packages are also available. These need to be installed using Windows installer, which is bundled with Windows ME, 2000, and XP. Older Windows versions may download it for free from http://www.microsoft.com/downloads/. The MSI package is recommended because it’s both smaller and, because it uses the operating system’s own installation tool, more tightly integrated with Windows.

Assuming you choose the MSI package, you should first verify that it’s a genuine and untampered-with copy of the Apache server distribution. This is an optional step, but an important safeguard if the server is at all public. You can do this by verifying the MD5 checksum or PGP signature of the file by downloading them from httpd.apache.org and checking them against the file. As this is the same process used to verify source distributions, I cover both MD5 and PGP in “Verifying the Apache Distribution Archive” in Chapter 3. (Official Linux distribution RPM packages are similarly signed by their distributors, and you can use the –verify option of rpm to check their integrity.)

Once the MSI package is verified, you can install it simply by double-clicking the file icon. The installer provides a GUI during the installation process that’s the familiar Windows installation wizard. Before going too much further, you may want to glance through the rest of this chapter, especially paying close attention to the “Decisions” section.

Click the Next button to proceed with the installation because this screen simply confirms that it’s the Apache server being installed. On the next screen, a software license agreement is presented. Once you accept the license terms and click the Next button, some more reading material will be presented that describes what the Apache server is. Next, you’ll see a screen that requests a few installation parameters. The items to be filled in include the domain name, the server name (which is the hostname plus the domain name), the administrator’s e-mail address (which can be in a completely different domain if necessary), and finally a choice of binding the server to port 80 or port 8080.

Port 80, as you may remember from previous discussions, is a privileged port and the default for HTTP requests, meaning in Unix it’s below port 1024 and only root can bind a listener to it. Apache treats this the same way under Windows, but the distinction is largely symbolic because Windows doesn’t impose such restrictions. Port 8080 is used, again like Unix, to be bound in user space and therefore doesn’t need to have the service started by the administrator or at system start, so an unprivileged user can start the server. This choice is also good if Apache must coexist with another Web server such as Internet Information Service (IIS). Be warned, however, that choosing a port other than 80 will result in Apache having to be started manually.

After clicking the Next button, you’re prompted to select the setup type, either Typical or Custom.

Usually you would select a Typical setup, which performs a default installation without further prompting. It installs everything except the source distribution and uses defaults for all options.

More advanced users may select the Custom option to customize the installation. This allows you to select the features that the Apache installation will have and, more importantly, the folder in which Apache is installed. By default, Apache 2 is installed in the Program FilesApache GroupApache2 folder. If you want to install Apache in a different folder, you can either select the Custom option or make the change in the wizard screen immediately prior to commencing the installation. The Custom option also allows you to specify the Start menu item name for Apache; the default name is Apache Web Server.

By specifying a different installation root and menu name, any number of Apache installations can be placed on the same server. Having said this, it’s not necessary to install Apache multiple times in order to get multiple running instances of Apache. You can also use the -f and -D options to run several Apache processes in different configurations using the same installation, as you’ll see shortly. The installer finishes by copying all the necessary files and informs you when installation is complete. Apache is now ready to run.

During installation, the standard configuration files shipped with Apache are copied to the conf folder within the chosen installation directory. If you’re overwriting an earlier installation, there may be old configuration files in this folder. In this case, the new configuration files will not overwrite the active configuration but instead be copied with the extension .default appended to the filename; therefore, httpd.conf will be copied as httpd.conf.default.

After installation, you can integrate the new configuration with your existing one. The Apache installer will also avoid installing its default Web site if it detects that an existing Web site has been placed in the default document root.

NOTE This completes the installation. You’ll want to carry out some configuration at some point, but the server should now be ready to run, at least for testing purposes.

This chapter is from Pro Apache by Peter Wainwright. (Apress, 2004, ISBN: 1590593006). Check it out at your favorite bookstore today. Buy this book now.

{mospagebreak title=Installing Apache by Hand}

It’s a good idea to install a binary Apache distribution using the install-bindist.sh script and to install a compiled one using make install, as detailed in Chapter 3. However, you can manually install Apache if necessary. You might want to do this when upgrading Apache to a new version where only one or two files—maybe only the Apache binary itself—have changed.

A full manual installation involves creating the directories where you can place Apache’s executables, configuration files, and logs and then ensuring that Apache knows how to find them. If you’re on a Unix system, you should also check and adjust file and directory permissions for server security. Because this inevitably introduces concepts I would otherwise leave to the next chapter, this section is only for people who like to do things the hard way or have already rebuilt Apache from source and want to perform a partial installation by hand rather than use the supplied scripts.

Locating Apache’s Files

The first and most important thing to decide with a manually installed Apache is where to put the server root that defines Apache’s base installation directory, the document root where the main Web site files are located, and Apache’s error log. Table 2-1 shows the important directives along with their default location and a possible alternative.

Directive Default Value Alternative Example Location
ServerRoot /usr/local/apache /etc/httpd
ErrorLog <ServerRoot>/logs
/error_log

/etc/httpd/logs
/errors

DocumentRoot <ServerRoot>/htdocs /home/httpd
/public_html

Table 2-1. Important Apache Directives

As this table shows, in the default Apache configuration the server root is also used as the basis for both the document root and the error log. In practice, the document root is often moved outside the server root as shown in the alternative example because the document root and server root have little to do with each other, and keeping them apart makes it easier to replace either the site or the server installation without disturbing the other. Other than actual Web content, and setting aside for the moment the issue of multiple virtual hosts, all of Apache’s other files are usually located under the server root. This includes the various executables, including the Apache server binary itself, as well as supporting scripts, log files, file icons, and example Common Gateway Interface (CGI) scripts. The point of the ServerRoot directive is to consolidate all these files into one place, so you don’t have to define all of them separately. If you want to move all or most of Apache’s files to a different location, redefining ServerRoot is a lot simpler than redefining the location of each file individually.

Apache provides two optional directives to move an individual file location:

  • PidFile, which contains Apache’s process ID on Unix systems and defaults to the runtime directory

  • pesConfig, which defines the file where media type definitions are kept

Both these directives default to a file in Apache’s default log directory. If you want to put any of them anywhere other than <SeverRoot> /logs, you’ll have to define each one in turn. The supplied httpd.conf file that comes with Apache, which is found in <ServerRoot> /conf, gives an example of each set to the default location, so it’s easy to find and change them.

If the server uses a particular directory for CGI scripts, you’ll need to locate it with a ScriptAlias directive. Apache has a cgi-bin directory for this purpose located under the server root, and the configuration file as supplied with Apache contains a ScriptAlias directive to match. It’s worth observing that the cgi-bin directory has no special significance other than that it’s supplied by the ScriptAlias directive in the default configuration; it’s not a fundamental default in Apache.

If you don’t need a specific place for CGI scripts, perhaps because they’re enabled to run from any location, you don’t need either the ScriptAlias directive or the cgi-bin directory. I’ll discuss this in more detail in Chapter 6.

Apache also comes with a set of icons for use in directory listings, usually located in the <ServerRoot> /icons directory. To avoid redefining each and every icon location, the default Apache configuration uses an Alias directive to specify the location of the icons directory. Change the directory alias to move all the icons to a different location.

Locating the Server Executables

The Apache binary, httpd, can be located anywhere, as can the support utilities that come with it. It’s not necessary to specify their location in the configuration, but apachectl may need to be edited to reflect the location you choose.

One popular alternative to placing the binaries in /usr/local/apache/bin is /usr/local/sbin or even /usr/sbin. Some prebuilt packages do this; for example, the RPM packages shipped with Red Hat Linux follow this convention.

Note that the Apache binary for Windows is called apache.exe and is usually found in a directory called apache.

Security and Permissions

Only privileged users should be able to write the Apache executable, configuration, log files, and all higher directories up to and including the root directory.

For example, on Unix systems, the following commands run by root create the configuration and log directories, with the correct permissions, under /usr/local/apache:

# mkdir /usr/local/apache
# chmod 755 /usr/local/apache

# cd /usr/local/apache
# mkdir conf logs
# chmod 755 conf logs

Likewise, this runs the Apache executable:

# cp /httpd /usr/local/bin
chmod 511 /usr/local/bin/httpd

Follow the same steps for any of the Apache utilities that are also installed. Note that they need not be located in the same place as Apache itself (or as each other, though for the sake of sanity I don’t recommend scattering them at random across the disk).

Note that even if Apache runs under the identity of a specified user and group (for example, nobody), the directories and files Apache uses are still owned by root. The point of a different user is that the Apache processes that handle client requests don’t have the privilege to interfere with the Web server or other sensitive systems running on the server such as email. This makes it harder for malicious users to compromise security. 

This chapter is from Pro Apache by Peter Wainwright. (Apress, 2004, ISBN: 1590593006). Check it out at your favorite bookstore today. Buy this book now.

 

{mospagebreak title=Upgrading Apache}

New versions of Apache are released quite frequently—the latest stable and beta versions are available from the Apache Web site along with notifications of bugs fixed and features added. In general, any recent version of Apache should run with an existing configuration, even if it supports new features.

The important exception is that when upgrading from Apache 1.3 to Apache 2; it may be better to transfer custom configuration details from the old httpd.conf to the new. To avoid mixing up custom and default directives, it may be wise to consider using an Include directive to store changes and additions in a different file to the main configuration to make future migrations simpler (this is described in Chapter 4).

Since version 1.3.4, Apache comes with a unified configuration file rather than three individual files. It isn’t necessary to merge an existing configuration when upgrading to a later version of Apache 1.3 because the other two files are still looked for. However, Apache 2 removes this feature, so Include directives will be needed to restore the original behavior—these and other issues are discussed in more detail in Chapter 4.

NOTE It’s not obligatory to upgrade simply because a new release is available. Unless a software bug or security vulnerability has been fixed that specifically applies to your configuration or platform, or a desired feature is now available, the maxim “if it isn’t broken, don’t fix it” applies. In particular, don’t even consider upgrading a production server to a beta release unless it’s critical to do so, and even so, use a test server to try the new release first. It’s generally far better to apply a work-around to a known bug than to potentially introduce several unknown ones in order to fix it.

Note that if you’re installing Apache from a binary distribution over an existing installation using install-bindist.sh, the script is intelligent enough to copy the new configuration files with .default extensions, leaving the existing files in place. Once the upgrade is installed, you can restart the server. Unless something unusual has occurred, the new Apache should start up with the old configuration without complaint.

In fact, it’s often possible to upgrade Apache just by replacing the existing httpd executable with the new version. However, the new httpd file cannot be copied over the old file if the server is running. Such an attempt would produce an error message such as the following:

$ cp httpd /usr/local/apache/bin
cp: cannot create regular file ‘http': Text file busy

Because the old file can be moved aside without disturbing the running server, the following command sequence in the bin directory can be used for carrying out an update:

$ mv httpd httpd.old
$ cp /bindist/bin/httpd httpd
$ apachectl stop
$ apachectl start

Note it’s not sufficient to use kill -HUP to restart the server if you intend to run a new binary; this will only cause the running server to perform a restart. To replace it, the server must be actually shut down and restarted using the new executable.

If you choose to just update the binary, be aware that some of the utility programs that come with Apache may cease to work unless you also replace them with new versions; apxs, the utility for compiling modules for Apache, is one that’s likely to break. Other scripts such as apachectl or htpasswd may continue to run but may be improved in newer releases so should probably be upgraded at the same time.

If you installed Apache from a package, you can upgrade it by performing a package upgrade. For example, using the RPM example from earlier, you can simply execute this:

$ rpm -Uvh apache-1.3.28-1.i386.rpm

This will protect existing configuration files where they have changed and install the new ones with an .rpmnew extension. You may then integrate any new configuration changes you like at your leisure. If you also installed packages such as apache-devel or apache-manual (depending on the platform), you should take care to also upgrade these at the same time. This will even serve to upgrade from Apache 1.3 to Apache 2, but there may be more issues to resolve afterward, in particular in relation to changes in Apache’s configuration syntax.

Other Issues

Before moving on to configuring and testing the server, there are few other issues worth considering.

Time

If you’re planning to run an Internet-accessible server, it’s a good idea to make sure the server’s clock is accurate so that time-dependent information such as the Expires header, cookies, and log messages (particularly when tracking suspicious activity) is handled correctly.

Given Internet connectivity, the ideal solution is to use a time synchronization protocol and receive accurate time from the Internet. The Network Time Protocol (NTP) is one that’s in widespread use and for which free software is available on many platforms. See http://www.eecis.udel.edu/~ntp/ for more information.

Multiple Installations

It’s possible to install Apache more than once. There are several reasons why you might want to do this. For example, you might want to separate a secure server using SSL with a restricted set of features from a more capable nonsecure server. Or you might want to run a privileged server with access restrictions independent of the main server. Running a second server is also an excellent way to test a new release in parallel with the current installation before changing it over to the main server.

One way to do this is to invoke install-bindist.sh with different installation roots. A more concise way, at least in terms of disk space consumed, is to use the same installation but use Apache’s -f option to specify alternative server configuration files.

Whatever the reason, as long as the server configurations use different IP addresses and/or ports, there’s no limit to how many different running installations of Apache you may have.

TIP As an alternative, to keep configurations mostly identical, consider using the -D option to enable optional sections of a single configuration.  

This chapter is from Pro Apache by Peter Wainwright. (Apress, 2004, ISBN: 1590593006). Check it out at your favorite bookstore today. Buy this book now.

{mospagebreak title=Basic Configuration}

In this section, you’ll configure Apache to operate as a basic Web server, which will run under the name www.alpha-complex.com. First, you make some decisions about what you need the server to do and then set up the configuration file so Apache behaves the way you want. In subsequent chapters, you’ll expand this configuration to handle secure connections, virtual domains, and more, but for now you’ll concentrate on the minimum configuration that every Apache Web server needs to work.

Decisions

Before you even begin to configure Apache, you have to make some decisions about the server—what name it will have, what network connections it will respond to, where the server’s configuration and log files will go, and where the Web site documents will reside. Each of these decisions is reflected in a configuration directive in Apache’s main configuration file.

The Server Name

This is the name that the server will use in HTTP responses, and it’s usually of the form www.my-domain.com. A common misconception is that the server name is what Apache responds to. This isn’t correct—Apache will respond to any connection request on any network interface and port number to which it’s configured to listen. By default, Apache 1.3 listens to all networks available to the host computer, and Apache 2 requires an explicit configuration. Either way, the server name is the name Apache uses in responses. As an example, the one you’ll use for the server is this:

ServerName www.alpha-complex.com

The IP Address and Port to Serve

This is the IP address on which Apache will receive HTTP requests. In fact, this isn’t a required part of Apache’s configuration at all; rather, it’s the host’s network configuration. You also want to make sure the host and any remote clients that contact it using the server name can associate it with the correct IP address. You’ll use the IP address 192.168.1.1 for the example server. This is a safe address that’s never relayed across the Internet (as discussed in Chapter 1), so you know you’ll never accidentally conflict with another computer somewhere else. When you connect the server to an intranet or the Internet, you’ll need to give it a proper IP address, but this will do for now.

You can force Apache to listen to explicit addresses using either the now deprecated BindAddress directive of Apache 1.3 or the Listen directive, which is valid for both Apache 1.3 and Apache 2. Accordingly, you’ll use Listen here:

Listen 192.168.1.1:80
Listen 192.168.1.1:443

This tells Apache to listen to the IP address 192.168.1.1 on ports 80 and 443, which are the ports for HTTP and HTTPS (the secure version of HTTP), respectively. If instead you wanted to allow access from any IP address available to Apache, you can leave out the IP address and just specify a port number:

Listen 80
Listen 443

If you wanted to restrict access to clients running on the host itself with a view to opening it up to external access once you’re finished, you could instead specify this:

Listen 127.0.0.1:80
Listen 127.0.0.1:443

NOTE I’ll come back to Listen in Chapter 7 when I discuss virtual hosts.

Using standalone or inetd (Apache 1.3, Unix Only)

On Unix servers only, Apache 1.3 can run in two modes.

The first, and almost universal mode, is the standalone mode. In this mode, Apache handles its own network connections, listening for connections on the port or ports it’s configured to serve. This is the default configuration for Apache and can be set explicitly with this:

[1.3] ServerType standalone

The second is inetd mode, which applies to Unix systems only. In this mode, Apache is run through inetd when a connection request is received on a configured port and is set with this:

[1.3] ServerType inetd

In this case, Apache pays no heed to any of its network configuration directives, and inetd is configured to start Apache. Because a new invocation of Apache is created for each individual connection, this is a very inefficient way to run the server.

Apache 2 drops support for inetd entirely and removes the ServerType directive, which is no longer legal. The best course of action is therefore to simply not specify it; any configurations that do should remove it.

User and Group (Unix Only)

On Unix systems, Apache can be configured to run under a specific user and group. When Apache is started by root (for example, at system start), it spawns one or more child processes to handle clients. If User and Group are set, the children give up their root status and adopt the configured identity instead (the perchild MPM of Apache 2 complicates this statement, but for the sake of simplicity, I’ll let it stand for now). This is a good thing because it makes the server a lot more secure and less vulnerable to attack. If you intend to run Apache as root, you should define these directives.

Most Unix systems define a special user and group nobody for running unprivileged processes, and for the time being, you’ll use this for your configuration:

User nobody
Group nobody

Many administrators prefer to give Apache its own private user and group, typically called web or httpd. The reason for this is that nobody is used by a lot of other programs because it’s the generic unprivileged user. As a result, Apache might share its permissions with other programs. To avoid this, a dedicated user and group that only Apache will use is considered more secure. If these don’t already exist, you can create them using (on most systems) the groupadd and useradd commands, for example:

groupadd -g 999
httpd useradd -u 999 -g httpd -s /bin/false -c ‘Web Server’

This example should create a group called httpd with group ID 999 and then create a user in that group with user ID 999. You gave the user a login shell of /bin/false, so the account can’t be used even if you set a password for it, and you include a comment so you know what this user ID is for. Obviously, you should pick a group and user ID that isn’t already taken. You don’t have to specify them at all, in which case they will be allocated for us, but using a known ID can be useful later when replicating an Apache setup on another server or restoring a previously saved backup.

Once you have the user and group set up, you can then configure Apache with this:

User httpd
Group httpd

Windows doesn’t support the concept of user ownership and privileges in the same way (and on older consumer versions such as 9 x and ME not at all), so these directives cannot work on those platforms. Specifying these directives will not cause an error on Windows, but they will not have any useful effect, either. 

This chapter is from Pro Apache by Peter Wainwright. (Apress, 2004, ISBN: 1590593006). Check it out at your favorite bookstore today. Buy this book now.

 

{mospagebreak title=Administrator’s E-Mail Address}

Usually when running a Web site, you’ll want an e-mail contact address so that people can report problems to you. In fact, Apache uses the administrator’s e-mail address in its default error messages when problems are encountered. The e-mail address is set with the ServerAdmin directive and can be any valid e-mail address; it isn’t restricted to the same domain name as the Web server, for example:

ServerAdmin administrator@someotherdomain.net

However, for this site, you’ll use the same domain as the Web site:

ServerAdmin webmaster@alpha-complex.com

Note that you don’t specify the hostname www in the e-mail address—remember, www.alpha-complex.com refers to the machine running Apache, not necessarily the machine running your mail server. Even if both are on the same machine, you may decide to separate them later, so it’s best to use a generic address from the start. Having said this, it’s true that a mail exchanger can be set up in the DNS to direct e-mail to the www address to a different server, if that’s what you want to do.

Server Root

The server root is where Apache keeps all its essential files and is the default root for Apache’s other directives to append to if they’re defined with a relative path—see the following error log and document root sections for two good examples. You’ll stick with the default for now:

ServerRoot /usr/local/apache

Default Error Log

Apache can support many different kinds of logs, of which the most common are an access log (also called a transfer log), referrer log, and error log. You might not want to bother with access and referrer logs because they take up space and processing time, but you certainly want an error log. Apache sets the error log name with the ErrorLog directive, which defaults to logs/error_log under Unix and logs/error.log for Windows and OS/2. The name of the error log is either an explicit pathname starting with / or a name relative to the server root. To put the error log explicitly in the default place under the server root, you could specify this:

ErrorLog /usr/local/apache/logs/error_log

However, more simply, and with the same effect, you can use this:

ErrorLog logs/error_log

Because you’ll probably want a transfer log (also called an access log) at some point, you can take care of it at the same time and worry about customizing it to your own requirements later:

TransferLog logs/access_log

If you want to allow for virtual hosts, you might also place per-host versions of these files in a directory related to the domain name of the Web site, alongside a document root, which is the last location you need to set.

Document Root

Last, but not least, you need to decide where the actual Web pages will reside. This can be any valid directory accessible to the server, even on another computer over NT File System (NFS) or Server Message Block (SMB), though this would be very inefficient unless you’re using a dedicated NFS system such as a NetApp filer (see http://www.netapp.com/products/filer/). As Chapter 8 discusses, there are additional considerations if the document root isn’t local, so you’ll assume it is for now.

By default, Apache looks for a directory called htdocs under the server root. If you want to change it, you can specify either a relative path, which Apache will look for under the server root, or an absolute path, which can be outside it. It’s quite usual for the document root to be moved somewhere else to distance the publicly accessible Web site or Web sites from any sensitive Apache configuration files. This also makes upgrading or replacing the Apache installation simpler. So to specify the default document root, either of the following will do:

DocumentRoot htdocs
DocumentRoot /usr/local/apache/htdocs

For your server, you’re going to place your Web site in its own directory inside a directory called www well outside the server root in /home:

DocumentRoot /home/www/alpha-complex/web

This naming scheme will serve you well if you decide to host multiple Web sites, as you can then add more directories under /home/www.

As suggested previously, you can also use this directory to store log files, CGI scripts, and other files related to the Web site that don’t go into the document root itself, as these alternative log directives illustrate:

TransferLog /home/www/alpha-complex/logs/access_log
ErrorLog /home/www/alpha-complex/logs/error_log

Introducing the Master Configuration File

Now that you’ve decided on your basic configuration choices, you need to make the necessary changes to Apache’s configuration. Originally, Apache came with three configuration files:

  • httpd.conf

  • access.conf

  • srm.conf

Since Apache 1.3.4 was released, only httpd.conf is now necessary, and the other two have been merged into it. Apache 2 removes support for them entirely, so you’ll make all your changes in httpd.conf.

Taking all the decisions you’ve made, you arrive at the basic configuration for your example server, and the httpd.conf file now will look like this:

ServerName www.alpha-complex.com
Listen 192.168.1.1:80
Listen 192.168.1.1:443
User nobody
Group nobody
ServerAdmin webmaster@alpha-complex.com
#ServerRoot /usr/local/apache
#ErrorLog logs/error_log
TransferLog logs/access_log
DocumentRoot /home/www/alpha-complex

The lines prefixed with a hash are commented out—they’re the defaults anyway, so they’re here only to remind you of what they are. Windows Apache doesn’t understand the User and Group directives, but it’s smart enough to just ignore them rather stopping with an error.

As it happens, all these directives are documented in httpd.conf, even in a three-file configuration, so setting these directives (uncommenting the ones you want to change if they’re commented) is a one-step operation—you simply need to uncomment if they’re commented. Once httpd.conf has been changed and saved back to the disk, you’re ready to go.

NOTE I’m listing only the configuration directives you’re actually changing because the Apache configuration file is long and contains a great deal of information. You want to keep all of it for the moment, so you’ll see only the things you need to for now.

Other Basic Configuration Directives

Although not usually part of a basic Apache installation, Apache does support a few other directives that control the location of certain files created by Apache during its execution. Because most of them are both somewhat technical and rarely need to be changed from the default setting, I mention them here for completeness. However, if you’re going to use them at all, this is the time and place to do it. Note that all of these directives are specific to Unix.

The PidFile directive determines the name and location of the file in which Apache stores the process ID of the parent Apache process. This is the process ID that can be sent signals to stop or restart the server, for example, to send a termination signal:

$ kill -TERM `cat /usr/local/apache/logs/httpd.pid`

TERM is the default signal for the kill command, so you don’t need to state it explicitly. Use kill -l to see a list of the available signal names, though Apache would recognize TERM, HUP, and USR1 only.

I’ll discuss the subject of starting and stopping Apache in more detail in a moment. The default value of PidFile is logs/httpd.pid, which places the file in the logs directory under the server root. Like all Apache’s Location directives, an absolute pathname can also be used to specify a location outside of the server root. For example, Apache packages often move the PidFile to /var/run with this:

PidFile /var/run/httpd.pid

The LockFile directive determines the name and location of the file that Apache uses for synchronizing the allocation of new network requests. In Apache 1.3, this is a compile-time setting. In Apache 2, the AcceptMutex directive determines how Apache handles synchronization, and the lock file is used only if it’s set to the values fcntl or flock. For platforms that don’t support any kind of in-memory lock, this directive can be used to move the lock file from the default of logs/accept.lock. This is necessary if the logs directory is on another server and is mounted via NFS or SMB because the lock file must be on a local file system. You’ll also need to do this if you want to run more than one Apache server, for example:

LockFile /usr/local/apache/logs/server2.lock

NOTE See Chapter 8 for a full discussion of Apache’s locking mechanism and how the different lock types affect performance.

The ScoreBoardFile directive determines the location of a file required on some platforms for the parent Apache process to communicate with child processes. Like the access lock, Apache will usually create the scoreboard in memory (technically, a shared memory segment), but not all platforms can support this. To find out if a given Apache binary needs a scoreboard file, simply run Apache and see if the file named by the ScoreBoardFile directive appears. The default value is logs/apache_status, which places the file in the logs directory under the server root. Administrators concerned about speed might want to move the scoreboard to a Random Access Memory (RAM) disk, which will improve Apache’s performance, for example:

ScoreBoardFile /mnt/ramdisk/apache_status

This assumes that a RAM disk is present and mounted on /mnt/ramdisk, of course. Keep in mind that if you want to run more than one Apache server, the servers need to use different scoreboard files. A more ideal solution would be to migrate to a platform that allows Apache to store the scoreboard in memory in the first place.

In modern versions of Apache (1.3.28 onward), the server creates the in-memory scoreboard owned by the user and group ID of the parent Apache process, which is more secure. In the rare case that the old behavior of creating the scoreboard with the user and group defined by the User and Group directives (which is technically wrong) specify the directive ScmemUIDisUser on; the default is off. In other words, unless you know you need to use this directive, you almost certainly don’t.

The CoreDumpDirectory directive determines where Apache will attempt to dump core in the—I hope rare—event of a crash. By default, Apache uses the server root, but because under normal circumstances Apache should be running as a user that doesn’t have the privilege to write to the server root, no file will be created. To get a core file for debugging purposes, the CoreDumpDirectory can be used to stipulate a different, writable directory, for example:

CoreDumpDirectory /home/highprogrammer/friendcomputer

Note that this is genuinely useful because Apache comes with source code, so debugging is actually possible. Building Apache from source makes this much more useful because the debugger will have something to get its teeth into. It’s important to note, however, that leaving this option set in a production server can lead to certain security risks associated with Denial of Service attacks if a flaw is found in the Apache server that can remotely crash the Apache server. This option should be left off in production environments. 

This chapter is from Pro Apache by Peter Wainwright. (Apress, 2004, ISBN: 1590593006). Check it out at your favorite bookstore today. Buy this book now.

 

{mospagebreak title=Starting, Stopping, and Restarting the Server}

Now that you’ve configured Apache with the basic information it needs to start successfully, it’s time to find out how to actually start it.

Starting Apache on Unix

To start Apache, it’s usually sufficient to invoke it without additional parameters, for example:

$ /usr/local/apache/bin/httpd

Apache immediately goes into the background on startup, so it’s not necessary to explicitly force the program to the background using the & option on a Unix system. Depending on what the server has been configured with, it may display several informative messages, or it may simply start without displaying a single message.

If you don’t want to use the default configuration file, you need to specify the configuration file, which you can do with the -f command line option:

$ /usr/local/apache/bin/httpd -f /home/www/alpha-complex/conf/httpd-test.conf

Alternatively, Apache comes with the very convenient apachectl script, which can be used to start the server with this:

$ /usr/local/apache/bin/apachectl start

apachectl allows you to do many things, depending on what arguments you pass, and it also provides help for a list of other options. The only other mode of interest right now is startssl, which defines the symbol SSL. If you have a configuration that’s set up to conditionally start using SSL, then this is a convenient way of enabling it. The default Apache 2 configuration is set up precisely this way, though it may not be convenient to maintain the ability to conditionally start Apache with SSL—it would be inconvenient to forget this on a production server, for instance. If you do want to use this, you can start Apache with SSL with this:

$ /usr/local/apache/bin/apachectl startssl

If the configuration of the server is valid, Apache should start up. You can verify it’s running under Linux using ps:

$ ps -aux | grep httpd

On System V Unix systems such as Solaris, use ps -elf instead for much the same result.

If the server cannot start, Apache will log an error message to the screen advising you to run apachectl configtest to get more details about the problem. If the configuration is valid enough that Apache knows where the server’s error log is, you may also find additional information about the problem there.

Even if the server does start, the error log may still highlight possible problems that aren’t serious enough to actually stop Apache running but imply a configuration error, for example, not specifying a ServerName directive.

If Apache successfully starts, it will log a message into its error log:

Server configured – resuming normal operations

To keep an eye on the error log while starting Apache under Unix, a background tail command can be very useful:

$ tail -f /usr/local/apache/logs/error_log & $ /usr/local/apache/bin/apachectl start

Starting Apache on Windows

Apache 2 for Windows can be run in two different ways:

  • From a console window

  • As a Windows service

If you don’t want to run Apache continuously, you can start it from a console window and shut it down whenever you want. This is the mode Apache is installed in if you use the installer to install it for the current user only.

You can run Apache as a Windows service if you want to keep Apache running continuously. This is the mode Apache is installed in if you use the installer to install it for all users.

You can start, stop, pause, or resume services on remote and local computers and configure startup and recovery options. You can also enable or disable services for a particular hardware profile. If Apache is installed as a service, it may be started automatically at the time of system boot. See the “Configuring Apache as a Windows Service” section later in the chapter.

Running As a Console Application

There are two different ways to run Apache as a console application:

  • From a Start menu option

  • From the command line in a command prompt window

Using the Menu Option

If you choose to run Apache stand-alone rather than as a service, and have installed it from a Windows installer archive as described earlier, then you can start it from the Start menu, using the name you gave to the installer previously.

Clicking the menu option opens a console window and starts Apache inside it. You can similarly stop the server at any time by clicking the Shutdown Apache Console App menu option.

Using the Command Prompt

Apache can be run from the command window by typing the following command at the command prompt:

C:Program FilesApache GroupApache2binapache

This starts Apache as a console application. In this case, the console window remains open as long as Apache is running; press Ctrl+C to shut down Apache again.

You may also specify options to modify how Apache starts. For example, you can specify a configuration file other than the default by using the -f option:

C:Program FilesApache GroupApache2binapache -f “Program FilesApache GroupApache2conf
myconfiguration.conf”

You should now be able to see Apache in the Task Manager, which can be brought up with Ctrl+Alt+Delete or by right-clicking the task bar and selecting Task Manager. Also, if Apache 2 is running, you can see the Apache Monitor icon in the system tray.

Detecting Configuration Errors

If there’s any error while running Apache, the console window will close unexpectedly. If this happens, you can determine the cause of the error by reading the error log; generally this file is located at C:Program FilesApache GroupApache2logserror.log. Early in the startup process, errors may also be sent directly to the console. The -E and -e invocation options can help trap these, along with -w on Windows platforms. I’ll discuss these and other options next.

Invocation Options

As you saw earlier in the chapter, the -f option can be used to point Apache at the location of a configuration file. The configuration file may in turn define the location of log and error files. However, Apache provides many other options, too.

Invoking Apache with httpd -h will produce a list of available options and should look something like this:

/usr/local/apache/bin/httpd
[-D name] [-d directory] [-f file]
[-C "directive"] [-c "directive"]
[-v] [-V] [-h] [-l] [-L] [-t] [-T]

I’ll describe each of these options in a moment, but Table 2-2 provides a quick summary of them for reference. The table shows the generally applicable options that are available on all platforms.

Option Description
-D name Define a name for use in directives
-d directory Specify an alternative initial ServerRoot
-f file Specify an alternative ServerConfigFile
-C “directive” Process directive before reading configuration files
-c “directive” Process directive after reading configuration 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
-t -D DUMP_VHOSTS Show parsed settings (currently only vhost settings)
-t Run syntax check for configuration files (with docroot check)
-T Run syntax check for configuration files (without docroot check)

Table 2-2. HTTPD Invocation Command Line Options

Apache 1.3 additionally provides an option to keep the parent Apache process in the foreground to help catch error status codes from a failed start (see Table 2-3).

Option

Description

-F

Foreground mode. Don’t detach from the console.

Table 2-3. Apache 1.3 Foreground Option

Apache 2 additionally provides two more options for assisting with debugging startup problems (see Table 2-4).

Option

Description

-e level

Specify an alternative startup log level, for example, debug

-E startuplogfile

Specify an alternative startup logfile for debugging startup problems

Table 2-4. Apache 2 Debugging Options

Both Apache versions also support two unlisted options (see Table 2-5).

Option

Description

-X

Single-process foreground debugging mode.

-R

Specify an alternative location for loadable modules (shared core Apache servers only)

Table 2-5. Additional Options

Option

Description

-I

Register Apache as a service

-k config

Modify existing service definition

-k install

Same as-I

-k uninstall

Deregister as a service

-k restart

Restart running Apache

-k start

Start Apache

-k stop

Stop Apache

-k shutdown

Same as-k stop

-n <servicename>

The name of the service to control with the-i,-u, and-kcommands

-u

Same as-k uninstall

-w

Leaves the initial shell window open for 30 seconds to view startup messages

-W <servicename>

The name of the service after which an Apache service should be started (with-k configor-i)

Table 2-6. Windows-Specific Options

Now that you have seen all the command line options that Apache supports, you can go through them in detail. Once you have done this, you’ll put a few of them into action in the “Starting, Stopping, and Restarting the Server” section.  

This chapter is from Pro Apache by Peter Wainwright. (Apress, 2004, ISBN: 1590593006). Check it out at your favorite bookstore today. Buy this book now.

{mospagebreak title=Generic Invocation Options}

These options are available on all platforms.

-C: Process Directive Before Reading Configuration

This allows Apache to be started with extra configuration directives that are prefixed to the configuration files, and directives inside the configuration file can therefore augment or override them. For example, the command:

$ httpd -d /usr/local/www

could also be written as this:

$ httpd -C “ServerRoot /usr/local/www”

It might also be used in preference to -D for enabling and disabling features that can be controlled with a single directive, for example:

$ httpd -C “SSLEngine on”

You can chain multiple -C options together to create compound directives; see the next example for -c.

-c: Process Directive After Reading Configuration

The -c option is identical to -C but adds the directive to Apache’s runtime configuration after the configuration files have been read. Because -c takes effect after the configuration files, it can override directives in them. This allows a directive to be changed without altering the configuration file itself. For example, the previous SSL directive for enabling SSL would not work with -C if an SSLEngine off were present in the configuration file. However, with -c, it would.

It’s possible to use -c and -C multiple times to add multiple configuration lines simultaneously. For example, you could include a module and configure it in one command:

$httpd -c “LoadModule status_module modules/mod_status.so”
       -c “<Location /status>” 
-c “SetHandler server-status”
-c “</Location>

Defining many directives this way starts to become unwieldy, so for configurations longer than this you should probably look at creating a configuration file and using it with -f or including it with this:

$ httpd -c “Include mod_status.conf”

This can be handy for maintaining your own configuration separately from the standard one while still making use of it (Chapter 4 elaborates on this idea).

-D: Define IfDefine Name

Since version 1.3.1, Apache has supported the directive, which allows optional parts of a configuration to be defined. In conjunction with the -D flag, this allows Apache to be started with several different configurations using only one configuration file, for example:

$ httpd -D no_network

It could be used in conjunction with a configuration file containing this:

<IfDefine no_network>
<Location>
order deny,allow
deny from all
allow from 127.0.0.1
  </Location>
</IfDefine>

This would prevent Apache from responding to client requests from anywhere except the local host. The number of possible uses of this feature is extensive, such as switching on and off modules, enabling or disabling security authorization, and so on. As a practical example, Apache’s default configuration uses -D SSL to switch SSL on and off and provides the startssl option in apachectl as a wrapper around it.

Apache 2 also supports some special defines that have meaning to specific parts of the server. In particular, you can cause Apache to print out a list of all configured virtual hosts with this:

$ httpd -D DUMP_VHOSTS

To dump out this information without actually starting the server, add -t or -T as well.

In Apache 2, most MPMs also recognize and react to four special defines that are mostly oriented around debugging:

  • NO_DETACH (Unix and BeOS only): Don’t detach from the controlling terminal.

  • FOREGROUND (Unix and BeOS only, implies NO_DETACH): Don’t daemonize or detach from the controlling terminal

  • ONE_PROCESS (All MPMs, implies NO_DETACH and FOREGROUND): Don’t allow a child process to handle client requests; use the initial process instead.

  • DEBUG (All MPMs, implies all of the previous): Places the MPM into a special debug mode with additional logging.

How these defines affect the operation of the server depends on the MPM in question; see Chapter 8 for a detailed description of MPMs. See also -X (Apache 2) and -F (Apache 1.3).

For those particularly interested in debugging Apache for performance reasons, a profiling Apache 2 can be created by supply -DGPROF as a compiler symbol at build time, as described in Chapter 3.

-d: Define Server Root

To define the server root, that is, the directory containing the default locations for log files, HTML documents, and so on, the value of the compile-time option HTTPD_ROOT is used; the default value of which is /usr/local/apache.

A different server root can be specified using -d. The supplied path must be absolute (that is, start with /), for example:

$ httpd -d /usr/local/www

This supplies an initial value for the configuration directive ServerRoot. This value will be overridden by a ServerRoot directive in one of the configuration files, if present.

-e: Specify Startup Log Level (Apache 2 Only)

The -e option allows you to temporarily alter the logging level from that defined by the LogLevel directive for startup messages only. The primary use for this option is to allow you to increase the logging level to reveal potential problems with Apache’s startup, without placing the server in a high level of logging during regular operation. For example, to give Apache a temporary logging level of debug at startup, you can use this:

$ httpd -e debug

The available logging levels range from emerg (the fewest messages) to debug (all messages) and are the same as those defined by the LogLevel directive. See “Setting the Log Level” in Chapter 9 for a detailed description of what each level provides. This option may be combined with -E to place messages generated at startup into a separate logfile.

NOTE Slightly confusingly, Apache 1.3 on NetWare also supports an -e option to send startup messages to the Apache logger screen rather than the main console. However, this isn’t strictly related to the -e option provided by Apache 2.

-E: Specify Startup Log File (Apache 2 Only)

Normally, Apache will place its own startup and restart messages in the error log. To help isolate and analyze startup problems, Apache 2 allows you to put startup messages into a separate file instead, defined by the -E option. This also allows you to capture errors that get sent to standard error before the error log has been established and that otherwise can be hard to capture at all. For example:

$ httpd -E logs/startup_log -e debug

This can be particularly useful when combined with the -e option described previously to keep runtime errors distinct from potentially very verbose startup messages.

-f: Specify Configuration File

The -f option can be used to specify a different configuration file for Apache. If the path is relative (doesn’t start with /), it’s taken to be under the server root (see -d previously). Note that it doesn’t look for a configuration file starting in the local directory, for example:

$ httpd -f conf/test.conf

If a configuration file is located elsewhere, an absolute path is required, for example:

$ httpd -f /usr/tmp/test.conf

Note that you can specify -f multiple times to include more than one file, but if you specify it even once, then Apache will not read the default configuration. To include an additional file and still have Apache read the default configuration, you must specify it explicitly or use -cInclude /usr/tmp/test.conf instead.

-F: Run in Foreground (Apache 1.3 Only)

This option will cause the main Apache process to stay in the foreground, rather than detaching from the console and moving into the background. It’s mostly useful for starting Apache from another program, which can use this option to capture the exit status from the server. Apache 2 instead provides -D FOREGROUND. The -X option is superficially similar, but forces Apache into a single-process debug mode; by contrast, -F causes the server to run entirely normally apart from the main process remaining undetached.

-h: Display Usage Information

This will cause Apache to produce a usage page similar to the previous. The exact output will depend on the version of Apache and the platform.

-l: List Compiled in Modules

Specifying the option -l lists all the modules that have been compiled into Apache, for example:

$ httpd -l

Compiled-in modules:

http_core.c
mod_env.c
mod_log_config.c
mod_mime.c
mod_negotiation.c
mod_status.c
mod_info.c
mod_include.c
mod_dir.c
mod_cgi.c

mod_actions.c
mod_proxy.c
mod_rewrite.c
mod_access.c
mod_auth.c
mod_auth_dbm.c
mod_headers.c
mod_browser.c

The order of this list is significant in Apache 1.3 because the modules are listed in order of increasing priority. The further down the module appears in the list, the higher its priority. In the previous example, mod_browser has the highest priority. It will therefore always receive precedence in processing a client request when one arrives. Apache 2 has a simpler and largely automatic mechanism for determining module order, so it’s not sensitive to the order in which modules are built into the server.

A fully dynamic Apache has no built-in modules apart from the core and mod_so, which provides the ability to load dynamic modules. It therefore produces a somewhat terse list:

Compiled-in modules:

http_core.c
mod_so.c

If the suExec CGI security wrapper is enabled, an additional line noting its status and the location of the suexec binary is appended to the bottom of the report. For example, for a correctly installed suexec on a Unix server:

suexec: enabled; valid wrapper /usr/bin/suexec

NOTE Chapter 6 covers using suExec in detail.

-L: List Available Configuration Commands

-L lists all available configuration commands together with short explanations. Only core directives and directives of modules statically built into Apache (that is, not dynamically loaded during startup) will be listed, for example:

$ httpd -L

ServerName (core.c)
The hostname and port of the server
  Allowed in *.conf only outside
<Directory>, <Files> or <Location>
ServerSignature (core.c)
En-/disable server signature (on|off|email)
Allowed in *.conf anywhere and in .htaccess
When AllowOverride isn’t None
ServerRoot (core.c)
Common directory of server-related files
(logs, confs, etc.)
  Allowed in *.conf only outside
<Directory>, <Files> or <Location>
ErrorLog (core.c)
The filename of the error log
Allowed in *.conf only outside
<Directory>, <Files> or <Location>
ServerAlias (core.c)
A name or names alternatively used to access the server
Allowed in *.conf only outside
<Directory>, <Files> or <Location>

Note that up until version 1.3.4, Apache used -h for listing configuration directives, now performed by -L, and had no equivalent for the modern -h. This was changed because there was actually no way to produce the usage page legally, and -h is conventionally used for this purpose. Older documentation may therefore refer to -h rather than -L.

-R: Define Loadable Modules Path

If your server has the mod_so module built-in (which you can check with the -l option), then this option allows you to override the default location that Apache looks in for loadable modules. The default location is the same as the server root rather than a subdirectory, which is why LoadModule directives usually include a parent directory such as libexec or modules. You can redefine it with this:

httpd -R /usr/lib/apache

This is necessary only if you want to move the standard location away from the server root; otherwise, moving the server root is usually enough. However, this option will probably not work unless the loadable modules directory is also on the path defined by the environment variable LD_LIBRARY_PATH; the apachectl script takes this into account when installed as part of a binary distribution, so it’s rare that you should need to use this option directly.

-S: Show Parsed Settings (Apache 1.3 Only)

This displays the configuration settings as parsed from the configuration file. Although it may expand in the future, currently it displays only virtual host information, for example:

$ httpd -S

VirtualHost configuration:
127.0.0.1:80 is a NameVirtualHost
default server www.alpha-complex.com
(/usr/local/apache/conf/httpd.conf:305)
port 80 namevhost www.alpha-prime.com
(/usr/local/apache/conf/httpd.conf:305)
port 80 namevhost www.beta-complex.com
(/usr/local/apache/conf/httpd.conf:313)

In Apache 2, the -S option is now shorthand for the combination of -t and -D DUMP_VHOSTS.

-t: Test Configuration

This option allows the configuration file or files to be tested without actually starting Apache. The server will list any configuration problems to the screen and stop with the first fatal one, for example:

$ httpd -t

Syntax error on line 34 of /etc/httpd/conf/httpd.conf:

Invalid command ‘BogusDirective’, perhaps misspelled or defined by a module not included in the server configuration

If the configuration is error free, Apache prints this:

Syntax OK

If you have included any directories into the configuration, you’ll also get a list of the configuration files Apache found and read. In Apache 2, if you additionally specify -D DUMP_VHOSTS, you can also get a list of the virtual hosts defined in the configuration, which is identical to the -S option of Apache 1.3 described earlier. Only DUMP_VHOSTS is currently supported as an argument to -D, though other options may appear in the future. Note that it isn’t actually necessary to specify -t to view this; the server will simply start up after dumping the virtual host configuration.

The return value of httpd -t is zero for a successful test, and nonzero otherwise. It can therefore be used by scripts (for example, a watchdog script on a dedicated server) to take action if Apache is unable to start.

-T: Test Configuration Without Document Root Checks

The -T option is identical to its lowercased counterpart except that it doesn’t perform the check for valid document root directories. This is useful if you happen to have virtual hosts that don’t actually use a real document root and map all URL requests to some other medium rather than the file system.

-v: Show Apache Version

This option will simply show Apache’s version, platform, and build time and then exit, for example:

$ httpd -v

  Server version: Apache/2.0.28
Server built:Jan 23 2002 22:08:38

-V: Show Apache Version and Compile-Time Options

The -V produces the same output as -v and in addition lists the compile-time definitions that were specified when Apache was built. Most of these can be changed or added to, depending on how Apache was configured at build time. Popular choices for redefinition are the server root and location of the log files. For example, this is for the previous Apache server:

$ httpd -V

Server version: Apache/2.0.47
Server built: Jul 22 2003 16:45:13
Server’s Module Magic Number: 20020903:3
Architecture: 32-bit
Server compiled with….
-D APACHE_MPM_DIR=”server/mpm/worker”
  -D APR_HAS_SENDFILE
-D APR_HAS_MMAP
-D APR_HAVE_IPV6 (IPv4-mapped addresses enabled)
-D APR_USE_SYSVSEM_SERIALIZE
-D APR_USE_PTHREAD_SERIALIZE
  -D SINGLE_LISTEN_UNSERIALIZED_ACCEPT
-D APR_HAS_OTHER_CHILD
-D AP_HAVE_RELIABLE_PIPED_LOGS
-D HTTPD_ROOT=”/usr/local/apache”
-D SUEXEC_BIN=”/usr/local/apache/bin/suexec”
-D DEFAULT_PIDLOG=”logs/httpd.pid”
-D DEFAULT_SCOREBOARD=”logs/apache_runtime_status”
-D DEFAULT_LOCKFILE=”logs/accept.lock”
-D DEFAULT_ERRORLOG=”logs/error_log”
-D AP_TYPES_CONFIG_FILE=”conf/mime.types”
-D SERVER_CONFIG_FILE=”conf/httpd.conf”

This Apache 2 server has been built with the worker MPM in the default location of /usr/local/apache and with the suExec wrapper enabled.

-X: Single Process Foreground Debug Mode

If Apache is called with -X, only one process will be started with no forked child processes or multiple threads, and Apache will not run in the background. This is primarily intended for use with debuggers and isn’t intended for normal operation, and it’s now largely superseded in Apache 2 by the FOREGROUND, ONE_PROCESS, and DEBUG special defines (see -D previously).

Administrators running Apache 1.3 may want to look at the -F option as an alternative if they want to start and monitor Apache using another program; Apache 2 administrators should look at -D NO_DETACH instead.  

This chapter is from Pro Apache by Peter Wainwright. (Apress, 2004, ISBN: 1590593006). Check it out at your favorite bookstore today. Buy this book now.

{mospagebreak title=Windows-Specific Invocation Options}

These options are specific to Windows servers.

-i: Install Apache As Service

The -i option is a short form of -k install and has the same effect. The following two commands are equivalent:

c:> apache -i -n Apache2
c:> apache -k install -n Apache2

-k: Issue Apache Service Command

The -k option is used to run Apache as a service on Windows and takes a command as an argument. The -k install and -k uninstall commands install and uninstall Apache as a service, respectively. They don’t, however, actually cause Apache to start or stop; the -i and -u options are shorthand abbreviations for these commands. For example, to install Apache under its default service name of Apache, use this:

c:> apache -k install

To specify a different service name, use -n in addition to -k. Other Apache options may also be specified to configure the service, as, for example, an alternative document root:

c:> apache -n Apache2 -k install -d alternativeapacheinstall

To modify the configuration of an existing service, use -k config instead:

c:> apache -n Apache2SSL -k config -DSSL -f alternativeapacheinstallconfhttpd.conf

The -k start command actually starts Apache running as a service. Once running, the -k restart and -k stop commands restart and stop the running server, respectively. -k shutdown is a synonym for -k stop:

c:> apache -k start
c:> apache -k restart
c:> apache -k stop

To install and run Apache with a specific service name, -k can be combined with the -n option:

c:> apache -n Apache2 -k restart

-N: Specify Apache Service Name

If Apache is being installed, uninstalled, or otherwise controlled as a service, -n specifies the service name. If Apache was started as a service using the default service name, then -n isn’t necessary. It has meaning only if used in combination with the -i, -u, or -k options, as shown previously and next. (On NetWare, -n renames the console screen instead.)

-u: Uninstall Apache As Service

The -u option is a short form of -k uninstall and has the same effect. The following two commands are equivalent:

c:> apache -u -n Apache2

c:> apache -k uninstall -n Apache2

-w: Keep Console Window Open

If Apache isn’t started from a command line, then this option preserves the initial console window for the given number of seconds, allowing you to see any important startup messages before the window closes. Normally, the transient console window closes almost immediately. To configure an existing service to keep it open for 10 seconds, use this:

c:> apache -n Apache2 -k config -w 10

See the -E option for an alternative way to preserve and view startup log messages separately from the error log.

-W: Specify Preceding Service

In conjunction with -k config, -k install, or -i, the -W option can be used to specify the name of the service that Apache is to be placed after on server startup. This determines the order in which it starts relative to other services, for example:

c:> apache -n Apache2 -k install -W SNMP

It’s possible to issue this command twice, from the bin directories of two different Apache installations, giving a different service name for each (for example, Apache2a and Apache2b).

Restarting the Server

There are several reasons you might want to restart Apache rather than shut it down, for instance, to read in an altered configuration if you have changed one or more configuration files.

Restarting is a gentler process than a full shutdown because it allows Apache to come back up as quickly as possible. In addition, you can do what is known as a graceful restart, which allows clients to complete their current request before being disconnected.

Restarting the Server Normally

The simplest way to restart an Apache 2 or Windows Apache 1.3 server is with this command:

$ /usr/local/apache/bin/httpd -k restart
c:> apache -k restart

Alternatively, any Apache server can be restarted using this command:

$ kill -HUP <pid>

Here <pid> is the process ID of the root Apache process, and HUP is the hang-up signal. Note that Apache may spawn multiple processes to handle incoming connections (Apache 1.3 and multiprocessing MPMs); if this is the case, then only HUPing the original process will restart the server. You can determine the pid by using ps and looking for the httpd that’s owned by root rather than the Apache default user (typically nobody), or alternatively, get it from the pid file generated by Apache on startup, for example:

$ kill -HUP `cat /usr/local/apache/logs/httpd.pid`

You can use the apachectl script to do the same thing as the first example:

$ /usr/local/apache/bin/apachectl restart

This is actually identical to the kill command but is easier to remember. Naturally, you’ll need to have apachectl installed in order to use it. The advantage of the kill command is that it will always work regardless of the server version and whether apachectl is installed. In either case, the error log should then contain the following two entries regarding this process:

SIGNUP received. Attempting to restart
Server configured – resuming normal operations

Restarting the server in this way takes it down and brings it back up again in the minimum possible time. As a result, it causes connections that are currently servicing client requests to terminate prematurely and also clears the queue of pending connection requests should any be waiting. As a way around this problem, Apache also supports the concept of a graceful restart.

Restarting the Server Gracefully

In a graceful restart, existing client connections aren’t interrupted as they are in a normal restart. The configuration file is reread, and all child processes or threads not currently engaged in servicing a request are terminated immediately and replaced by ones using the new configuration. Processes engaged in a client request are instructed to terminate themselves only after completing the current request. Only then will new ones replace them. The ports on which Apache is listening will not be shut down during this process, preserving the queue of connection requests. The exception to this is if a port number was changed in or removed from the configuration file—then the queue is dropped, as you would expect.

Graceful restarts make use of the USR1 signal, but, other than this, they’re identical to the other restart and stop methods. To do a graceful restart the old-fashioned way, use this:

$ kill -USR1 `cat /usr/local/etc/httpd/logs/httpd.pid`

or with apachectl, use this:

$ /usr/local/apache/bin/apachectl graceful

Apache 2 and Windows Apache 1.3 servers will also understand this:

$ /usr/local/apache/bin/httpd -k graceful
c:> apache -k graceful

The following two entries should then appear in the error log:

SIGUSR1 received. Doing graceful restart
Server configured – resuming normal operations

Wherever possible, a graceful restart should be used in preference to a normal restart, particularly in the case of a production Web server that’s potentially receiving a new request at any given moment.

A graceful restart is also useful for scripts performing log file rotation. In a graceful restart, child processes still engaged in an existing connection will continue to log to the original log files until they complete the request rather than terminate prematurely. Because the log files may still be in use for a short time after the restart, a rotation script should wait until all existing processes have completed before rotating the log files. It can do this either by monitoring the process IDs of the running server or simply waiting a “reasonable” period of time before commencing—a minute is generally more than adequate. See the discussion of log rotation in Chapter 9 for more about this.

Stopping the Server

Stopping the server follows a similar pattern to restarting it using the old style:

$ kill -TERM

or the new style:

$ /usr/local/apache/bin/httpd -k stop
c:> apache -k stop

and this:

$ /usr/local/apache/bin/apachectl stop

Any of these commands will cause Apache to shut down all its processes (under Unix, as Windows has only one), close all open log files, and terminate cleanly with an error log message:

httpd: caught SIGTERM, shutting down

Note that if the server is shut down at a point of high activity, it may take a while for all the running processes to terminate. One upshot of this is that attempting to start the server back up again immediately may fail because the old instance is still not completely terminated (the continued existence of the httpd.pid file is an indication of this). The solution to this problem is, of course, to restart the server instead:

-k shutdown is a synonym for -k stop:
c:> apache -k shutdown

Starting the Server Automatically

Just as with any other network service, Apache should be started automatically when the server is booted. This is especially important if you want the server to be capable of being shut down and started up again without our manual intervention, which is usually the case for a production system. The exception is a development server, where the Apache configuration may not yet be stable or secure enough to run full-time.

Configuring Apache As a Unix Service

On Unix systems, the standard place for stand-alone boot-time scripts to run from is /etc/rc.d/rc .d or /etc/init.d/rc<n>.d, where <n> is a run level from 0 to 6. These scripts must understand a common set of command line parameters including start, stop, and restart. Individual commands can usually be added to the startup in a file called rc.local, usually located in /etc/rc.d. Some systems support a similar idea to rc.local but use a different name. For example, some Unix implementations have /etc/init.d/boot.local as an equivalent. To have Apache start up with the server, either route can be followed.

Given the existence of rc.local, add the following lines to the bottom to automatically start Apache:

/usr/local/apache/bin/httpd

or, using apachectl:

/usr/local/apache/bin/apachectl start

Alternatively, an Apache start/stop script—for example, apachectl—can be installed into the standard run-level directories /etc/rc.d/rc.<n>.d. Scripts in these directories are usually invoked with start, stop, and restart parameters by the operating system during startup and shutdown. Because apachectl understands these parameters, it’s suitable for use as a system script, if desired. Although different Unix implementations vary in the details of how they do this, they’re all broadly similar.

First, copy or (preferably) link to apachectl from the init.d directory, for example:

ln -s /usr/local/bin/apachectl /etc/rc.d/init.d/httpd

Creating a link will ensure that if you upgrade Apache, the apachectl that came with it is automatically used rather than an older and potentially incompatible version.

Next, create start links that point to the new init.d entry, according to when you want Apache to start. The run level for networking is 3, and for graphical desktops 5, so you need to add a link from both rc3.d and rc5.d (if you don’t intend to run a graphical interface, you can ignore rc5.d), like this:

ln -s /etc/rc.d/init.d/httpd /etc/rc.d/rc3.d/S30httpd
ln -s /etc/tc.d/init.d/httpd /etc/rc.d/rc5.d/S30httpd

Startup scripts are always named with an S followed by a number, which serves to determine the order in which the operating system will run them. In this example, I’ve picked 30 to ensure it starts after other essential services, such as the network. If you have Apache automatically making database connections, then you’ll also want to make sure the database starts up first. If in doubt, start Apache toward the end of the initialization to ensure all prerequisite services are started first. Apache failing to start because a prerequisite service did not start before it can be very difficult to troubleshoot, especially for someone not fully familiar with the nuances of Unix.

Now, create stop links that point to the new init.d entry, according to when you want Apache to stop. This is generally the opposite of the start order—you want Apache to stop first, then the network, to give Apache a chance to clean itself up and exit rather than pull the carpet out from under it:

ln -s /etc/rc.d/init.d/httpd /etc/rc.d/rc3.d/K04httpd

ln -s /etc/tc.d/init.d/httpd /etc/rc.d/rc5.d/K04httpd

With this in place, Apache should now start and stop automatically with the server.

Prebuilt packages for Apache generally come with suitable scripts to start and stop Apache. In many cases, they’re just a wrapper for apachectl; in others, they perform various kinds of integration with the rest of the operating system. If one is available, it’s generally better to use it. For the more adventurous administrator, it’s also quite possible to download a prebuilt Apache package, extract the scripts from it and throw the rest away, build Apache from scratch, and install the scripts by hand.

Configuring Apache As a Windows Service

Running Apache as a Windows service is not greatly different from the stand-alone approach described previously. However, it allows Apache to be administered more easily through the operating system Services window. You can also use the Apache Monitor, by default installed into the system tray, to control the running server and access the Services window.

Starting Apache as a Service from the Start Menu (Windows NT, 2000, and XP Only)

The simplest way to start Apache as a service is to install it as a service to begin with. It can also be installed, uninstalled, and reinstalled by using the -n and -k command line options, which allows you to change the service name. Different command line options (notably -f and -D) can also be specified with different service names to create multiple configurations, each running as a different service but using the same installed software.

Apache may now be started and stopped at any time by opening Control Panel -> Administrative Tools ->ervices Window and selecting the Apache (or Apache2) service—clicking the Start button starts the service, clicking the Stop button stops the service, and clicking the Restart button restarts the service. Figure 2-1 shows Apache installed and running as a service with the name Apache2 in the Services window.

 
Figure 2-1.  The Services window showing the Apache 2 service

Note that the Startup Type column indicates that the Apache2 service currently has to be started manually. To start the Apache2 service automatically, follow these steps:

  1. Right-click the Apache2 service.

  2. Select the Properties option from the pop-up menu.

  3. Change the Startup Type option on the General tab to Automatic (see Figure 2-2).

  4. Click the Apply button in the bottom.

 
Figure 2-2. Changing the startup type with the Apache2 Properties dialog box

Once this is done, Apache will now start up automatically, and the Services window should reflect the changed value of the Startup Type option (see Figure 2-3).

 
Figure 2-3.  After changing the startup type

Starting Apache As a Service from a Console Window

From a console window, you may start Apache as a service from a command prompt by entering this:

C:> NET START APACHE2

Likewise, to stop a running service, use this:

C:> NET STOP APACHE2

To install Apache as a service, use the following command:

c:> apache -n Apache2 -k install

This doesn’t actually start the server—it only installs it as a Windows service so that Windows knows how to interact with it.

You can also specify any number of general Apache options, which are recorded into the registry and used when the service is started. This allows you to specify the server root, configuration file, defines, and so on:

c:> apache -n Apache2b -k install -d alternateapacheinstall -f conf/alternate.conf w10

You may install several different Apache services by specifying a different service name for each invocation of the above command. However, each configuration must use a different set of Listen directives, or the services will clash when they try to bind to the same network address and port.

Once Apache has been installed as a service, you can start it from the Services window or from the command line using this:

c:> apache -n Apache2 -k start

One command must be issued for each service installed. In combination with the -f, -D, -c, and -C options, this can be used this to run different servers with different capabilities, each serving its own Web sites. Note that at the minimum you must specify different ports for each service to listen to; otherwise, they will conflict, and only one will be able to start.

Conversely, if you used the default service name (which differs depending on whether version 1.3 or 2 is installed), you can omit the -n option entirely:

c:> apache -k stop

If both versions are installed, this command is ambiguous, so to be safe, it’s better to specify the service name even if it’s the default.

Once Apache is running as a service, it can be stopped again from the Services window or by entering this:

c:> apache -n Apache2 -k stop

Similarly, to restart it, use this:

c:> apache -n Apache2 -k restart

or, to remove Apache as a service, use this:

c:> apache -n Apache2 -k uninstall

You can also reconfigure the service using the -k config variant, after which you may restart the server to have it pick up the new configuration:

c:> apache -n Apache2 -k config -f conf/alternate_httpd.conf

Most of Windows NT/2000/XP services log errors to Windows’ own system logs. Because Apache has more demanding and specialized logging requirements, it continues logging its errors to the error.log file in the logs folder, as described previously.  

This chapter is from Pro Apache by Peter Wainwright. (Apress, 2004, ISBN: 1590593006). Check it out at your favorite bookstore today. Buy this book now.

{mospagebreak title=Testing the Server}

Once the server is running and you have dealt with any error messages, the next step is to test it. The most obvious way to test a Web server is with a Web browser, but you can also test from the command line.

Before trying to test the server, create a short but valid home page, so Apache has something to send. You can use the page Apache installs by default or put together your own, for example:

<html>
<head>
<title>Welcome to Alpha Complex</title>
</head>
<body>
The Computer is Your Friend
</body>
</html>

This is a somewhat minimal HTML document, but it’s good enough for testing purposes. Put this in a file called index.htm or index.html and place it in the directory specified as the document root in Apache’s configuration.

NOTE If no document root has been specified, Apache looks for a directory called htdocs under the server root. If neither the server root nor the document root is defined, the default home page would be /usr/local/apache/htdocs/index.html .

Testing with a Browser

The simplest and most obvious approach is to start a Web browser and point it at the server using the server’s configured root domain name if it has one, or localhost, which should work on any Unix system. Alternatively, the configured IP address of the server should also work:

Domain name : http://www.alpha-complex.com/
IP Address : 192.168.1.1
Local Host : http://localhost/
Local Host IP : 127.0.0.1

Apache needs to know what domain or domains it’s to handle, but it’s not responsible for managing them, only responding to them. In version 1.3, Apache listens to all valid IP addresses for the host it’s running on by default, so an attempt to contact any valid network name or IP address for the host with a browser should cause Apache to respond. Apache 2 requires that you specify at least one Listen directive; it determines whether Apache will receive the connection request.

If you’re setting up Apache to use a particular domain name but don’t yet have a proper IP address for it, you can associate www.alpha-complex.com in this example with the loopback IP address 127.0.0.1 as a temporary stand-in, which will allow the domain name to work without a real network interface in place.

NOTE For more information on domain names and IP, see the introductory section about TCP/IP networking in Chapter 1 and the Listen directive.

Testing from the Command Line or a Terminal Program

It’s also possible to test the server either directly from the command line or by using a basic terminal program. This can be especially handy when checking the values of response headers that are otherwise hard to see. On Unix systems, the telnet command can be used to make a network connection to the server. On other operating systems, a telnet utility is usually available, and syntax and location vary from system to system. Most browsers support a telnet mode.

To contact the server with telnet, type the following under both Windows and Unix:

telnet localhost 80

or in a browser, enter this URL:

telnet://localhost:80

If Apache is running and responding to connections, this should produce something similar to the following (some telnet commands are more verbose than others):

Trying 127.0.0.1…
Connected to localhost.
Escape character is ‘^]’.

At this point, you may type in any valid HTTP protocol command, and if the server is working correctly, you can expect a response. For example, the following will return a short informational message about the server:

HEAD / HTTP/1.0

Because HTTP 1.0 and newer allows you to send additional information in the form of additional header lines, you need to press the Return key twice after this command to let the server know the whole request has been sent.

What does this mean? HEAD tells the server you just want header information. The / is the URL you want, which needs to be valid even if you don’t actually want the page; / must be valid on any server, so it’s safe to use here. HTTP/1.0 tells Apache you’re sending a version 1.0 HTTP command. Without the HEAD command, Apache will assume that you’re sending HTTP 0.9 commands because the HEAD command was introduced in HTTP 1.0. You’ll need to explicitly set the HTTP version, or Apache will return the following error:

<!DOCTYPE HTML PUBLIC “-//IETF//DTD HTML 2.0//EN”>
<html>
<head>
<title>400 Bad Request</title>
</head>
<body>
<h1>Bad Request</h1>
Your browser sent a request that this server could not
understand.<p>client sent invalid HTTP/0.9 request:
head </p>
</body>
</html>

If the server is working correctly, HEAD / HTTP/1.0 should produce something like this, depending on the exact configuration:

HTTP/1.1 200 OK
Date: Mon, 28 Jul 2003 14:22:23 GMT
Server: Apache/2.0.46 (Unix) DAV/2
Connection: close
Content-Type: text/html; charset=ISO-8859-1

This tells you what version of HTTP Apache supports (1.1 for any version from 1.2 and newer), the time of the request, and the server type and version. In this case, Apache, of course, plus the operating system. Connection: close tells you that Apache

will close the connection after responding, and Content-Type tells you what kind of document you asked about. This particular home page is an HTML document. If the server responds to a HEAD command, it’s time to try to retrieve the homepage of the Web site with this:

GET /

This will cause Apache to interpret the request as an HTTP version 0.9 command and should produce the homepage:

Trying 127.0.0.1...
Connected to localhost.
Escape character is ‘^]’.
GET /
HTTP/1.1 200 OK
Date: Mon, 28 Jul 2003 14:22:31 GMT
Server: Apache/2.0.46 (Unix) DAV/2
Connection: close
Content-Type: text/html

<html>
<head>
<title>Welcome to Alpha Complex</title>
</head>
<body>
The Computer is Your Friend
</body>
</html>

You could also use a protocol parameter to tell Apache you want to use HTTP version 1.0:

GET / HTTP/1.0

If you do this, you have to press Return twice to tell Apache you don’t want to send any headers. If you were to specify HTTP/1.1, you would be obliged to send a hostname as a header. You could do this anyway with either 1.1 or 1.0, and if there are virtual hosts set up, you can test each one individually, for example:

GET / HTTP/1.1
Host: www.alpha-complex.com

and:

GET / HTTP/1.1
Host: www.alpha-prime.com

If Apache responds correctly to each GET request with the appropriate home page, you have a working server.

Unless it has been configured otherwise with the KeepAlive directive, Apache will keep a connection open after handling an HTTP/1.1 request. This allows you to type in another request immediately. With HTTP/1.0, the connection is dropped after the response is sent.  

This chapter is from Pro Apache by Peter Wainwright. (Apress, 2004, ISBN: 1590593006). Check it out at your favorite bookstore today. Buy this book now.

{mospagebreak title=Testing the Server Configuration Without Starting It}

If you want to check that Apache’s configuration is valid without actually starting the server, you can do so by passing the server executable the -t option. The following uses a Unix installation path as an example:

$ /usr/local/apache/bin/httpd -t

This will report any problems with the configuration or return a “Syntax OK” message if all is well. If you included any directories into the configuration, then you’ll also get a list of the configuration files Apache found and processed. The document roots of the primary server and any virtual hosts you have created are also checked, and a warning is issued in each case if the associated directory is not present. You can disable this check by using the -T option, which is in all other respects identical to -t:

$ /usr/local/apache/bin/httpd -T

You can also use apachectl, which will test the configuration inclusive of document root checks using the configtest mode:

$ apachectl configtest

To test a Windows service configuration, use the -t or -T options in conjunction with -n:

c:> apache -n Apache2 -t

This is just a convenience wrapper around a call to the server executable using -t; in a default installation, it’s identical to the first command given previously. If you want to change it to -T or add a corresponding configtestnoroot mode, then it’s simple to adapt apachectl accordingly.

Windows installations performed by the installer additionally create a menu item to test the configuration.

Getting the Server Status from the Command Line

If you have mod_status configured into the server, you can also test it from the command line using apachectl and the status or fullstatus options. These extract a status report from the server:

$ apachectl status

or for a full status report (note that this option is called extendedstatus in earlier versions of apachectl):

$ apachectl fullstatus

Nice though this seems, it’s really just a wrapper around a conventional HTTP request that you might equally have made with a browser or a telnet command. As such, it will work only if apachectl is configured to point to a URL that will return a status page. If you have modified how and where a status page is delivered, you’ll need to modify apachectl. In addition, apachectl uses an external program, by default the text-only Lynx browser, to actually do the work, so the fullstatus option is actually equivalent (on a default Unix installation where the port is set to 80 with Listen or Port) to the following:

lynx -dump http://localhost:80/server-status

This is actually what the default Apache configuration responds to, so out of the box it should work (so long as you have Lynx actually installed, of course). In addition, if you build Apache with a different initial configuration—for instance, a different default listening port or a different name for the server binary—then apachectl will be installed with that port number or server name preset in the program.

It’s entirely possible and actually easy to extend apachectl to produce other kinds of test reports, for instance, adding the apachectl info command to retrieve the information page produced by mod_info. You just need to add a clause for info and maybe add an INFOURL constant at the top of the program. After viewing the apachectl script in an editor, the changes to make should be self-evident. Given time, it’s possible and quite appealing to turn apachectl into a custom Web server tuning and monitoring tool. 

This chapter is from Pro Apache by Peter Wainwright. (Apress, 2004, ISBN: 1590593006). Check it out at your favorite bookstore today. Buy this book now.

 

{mospagebreak title=Using Graphical Configuration Tools}

Although Apache has no official configuration applications, there are many capable third-party GUI tools available and under development. Some are freely available, and others are commercial offerings.

The best place to look for software and information on GUI configuration tools is the Apache GUI Development project page located at http://gui.apache.org/. This contains links to all the major Apache GUI configuration applications as well as current news and information on existing and developing projects. This section covers a selection of freely available graphical configuration tools.

Comanche

Comanche is a graphical configuration editor for Apache, freely available for both Unix and Windows, and is the most widely used tool to configure Apache. The latest version supports Apache 1.3.

The Windows version contains a static binary with the Tcl/Tk libraries linked in and runs out of the archive; it reads the Windows registry for Apache’s configuration information, so additional configuration shouldn’t be necessary.

The Unix version is available as source, which requires the prior installation of Tcl/Tk and iTcl, and as a binary package for several platforms, which come with all necessary components included. RPM packages for Linux are also available. Both versions are available from http://www.comanche.org/ or http://apache.covalent.net/projects/
comanche/
. Comanche’s interface style mirrors that of a tree-based organizer or, in Windows terminology, an explorer. Although it doesn’t provide extensive configuration options, it does the work of making sure the basic organization of the configuration file is logical and valid while allowing the administrator to enter individual configuration options—which are then written to the appropriate points in the file when it’s regenerated.

Like Apache itself, Comanche is a work in progress. It’s worth checking the Comanche Web site at regular intervals to download new versions as they become available.

Installing Comanche on Linux

Comanche is available as an RPM for most Linux distributions, as well as a compressed tar archive. To install Comanche on Linux, use the tar command:

# tar -zxvf comanche3.0b4-x86-linux-glibc2.tar.gz

The tool is installed under the directory comanche3-0b4. This completes the installation of Comanche. To start Comanche, run the startup script as follows:

# ./comanche3.0b4 &

This should produce the startup screen as shown in Figure 2-4.


Figure 2-4. Comanche startup screen

Now press the Comanche button on the screen. Because Comanche is not yet configured with Apache, you have to configure Apache installation for Comanche. Follow the New Apache Installation link to configure Apache with Comanche, as shown in Figure 2-5.


Figure 2-5. Comanche main screen

Comanche will then ask for the location of your Apache installation; by default it uses /usr/local/apache. This is where a default installation from source installs Apache. You’ll use the same path (see Figure 2-6).

This is all that’s necessary to configure an Apache installation with Comanche. With the Server Management option, you can now start, stop, and restart the server.

Now select the Default Web Server option. It shows the link to default Web site properties (see Figure 2-7).


Figure 2-6. Adding an Apache installation to Commanche

 
Figure 2-7. Default Web server main Screen

This link leads to the window shown in Figure 2-8.


Figure 2-8. Default Web server basic configuration

Here you can modify basic directives such as DocumentRoot, ServerName, and so on. Make changes for these directives, and restart the server to see the changes.

Modularization

Management modules (plug-ins) can be built using the Comanche framework. There are plug-ins for Apache, Samba, and so on, but because Apache is a complex program, the plug-in itself is modular and support for directives and modules is achieved via an extension mechanism. The process is relatively simple—all you have to do is write a few Extensible Markup Language (XML) files.

Modules are located under ComancheHomepluginsapachemodules. Each module is placed under a separate folder. There are certain files that are needed to support the module:

  • moduleDescription.xml: This file contains basic information about the module such as its name, nodes in which you’re interested, and so on.

  • directives.xml: This file contains description of the directives that are declared in this module.

  • propertyPages.xml: This file contains the description of the property pages for this module, which are presented to the user during configuration.

  • specialCases.tcl: This file contains the actual Tcl code used to convert from XML format to httpd.conf.
  • messages: The text corresponding to the messages are stored in the messages/ subdirectory so they can easily be translated by other people. The messages are stored with a suffix corresponding to the language—messages.en, messages.es, and so on.
TkApache

TkApache is a graphical configuration editor for Unix systems. It’s written in Perl/Tk and therefore needs Perl and the Perl::Tk package installed as prerequisites; however, it doesn’t require Tcl.

TkApache is available from http://ultra.litpixel.com:82/TkApache/ TkApache_content.html or http://everythinglinux.org/TkApache/.

Installation of TkApache is slightly fiddly—after running TkApache for the first time, you see a dialog box of basic configuration details. This dialog box must be given an installation directory that’s different from the one in which the TkApache files are initially located, for example, /usr/local/apache/gui/TkApache.

The TkApache configuration file must have this directory explicitly prefixed to it in order for the installation to proceed successfully. You must also supply the server root and configuration parameters with the correct locations for your installation. The installation process is likely to be much improved in future versions.

The interface for TkApache is based on a layered folder/tab dialog box for each part of the configuration.

TkApache is a little less advanced in development than Comanche, but shows promise. It also provides some limited abilities to track the access and error logs as well as the Apache process pool.

LinuxConf

LinuxConf is an all-purpose configuration tool that has gained increasing popularity on the Linux platform and is bundled as standard with several distributions. Modern versions of LinuxConf come with a fairly credible Apache configuration module.

Current releases of LinuxConf in source, binary, and RPM packages are available for most distributions of Linux from http://www.solucorp.qc.ca/linuxconf/.

Webmin

Webmin is a server configuration tool that provides a graphical user interface for configuring different servers such as Apache, FTP server, MySQL database server, Samba server, and many others. It’s Perl-based, so Perl must also be installed to use it. You can download it from http://www.webmin.com/download.html.

Installing Webmin

The Webmin installation comes with both RPM and conventional archive distributions. To install the RPM, use a command line such as the following:

$rpm -i webmin1.100-1.noarch.rpm

The installation program prints a message to the user after the program is successfully installed:

Operating system is SuSE Linux 8.2
webmin #######################################
Webmin install complete. You can now login to https://localhost:10000/

as root with your root password.

Despite the previous messages, Webmin may not yet be running. If the URL isn’t accessible, then Webmin can be started up manually with a command like this:

$ /etc/webmin/start

RPM distributions typically install start and stop scripts, so this will also work on many servers:

$ /etc/rc.d/init.d/webmin start

For the example SuSE server, here you would instead use either of these:

$ /etc/init.d/webmin start
$ rcwebmin start

Accessing Webmin

Because Webmin is a Web-based administration tool, it must be accessed using a browser. By default the access URL is the local host, port 1000, in order not to conflict with the Apache server (or servers) that it’s going to configure. The first time Webmin is accessed, it’ll present the login screen shown in Figure 2-9.

Use the root username and password to log in and access Webmin’s main page, as shown in Figure 2-10.

This page provides options to configure Webmin itself. Select Servers and then Apache Server to access the Apache configuration module. Webmin will perform a scan to detect the installed Apache instance and then offer to manage it and any available dynamic modules. Once you pass this step, you get to the Apache configuration screen.


Figure 2-9. Webmin login page


Figure 2-10. Webmin main page

Webmin understands both Apache 1.3 and Apache 2 configurations. For Apache 2 the Apache configuration screen looks like this, notably including a Filters configuration option, as shown in Figure 2-11.

Apache 1.3 instead produces the screen shown in Figure 2-12.

 
Figure 2-11. Webmin Apache 2 main page


Figure 2-12. Webmin Apache 1.3 main page

Select the Module Config tab to configure the Webmin Apache module. Here the locations that the module uses can be changed, if necessary, to point to a different Apache installation. Change just the server root and set the other options to Automatic to have Webmin pick up most locations automatically, as shown in Figure 2-13.


Figure 2-13. Apache module configuration

After setting the basic parameters on this screen, Webmin will return to the main Apache configuration page where you can customize the chosen Apache’s configuration. Webmin initially shows you a list of all the virtual servers configured on the server, along with both the main (nonvirtual) server and the configuration details that you may modify. You may also add a new virtual server or remove an existing one.

The following global configuration options are provided by Webmin:

  • Processes and Limits: This allows you to set limits for various server options such as the maximum number of concurrent requests, the maximum number of headers in a request, and so on.

  • Networking and Addresses: Here you can set the default IP addresses and the ports to which Apache listens. You can also set the request and keep-alive time-out values and the maximum requests per child.

  • Apache Modules: This option allows you to choose which dynamic modules are included in the server.

  • MIME Types:Here you can configure the location of the MIME-type definitions file, which usually points to conf/mime types in the server root. You can also view the list of MIME-type definitions here.

  • User and Group (Apache 2): Here you can configure the user and group that Apache runs under. If the perchild MPM is in user, the user and group of each virtual host can also be set here.

  • M iscellaneous: This allows you to configure the core dump file, server PID file, server lock file, shared memory scoreboard file, and so on.

  • CGI Programs (Apache 1.3): This allows various CGI program configurations such as CGI script log, maximum CGI log size, and so on.

  • Filters (Apache 2): This allows filter configurations to be added, removed, or altered.

  • Per-Directory Options Files: Here you can set per-directory option files (such as .htaccess) for any selected directory.

  • Reconfigure Known Modules: This provides lists of all the modules whose configuration is known and supported by the Webmin interface and that are currently enabled. Individual module configurations may be carried out from here.

  • Edit Defined Parameters: This allows you to edit the definitions passed with the -D option while starting. This is covered in detail in Chapter 4.

Lower on the page is a form to add, remove, and modify virtual hosts, as Figure 2-14 demonstrates.

 
Figure 2-14. Virtual host configuration form

ApacheConf

ApacheConf is a configuration tool installed with Red Hat Linux if you choose to install the version of Apache bundled with the operating system. It can also be found as an RPM on http://www.rpmfind.net and elsewhere. (Confusingly, it’s also the name of a number of different configuration tools available on the Internet, including a commercial Windows offering.)

Similar tools exist for all Linux and BSD platforms and are roughly similar in capabilities. You may also install the configuration tool subsequently by locating the apacheconf package and installing it with this:

# rpm -ivh apacheconf-0.8.1-1.noarch.rpm

ApacheConf provides a simple graphical user interface to configure Apache. It’s suited only to simple configurations as it has a fairly restricted set of features and may not read hand-modified configuration files, as shown in Figure 2-15.

 
Figure 2-15.  ApacheConf main screen

This figure shows the configuration dialog box for basic settings such as the server name and administrator’s email address. It also lists which addresses and ports Apache is configured to listen to—all addresses on port 80, in this example. You can add to or modify these addresses before going on to configure virtual hosts, which you do by selecting the Virtual Hosts tab. This produces a screen like that shown in Figure 2-16.


Figure 2-16.  ApacheConf virtual host selection

If you click the Add button to configure a new virtual host, you get to the screen shown in Figure 2-17. Here you can enter the specific details for this virtual host.


Figure 2-17.  ApacheConf virtual host configuration

Other Configuration Tools

None of the GUI configuration tools for Apache go much beyond the configuration file itself, with the notable exception of Webmin, which is a generic configuration tool that happens to support Apache reasonably well. In addition to the tools mentioned here, there are a diverse number of other options of varying quality and usefulness.

One popular and capable package for user- and host-based access configuration is user_manage, available from http://stein.chl.org/~lstein/user_manage/. This is an HTML-based interface implemented in a Perl CGI script and manages user and group account details in text, .dbm and .db files, and SQL databases. It provides for both administrator-level management as well as permitting users to alter their own details and change their password.

user_manage is ideally suited to remote administration, but it should be set up carefully according to the installation instructions for reasons of security.


Text Files Don’t Bite

Having outlined a few of the options for graphical configuration, it’s worth pointing out that editing configuration files by hand is not all that hard, and for many purposes it’s easier because it doesn’t require extra software. It also enables you to control the exact layout of the file or files, if you choose to split them up. You can easily edit a text file over a simple telnet (or preferably encrypted with ssh) connection. Complex configurations involving large numbers of virtual hosts or automated configuration generation also benefit from the text file approach. As many of the virtual host examples in Chapter 7 will demonstrate, there are many practical configuration techniques that are either hard or simply impossible to implement with a GUI editor. When using a GUI tool, be aware that it may limit your options in circumstances where Apache is actually more than capable.


Summary

In this chapter, you have seen how to install Apache from both a binary distribution and a prebuilt package, with special attention paid to Windows installer files and Linux RPM packages. You have carried out the initial configuration of the server, started it up, and tested it to prove that it’s up and running.

You have also examined Apache’s various means of invocation, including its command line options and the apachectl script. You have looked at how to start up multiple Apache servers and directing the server to use a different file for its configuration, as well as supplying configuration directives on the command line.

Finally, you discussed some of the graphical configuration tools for Apache, summarized their features, and considered some of the reasons you might choose to forego a GUI tool and configure Apache by hand.

Now that you have Apache on your server, you can start to worry about the next steps in configuration, which you start in Chapter 4. You may also at this point decide to customize the makeup of the server by building it from source—that’s the subject of the next chapter.  

This chapter is from Pro Apache by Peter Wainwright. (Apress, 2004, ISBN: 1590593006). Check it out at your favorite bookstore today. Buy this book now.

[gp-comments width="770" linklove="off" ]

chat