Chapter 1

Chapter 1. Getting Started

1.1 What Does a Web Server Do?
1.2 How Apache Works
1.3 Apache and Networking
1.4 How HTTP Clients Work
1.5 What Happens at the Server End?
1.6 Planning the Apache Installation
1.7 Windows?
1.8 Which Apache?
1.9 Installing Apache
1.10 Building Apache 1.3.X Under Unix
1.11 New Features in Apache v2
1.12 Making and Installing Apache v2 Under Unix
1.13 Apache Under Windows

Apache is the dominant web server on the Internet today, filling a key place in the infrastructure of the Internet. This chapter will explore what web servers do and why you might choose the Apache web server, examine how your web server fits into the rest of your network infrastructure, and conclude by showing you how to install Apache on a variety of different systems.

1.1 What Does a Web Server Do?

The whole business of a web server is to translate a URL either into a filename, and then send that file back over the Internet, or into a program name, and then run that program and send its output back. That is the meat of what it does: all the rest is trimming.

When you fire up your browser and connect to the URL of someone's home page — say the notional http://www.butterthlies.com/ we shall meet later on — you send a message across the Internet to the machine at that address. That machine, you hope, is up and running; its Internet connection is working; and it is ready to receive and act on your message.

URL stands for Uniform Resource Locator. A URL such as http://www.butterthlies.com/ comes in three parts:

<scheme>://<host>/<path>

So, in our example, < scheme> is http, meaning that the browser should use HTTP (Hypertext Transfer Protocol); <host> is www.butterthlies.com ; and <path> is /, traditionally meaning the top page of the host.^[1] The <host> may contain either an IP address or a name, which the browser will then convert to an IP address. Using HTTP 1.1, your browser might send the following request to the computer at that IP address:

GET / HTTP/1.1
Host: www.butterthlies.com

The request arrives at port 80 (the default HTTP port) on the host www.butterthlies.com. The message is again in four parts: a method (an HTTP method, not a URL method), that in this case is GET, but could equally be PUT, POST, DELETE, or CONNECT; the Uniform Resource Identifier (URI) /; the version of the protocol we are using; and a series of headers that modify the request (in this case, a Host header, which is used for name-based virtual hosting: see Chapter 4). It is then up to the web server running on that host to make something of this message.

The host machine may be a whole cluster of hypercomputers costing an oil sheik's ransom or just a humble PC. In either case, it had better be running a web server, a program that listens to the network and accepts and acts on this sort of message.

1.1.1 Criteria for Choosing a Web Server

What do we want a web server to do? It should:

Run fast, so it can cope with a lot of requests using a minimum of hardware.
Support multitasking, so it can deal with more than one request at once and so that the person running it can maintain the data it hands out without having to shut the service down. Multitasking is hard to arrange within a program: the only way to do it properly is to run the server on a multitasking operating system.
Authenticate requesters: some may be entitled to more services than others. When we come to handling money, this feature (see Chapter 11) becomes essential.
Respond to errors in the messages it gets with answers that make sense in the context of what is going on. For instance, if a client requests a page that the server cannot find, the server should respond with a "404" error, which is defined by the HTTP specification to mean "page does not exist."
Negotiate a style and language of response with the requester. For instance, it should — if the people running the server can rise to the challenge — be able to respond in the language of the requester's choice. This ability, of course, can open up your site to a lot more action. There are parts of the world where a response in the wrong language can be a bad thing.
Support a variety of different formats. On a more technical level, a user might want JPEG image files rather than GIF, or TIFF rather than either of those. He might want text in vdi format rather than PostScript.
Be able to run as a proxy server. A proxy server accepts requests for clients, forwards them to the real servers, and then sends the real servers' responses back to the clients. There are two reasons why you might want a proxy server:
- The proxy might be running on the far side of a firewall (see Chapter 11), giving its users access to the Internet.
- The proxy might cache popular pages to save reaccessing them.
Be secure. The Internet world is like the real world, peopled by a lot of lambs and a few wolves.^[2] The aim of a good server is to prevent the wolves from troubling the lambs. The subject of security is so important that we will come back to it several times.

1.1.2 Why Apache?

Apache has more than twice the market share than its next competitor, Microsoft. This is not just because it is freeware and costs nothing. It is also open source,^[3] which means that the source code can be examined by anyone so inclined. If there are errors in it, thousands of pairs of eyes scan it for mistakes. Because of this constant examination by outsiders, it is substantially more reliable^[4] than any commercial software product that can only rely on the scrutiny of a closed list of employees. This is particularly important in the field of security, where apparently trivial mistakes can have horrible consequences.

Anyone is free to take the source code and change it to make Apache do something different. In particular, Apache is extensible through an established technology for writing new Modules (described in more detail in Chapter 20), which many people have used to introduce new features.

Apache suits sites of all sizes and types. You can run a single personal page on it or an enormous site serving millions of regular visitors. You can use it to serve static files over the Web or as a frontend to applications that generate customized responses for visitors. Some developers use Apache as a test-server on their desktops, writing and trying code in a local environment before publishing it to a wider audience. Apache can be an appropriate solution for practically any situation involving the HTTP protocol.

Apache is freeware . The intending user downloads the source code and compiles it (under Unix) or downloads the executable (for Windows) from http://www.apache.org or a suitable mirror site. Although it sounds difficult to download the source code and configure and compile it, it only takes about 20 minutes and is well worth the trouble. Many operating system vendors now bundle appropriate Apache binaries.

The result of Apache's many advantages is clear. There are about 75 web-server software packages on the market. Their relative popularity is charted every month by Netcraft (http://www.netcraft.com). In July 2002, their June survey of active sites, shown in Table 1-1, had found that Apache ran nearly two-thirds of the sites they surveyed (continuing a trend that has been apparent for several years).

Table 1-1. Active sites counted by Netcraft survey, June 2002
Developer	May 2002	Percent	June 2002	Percent
Apache	10411000	65.11	10964734	64.42
Microsoft	4121697	25.78	4243719	24.93
iPlanet	247051	1.55	281681	1.66
Zeus	214498	1.34	227857	1.34

1.2 How Apache Works

Apache is a program that runs under a suitable multitasking operating system. In the examples in this book, the operating systems are Unix and Windows 95/98/2000/Me/NT/..., which we call Win32. There are many others: flavors of Unix, IBM's OS/2, and Novell Netware. Mac OS X has a FreeBSD foundation and ships with Apache.

The Apache binary is called httpd under Unix and apache.exe under Win32 and normally runs in the background.^[5] Each copy of httpd/apache that is started has its attention directed at a web site, which is, for our purposes, a directory. Regardless of operating system, a site directory typically contains four subdirectories:

conf: Contains the configuration file(s), of which httpd.conf is the most important. It is referred to throughout this book as the Config file. It specifies the URLs that will be served.
htdocs: Contains the HTML files to be served up to the site's clients. This directory and those below it, the web space, are accessible to anyone on the Web and therefore pose a severe security risk if used for anything other than public data.
logs: Contains the log data, both of accesses and errors.
cgi-bin: Contains the CGI scripts. These are programs or shell scripts written by or for the webmaster that can be executed by Apache on behalf of its clients. It is most important, for security reasons, that this directory not be in the web space — that is, in .../htdocs or below.

In its idling state, Apache does nothing but listen to the IP addresses specified in its Config file. When a request appears, Apache receives it and analyzes the headers. It then applies the rules it finds in the Config file and takes the appropriate action.

The webmaster's main control over Apache is through the Config file. The webmaster has some 200 directives at her disposal, and most of this book is an account of what these directives do and how to use them to reasonable advantage. The webmaster also has a dozen flags she can use when Apache starts up.

We've quoted most of the formal definitions of the directives directly from the Apache site manual pages because rewriting seemed unlikely to improve them, but very likely to introduce errors. In a few cases, where they had evidently been written by someone who was not a native English speaker, we rearranged the syntax a little. As they stand, they save the reader having to break off and go to the Apache site

1.3 Apache and Networking

At its core, Apache is about communication over networks. Apache uses the TCP/IP protocol as its foundation, providing an implementation of HTTP. Developers who want to use Apache should have at least a foundation understanding of TCP/IP and may need more advanced skills if they need to integrate Apache servers with other network infrastructure like firewalls and proxy servers.

1.3.1 What to Know About TCP/IP

To understand the substance of this book, you need a modest knowledge of what TCP/IP is and what it does. You'll find more than enough information in Craig Hunt and Robert Bruce Thompson's books on TCP/IP,^[6] but what follows is, we think, what is necessary to know for our book's purposes.

TCP/IP (Transmission Control Protocol/Internet Protocol) is a set of protocols enabling computers to talk to each other over networks. The two protocols that give the suite its name are among the most important, but there are many others, and we shall meet some of them later. These protocols are embodied in programs on your computer written by someone or other; it doesn't much matter who. TCP/IP seems unusual among computer standards in that the programs that implement it actually work, and their authors have not tried too much to improve on the original conceptions.

TCP/IP is generally only used where there is a network.^[7] Each computer on a network that wants to use TCP/IP has an IP address, for example, 192.168.123.1.

There are four parts in the address, separated by periods. Each part corresponds to a byte, so the whole address is four bytes long. You will, in consequence, seldom see any of the parts outside the range 0 -255.

Although not required by the protocol, by convention there is a dividing line somewhere inside this number: to the left is the network number and to the right, the host number. Two machines on the same physical network — usually a local area network (LAN) — normally have the same network number and communicate directly using TCP/IP.

How do we know where the dividing line is between network number and host number? The default dividing line used to be determined by the first of the four numbers, but a shortage of addresses required a change to the use of subnet masks. These allow us to further subdivide the network by using more of the bits for the network number and less for the host number. Their correct use is rather technical, so we leave it to the routing experts. (You should not need to know the details of how this works in order to run a host, because the numbers you deal with are assigned to you by your network administrator or are just facts of the Internet.)

Now we can think about how two machines with IP addresses X and Y talk to each other. If X and Y are on the same network and are correctly configured so that they have the same network number and different host numbers, they should be able to fire up TCP/IP and send packets to each other down their local, physical network without any further ado.

If the network numbers are not the same, the packets are sent to a router, a special machine able to find out where the other machine is and deliver the packets to it. This communication may be over the Internet or might occur on your wide area network (WAN). There are several ways computers use IP to communicate. These are two of them:

UDP (User Datagram Protocol): A way to send a single packet from one machine to another. It does not guarantee delivery, and there is no acknowledgment of receipt. DNS uses UDP, as do other applications that manage their own datagrams. Apache doesn't use UDP.
TCP (Transmission Control Protocol): A way to establish communications between two computers. It reliably delivers messages of any size in the order they are sent. This is a better protocol for our purposes.

1.3.2 How Apache Uses TCP/IP

Let's look at a server from the outside. We have a box in which there is a computer, software, and a connection to the outside world — Ethernet or a serial line to a modem, for example. This connection is known as an interface and is known to the world by its IP address. If the box had two interfaces, they would each have an IP address, and these addresses would normally be different. A single interface, on the other hand, may have more than one IP address (see Chapter 3).

Requests arrive on an interface for a number of different services offered by the server using different protocols:

Network News Transfer Protocol (NNTP): news
Simple Mail Transfer Protocol (SMTP): mail
Domain Name Service (DNS)
HTTP: World Wide Web

The server can decide how to handle these different requests because the four-byte IP address that leads the request to its interface is followed by a two-byte port number. Different services attach to different ports:

NNTP: port number 119
SMTP: port number 25
DNS: port number 53
HTTP: port number 80

As the local administrator or webmaster, you can decide to attach any service to any port. Of course, if you decide to step outside convention, you need to make sure that your clients share your thinking. Our concern here is just with HTTP and Apache. Apache, by default, listens to port number 80 because it deals in HTTP business.

Port numbers below 1024 can only be used by the superuser (root, under Unix); this prevents other users from running programs masquerading as standard services, but brings its own problems, as we shall see.

Under Win32 there is currently no security directly related to port numbers and no superuser (at least, not as far as port numbers are concerned).

This basic setup is fine if our machine is providing only one web server to the world. In real life, you may want to host several, many, dozens, or even hundreds of servers, which appear to the world as completely different from each other. This situation was not anticipated by the authors of HTTP 1.0, so handling a number of hosts on one machine has to be done by a kludge, assigning multiple addresses to the same interface and distinguishing the virtual host by its IP address. This technique is known as IP-intensive virtual hosting. Using HTTP 1.1, virtual hosts may be created by assigning multiple names to the same IP address. The browser sends a Host header to say which name it is using.

1.3.3 Apache and Domain Name Servers

In one way the Web is like the telephone system: each site has a number that uniquely identifies it — for instance, 192.168.123.5. In another way it is not: since these numbers are hard to remember, they are automatically linked to domain names — www.amazon.com, for instance, or www.butterthlies.com, which we shall meet later in examples in this book.

When you surf to http://www.amazon.com, your browser actually goes first to a specialist server called a Domain Name Server (DNS), which knows (how it knows doesn't concern us here) that this name translates into 208.202.218.15.It then asks the Web to connect it to that IP number. When you get an error message saying something like "DNS not found," it means that this process has broken down. Maybe you typed the URL incorrectly, or the server is down, or the person who set it up made a mistake — perhaps because he didn't read this book.

A DNS error impacts Apache in various ways, but one that often catches the beginner is this: if Apache is presented with a URL that corresponds to a directory, but does not have a / at the end of it, then Apache will send a redirect to the same URL with the trailing / added. In order to do this, Apache needs to know its own hostname, which it will attempt to determine from DNS (unless it has been configured with the ServerName directive, covered in Chapter 2. Often when beginners are experimenting with Apache, their DNS is incorrectly set up, and great confusion can result. Watch out for it! Usually what will happen is that you will type in a URL to a browser with a name you are sure is correct, yet the browser will give you a DNS error, saying something like "Cannot find server." Usually, it is the name in the redirect that causes the problem. If adding a / to the end of your URL causes it, then you can be pretty sure that's what has happened.

1.3.3.1 Multiple sites: Unix

It is fortunate that the crucial Unix utility ifconfig, which binds IP addresses to physical interfaces, often allows the binding of multiple IP numbers to a single interface so that people can switch from one IP number to another and maintain service during the transition. This is known as "IP aliasing" and can be used to maintain multiple "virtual" web servers on a single machine.

In practical terms, on many versions of Unix, we run ifconfig to give multiple IP addresses to the same interface. The interface in this context is actually the bit of software — the driver — that handles the physical connection (Ethernet card, serial port, etc.) to the outside. While writing this book, we accessed the practice sites through an Ethernet connection between a Windows 95 machine (the client) and a FreeBSD box (the server) running Apache.

Our environment was very untypical, since the whole thing sat on a desktop with no access to the Web. The FreeBSD box was set up using ifconfig in a script lan_setup, which contained the following lines:

ifconfig ep0 192.168.123.2
ifconfig ep0 192.168.123.3 alias netmask 0xFFFFFFFF
ifconfig ep0 192.168.124.1 alias

The first line binds the IP address 192.168.123.2 to the physical interface ep0. The second binds an alias of 192.168.123.3 to the same interface. We used a subnet mask (netmask 0xFFFFFFFF) to suppress a tedious error message generated by the FreeBSD TCP/IP stack. This address was used to demonstrate virtual hosts. We also bound yet another IP address, 192.168.124.1, to the same interface, simulating a remote server to demonstrate Apache's proxy server. The important feature to note here is that the address 192.168.124.1 is on a different IP network from the address 192.168.123.2, even though it shares the same physical network. No subnet mask was needed in this case, as the error message it suppressed arose from the fact that 192.168.123.2 and 192.168.123.3 are on the same network.

Unfortunately, each Unix implementation tends to do this slightly differently, so these commands may not work on your system. Check your manuals!

In real life, we do not have much to do with IP addresses. Web sites (and Internet hosts generally) are known by their names, such as www.butterthlies.com or sales.butterthlies.com , which we shall meet later. On the authors' desktop system, these names both translate into 192.168.123.2. The distinction between them is made by Apache' Virtual Hosting mechanism — see Chapter 4.

1.3.3.2 Multiple sites: Win32

As far as we can discern, it is not possible to assign multiple IP addresses to a single interface under a standard Windows 95 system. On Windows NT it can be done via Control Panel Networks Protocols TCP/IP/Properties... IP Address Advanced. Later versions of Windows, notably Windows 2000 and XP, support multiple IP addresses through the TCP/IP properties dialog of the Local Area Network in the Network and Dial-up Settings area of the Start menu.

1.4 How HTTP Clients Work

Once the server is set up, we can get down to business. The client has the easy end: it wants web action on a particular site, and it sends a request with a URL that begins with http to indicate what service it wants (other common services are ftp for File Transfer Protocolor https for HTTP with Secure Sockets Layer — SSL) and continues with these possible parts:

 //<user>:<password>@<host>:<port>/<url-path>

RFC 1738 says:

Some or all of the parts "<user>:<password>@", ":<password>",":<port>", and "/<url-path>" may be omitted. The scheme specific data start with a double slash "//" to indicate that it complies with the common Internet scheme syntax.

In real life, URLs look more like: http://www.apache.org/ — that is, there is no user and password pair, and there is no port. What happens?

The browser observes that the URL starts with http: and deduces that it should be using the HTTP protocol. The client then contacts a name server, which uses DNS to resolve www.apache.org to an IP address. At the time of writing, this was 63.251.56.142. One way to check the validity of a hostname is to go to the operating-system prompt^[8] and type:

ping www.apache.org

If that host is connected to the Internet, a response is returned:

Pinging www.apache.org [63.251.56.142] with 32 bytes of data:

Reply from 63.251.56.142: bytes=32 time=278ms TTL=49
Reply from 63.251.56.142: bytes=32 time=620ms TTL=49
Reply from 63.251.56.142: bytes=32 time=285ms TTL=49
Reply from 63.251.56.142: bytes=32 time=290ms TTL=49

Ping statistics for 63.251.56.142:

A URL can be given more precision by attaching a post number: the web address http://www.apache.org doesn't include a port because it is port 80, the default, and the browser takes it for granted. If some other port is wanted, it is included in the URL after a colon — for example, http://www.apache.org:8000/. We will have more to do with ports later.

The URL always includes a path, even if is only /. If the path is left out by the careless user, most browsers put it back in. If the path were /some/where/foo.html on port 8000, the URL would be http://www.apache.org:8000/some/where/foo.html.

The client now makes a TCP connection to port number 8000 on IP 204.152.144.38 and sends the following message down the connection (if it is using HTTP 1.0):

GET /some/where/foo.html HTTP/1.0<CR><LF><CR><LF>

These carriage returns and line feeds (CRLF) are very important because they separate the HTTP header from its body. If the request were a POST, there would be data following. The server sends the response back and closes the connection. To see it in action, connect again to the Internet, get a command-line prompt, and type the following:

% telnet www.apache.org 80

> telnet www.apache.org 80
GET http://www.apache.org/foundation/contact.html HTTP/1.1
Host: www.apache.org

On Win98, telnet puts up a dialog box. Click connect remote system, and change Port from "telnet" to "80". In Terminal preferences, check "local echo". Then type this, followed by two Returns:

GET http://www.apache.org/foundation/contact.html HTTP/1.1
Host: www.apache.org

You should see text similar to that which follows.

Some implementations of telnet rather unnervingly don't echo what you type to the screen, so it seems that nothing is happening. Nevertheless, a whole mess of response streams past:

Trying 64.125.133.20...
Connected to www.apache.org.
Escape character is '^]'.
HTTP/1.1 200 OK
Date: Mon, 25 Feb 2002 15:03:19 GMT
Server: Apache/2.0.32 (Unix)
Cache-Control: max-age=86400
Expires: Tue, 26 Feb 2002 15:03:19 GMT
Accept-Ranges: bytes
Content-Length: 4946
Content-Type: text/html

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
               "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html>
 <head>
  <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
      <title>Contact Information--The Apache Software Foundation</title>
 </head>
 <body bgcolor="#ffffff" text="#000000" link="#525D76">        
  <table border="0" width="100%" cellspacing="0">
   <tr><!-- SITE BANNER AND PROJECT IMAGE -->
    <td align="left" valign="top">
<a href="http://www.apache.org/"><img src="../images/asf_logo_wide.gif" alt="The 
Apache Software Foundation" align="left" border="0"/></a>
</td>
   </tr>
  </table>
  <table border="0" width="100%" cellspacing="4">
   <tr><td colspan="2"><hr noshade="noshade" size="1"/></td></tr>
   <tr>
    <!-- LEFT SIDE NAVIGATION -->
    <td valign="top" nowrap="nowrap">
           <p><b><a href="/foundation/projects.html">Apache Projects</a></b></p>
    <menu compact="compact">
          <li><a href="http://httpd.apache.org/">HTTP Server</a></li>
          <li><a href="http://apr.apache.org/">APR</a></li>
          <li><a href="http://jakarta.apache.org/">Jakarta</a></li>
          <li><a href="http://perl.apache.org/">Perl</a></li>
          <li><a href="http://php.apache.org/">PHP</a></li>
          <li><a href="http://tcl.apache.org/">TCL</a></li>
          <li><a href="http://xml.apache.org/">XML</a></li>
          <li><a href="/foundation/conferences.html">Conferences</a></li>
          <li><a href="/foundation/">Foundation</a></li>
        </menu>
...... and so on

1.5 What Happens at the Server End?

We assume that the server is well set up and running Apache. What does Apache do? In the simplest terms, it gets a URL from the Internet, turns it into a filename, and sends the file (or its output if it is a program)^[9] back down the Internet. That's all it does, and that's all this book is about!

Two main cases arise:

The Unix server has a standalone Apache that listens to one or more ports (port 80 by default) on one or more IP addresses mapped onto the interfaces of its machine. In this mode (known as standalone mode), Apache actually runs several copies of itself to handle multiple connections simultaneously.
On Windows, there is a single process with multiple threads. Each thread services a single connection. This currently limits Apache 1.3 to 64 simultaneous connections, because there's a system limit of 64 objects for which you can wait at once. This is something of a disadvantage because a busy site can have several hundred simultaneous connections. It has been improved in Apache 2.0. The default maximim is now 1920 — but even that can be extended at compile time.

Both cases boil down to an Apache server with an incoming connection. Remember our first statement in this section, namely, that the object of the whole exercise is to resolve the incoming request either into a filename or the name of a script, which generates data internally on the fly. Apache thus first determines which IP address and port number were used by asking the operating system to where the connection is connecting. Apache then uses the IP address, port number — and the Host header in HTTP 1.1 — to decide which virtual host is the target of this request. The virtual host then looks at the path, which was handed to it in the request, and reads that against its configuration to decide on the appropriate response, which it then returns.

Most of this book is about the possible appropriate responses and how Apache decides which one to use.

1.6 Planning the Apache Installation

Unless you're using a prepackaged installation, you'll want to do some planning before setting up the software. You'll need to consider network integration, operating system choices, Apache version choices, and the many modules available for Apache. Even if you're just using Apache at an ISP, you may want to know which choices the ISP made in its installation.

1.6.1 Fitting Apache into Your Network

Apache installations come in many flavors. If an installation is intended only for local use on a developer's machine, it probably needs much less integration with network systems than an installation meant as public host supporting thousands of simultaneous hits. Apache itself provides network and security functionality, but you'll need to set up supporting services separately, like the DNS that identifies your server to the network or the routing that connects it to the rest of the network. Some servers operate behind firewalls, and firewall configuration may also be an issue. If these are concerns for you, involve your network administrator early in the process.

1.6.2 Which Operating System?

Many webmasters have no choice of operating system — they have to use what's in the box on their desks — but if they have a choice, the first decision to make is between Unix and Windows. As the reader who persists with us will discover, much of the Apache Group and your authors prefer Unix. It is, itself, essentially open source. Over the last 30 years it has been the subject of intense scrutiny and improvement by many thousands of people. On the other hand, Windows is widely available, and Apache support for Windows has improved substantially in Apache 2.0.

1.6.3 Which Unix?

The choice is commonly between some sort of Linux and FreeBSD. Both are technically acceptable. If you already know someone who has one of these OSs and is willing to help you get used to yours, then it would make sense to follow them. If you are an Apple user, OS X has a Unix core and includes Apache.

Failing that, the difference between the two paths is mainly a legal one, turning on their different interperations of open source licensing.

Linux lives at http://www.linux.org, and there are more than 160 different distributions from which Linux can be obtained free or in prepackaged pay-for formats. It is rather ominously described as a "Unix-type" operating system, which sometimes means that long-established Unix standards have been "improved", not always in an upwards direction.

Linux supports Apache, and most of the standard distributions include it. However, the default position of the Config files may vary from platform to platform, though usually on Linux they are to be found in /etc. Under Red Hat Linux they will be in/etc/httpd/conf by default.

FreeBSD ("BSD" means "Berkeley Software Distribution" — as in the University of California, Berkeley, where the version of Unix FreeBSD is derived from) lives at http://www.freebsd.org. We have been using FreeBSD for a long time and think it is the best environment.

If you look at http://www.netcraft.com and go to What's that site running?, you can examine any web site you like. If you choose, let's say, http://www.microsoft.com, you will discover that the site's uptime (length of time between rebooting the server) is about 12 days, on average. One assumes that Microsoft's servers are running under their own operating systems. The page Longest uptimes, also at Netcraft, shows that many Apache servers running Unix have uptimes of more than 1380 days (which is probably as long as Netcraft had been running the survey when we looked at it). One of the authors (BL) has a server running FreeBSD that has been rebooted once in 15 years, and that was when he moved house.

The whole of FreeBSD is freely available from http://www.freebsd.org/. But we would suggest that it's well worth spending a few dollars to get the software on CD-ROM or DVD plus a manual that takes you though the installation process.

If you plan to run Apache 2.0 on FreeBSD, you need to install FreeBSD 4.x to take advantage of Apache's support for threads: earlier versions of FreeBSD do not support them, at least not well enough to run Apache.

If you use FreeBSD, you will find (we hope) that it installs from the CD-ROM easily enough, but that it initially lacks several things you will need later. Among these are Perl, Emacs, and some better shell than sh (we like bash and ksh), so it might be sensible to install them straightaway from their lurking places on the CD-ROM.

1.7 Windows?

The main problem with the Win32 version of Apache lies in its security, which must depend, in turn, on the security of the underlying operating system. Unfortunately, Windows 95, Windows 98, and their successors have no effective security worth mentioning. Windows NT and Windows 2000 have a large number of security features, but they are poorly documented, hard to understand, and have not been subjected to the decades of public inspection, discussion, testing, and hacking that have forged Unix security into a fortress that can pretty well be relied upon.

It is a grave drawback to Windows that the source code is kept hidden in Microsoft's hands so that it does not benefit from the scrutiny of the computing community. It is precisely because the source code of free software is exposed to millions of critical eyes that it works as well as it does.

In the view of the Apache development group, the Win32 version is useful for easy testing of a proposed web site. But if money is involved, you would be wise to transfer the site to Unix before exposure to the public and the Bad Guys.

1.8 Which Apache?

At the time this edition was prepared, Apache 1.3.26 was the stable release. It has an improved build system (see the section that follows). Both the Unix and Windows versions were thought to be in good shape. Apache 2.0 had made it through beta test into full release. We suggest that if you are working under Unix and you don't need Apache 2.0's improved features (which are multitudinous but not fundamental for the ordinary webmaster), you go for Version 1.3.26 or later.

1.8.1 Apache 2.0

Apache 2.0 is a major new version. The main new features are multithreading (on platforms that support it), layered I/O (also known as filters), and a rationalized API. The ordinary user will see very little difference, but the programmer writing new modules (see the section that follows) will find a substantial change, which is reflected in our rewritten Chapter 20 and Chapter 21. However, the improvements in Apache v2.0 look to the future rather than trying to improve the present. The authors are not planning to transfer their own web sites to v2.0 any time soon and do not expect many other sites to do so either. In fact, many sites are still happily running Apache v1.2, which was nominally superseded several years ago. There are good security reasons for them to upgrade to v1.3.

1.8.2 Apache 2.0 and Win32

Apache 2.0 is designed to run on Windows NT and 2000. The binary installer will only work with x86 processors. In all cases, TCP/IP networking must be installed. If you are using NT 4.0, install Service Pack 3 or 6, since Pack 4 had TCP/IP problems. It is not recommended that Windows 95 or 98 ever be used for production servers and, when we went to press, Apache 2.0 would not run under either at all. See http://www.apache.org/docs-2.0/platform/windows.html.

1.9 Installing Apache

There are two ways of getting Apache running on your machine: by downloading an appropriate executable or by getting the source code and compiling it. Which is better depends on your operating system.

1.9.1 Apache Executables for Unix

The fairly painless business of compiling Apache, which is described later, can now be circumvented by downloading a precompiled binary for the Unix of your choice. When we went to press, the following operating systems (mostly versions of Unix) were suported, but check before you decide. (See http://httpd.apache.org/dist/httpd/binaries.)

aix	aux	beos	bs2000-osd	bsdi
darwin	dgux	digitalunix	freebsd	hpux
irix	linux	macosx	macosxserver	netbsd
netware	openbsd	os2	os390	osf1
qnx	reliantunix	rhapsody	sinix	solaris
sunos	unixware	win32

Although this route is easier, you do forfeit the opportunity to configure the modules of your Apache, and you lose the chance to carry out quite a complex Unix operation, which is in itself interesting and confidence-inspiring if you are not very familiar with this operating system.

1.9.2 Making Apache 1.3.X Under Unix

Download the most recent Apache source code from a suitable mirror site: a list can be found at http://www.apache.org/^[10]. You will get a compressed file — with the extension .gz if it has been gzipped or .Z if it has been compressed. Most Unix software available on the Web (including the Apache source code) is zipped using gzip, a GNU compression tool.

When expanded, the Apache .tar file creates a tree of subdirectories. Each new release does the same, so you need to create a directory on your FreeBSD machine where all this can live sensibly. We put all our source directories in /usr/src/apache. Go there, copy the <apachename>.tar.gz or <apachename>.tar.Z file, and uncompress the .Z version or gunzip (or gzip -d ) the .gz version:

uncompress <apachename>.tar.Z

or:

gzip -d <apachename>.tar.gz

Make sure that the resulting file is called <apachename>.tar, or tar may turn up its nose. If not, type:

mv <apachename> <apachename>.tar

Now unpack it:

% tar xvf <apachename>.tar

Incidentally, modern versions of tar will unzip as well:

% tar xvfz <apachename>.tar.gz

Keep the .tar file because you will need to start fresh to make the SSL version later on (see Chapter 11). The file will make itself a subdirectory, such as apache_1.3.14.

Under Red Hat Linux you install the .rpmfile and type:

rpm -i apache

Under Debian:

aptget install apache

The next task is to turn the source files you have just downloaded into the executable httpd. But before we can discuss that that, we need to talk about Apache modules.

1.9.3 Modules Under Unix

Apache can do a wide range of things, not all of which are needed on every web site. Those that are needed are often not all needed all the time. The more capability the executable, httpd, has, the bigger it is. Even though RAM is cheap, it isn't so cheap that the size of the executable has no effect. Apache handles user requests by starting up a new version of itself for each one that comes in. All the versions share the same static executable code, but each one has to have its own dynamic RAM. In most cases this is not much, but in some — as in mod_perl (see Chapter 17) — it can be huge.

The problem is handled by dividing Apache's functionality into modules and allowing the webmaster to choose which modules to include into the executable. A sensible choice can markedly reduce the size of the program.

There are two ways of doing this. One is to choose which modules you want and then to compile them in permanently. The other is to load them when Apache is run, using the Dynamic Shared Object (DSO) mechanism — which is somewhat like Dynamic Link Libraries (DLL) under Windows. In the two previous editions of this book, we deprecated DSO because:

It was experimental and not very reliable.
The underlying mechanism varies strongly from Unix to Unix so it was, to begin with, not available on many platforms.

However, things have moved on, the list of supported platforms is much longer, and the bugs have been ironed out. When we went to press, the following operating systems were supported:

Linux	SunOS	UnixWare
Darwin/Mac OS	FreeBSD	AIX
OpenStep/Mach	OpenBSD	IRIX
SCO	DYNIX/ptx	NetBSD
HPUX	ReliantUNIX	BSDI
Digital Unix	DGUX

Ultrix was entirely unsupported. If you use an operating system that is not mentioned here, consult the notes in INSTALL.

More reasons for using DSOs are:

Web sites are also getting more complicated so they often positively need DSOs.
Some distributions of Apache, like Red Hat's, are supplied without any compiled-in modules at all.
Some useful packages, such as Tomcat (see Chapter 17), are only available as shared objects.

Having said all this, it is also true that using DSOs makes the novice webmaster's life more complicated than it need be. You need to create the DSOs at compile time and invoke them at runtime. The list of them clogs up the Config file (which is tricky enough to get right even when it is small), offers plenty of opportunity for typing mistakes, and, if you are using Apache v1.3.X, must be in the correct order (under Apache v2.0 the DSO list can be in any order).

Our advice on DSOs is not to use them unless:

You have a precompiled version of Apache (e.g., from Red Hat) that only handles modules as DSOs.
You need to invoke the DSO mechanism to use a package such as Tomcat (see Chapter 17).
Your web site is so busy that executable size is really hurting performance. In practice, this is extremely unlikely, since the code is shared across all instances on every platform we know of.

If none of these apply, note that DSOs exist and leave them alone.

1.9.3.1 Compiled in modules

This method is simple. You select the modules you want, or take the default list in either of the following methods, and compile away. We will discuss this in detail here.

1.9.3.2 DSO modules

To create an Apache that can use the DSO mechanism as a specific shared object, the compile process has to create a detached chunk of executable code — the shared object. This will be a file like (in our layout) /usr/src/apache/apache_1.3.26/src/modules/standard/mod_alias.so.

If all the modules are defined to be DSOs, Apache ends up with only two compiled-in modules: core and mod_so. The first is the real Apache; the second handles DSO loading and running.

You can, of course, mix the two methods and have the standard modules compiled in with DSO for things like Tomcat.

1.9.3.3 APXS

Once mod_so has been compiled in (see later), the necessary hooks for a shared object can be inserted into the Apache executable, httpd, at any time by using the utility apxs:

apxs -i -a -c mod_foo.c

This would make it possible to link in mod_foo at runtime. For practical details see the manual page by running man apxs or search http://www.apache.org for "apxs".

The apxs utility is only built if you use the configure method — see Section 1.10.1 later in this chapter. Note that if you are running a version of Apache prior to 1.3.24, have previously configured Apache and now reconfigure it, you'll need to remove src/support/apxs to force a rebuild when you remake Apache. You will also need to reinstall Apache. If you do not do all this, things that use apxs may mysteriously fail.

1.10 Building Apache 1.3.X Under Unix

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

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

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

1.10.1 Out of the Box

Until Apache 1.3, there was no real out-of-the-box batch-capable build and installation procedure for the complete Apache package. This method is provided by a top-level configure script and a corresponding top-level Makefile.tmpl file. The goal is to provide a GNU Autoconf-style frontend that is capable of driving the old src/Configure stuff in batch.

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

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

./configure
make
make install

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

make clean

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

rm -R /usr/local/apache

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

1.10.2 Semimanual Build Method

Go to the top directory of the unpacked download — we used /usr/src/apache/apache1_3.26. Start off by reading README. This tells you how to compile Apache. The first thing it wants you to do is to go to the src subdirectory and read INSTALL. To go further, you must have an ANSI C-compliant compiler. Most Unices come with a suitable compiler; if not, GNU gcc works fine.

If you have downloaded a beta test version, you first have to copy .../src/Configuration.tmpl to Configuration. We then have to edit Configuration to set things up properly. The whole file is in Appendix A of the installation kit. A script called Configure then uses Configuration and Makefile.tmpl to create your operational Makefile. (Don't attack Makefile directly; any editing you do will be lost as soon as you run Configure again.)

It is usually only necessary to edit the Configuration file to select the permanent modules required (see the next section). Alternatively, you can specify them on the command line. The file will then automatically identify the version of Unix, the compiler to be used, the compiler flags, and so forth. It certainly all worked for us under FreeBSD without any trouble at all.

Configuration has five kinds of things in it:

Comment lines starting with #
Rules starting with the word Rule
Commands to be inserted into Makefile , starting with nothing
Module selection lines beginning with AddModule, which specify the modules you want compiled and enabled
Optional module selection lines beginning with %Module, which specify modules that you want compiled-but not enabled until you issue the appropriate directive

For the moment, we will only be reading the comments and occasionally turning a comment into a command by removing the leading #, or vice versa. Most comments are in front of optional module-inclusion lines to disable them.

1.10.3 Choosing Modules

Inclusion of modules is done by uncommenting (removing the leading #) lines in Configuration. The only drawback to including more modules is an increase in the size of your binary and an imperceptible degradation in performance.^[12]

The default Configuration file includes the modules listed here, together with a lot of chat and comment that we have removed for clarity. Modules that are compiled into the Win32 core are marked with "W"; those that are supplied as a standard Win32 DLL are marked "WD." Our final list is as follows:

AddModule modules/standard/mod_env.o: Sets up environment variables to be passed to CGI scripts.
AddModule modules/standard/mod_log_config.o: Determines logging configuration.
AddModule modules/standard/mod_mime_magic.o: Determines the type of a file.
AddModule modules/standard/mod_mime.o: Maps file extensions to content types.
AddModule modules/standard/mod_negotiation.o: Allows content selection based on Accept headers.
AddModule modules/standard/mod_status.o (WD): Gives access to server status information.
AddModule modules/standard/mod_info.o: Gives access to configuration information.
AddModule modules/standard/mod_include.o: Translates server-side include statements in CGI texts.
AddModule modules/standard/mod_autoindex.o: Indexes directories without an index file.
AddModule modules/standard/mod_dir.o: Handles requests on directories and directory index files.
AddModule modules/standard/mod_cgi.o: Executes CGI scripts.
AddModule modules/standard/mod_asis.o: Implements .asis file types.
AddModule modules/standard/mod_imap.o: Executes imagemaps.
AddModule modules/standard/mod_actions.o: Specifies CGI scripts to act as handlers for particular file types.
AddModule modules/standard/mod_speling.o: Corrects common spelling mistakes in requests.
AddModule modules/standard/mod_userdir.o: Selects resource directories by username and a common prefix.
AddModule modules/proxy/libproxy.o: Allows Apache to run as a proxy server; should be commented out if not needed.
AddModule modules/standard/mod_alias.o: Provides simple URL translation and redirection.
AddModule modules/standard/mod_rewrite.o (WD): Rewrites requested URIs using specified rules.
AddModule modules/standard/mod_access.o: Provides access control.
AddModule modules/standard/mod_auth.o: Provides authorization control.
AddModule modules/standard/mod_auth_anon.o (WD): Provides FTP-style anonymous username/password authentication.
AddModule modules/standard/mod_auth_db.o: Manages a database of passwords; alternative to mod_auth_dbm.o.
AddModule modules/standard/mod_cern_meta.o (WD): Implements metainformation files compatible with the CERN web server.
AddModule modules/standard/mod_digest.o (WD): Implements HTTP digest authentication; more secure than the others.
AddModule modules/standard/mod_expires.o (WD): Applies Expires headers to resources.
AddModule modules/standard/mod_headers.o (WD): Sets arbitrary HTTP response headers.
AddModule modules/standard/mod_usertrack.o (WD): Tracks users by means of cookies. It is not necessary to use cookies.
AddModule modules/standard/mod_unique_id.o: Generates an ID for each hit. May not work on all systems.
AddModule modules/standard/mod_so.o: Loads modules at runtime. Experimental.
AddModule modules/standard/mod_setenvif.o: Sets environment variables based on header fields in the request.

Here are the modules we commented out, and why:

# AddModule modules/standard/mod_log_agent.o: Not relevant here — CERN holdover.
# AddModule modules/standard/mod_log_referer.o: Not relevant here — CERN holdover.
# AddModule modules/standard/mod_auth_dbm.o: Can't have both this and mod_auth_db.o. Doesn't work with Win32.
# AddModule modules/example/mod_example.o: Only for testing APIs (see Chapter 20).

These are the "standard" Apache modules, approved and supported by the Apache Group as a whole. There are a number of other modules available (see http://modules.apache.org).

Although we mentioned mod_auth_db.o and mod_auth_dbm.o earlier, they provide equivalent functionality and shouldn't be compiled together.

We have left out any modules described as experimental. Any disparity between the directives listed in this book and the list obtained by starting Apache with the -h flag is probably caused by the errant directive having moved out of experimental status since we went to press.

Later on, when we are writing Apache configuration scripts, we can make them adapt to the modules we include or exclude with the IfModule directive. This allows you to give out predefined Config files that always work (in the sense of Apache loading), regardless of what mix of modules is actually compiled. Thus, for instance, we can adapt to the absence of configurable logging with the following:

...
<IfModule mod_log_config.c>
LogFormat "customers: host %h, logname %l, user %u, time %t, request %r, status %s, 
bytes %b"
</IfModule>
...

1.10.4 Shared Objects

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

Enable mod_so by uncommenting its line.
Change an existing AddModule <path>/<modulename>.o so it ends in .so rather than .o and, of course, making sure the path is correct.

1.10.5 Configuration Settings and Rules

Most Apache users won't have to bother with this section at all. However, you can specify extra compiler flags (for instance, optimization commands), libraries, or includes by giving values to the following :

EXTRA_CFLAGS=
EXTRA_LDFLAGS=
EXTRA_LIBS=
EXTRA_INCLUDES=

Configure will try to guess your operating system and compiler; therefore, unless things go wrong, you won't need to uncomment and give values to these:

#CC=
#OPTIM=-02
#RANLIB=

The rules in the Configuration file allow you to adapt for a few exotic configuration problems. The syntax of a rule in Configuration is as follows:

Rule RULE =value

The possible values are as follows:

yes: Configure does what is required.
default: Configure makes a best guess.

Any other value is ignored.

The Rule s are as follows:

STATUS: If yes, and Configure decides that you are using the status module, then full status information is enabled. If the status module is not included, yes has no effect. This is set to yes by default.
SOCKS4: SOCKS is a firewall traversal protocol that requires client-end processing. See http://ftp.nec.com/pub/security/socks.cstc. If set to yes, be sure to add the SOCKS library location to EXTRA_LIBS; otherwise, Configure assumes L/usr/local/lib -lsocks. This allows Apache to make outgoing SOCKS connections, which is not something it normally needs to do, unless it is configured as a proxy. Although the very latest version of SOCKS is SOCKS5, SOCKS4 clients work fine with it. This is set to no by default.
SOCKS5: If you want to use a SOCKS5 client library, you must use this rule rather than SOCKS4. This is set to no by default.
IRIXNIS: If Configure decides that you are running SGI IRIX, and you are using NIS, set this to yes. This is set to no by default.
IRIXN32: Make IRIX use the n32 libraries rather than the o32 ones. This is set to yes by default.
PARANOID: During Configure, modules can run shell commands. If PARANOID is set to yes, it will print out the code that the modules use. This is set to no by default.

There is a group of rules that Configure will try to set correctly, but that can be overridden. If you have to do this, please advise the Apache Group by filling out a problem report form at http://apache.org/bugdb.cgi or by sending an email to apache-bugs@ apache.org. Currently, there is only one rule in this group:

WANTHSREGEX:

Apache needs to interpret regular expressions using POSIX methods. A good regex package is included with Apache, but you can use your OS version by setting WANTHSREGEX=no or commenting out the rule. The default action depends on your OS:

Rule WANTSHREGEX=default

1.10.6 Making Apache

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

Then type:

% ./Configure

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

Using config file: Configuration
Creating Makefile
 + configured for FreeBSD platform
 + setting C compiler to gcc
 + Adding selected modules
    o status_module uses ConfigStart/End:
    o dbm_auth_module uses ConfigStart/End:
    o db_auth_module uses ConfigStart/End:
    o so_module uses ConfigStart/End:
 + doing sanity check on compiler and options
Creating Makefile in support
Creating Makefile in main
Creating Makefile in ap
Creating Makefile in regex
Creating Makefile in os/unix
Creating Makefile in modules/standard
Creating Makefile in modules/proxy

Then type:

% make

When you run make, the compiler is set in motion using the makefile built by Configure, and streams of reassuring messages appear on the screen. However, things may go wrong that you have to fix, although this situation can appear more alarming than it really is. For instance, in an earlier attempt to install Apache on an SCO machine, we received the following compile error:

Cannot open include file 'sys/socket.h'

Clearly (since sockets are very TCP/IP-intensive), this had to do with TCP/IP, which we had not installed: we did so. Not that this is a big deal, but it illustrates the sort of minor problem that arises. Not everything turns up where it ought to. If you find something that really is not working properly, it is sensible to make a bug report via the Bug Report link in the Apache Server Project main menu. But do read the notes there. Make sure that it is a real bug, not a configuration problem, and look through the known bug list first so as not to waste everyone's time.

The result of make was the executable httpd. If you run it with:

% ./httpd

it complains that it:

could not open document config file /usr/local/etc/httpd/conf/httpd.conf

This is not surprising because, at the moment, httpd.conf, which we call the Config file, doesn't exist. Before we are finished, we will become very familiar with this file. It is perhaps unfortunate that it has a name so similar to the Configuration file we have been dealing with here, because it is quite different. We hope that the difference will become apparent later on. The last step is to copy httpd to a suitable storage directory that is on your path. We use /usr/local/bin or /usr/local/sbin.

1.11 New Features in Apache v2

The procedure for configuring and compiling Apache has changed, as we will see later.

High-level decisions about the way Apache works internally can now be made at compile time by including one of a series of Multi Processing Modules (MPMs). This is done by attaching a flag to configure:

./configure <other flags> --with_mpm=<name of MPM>

Although MPMs are rather like ordinary modules, only one can be used at a time. Some of them are designed to adapt Apache to different operating systems; others offer a range of different optimizations for Unix.

It will be shown, along with the other compiled-in modules, by executing httpd -l. When we went to press, these were the possible MPMs under Unix:

prefork: Default. Most closely imitates behavior of v1.3. Currently the default for Unix and sites that require stability, though we hope that threading will become the default later on.
threaded: Suitable for sites that require the benefits brought by threading, particularly reduced memory footprint and improved interthread communications. But see "prefork" earlier in this list.
perchild: Allows different hosts to have different user IDs.
mpmt_pthread: Similar to prefork, but each child process has a specified number of threads. It is possible to specify a minimum and maximum number of idle threads.
Dexter: Multiprocess, multithreaded MPM that allows you to specify a static number of processes.
Perchild: Similar to Dexter, but you can define a seperate user and group for each child process to increase server security.

Other operating systems have their own MPMs:

spmt_os2: For OS2.
beos: For the Be OS.
WinNT: Win32-specific version, taking advantage of completion ports and native function calls to give better network performance.

To begin with, accept the default MPM. More advanced users should refer to http://httpd.apache.org/docs-2.0/mpm.html and http://httpd.apache.org/docs-2.0/misc/perf-tuning.html.

See the entry for the AcceptMutex directive in Chapter 3.

1.11.1 Config File Changes in v2

Version 2.0 makes the following changes to the Config file:

CacheNegotiatedDocs now takes the argument on/off. Existing instances of CacheNegotiatedDocs should be given the argument on.
ErrorDocument <HTTP error number> "<message>" now needs quotes around the <message>, not just at the start.
The AccessConfig and ResourceConfig directives have been abolished. If you want to use these files, replace them by Include conf/srm.conf Include conf/access.conf in that order, and at the end of the Config file.
The BindAddress directive has been abolished. Use Listen.
The ExtendedStatus directive has been abolished.
The ServerType directive has been abolished.
The AgentLog, ReferLog, and ReferIgnore directives have been removed along with the mod_log_agent and mod_log_referer modules. Agent and referer logs are still available using the CustomLog directive.
The AddModule and ClearModule directives have been abolished. A very useful point is that Apache v2 does not care about the order in which DSOs are loaded.

1.11.2 httpd Command-Line Changes

Running the v2 httpd with the flag -h to show the possible command-line flags produces this:

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

In particular, the -X flag has been removed. You can get the same effect — running a single copy of Apache without any children being generated — with this:

httpd -D ONE_PROCESS

or:

httpd -D NO_DETACH

depending on the MPM used. The available flags for each MPM will be visible on running httpd with -?.

1.11.3 Module Changes in v2

Version 2.0 makes the following changes to module handling:

mod_auth_digest is now a standard module in v2.
mod_mmap_static, which was experimental in v1.3, has been replaced by mod_file_cache.
Third-party modules written for Apache v1.3 will not work with v2 since the API has been completely rewritten. See Chapter 20 and Chapter 21.

1.12 Making and Installing Apache v2 Under Unix

Disregard all the previous instructions for Apache compilation. There is no longer a .../src directory. Even the name of the Unix source file has changed. We downloaded httpd-2_0_40.tar.gz and unpacked it in /usr/src/apache as usual. You should read the file INSTALL. The scheme for building Apache v2 is now much more in line with that for most other downloaded packages and utilities.

Set up the configuration file with this:

./configure  --prefix=/usr/local

or wherever it is you want to keep the Apache bits — which will appear in various subdirectories. The executable, for instance, will be in .../sbin. If you are compiling under FreeBSD, as we were, --with-mpm=prefork is automatically used internally, since threads do not currently work well under this operating system. To see all the configuration possibilities:

./configure --help | more

If you want to preserve your Apache 1.3.X executable, you might rename it to httpd.13, wherever it is, and then:

make

which takes a surprising amount of time to run. Then:

make install

The result is a nice new httpd in /usr/local/sbin.

1.13 Apache Under Windows

Apache 1.3 will work under Windows NT 4.0 and 2000. Its performance under Windows 95 and 98 is not guaranteed. If running on Windows 95, the "Winsock2" upgrade must be installed before Apache will run. "Winsock2" for Windows 95 is available at http://www.microsoft.com/windows95/downloads/contents/WUAdminTools/S_WUNetworkingTools/W95Sockets2. Be warned that the Dialup Networking 1.2 (MS DUN) updates include a Winsock2 that is entirely insufficient, and the Winsock2 update must be reinstalled after installing Windows 95 dialup networking. Windows 98, NT (Service Pack 3 or later), and 2000 users need to take no special action; those versions provide Winsock2 as distributed.

Apache v2 will run under Windows 2000 and NT, but, when we went to press, they did not work under Win 95, 98, or Me. These different versions are the same as far as Apache is concerned, except that under NT, Apache can also be run as a service. From Apache v1.3.14, emulators are available to provide NT services under the other Windows platforms. Performance under Win32 may not be as good as under Unix, but this will probably improve over coming months.

Since Win32 is considerably more consistent than the sprawling family of Unices, and since it loads extra modules as DLLs at runtime rather than compiling them at make time, it is practical for the Apache Group to offer a precompiled binary executable as the standard distribution. Go to http://www.apache.org/dist, and click on the version you want, which will be in the form of a self-installing .exe file (the .exe extension is how you tell which one is the Win32 Apache). Download it into, say, c:\temp, and then run it from the Win32 Start menu's Run option.

The executable will create an Apache directory, C:\Program Files\Apache, by default. Everything to do with Win32 Apache happens in an MS-DOS window, so get into a window and type:

> cd c:\<apache directory>
> dir

and you should see something like this:

Volume in drive C has no label
 Volume Serial Number is 294C-14EE
 Directory of C:\apache
.              <DIR>        21/05/98   7:27 .
..             <DIR>        21/05/98   7:27 ..
DEISL1   ISU        12,818  29/07/98  15:12 DeIsL1.isu
HTDOCS         <DIR>        29/07/98  15:12 htdocs
MODULES        <DIR>        29/07/98  15:12 modules
ICONS          <DIR>        29/07/98  15:12 icons
LOGS           <DIR>        29/07/98  15:12 logs
CONF           <DIR>        29/07/98  15:12 conf
CGI-BIN        <DIR>        29/07/98  15:12 cgi-bin
ABOUT_~1            12,921  15/07/98  13:31 ABOUT_APACHE
ANNOUN~1             3,090  18/07/98  23:50 Announcement
KEYS                22,763  15/07/98  13:31 KEYS
LICENSE              2,907  31/03/98  13:52 LICENSE
APACHE   EXE         3,072  19/07/98  11:47 Apache.exe
APACHE~1 DLL       247,808  19/07/98  12:11 ApacheCore.dll
MAKEFI~1 TMP        21,025  15/07/98  18:03 Makefile.tmpl
README               2,109  01/04/98  13:59 README
README~1 TXT         2,985  30/05/98  13:57 README-NT.TXT
INSTALL  DLL        54,784  19/07/98  11:44 install.dll
_DEISREG ISR           147  29/07/98  15:12 _DEISREG.ISR
_ISREG32 DLL        40,960  23/04/97   1:16 _ISREG32.DLL
        13 file(s)        427,389 bytes
         8 dir(s)     520,835,072 bytes free

Apache.exe is the executable, and ApacheCore.dll is the meat of the thing. The important subdirectories are as follows:

conf: Where the Config file lives.
logs: Where the logs are kept.
htdocs: Where you put the material your server is to give clients. The Apache manual will be found in a subdirectory.
modules: Where the runtime loadable DLLs live.

After 1.3b6, leave alone your original versions of files in these subdirectories, while creating new ones with the added extension .default — which you should look at. We will see what to do with all of this in the next chapter.

See the file README-NT.TXT for current problems.

1.13.1 Modules Under Windows

Under Windows, Apache is normally downloaded as a precompiled executable. The core modules are compiled in, and others are loaded <module name>.so at runtime (if needed), so control of the executable's size is less urgent. The DLLs supplied (they really are called .so and not .dll ) in the .../apache/modules subdirectory are as follows:

mod_auth_anon.so
mod_auth_dbm.so
mod_auth_digest.so
mod_cern_meta.so
mod_dav.so
mod_dav_fs.so
mod_expires.so
mod_file_cache.so
mod_headers.so
mod_info.so
mod_mime_magic.so
mod_proxy.so
mod_rewrite.so
mod_speling.so
mod_status.so
mod_unique_id.so
mod_usertrack.so
mod_vhost_alias.so
mod_proxy_connect.so
mod_proxy_ftp.so
mod_proxy_http.so
mod_access.so
mod_actions.so
mod_alias.so
mod_asis.so
mod_auth.so
mod_autoindex.so
mod_cgi.so
mod_dir.so
mod_env.so
mod_imap.so
mod_include.so
mod_isapi.so
mod_log_config.so
mod_mime.so
mod_negotiation.so
mod_setenvif.so
mod_userdir.so

What these are and what they do will become more apparent as we proceed.

1.13.2 Compiling Apache Under Win32

The advanced user who wants to write her own modules (see Chapter 21) will need the source code. This can be installed with the Win32 version by choosing Custom installation. It can also be downloaded from the nearest mirror Apache site (start at http://apache.org/ ) as a .tar.gz file containing the normal Unix distribution. In addition, it can be unpacked into an appropriate source directory using, for instance, 32-bit WinZip, which deals with .tar and .gz format files, as well as .zip. You will also need Microsoft's Visual C++ Version 6. Scripts are available for users of MSVC v5, since the changes are not backwards compatible. Once the sources and compiler are in place, open an MS-DOS window, and go to the Apache src directory. Build a debug version, and install it into \Apache by typing:

> nmake /f Makefile.nt _apached
> nmake /f Makefile.nt installd

or build a release version by typing:

> nmake /f Makefile.nt _apacher
> nmake /f Makefile.nt installr

This will build and install the following files in and below \Apache\:

Apache.exe: The executable
ApacheCore.dll: The main shared library
Modules\ApacheModule*.dll: Seven optional modules
\conf: Empty config directory
\logs: Empty log directory

The directives described in the rest of the book are the same for both Unix and Win32, except that Win32 Apache can load module DLLs. They need to be activated in the Config file by the LoadModule directive. For example, if you want status information, you need the line:

LoadModule status_module modules/ApacheModuleStatus.dll

Apache for Win32 can also load Internet Server Applications (ISAPI extensions). Notice that wherever filenames are relevant in the Config file, the Win32 version uses forward slashes (/) as in Unix, rather than backslashes (\) as in MS-DOS or Windows. Since almost all the rest of the book applies to both Win32 and Unix without distinction between then, we will use forward slashes (/) in filenames wherever they occur.

[1]  Note that since a URL has no predefined meaning, this really is just a tradition, though a pretty well entrenched one in this case.
[2]  We generally follow the convention of calling these people the Bad Guys. This avoids debate about "hackers," which to many people simply refers to good programmers, but to some means Bad Guys. We discover from the French edition of this book that in France they are Sales Types -- dirty fellows.
[3]  For more on the open source movement, see Open Sources: Voices from the Open Source Revolution (O'Reilly & Associates, 1999).
[4]  Netcraft also surveys the uptime of various sites. At the time of writing, the longest running site was http://wwwprod1.telia.com, which had been up for 1,386 days.
[5]  This double name is rather annoying, but it seems that life has progressed too far for anything to be done about it. We will, rather clumsily, refer to httpd/apache and hope that the reader can pick the right one.
[6]  Windows NT TCP/IP Network Administration, by Craig Hunt and Robert Bruce Thompson (O'Reilly & Associates, 1998), and TCP/IP Network Administration, Third Edition, by Craig Hunt (O'Reilly & Associates, 2002).
[7]  In the minimal case we could have two programs running on the same computer talking to each other via TCP/IP — the network is "virtual".
[8]  The operating-system prompt is likely to be ">" (Win95) or "%" (Unix). When we say, for instance, "Type % ping," we mean, "When you see '%', type 'ping'."
[9]  Usually. We'll see later that some URLs may refer to information generated completely within Apache.
[10]  It is best to download it, so you get the latest version with all its bug fixes and security patches.
[11]  New is a dirty four letter word in computing.
[12]  Assuming the module has been carefully written, it does very little unless enabled in the httpd.conf files.

CONTENTS