Starting the Server in Single-Process Mode (Practical mod

5.2. Starting the Server in Single-Process Mode

When developing new code, it is often helpful to run the server in single-process mode. This is most often used to find bugs in code that seems to work fine when the server starts, but refuses to work correctly after a few requests have been made. It also helps to uncover problems related to collisions between module names.

Running in single-process mode inhibits the server from automatically running in the background. This allows it to more easily be run under the control of a debugger. The -X switch is used to enable this mode:

panic% /home/httpd/httpd_perl/bin/httpd_perl -X

With the -X switch, the server runs in the foreground of the shell, so it can be killed by typing Ctrl-C. You can run it in the background by appending an ampersand:

panic% /home/httpd/httpd_perl/bin/httpd_perl -X &

Note that in -X (single-process) mode, the server will run very slowly when fetching images. Because only one request can be served at a time, requests for images normally done in parallel by the browser will now be serialized, making the page display slower.

Note for Netscape Users

If Netscape is being used as the test browser while the server is running in single-process mode, the HTTP protocol's KeepAlive feature gets in the way. Netscape tries to open multiple connections and keep them all open, as this should be faster for browsing. But because there is only one server process listening, each connection has to time out before the next one succeeds. Turn off KeepAlive in httpd.conf to avoid this effect while testing. Assuming you use width and height image size parameters in your HTML files, Netscape will be able to render the page without the images, so you can press the browser's Stop button after a few seconds to speed up page display. It's always good practice to specify width and height image size parameters.

Also note that when running with -X, the control messages that the parent server normally writes to error_log (e.g., "server started", "server stopped", etc.) will not be written anywhere. httpd -X causes the server to handle all requests itself without forking any children, so there is no controlling parent to write the status messages.

Usually Ctrl-C is used to kill a server running in single process mode, but Ctrl-C doesn't constitute a clean shutdown. httpd.pid doesn't get removed, so the next time the server is started, the message:

[warn] pid file /home/httpd/httpd_perl/logs/httpd.pid
overwritten -- Unclean shutdown of previous Apache run?

will appear in error_log. You can ignore this warning; there's nothing to worry about.