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:
could also be written as this:
It might also be used in preference to -D for enabling and disabling features that can be controlled with a single directive, for example:
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"\
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:
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
It could be used in conjunction with a configuration file containing this:
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:
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:
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:
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:
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:
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:
If a configuration file is located elsewhere, an absolute path is required, for example:
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:
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:
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:
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:
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:
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:
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:
If the configuration is error free, Apache prints this:
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:
-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:
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.
blog comments powered by Disqus