Windows-Specific Invocation Options - Apache

These options are specific to Windows servers.

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

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

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

c:\> apache -k install

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

c:\> apache -n Apache2 -k install -d \alternative\apache\install

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

c:\> apache -n Apache2SSL -k config -DSSL -f \alternative\apache\install\conf\httpd.conf

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

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

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

c:\> apache -n Apache2 -k restart

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

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

c:\> apache -u -n Apache2

c:\> apache -k uninstall -n Apache2

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

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

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

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

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

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

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

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

Restarting the Server Normally

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

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

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

$ kill -HUP <pid>

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

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

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

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

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

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

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

Restarting the Server Gracefully

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

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

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

or with apachectl, use this:

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

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

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

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

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

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

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

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

$ kill -TERM

or the new style:

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

and this:

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

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

httpd: caught SIGTERM, shutting down

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

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

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

Configuring Apache As a Unix Service

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

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

/usr/local/apache/bin/httpd

or, using apachectl:

/usr/local/apache/bin/apachectl start

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

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

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

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

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

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

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

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

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

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

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

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

Configuring Apache As a Windows Service

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

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

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

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

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

1. Right-click the Apache2 service.

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

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

4. Click the Apply button in the bottom.

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

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

 
Figure 2-3.  After changing the startup type

Starting Apache As a Service from a Console Window

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

C:\> NET START APACHE2

Likewise, to stop a running service, use this:

C:\> NET STOP APACHE2

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

c:\> apache -n Apache2 -k install

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

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

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

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

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

c:\> apache -n Apache2 -k start

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

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

c:\> apache -k stop

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

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

c:\> apache -n Apache2 -k stop

Similarly, to restart it, use this:

c:\> apache -n Apache2 -k restart

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

c:\> apache -n Apache2 -k uninstall

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

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

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