Getting Started with Apache - Generic Invocation Options

(Page 10 of 14 )

These options are available on all platforms.

-C: Process Directive Before Reading Configuration

This allows Apache to be started with extra configuration directives that are prefixed to the configuration files, and directives inside the configuration file can therefore augment or override them. For example, the command:

$ httpd -d /usr/local/www

could also be written as this:

$ httpd -C "ServerRoot /usr/local/www"

It might also be used in preference to -D for enabling and disabling features that can be controlled with a single directive, for example:

$ httpd -C "SSLEngine on"

You can chain multiple -C options together to create compound directives; see the next example for -c.

-c: Process Directive After Reading Configuration

The -c option is identical to -C but adds the directive to Apache’s runtime configuration after the configuration files have been read. Because -c takes effect after the configuration files, it can override directives in them. This allows a directive to be changed without altering the configuration file itself. For example, the previous SSL directive for enabling SSL would not work with -C if an SSLEngine off were present in the configuration file. However, with -c, it would.

It’s possible to use -c and -C multiple times to add multiple configuration lines simultaneously. For example, you could include a module and configure it in one command:

$httpd -c "LoadModule status_module modules/mod_status.so"\
       -c "<Location /status>"\ 
-c "SetHandler server-status" \
-c "</Location>"

Defining many directives this way starts to become unwieldy, so for configurations longer than this you should probably look at creating a configuration file and using it with -f or including it with this:

$ httpd -c "Include mod_status.conf"

This can be handy for maintaining your own configuration separately from the standard one while still making use of it (Chapter 4 elaborates on this idea).

-D: Define IfDefine Name

Since version 1.3.1, Apache has supported the directive, which allows optional parts of a configuration to be defined. In conjunction with the -D flag, this allows Apache to be started with several different configurations using only one configuration file, for example:

$ httpd -D no_network

It could be used in conjunction with a configuration file containing this:

<IfDefine no_network>
<Location>
order deny,allow
deny from all
allow from 127.0.0.1
  </Location>
</IfDefine>

This would prevent Apache from responding to client requests from anywhere except the local host. The number of possible uses of this feature is extensive, such as switching on and off modules, enabling or disabling security authorization, and so on. As a practical example, Apache’s default configuration uses -D SSL to switch SSL on and off and provides the startssl option in apachectl as a wrapper around it.

Apache 2 also supports some special defines that have meaning to specific parts of the server. In particular, you can cause Apache to print out a list of all configured virtual hosts with this:

$ httpd -D DUMP_VHOSTS

To dump out this information without actually starting the server, add -t or -T as well.

In Apache 2, most MPMs also recognize and react to four special defines that are mostly oriented around debugging:

• NO_DETACH (Unix and BeOS only): Don’t detach from the controlling terminal.

• FOREGROUND (Unix and BeOS only, implies NO_DETACH): Don’t daemonize or detach from the controlling terminal

• ONE_PROCESS (All MPMs, implies NO_DETACH and FOREGROUND): Don’t allow a child process to handle client requests; use the initial process instead.

• DEBUG (All MPMs, implies all of the previous): Places the MPM into a special debug mode with additional logging.

How these defines affect the operation of the server depends on the MPM in question; see Chapter 8 for a detailed description of MPMs. See also -X (Apache 2) and -F (Apache 1.3).

For those particularly interested in debugging Apache for performance reasons, a profiling Apache 2 can be created by supply -DGPROF as a compiler symbol at build time, as described in Chapter 3.

-d: Define Server Root

To define the server root, that is, the directory containing the default locations for log files, HTML documents, and so on, the value of the compile-time option HTTPD_ROOT is used; the default value of which is /usr/local/apache.

A different server root can be specified using -d. The supplied path must be absolute (that is, start with /), for example:

$ httpd -d /usr/local/www

This supplies an initial value for the configuration directive ServerRoot. This value will be overridden by a ServerRoot directive in one of the configuration files, if present.

-e: Specify Startup Log Level (Apache 2 Only)

The -e option allows you to temporarily alter the logging level from that defined by the LogLevel directive for startup messages only. The primary use for this option is to allow you to increase the logging level to reveal potential problems with Apache’s startup, without placing the server in a high level of logging during regular operation. For example, to give Apache a temporary logging level of debug at startup, you can use this:

$ httpd -e debug

The available logging levels range from emerg (the fewest messages) to debug (all messages) and are the same as those defined by the LogLevel directive. See “Setting the Log Level” in Chapter 9 for a detailed description of what each level provides. This option may be combined with -E to place messages generated at startup into a separate logfile.

NOTE Slightly confusingly, Apache 1.3 on NetWare also supports an -e option to send startup messages to the Apache logger screen rather than the main console. However, this isn’t strictly related to the -e option provided by Apache 2.

-E: Specify Startup Log File (Apache 2 Only)

Normally, Apache will place its own startup and restart messages in the error log. To help isolate and analyze startup problems, Apache 2 allows you to put startup messages into a separate file instead, defined by the -E option. This also allows you to capture errors that get sent to standard error before the error log has been established and that otherwise can be hard to capture at all. For example:

$ httpd -E logs/startup_log -e debug

This can be particularly useful when combined with the -e option described previously to keep runtime errors distinct from potentially very verbose startup messages.

-f: Specify Configuration File

The -f option can be used to specify a different configuration file for Apache. If the path is relative (doesn’t start with /), it’s taken to be under the server root (see -d previously). Note that it doesn’t look for a configuration file starting in the local directory, for example:

$ httpd -f conf/test.conf

If a configuration file is located elsewhere, an absolute path is required, for example:

$ httpd -f /usr/tmp/test.conf

Note that you can specify -f multiple times to include more than one file, but if you specify it even once, then Apache will not read the default configuration. To include an additional file and still have Apache read the default configuration, you must specify it explicitly or use -cInclude /usr/tmp/test.conf instead.

-F: Run in Foreground (Apache 1.3 Only)

This option will cause the main Apache process to stay in the foreground, rather than detaching from the console and moving into the background. It’s mostly useful for starting Apache from another program, which can use this option to capture the exit status from the server. Apache 2 instead provides -D FOREGROUND. The -X option is superficially similar, but forces Apache into a single-process debug mode; by contrast, -F causes the server to run entirely normally apart from the main process remaining undetached.

-h: Display Usage Information

This will cause Apache to produce a usage page similar to the previous. The exact output will depend on the version of Apache and the platform.

-l: List Compiled in Modules

Specifying the option -l lists all the modules that have been compiled into Apache, for example:

$ httpd -l

Compiled-in modules:

http_core.c
mod_env.c
mod_log_config.c
mod_mime.c
mod_negotiation.c
mod_status.c
mod_info.c
mod_include.c
mod_dir.c
mod_cgi.c

mod_actions.c
mod_proxy.c
mod_rewrite.c
mod_access.c
mod_auth.c
mod_auth_dbm.c
mod_headers.c
mod_browser.c

The order of this list is significant in Apache 1.3 because the modules are listed in order of increasing priority. The further down the module appears in the list, the higher its priority. In the previous example, mod_browser has the highest priority. It will therefore always receive precedence in processing a client request when one arrives. Apache 2 has a simpler and largely automatic mechanism for determining module order, so it’s not sensitive to the order in which modules are built into the server.

A fully dynamic Apache has no built-in modules apart from the core and mod_so, which provides the ability to load dynamic modules. It therefore produces a somewhat terse list:

Compiled-in modules:

http_core.c
mod_so.c

If the suExec CGI security wrapper is enabled, an additional line noting its status and the location of the suexec binary is appended to the bottom of the report. For example, for a correctly installed suexec on a Unix server:

suexec: enabled; valid wrapper /usr/bin/suexec

NOTE Chapter 6 covers using suExec in detail.

-L: List Available Configuration Commands

-L lists all available configuration commands together with short explanations. Only core directives and directives of modules statically built into Apache (that is, not dynamically loaded during startup) will be listed, for example:

$ httpd -L
...
ServerName (core.c)
The hostname and port of the server
  Allowed in *.conf only outside
<Directory>, <Files> or <Location>
ServerSignature (core.c)
En-/disable server signature (on|off|email)
Allowed in *.conf anywhere and in .htaccess
When AllowOverride isn't None
ServerRoot (core.c)
Common directory of server-related files
(logs, confs, etc.)
  Allowed in *.conf only outside
<Directory>, <Files> or <Location>
ErrorLog (core.c)
The filename of the error log
Allowed in *.conf only outside
<Directory>, <Files> or <Location>
ServerAlias (core.c)
A name or names alternatively used to access the server
Allowed in *.conf only outside
<Directory>, <Files> or <Location>

Note that up until version 1.3.4, Apache used -h for listing configuration directives, now performed by -L, and had no equivalent for the modern -h. This was changed because there was actually no way to produce the usage page legally, and -h is conventionally used for this purpose. Older documentation may therefore refer to -h rather than -L.

-R: Define Loadable Modules Path

If your server has the mod_so module built-in (which you can check with the -l option), then this option allows you to override the default location that Apache looks in for loadable modules. The default location is the same as the server root rather than a subdirectory, which is why LoadModule directives usually include a parent directory such as libexec or modules. You can redefine it with this:

httpd -R /usr/lib/apache

This is necessary only if you want to move the standard location away from the server root; otherwise, moving the server root is usually enough. However, this option will probably not work unless the loadable modules directory is also on the path defined by the environment variable LD_LIBRARY_PATH; the apachectl script takes this into account when installed as part of a binary distribution, so it’s rare that you should need to use this option directly.

-S: Show Parsed Settings (Apache 1.3 Only)

This displays the configuration settings as parsed from the configuration file. Although it may expand in the future, currently it displays only virtual host information, for example:

$ httpd -S

VirtualHost configuration:
127.0.0.1:80 is a NameVirtualHost
default server www.alpha-complex.com
(/usr/local/apache/conf/httpd.conf:305)
port 80 namevhost www.alpha-prime.com
(/usr/local/apache/conf/httpd.conf:305)
port 80 namevhost www.beta-complex.com
(/usr/local/apache/conf/httpd.conf:313)

In Apache 2, the -S option is now shorthand for the combination of -t and -D DUMP_VHOSTS.

-t: Test Configuration

This option allows the configuration file or files to be tested without actually starting Apache. The server will list any configuration problems to the screen and stop with the first fatal one, for example:

$ httpd -t

Syntax error on line 34 of /etc/httpd/conf/httpd.conf:

Invalid command 'BogusDirective', perhaps misspelled or defined by a module not included in the server configuration

If the configuration is error free, Apache prints this:

Syntax OK

If you have included any directories into the configuration, you’ll also get a list of the configuration files Apache found and read. In Apache 2, if you additionally specify -D DUMP_VHOSTS, you can also get a list of the virtual hosts defined in the configuration, which is identical to the -S option of Apache 1.3 described earlier. Only DUMP_VHOSTS is currently supported as an argument to -D, though other options may appear in the future. Note that it isn’t actually necessary to specify -t to view this; the server will simply start up after dumping the virtual host configuration.

The return value of httpd -t is zero for a successful test, and nonzero otherwise. It can therefore be used by scripts (for example, a watchdog script on a dedicated server) to take action if Apache is unable to start.

-T: Test Configuration Without Document Root Checks

The -T option is identical to its lowercased counterpart except that it doesn’t perform the check for valid document root directories. This is useful if you happen to have virtual hosts that don’t actually use a real document root and map all URL requests to some other medium rather than the file system.

-v: Show Apache Version

This option will simply show Apache’s version, platform, and build time and then exit, for example:

$ httpd -v

  Server version: Apache/2.0.28
Server built:Jan 23 2002 22:08:38

-V: Show Apache Version and Compile-Time Options

The -V produces the same output as -v and in addition lists the compile-time definitions that were specified when Apache was built. Most of these can be changed or added to, depending on how Apache was configured at build time. Popular choices for redefinition are the server root and location of the log files. For example, this is for the previous Apache server:

$ httpd -V

Server version: Apache/2.0.47
Server built: Jul 22 2003 16:45:13
Server's Module Magic Number: 20020903:3
Architecture: 32-bit
Server compiled with....
-D APACHE_MPM_DIR="server/mpm/worker"
  -D APR_HAS_SENDFILE
-D APR_HAS_MMAP
-D APR_HAVE_IPV6 (IPv4-mapped addresses enabled)
-D APR_USE_SYSVSEM_SERIALIZE
-D APR_USE_PTHREAD_SERIALIZE
  -D SINGLE_LISTEN_UNSERIALIZED_ACCEPT
-D APR_HAS_OTHER_CHILD
-D AP_HAVE_RELIABLE_PIPED_LOGS
-D HTTPD_ROOT="/usr/local/apache"
-D SUEXEC_BIN="/usr/local/apache/bin/suexec"
-D DEFAULT_PIDLOG="logs/httpd.pid"
-D DEFAULT_SCOREBOARD="logs/apache_runtime_status"
-D DEFAULT_LOCKFILE="logs/accept.lock"
-D DEFAULT_ERRORLOG="logs/error_log"
-D AP_TYPES_CONFIG_FILE="conf/mime.types"
-D SERVER_CONFIG_FILE="conf/httpd.conf"

This Apache 2 server has been built with the worker MPM in the default location of /usr/local/apache and with the suExec wrapper enabled.

-X: Single Process Foreground Debug Mode

If Apache is called with -X, only one process will be started with no forked child processes or multiple threads, and Apache will not run in the background. This is primarily intended for use with debuggers and isn’t intended for normal operation, and it’s now largely superseded in Apache 2 by the FOREGROUND, ONE_PROCESS, and DEBUG special defines (see -D previously).

Administrators running Apache 1.3 may want to look at the -F option as an alternative if they want to start and monitor Apache using another program; Apache 2 administrators should look at -D NO_DETACH instead.  

This chapter is from Pro Apache by Peter Wainwright. (Apress, 2004, ISBN: 1590593006). Check it out at your favorite bookstore today. Buy this book now.

Next: Windows-Specific Invocation Options >>
 

More Apache Articles
More By Apress Publishing

Comments On: Getting Started with Apache

· How many intro to Apache articles does the Developer Shed network need?    · As many as we feel like posting ;)    · And as many as the community feel like reading...   >>> Post your comment now!