how-to

Set Up an Apache Web Server

by Adam M. Donahue
<adam@donahueinc.net>

Adam is owner and chief technologist of Donahue Consulting, a consulting firm in Manhattan.

This How-To describes how to install and configure an Apache Web server. It also includes pointers to resources on the myriad options that this Web server offers the system administrator.

As of this writing, Apache is the most popular Web server on the Internet[1]. Part of Apache's appeal is the wealth of add-ons and extensions available for the server. These are referred to as "modules." The core Web server is rather useless by itself. Thus, the basic distribution includes what are considered the "essential" modules: those handling access control and authentication, for example, as well as modules that activate CGI awareness, aliases, server-side includes, and logging. The breadth of modules available means you can usually can find the solution to a particular problem, even something highly out of the ordinary. (A searchable database of modules is available at <http://modules.apache.org>.) Though even a brief explanation of each module is outside the scope of this How-To, we will take a look at how to activate individual modules after the initial configuration. A need for additional functionality will no doubt arise as new challenges present themselves to you.

Let's start building the basic server. You will need:

• a UNIX machine, built (and properly secured). Apache is available for NT, but we will focus on the UNIX flavors here.
• root privileges if you wish to install the server in a standard location, as well as use the preassigned HTTP port.
• working tools, in your path:

  = sh

  = gzip

  = tar

  = C compiler

  = make

• Perl (version 5.004 or greater) is highly recommended; some of the utilities that come with Apache require it. You'll also find it difficult to run many existing CGI-enabled programs without Perl. It has become the de facto language of the Web.

Steps
For most of this installation, you should be the superuser. However, much of this is applicable to a nonprivileged user working from his home directory. I will assume you are installing the server on a machine meant to act as a dedicated Web server, and this requires access to privileged port numbers and nonpublic directories.

1. Obtain server software.

Apache has an excellent track record of reliable releases. You should always download the latest production source release. As of this writing, that is version 1.3.6. A few changes were made to the installation process as of this version, so be sure to use it or — by the time this issue of ;login: finds its way into your mailbox — a more recent release.

If you've got Lynx, a quick "source dump" will grab Apache. Run this from a scratch directory:

   % lynx -source http://www.apache.org/dist/apache_1.3.6.tar.gz \
          >apache_1.3.6.tar.gz

Note that the Apache Group also provides binary distributions for an array of platforms. Unfortunately, these lag behind the most up-to-date versions by two or three minor release numbers. It's a better idea to download and compile the source yourself, as we'll do here. If you download a binary and later wish to add a new module, you'll need to recompile. So you might as well compile from the get-go. Of course, if you do not have access to a compiler, then the binary version is your only alternative.

Before continuing, become the superuser.

2. Create Web user and group.

It's a good idea to create an underprivileged user and group that you can use to run the server. This has to do with security. Files are read by — and CGI programs executed as — the Web-server process owner. If this owner is root, you leave yourself open to misconfiguration vulnerabilities. An incorrectly written CGI-based program, for example, could allow outsiders to issue commands on your system as superuser! By using an underprivileged user you avoid many of these types of problems.

I use the username httpd and the group web on my machines, but it isn't important which names you choose. Make sure the user does not have access to any privileged files. In addition, set the Web user's shell to /bin/false so no one can log in as that user. (/bin/false is a standard UNIX utility that does nothing but return a false value to the caller; any user logging in with it as her shell will immediately be logged back out.) The home-directory setting also is not relevant, though for consistency's sake you may wish to set this to the base directory of the Web-server software.

(How to create a user for the various UNIX platforms is outside the scope of this How-To. I'll assume you've created the necessary user. Also note that Web security is a large issue that involves much more than simply creating a special httpd user. I recommend Garfinkel and Spafford[2] and Rubin[3] for more information on Web security.)

3. Decide on location of server source code.

You'll be unpacking the Apache source. This tree contains the code needed for the core server, as well as subdirectories for each major module. Later, when you add new modules, you can simply "attach" them right into this tree, recompile Apache, and reinstall the binary. I find it easier to manage my production server by keeping the source tree completely separate from the installation tree. For example, for many installations I use /usr/local/src as the base directory of the source tree, and /usr/local/web or /usr/local/apache as the installation's base directory. Whatever you decide, move the distribution tar file to the desired source directory before continuing on to the next step:

   # mv apache_1.3.6.tar.gz /usr/local/src

Then change to that directory:

   # cd /usr/local/src

4. Extract Apache source code.

We'll now extract the source from the tar file. At this point you should consider the amount of disk space required for the server source. (This is different from that required for the fully installed server, which is discussed below.) The Apache distribution is now at 1.3MB. The extracted source tree is about 7.5MB in size. You should think about leaving an additional 10MB of space on the source partition dedicated to Apache. This will allow you to add additional modules and options directly into the Apache source tree later on. Apache upgrades occur frequently. In case you want to keep each upgrade in its own directory (e.g., apache_1.3.3, apache_1.3.4, and so forth), make accommodations for about 20MB of space per distribution. The bottom line: always leave room for growth.

Make sure you're in the root of the source directory (for example, /usr/local/src), and execute:

   # gzip -dc apache_1.3.6.tar.gz | tar xfv -

This will create a subdirectory, apache_1.3.6, where 1.3.6 is the release number. Now move to that directory and get ready to compile:

   # cd apache_1.3.6

5. Configure compilation options.

Apache comes with a autoconfig-style configure program that allows you to activate and/or remove modules and specify other configuration settings. The main thing you need to consider at this stage is where you want your production server to go and how much space this server will require. A production server typically includes both static and dynamic files. The static files include the server binary executable, other binary utilities, and (in general) the configuration files. The dynamic files include your Web content and log files. The base Apache installation is around 2.5MB. You should allocate at least twice that much space on your installation partition. The space required for your Web documents and log files is highly dependent on your particular situation. The good news is that Apache lets you configure it to serve documents from (and write log files to) any directory in your directory tree (as well as other places, like database files). That means that at this point you don't need to worry about whether you have enough space on your installation partition to hold megabytes of content. You can dedicate additional partitions to content later, flexibly and easily, through aliases or other mechanisms. The same goes with log files. The default log-file location can be changed to whatever you deem fit at any time.

As I mentioned, I typically use /usr/local/apache (which the Apache Group recommends) as the server installation location. With this base directory in mind, do the following:

   # ./configure --prefix=/usr/local/apache

The --prefix is one of the few options you need to concern yourself with at this point. It's used to set the base installation directory of the server. Later, when we run an install, all the necessary files for this particular server instance will be copied to that directory. This makes it easy to compile several servers from the same source tree, some for production, some for testing. You need only run configure again with a new prefix and rerun the install. Any other existing installations will not be affected.

Running configure results in a series of messages explaining the compiler options it's setting, as well as the makefiles it is generating. When configure has exited, you are now ready to compile:

   # make

Now install the files needed to run the server into the appropriate installation directory.

   # make -n install

The -n switch to make lets you see what that invocation of make would do without having it actually do it. Take this opportunity to ensure that the install paths check out and that any of the utilities used during the install are referenced in their proper locations.

If everything looks right, do the real installation:

   # make install

After running this, a Web-server instance has been installed in the directory specified in the --prefix option above. The following tree is what results (off of the server installation root):

conf/     - configuration file
htdocs/   - web pages
cgi-bin/  - CGI-based programs
bin/      - server executable and utilities
logs/     - server logs
icons/    - icons for directory listings
man/      - man pages
include/  - include files

(Note that as of 1.3.4, several different directory layouts are possible. You can configure this with the --with-layout option to the configure program. I will assume you stuck with the default for this How-To. Those who wish to explore other layout options should take a look at the config.layout file that comes with the distribution.)

Before continuing, change the ownership of these files as appropriate. You may wish to leave them owned by root, though your Web documents will generally be maintained by you or a group of people, so you might want different ownership settings for them to reflect this. The main thing to remember is that the Web server user must be able to READ these files in order to serve them up on the Web.

The main configuration file for Apache is located in the conf/ directory and is known as httpd.conf. In prior versions of Apache, there were in fact two additional files, srm.conf and access.conf. Most people found maintaining the three files a bit tedious. Also, which directives belonged in each of the three files was hazy at best. As of 1.3.4 the recommended setup is to use a single file and, as you might expect, this is the default.

httpd.conf as provided with the Apache distribution is usually properly configured as part of the build and installation process. If you plan on using port 80 as your server port — which is highly recommended, as that's the port assigned by IANA — then you're practically ready to launch your server at this point. There are a couple of things you will first need to change in httpd.conf. But before that you should know a little about how Apache configuration works.

Apache configuration files are made up of directives. There are two directive styles: single-line directives and container directives. Single-line directives are lines consisting of a directive name followed by one or more arguments. For example, to configure the root directory for your Web pages, you use the DocumentRoot directive:

   DocumentRoot /usr/local/apache/htdocs

Other single-line directives that you should be aware of include:

   ServerRoot - the path to your installation directory base
   Listen     - which IP addresses and ports to listen on
   User       - the user the web server is running as
   Group      - the group the web server is running as

DocumentRoot, ServerRoot, and Listen are set up correctly as part of the installation process. The installer, however, does not know about your Web-server user and group. Thus the latter two directives above need to be updated. Move to the configuration directory and edit httpd.conf using your favorite text editor:

   # cd /usr/local/apache/conf
   # vi httpd.conf

Change the User and Group directives to read:

   User httpd
   Group web

or whatever you decided to call your Web-server user and group. (The order of the directives is not important; notice that the User and Group directives are already present, however, so you should simply edit their existing values.)

The other type of directive is what I call a "container" directive. It resembles an HTML tag set, with a start tag and a corresponding close tag. The most common use of this type of directive is to configure options on a directory-by-directory basis. A typical entry looks like:

   <Directory /usr/local/apache/htdocs>
      Options FollowSymLinks ExecCGI
      AddHandler cgi-script .cgi
   </Directory>

Note how the directive name, in this example Directory, is located inside less-than/greater-than signs. It can take options that go within these signs as well. There is also a corresponding close tag for this directive. Inside, we put options that are relevant to the parent directive. For Directory, this means options that apply to that directory. Other container directives include if-like statements and virtual-host configurations.

You do not need to edit any of these directives for the basic server installation.

6. Start the server.

Move to the server root directory and type:

   # bin/apachectl start

apachectl is an included utility that acts as a front end to the server executable, which is known as httpd. It acts similarly to the SVR4 init.d scripts. If all went well, you should be able to access your host with a regular Web browser. Open up to the URL http://hostname/ and you'll find a document included with the distribution that says, "It worked." If you see this message, your server is running successfully.

7. Clean up the document root.

Inside htdocs/ is a series of pages that ships by default with the Apache distribution. These pages include the welcome message you just viewed and a copy of the Apache manual. You don't need either since these files are directly available from the Apache Group Web site[4]. I usually get rid of them in order to start with a fresh slate:

   # cd /usr/local/apache/htdocs
   # ls apache_pb.gif index.html manual
   # rm -rf manual index.html apache_pb.gif

Now you can create your own home page:

   # vi index.html

8. Add the server to your machine's start-up configuration.

If you want the server to begin each time you boot up your machine, you need to add the commands necessary to do so to your rc files. If you run a BSD-like machine, add the following line to rc.local:

   /usr/local/apache/bin/apachectl start

(Add error checking as appropriate.)

If you run an SVR4 machine, create a script, say httpd, with the line above and place it in your init.d directory. Make sure it is executable. Then create a symbolic link from the rc directories corresponding to the run levels at which you wish the server to launch automatically. This is usually run levels two and/or three:

   # cd /etc/init.d
   # vi httpd
   # chmod u+x httpd
   # cd /etc/rc2.d
   # ln -s ../init.d/httpd S99httpd

Here is a sample httpd script:

   #! /bin/sh

   #
   WEBBASE=/local/web/apache
     [ -f ${WEBBASE}/bin/httpd ] || exit 0

   # See how we were called.
   case "$1" in
   start)
   echo -n "Starting HTTP daemon: "
   ${WEBBASE}/bin/httpd
     ;;
   stop)
   echo -n "Stopping HTTP daemon: "
   kill -TERM `cat ${WEBBASE}/logs/httpd.pid`
   ;;
   restart|reload)
   kill -USR1 `cat ${WEBBASE}/logs/httpd.pid`
   ;;
   *)
   echo "Usage: httpd {start|stop|restart|reload}"
   exit 1
   esac
   exit 0

Steps 9, 10, 11 (and, inevitably, 12, 13, etc.) are outside the scope of this How-To. Web development is one topic that does not lack resources. I have included a highly biased listing of some of the texts I found handy when first learning Web technologies.

9. Create your Web pages.

See references [5] and [6].

10. Get comfortable with the server logs.

See reference [6].

11. Activate CGI and begin writing CGI scripts.

See references [6] and [7].


References
[1] Netcraft Web Server Survey <http://www.netcraft.co.uk/Survey/>.

[2] Garfinkel, S., and Spafford, G. Web Security and Commerce. O'Reilly & Associates, 1997.

[3] Rubin, Aviel D., et al. Web Security Sourcebook. John Wiley & Company, 1997.

[4] The Apache Group <http://www.apache.org/>.

[5] Musciano, Chuck, et al. HTML: The Definitive Guide. O'Reilly & Associates, 1998.

[6] Spainhour, S., and Quercia, V. Webmaster in a Nutshell: Deluxe Edition. O'Reilly & Associates, 1997.

[7] Wall, Larry, et al. Programming Perl, 2nd ed. O'Reilly & Associates, 1996.