Your Daily Source for Apache News and Information

By:
Copyright © 2000 by Ken Coar. All rights reserved. Limited rights granted to Internet.Com.

Introduction

Hopefully you know something about Web servers in general, and the Apache Web server in particular, or else you wouldn't be reading this page. This article isn't intended to give background on what Apache is nor why you should use it, but how to get going with it once the decision has been made. In other words, simply how to download it, and install it, and turn it on.

I should make it very clear right away that this article is about the latest released version of the server, Apache 1.3. It is not about the still-under-development 2.0 version. You'll have to wait for another article for that. :-)

The setting up of an Apache Web server falls naturally into a number of steps. Unfortunately, the steps differ slightly depending upon whether you're going to be using a binary distribution or if you're using Windows; the steps that may not apply are marked as 'optional' below.

1. Download the software
2. [optional] Build the software (unless you downloaded a binary distribution)
3. Stop any currently-running Apache server
4. [optional] De-install any existing Apache package (Windows only)
5. Install the new Apache software
6. Make sure the configuration is correct
7. Start the Web server
8. Customise your content

Assumptions and Conventions

Before getting into the nitty-gritty, let's set up a little background. A lot of what follows is going to refer to files and directories and commands and locations and things like that, so let us be sure we both understand them to mean the same things.

An Apache server has at least two important directory trees, and possibly three. The first is where the server software lives (called the ServerRoot), the second is where the documents that get served to network visitors live (called the DocumentRoot), and the third is the home of the software sources (called the source tree). In many cases these all live in close proximity; if you install Apache from a package, the DocumentRoot might actually be a subdirectory under the ServerRoot, for instance.

For the sake of clarity, the rest of this article makes the following assaumptions about where things are on your system:

These locations will be used by all of the cd and other shell commands in this article.

Some formatting conventions used in examples in this article:

• 'normal text' represents output from the computer.
• bold text indicates what you need to type. Unbolded text shows output from the computer.
• bold italicised text represents something you need to replace with your own value; for example, when following the steps in an example, when I came to "cd /home/username", I would type "/home/coar" instead.
• normal italicised text in brackets ('[' and ']') is used to represent commentary, such as "[lots of output here]".
• In order to make long lines in this article fit within the width of your window, they may be arbitrarily wrapped. This is signified by one line ending with a slosh ('\') and the next line beginning with an open broket ('>'). For example:

      % this is the first part of the line \
      > and this is the second
      

  You can run these split-up pieces together into the single line they represent, or, on Unix, you can actually type the '\' and hit Enter and type in the next portion when the system prompts you with the '>'. (This convention was chosen because it matches this Unix behaviour, and most Apache servers are run on Unix.)

Platforms

The Apache Web server runs on almost every Unix-like system in the world, and quite a few systems that don't resemble Unix at all. It's supported on the server platforms of Microsoft Windows (such as Windows NT and Windows 2000), and runs--but isn't supported--on the Windows 95 and Windows 98 platforms.

This breadth of support means that, whatever you're running, you can probably use Apache on it. If you want to use Apache on something that isn't clearly Windows nor Unix, or you are otherwise unsure, check the resources in the 'Going Further' section of this article for places to inquire on how to proceed.

Prebuilt Packages--or Building Your Own

Since Apache is developed as an Open Source' project, you have a choice of either using a package that someone else prepared for your platform--if anyone has--or of downloading the source and building it yourself from the ground up. Of course, with the dozens of available platforms, there are sure to be some to which the Apache developers themselves don't have access, and so your options may actually be reduced to building the Apache Web server from scratch yourself.

Since different redistributors and repackagers have their own ideas about where to put files, the locations identified in the assumptions section may not be valid if you installed Apache from such a package. If that's the case, you'll just need to make the appropriate translations between the locations in this article and those on your system.

Downloading the Software

The latest and greatest released version of Apache is always available from the Apache Web site in the /dist/ location: <URL:http://www.apache.org/dist/>. If you look at that page, one of the first things you'll see is a link to a way of finding a distribution point, or mirror, that's closer to you.

Exactly how you download the software depends on your Web browser, but it may be as simple as holding down the 'Shift' key and clicking on the name of the file.

There are two types of packages you can download from the Apache site:

1. Packages containing only the Web server source code, and
2. Packages containing the source code and a pre-built binary.

The source-only packages are located in the top directory of the URL listed above; the prebuilt binaries are located in subdirectories underneath the /binaries/ folder.

Package naming

The Apache packages are named according to a formula:

• The word 'apache', followed by
• the three-component version number (e.g., '1.3.12'), followed by
• optional suffix information (such as 'win32' to stress that the package is for Windows, or 'i386-whatever-linux2', which indicates a package built for Linux systems running on x86 hardware with a 2.* kernel version), followed by
• package-type information (such as '.exe', or '.tar.gz')

A package that is missing the optional suffix information, such as 'apache_1.3.12.tar.gz', is a source-only package. If you download such you will have to compile and build the server yourself from scratch. Packages that include the optional suffix have been pre-built for the named platform, but they also include the source code in case you want or need to rebuild the server yourself.

The version number is very important. It's read from left to right, and each component is treated as a number in its own right. So the package named 'apache_1.3.12.tar.gz' contains version '1.3.12', which is pronounced 'one point three point twelve,' and is more recent than '1.3.9'.

Signature Files

In addition to the packages themselves, there are frequently accompanying signature files. These are used to verify that the packages were really built by the Apache developers, and have the same name as the package with either a '.asc' or '.md5' suffix attached. To use these, you will need either something that can read and verify PGP signatures (such as PGP itself), or a tool that can generate MD5 checksums.

The MD5 checksum, if one is provided for the package, is easier to check. You simply use your MD5 checksumming tool to generate a checksum of the package, and then you compare that value with what's in the .md5 file. For example:

    % md5sum apache_1.3.12.tar.gz
    de3ccff384b0d4ab94c3251cb85d49d2  apache_1.3.12.tar.gz
    % cat apache_1.3.12.tar.gz.md5
    MD5 (apache_1.3.12.tar.gz) = de3ccff384b0d4ab94c3251cb85d49d2
  

The other signature type, which is replacing MD5 in the Apache distribution process, is a PGP signature. In order to check it, you will need to have loaded the PGP keys of the Apache developers (available on the Apache site at <URL:http://www.apache.org/dist/KEYS>) into your PGP tool. Verify the signature on the file using your PGP tool; for instance, like this:

    % pgpv apache_1.3.12.tar.gz.asc
    This signature applies to another message
    File to check signature against [apache_1.3.12.tar.gz]: [hit Enter]
    Good signature made 2000-02-23 23:14 GMT by key:
       768 bits, Key ID A0BB71C1, Created 1997-06-03
       "Jim Jagielski "

    WARNING: The signing key is not trusted to belong to:
    Jim Jagielski 
  

(The last portion of the message simply means that you haven't marked Jim's key on your keyring as definitely being Jim's.)

PGP signatures provide more information about an Apache package. They identify whom of the Apache developers approved it, when, and that the package you downloaded is the same as the one the developer approved.

If either of the signatures don't match (that is, PGP reports an error or the MD5 checksum you generated is different from the one in the .md5 file), please report the problem to <>.

The CHANGES file

Also in the main distribution directory are some files with names starting with "CHANGES". These describe all the modifications and bug-fixes that have been applied to the latest version found in the main distribution directory. If you're upgrading from an earlier version of Apache, reading through this file can be enlightening and informative.

Building the Software from Source

If you download an Apache package, you get the source code -- even if you downloaded a binary distribution. This means that you can always rebuild the Apache binary if you need to (and have the appropriate tools installed). The exact method of rebuilding depends on your platform, but there are really only two different platforms for this process: Windows and Unix (or Unix-like).

[Re]Building Apache on Unix

If you want or need to build Apache from source, you can use the following commands as a quick-start. You should download the latest released version of the Apache tarball and unpack it into a working directory. The top-level directory will then be ./apache-1.3, which matches the assumptions described earlier.

    % cd ./apache-1.3
    % env CC=gcc CFLAGS="-O2 -Wall" \
    > ./configure --enable-shared=max --enable-module=most \
    > --with-layout=Apache --prefix=/usr/local/web/apache \
    > --with-port=80
    Configuring for Apache, Version 1.3.13-dev
     + using installation path layout: Apache (config.layout)
    Creating Makefile
    Creating Configuration.apaci in src
        [more configuration output]
    % make
        [lots of compilation output]
    % /usr/local/web/apache/bin/apachectl start
    % make install
        [lots of output describing file placement]
  

If you didn't encounter any errors, you should now have a working Apache installation in the location that matches the assumptions described earlier. It's been built to work with dynamic modules rather than static ones for maximum flexibility. The next step is to start the server.

[Re]Building Apache on Windows

Unfortunately, this is a pretty esoteric area. Almost every flavour of Unix in the world comes with the tools necessary to turn source code into something you can run; but the same is not true of Windows. All development packages on the Windows platforms are add-ons, and there are a few possibilities. When the Apache developers began working on the Windows version of Apache, they decided to standardise on a single add-on development tool: Visual Studio C++ version 5.0 from Microsoft. So if you don't have a Windows development package, you can't rebuild the Apache software. If you have a different one than Visual Studio, how to get it to work with the Apache sources is a problem you'll have to solve yourself.

If, however, you have Visual C++ on your Windows box, then you can rebuild the Apache Web server from source either from a command line in a DOS window, such as:

    C:\>cd "\Program Files\Apache Group\Apache\src"
    C:\Program Files\Apache Group\APACHE\src>nmake -f Makefile.nt target
  

The target can be one of the following:

installr

Build a fully-functional Apache.exe executable.

installd

Same as installr, except that the executable is built for use with a debugger.

_cleanr

Clean up the directory tree in preparation for doing a installr build.

_cleand

Clean up the directory tree in preparation for doing a installd build.

Beyond that you're on your own, as building Apache on Windows is not exactly a 'getting started' topic! You can find more (possibly outdated) information on the Apache site at <URL:http://www.apache.org/docs/windows.html>.

Shutting Down Apache

On Unix systems, you use the apachectl script to manage the Web server. This script typically lives in the bin/ subdirectory under the ServerRoot. If Apache has been installed according to the assumptions made by this article, that means you should shut the server down with a command like this:

    # /usr/local/web/apache/bin/apachectl stop
  

If this doesn't work, the alternative is to locate the master httpd process and send it a SIGTERM signal. However, if apachectl failed, you should check with someone about how to proceed -- not that there's any danger, just that it can be confusing unless you're familiar with Unix and process management tools.

On Windows, you can either stop a running Apache server process by choosing the Stop Apache item from the Apache Web Server programme group, or by issuing the following in a DOS window:

    C:\Program Files\Apache Group\APACHE>apache -k stop
  

De-installing Apache on Windows

If you have previously installed the Apache Web server on your Windows system, it is a good idea -- a very good idea, in fact -- to uninstall it before upgrading, or even re-installing the same version.

To deinstall Apache from your system, choose the Add/Remove Programs control panel item. You should be able to get this from the task bar by choosing Start->Settings->Control Panel and double-clicking on the Add/Remove Programs icon.

Apache should be one of the applications available to remove. Select it, and click on the Add/Remove... button.

Installing the Apache Server

How you install the Apache Web server software depends on your platform and the type of package you downloaded. For example, the Windows installation is a simple point-and-click operation; for Unix it can be a little more complex.

Installing a Linux RPM

This is perhaps the simplest option of all. Once you've acquired the RPM file (which you have to get from some other location than the Apache distribution site; the Apache Software Foundation doesn't distribute RPM files), you can just 'make it so' by being logged in as root and issuing the following command from the directory where the Apache RPM file is located:

    # rpm -Uvh apache*
  

Of course, this may or may not install the source tree, and probably won't put files into the same directories as assumed by this article -- you'll need to find out the differences and make adjustments.

Installing a Pre-built Package on Unix

After you unpack the binary package, there should be a file named install-bindist.sh in the top-level directory. To install the Apache package, execute this script with a single parameter: the location of the ServerRoot you want it to create. For example:

    # cd /tmp
    # zcat apache_1.3.12-i386-whatever-linux2.tar.gz | tar xf -
    # cd apache_1.3.12
    # ./install-bindist.sh /usr/local/web/apache
  

This should install the binary and documentation as follows:

In other words, with the exception of the source code, the script will install the Apache elements in the locations mentioned by the assumptions at the beginning of this article.

The source directory in the above example is still where you unpacked it, at /tmp/apache_1.3.12/src/.

Installing on Windows

Installing the prebuilt package on Windows is a snap. Once you've downloaded it into some working directory (such as C:\TEMP), just double-click on the package and away you go. By default, it will use the directories mentioned in the assumptions section of this article (that's why I assumed those particular locations), but you can change these during the installation.

Checking the Configuration

By this point you should have an Apache binary application on your system, just rarin' to go and start serving files. Before you actually turn it loose, though, you should make sure you've dotted all the eyes and crossed all the teas.

Verifying the ServerName

For a Windows installation, edit the conf\httpd.conf file under your ServerRoot directory. (Use whatever editor you like, as long as it creates normal text files as output; Notepad works just fine.) Look through the file for the word 'ServerName' at the beginning of a line, and make sure that the second word on that line is a valid hostname or IP address (such as localhost, foo.bar.com, or 127.0.0.1). If it isn't, Apache won't start.

For the very best results, you should verify that the ServerName directive in your httpd.conf file matches your system's actual fully-qualified domain name. If your system is named "www.foo.bar.com", then that's what you should put on the ServerName directive line.

If your system is running Unix, you can find its fully-qualified name by simply typing "hostname" at the shell prompt. The result should look something like this:

    % hostname
    www.foo.bar.com
  

If it only displays a partial name (like "www"), you need to find out the correct domain name and put the two together.

If you're running Windows NT, you can find out your fully-qualified system name by going to the Start->Settings->Control Panel menu choice and double-clicking on the Network icon. Choose the Protocols tab, select TCP/IP Protocol, and click the Properties... button. Finally, choose the DNS tab. Your fully-qualified host name is the Host Name put together with the Domain value, separated by a dot.

Validating the Configuration Files

The last thing to do before starting up your new Apache installation is to make sure it's configured properly. On a Unix system, you do this with the following command:

    # /usr/local/web/apache/bin/apachectl configtest
    Syntax OK
  

On Windows, you can do this by typing the following command in a DOS window:

    C:\Program Files\Apache Group\APACHE>apache -t
    c:/program files/apache group/apache/conf/httpd.conf: Syntax OK
  

If there's anything syntactically wrong with your configuration files, you'll get an error message describing the problem. But from a vanilla installation everything should be healthy.

Starting Apache

Once the Apache software is ready to go, the next step is to actually activate it. The means of doing this differs depending upon your platform and how you installed it; for instance, if you installed an RPM package, there's a good chance that the installation automatically started the server as well.

Starting Apache on Unix

Once you've done the make install, you're ready to actually start the server running. You do this on Unix with the following command:

    % /usr/local/web/apache/bin/apachectl start
    /usr/local/web/apache/bin/apachectl start: httpd started
  

Starting Apache on Windows

There are two ways to start Apache on the Windows platform. One is to select the Start->Programs->Apache Web Server->Start Apache menu item, and the other is to do it in a DOS window:

    C:\Program Files\Apache Group\APACHE>apache -k start
  

Actually, as a third method you can go into the services control panel and start the Apache servce, if you first select the Start->Programs->Apache Web Server->Install Apache&nsbp;as a service option first -- but I suggest that you leave that option for later, after you're assured that your server is running properly.

Customising Your Content

The very most important thing you should do before you turn the server on and let people start accessing it is:

CHANGE THE MAIN PAGE!

By default, following an Apache installation the main page in your DocumentRoot directory will say something reassuring -- to you -- about the success of the installation. It's sort of like the ReadMe.txt file you get to see after installing an application on Windows; it's just there to a) give the installer (you) a warm, fuzzy feeling that everything worked, and b) provide something other than a list of files to anyone who hits the site before it's ready. Unfortunately, there are a lot of people on the Internet that don't understand how the Web works, or the whole idea of clients and servers, and if they see that page saying 'Apache has been successfully installed!' they're going to think it's beein installed on their desktop system. Or, if you just upgraded an existing Web site, they're going to think the Apache Software Foundation has just invaded you and taken over your site.

So please, please, please replace the default index.html* file (or files) with something of your own, perhaps saying something like "Welcome to Joe's Web Pages. They're off getting dusted and cleaned right now, but they'll be back soon. Please come back in a couple of days!" Or something like that.

One way to do this, of course, is to modify the index.html.en file itself, since this is the one Apache will display by default. Another way is to create another directory somewhere, such as /usr/local/web/apache/realdocs (or C:\Progam Files\Apache Group\Apache\realdocs, if you're using Windows), put your own content files in it, and change the DocumentRoot line in your httpd.conf file to point to it. You'll need to change all occurences in the config file of the old htdocs directory to your new realdocs one, and restart the server after saving the file, but this is probably the cleaner solution.

Testing Your Installation

If you didn't get any errors when you started Apache, hopefully that means it's running. Try it out; use a browser to access the default page: <URL:http://localhost/>. You should see a page declaiming that the installation was a success. If you don't, make a note of what you see instead, and the contents of the error log under the ServerRoot location, in the logs subdirectory. It's called 'error_log' on Unix, but 'error.log' on Windows. With that information, go search the Apache FAQ or other resources listed under Going Further. If all else fails, you can , but please try to find a ready-made answer elsewhere first!

Reloading After Changes

Whevever you make changes to the server configuration files (such as httpd.conf, they won't take effect until the server is restarted and reloaded. On Unix, the command to do this is:

    # /usr/local/web/apache/bin/apachectl graceful
  

On Windows, the equivalent command (run in a DOS window) is:

    C:\Program Files\Apache Group\APACHE>apache -k restart
  

Going Further

Once you've got your Apache Web server up and running, the first hurdle has been surmounted. Now you can move on to exploring its capabilities and features. Here are some pointers to resources for further investigation:

• The main Apache Web site, of course: <URL:http://www.apache.org/>
The documentation for Apache and its modules: <URL:http://www.apache.org/docs/>
• The canonical email response page: <URL:http://www.apache.org/foundation/email-response.html>
  (This page is normally used to respond to email requests for support, but there are lots of good resources listed on it.)

Conclusion

If you want to get the Apache Web server up and running, it's really quite simple; most of the hard part has been pre-configured for you. Follow the instructions here and you should be able to start serving simple pages in a matter of minutes.

Got a Topic You Want Covered?

If you have a particular Apache-related topic that you'd like covered in a future article in this column, please let me know; drop me an email at <>. I do read and answer my email, usually within a few hours (although a few days may pass if I'm travelling or my mail volume is 'way up). If I don't respond within what seems to be a reasonable amount of time, feel free to ping me again.

About the Author

Ken Coar is a member of the Apache Group and a director and vice president of the Apache Software Foundation. He is also a core member of the Jikes open-source Java compiler project, a contributor to the PHP project, the author of Apache Server for Dummies, and a contributing author to Apache Server Unleashed. He can be reached via email at <>.

All times are recorded in UTC. Linux is a trademark of Linus Torvalds. Powered by Linux 2.4, Apache 1.3, and PHP 4 Copyright 2002 INT Media Group, Incorporated All Rights Reserved. Legal Notices,  Licensing, Reprints, & Permissions,  Privacy Policy.