docs/manual/invoking.html

	invoking.html revision bac4dbe8b4693cc49acddcaaaa4144691149aa58
c25356d5978632df6203437e1953bcb29e0c736fTimo Sirainen<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
c25356d5978632df6203437e1953bcb29e0c736fTimo Sirainen<HTML>
28c75d59f1d1a7caeb85635964f3881c0038eb23Timo Sirainen<HEAD>
e28b4fc2b62be020156a857485b61842b3b5d791Timo Sirainen<TITLE>Starting Apache</TITLE>
28c75d59f1d1a7caeb85635964f3881c0038eb23Timo Sirainen</HEAD>
28c75d59f1d1a7caeb85635964f3881c0038eb23Timo Sirainen
28c75d59f1d1a7caeb85635964f3881c0038eb23Timo Sirainen<!-- Background white, links blue (unvisited), navy (visited), red (active) -->
10399559650f552a23949772be79eb6a80198c5aTimo Sirainen<BODY
39ea5717264668e2c7f9f7986eb821d21785f47fTimo Sirainen BGCOLOR="#FFFFFF"
eca38954bcf972618f6b85932a3690acbd2b673aTimo Sirainen TEXT="#000000"
28c75d59f1d1a7caeb85635964f3881c0038eb23Timo Sirainen LINK="#0000FF"
c4478af52de63804efef2055580adf1dfc8679c6Timo Sirainen VLINK="#000080"
28c75d59f1d1a7caeb85635964f3881c0038eb23Timo Sirainen ALINK="#FF0000"
f8ead0942a9b7c8fcf91414ed1b534d5807ca555Timo Sirainen>
b5052fbfdbc2678cc8f12899afe55c998f43b740Timo Sirainen<!--#include virtual="header.html" -->
b5052fbfdbc2678cc8f12899afe55c998f43b740Timo Sirainen<H1 ALIGN="CENTER">Starting Apache</H1>
28c75d59f1d1a7caeb85635964f3881c0038eb23Timo Sirainen
28c75d59f1d1a7caeb85635964f3881c0038eb23Timo Sirainen<H2>Invoking Apache</H2>
9c7f6dbf65ca01026e5f9c8c8b67c7e629c0b5e7Timo Sirainen
92d1458b00f4f236c4cec96a696253d3bbf8b05aTimo SirainenOn Unix, the <CODE>httpd</CODE> program is usually run as a daemon
8d25b6ad05b99e75613cb045a121efd51e6afbb6Timo Sirainenwhich executes continuously, handling requests.  It is possible to
8d25b6ad05b99e75613cb045a121efd51e6afbb6Timo Siraineninvoke Apache by the Internet daemon <CODE>inetd</CODE> each time a
055389c58fa3915e12fb4e72ec86782ce77c5c72Timo Sirainenconnection to the HTTP service is made (use the <A
055389c58fa3915e12fb4e72ec86782ce77c5c72Timo SirainenHREF="mod/core.html#servertype">ServerType</A> directive) but this is
28c75d59f1d1a7caeb85635964f3881c0038eb23Timo Sirainennot recommended.
28c75d59f1d1a7caeb85635964f3881c0038eb23Timo Sirainen
c2a66e7950cb4d3fc4d68e4480ea8f39bdd7c871Timo Sirainen<P>
c2a66e7950cb4d3fc4d68e4480ea8f39bdd7c871Timo Sirainen
c2a66e7950cb4d3fc4d68e4480ea8f39bdd7c871Timo SirainenOn Windows, Apache is normally run as a service on Windows NT, or as a
c2a66e7950cb4d3fc4d68e4480ea8f39bdd7c871Timo Sirainenconsole application on Windows 95. See also <A
c2a66e7950cb4d3fc4d68e4480ea8f39bdd7c871Timo SirainenHREF="windows.html#run">running Apache for Windows</A>.
28c75d59f1d1a7caeb85635964f3881c0038eb23Timo Sirainen
28c75d59f1d1a7caeb85635964f3881c0038eb23Timo Sirainen<H2>Command line options</H2>
28c75d59f1d1a7caeb85635964f3881c0038eb23Timo SirainenThe following options are recognized on the httpd command line:
28c75d59f1d1a7caeb85635964f3881c0038eb23Timo Sirainen<DL>
92d1458b00f4f236c4cec96a696253d3bbf8b05aTimo Sirainen<DT><CODE>-d</CODE> <EM>serverroot</EM>
92d1458b00f4f236c4cec96a696253d3bbf8b05aTimo Sirainen<DD>Set the initial value for the
28c75d59f1d1a7caeb85635964f3881c0038eb23Timo Sirainen<A HREF="mod/core.html#serverroot">ServerRoot</A> variable to
28c75d59f1d1a7caeb85635964f3881c0038eb23Timo Sirainen<EM>serverroot</EM>. This can be overridden by the ServerRoot command
d694b6009574ee6e3cfaee3834cbdbcd431affb0Timo Sirainenin the configuration file. The default is
d694b6009574ee6e3cfaee3834cbdbcd431affb0Timo Sirainen<CODE>/usr/local/apache</CODE> on Unix, <CODE>/apache</CODE> on
d694b6009574ee6e3cfaee3834cbdbcd431affb0Timo SirainenWindows and <CODE>/os2httpd</CODE> on OS/2.
a5ec9755556e3d97d7e6d78cb1b53046370e6598Timo Sirainen
e28b4fc2b62be020156a857485b61842b3b5d791Timo Sirainen<DT><CODE>-D</CODE> <EM>name</EM>
e28b4fc2b62be020156a857485b61842b3b5d791Timo Sirainen<DD>Define a name for use in in
28c75d59f1d1a7caeb85635964f3881c0038eb23Timo Sirainen<A HREF="mod/core.html#ifdefine">IfDefine</A> directives.
28c75d59f1d1a7caeb85635964f3881c0038eb23Timo SirainenThis option can be used to optionally enable certain functionality in the
28c75d59f1d1a7caeb85635964f3881c0038eb23Timo Sirainenconfiguration file, or to use a common configuration for
28c75d59f1d1a7caeb85635964f3881c0038eb23Timo Sirainenseveral independent hosts, where host specific information is enclosed in
28c75d59f1d1a7caeb85635964f3881c0038eb23Timo Sirainen&lt;IfDefine&gt; sections.
28c75d59f1d1a7caeb85635964f3881c0038eb23Timo Sirainen
b198cd6da331eb55d300b0e83f59695c58d5885cTimo Sirainen<DT><CODE>-f</CODE> <EM>config</EM>
f32da6b73c1edb6963eae0d4a5c1f995ad23151aAki Tuomi<DD>Execute the commands in the file <EM>config</EM> on startup. If
5012586ed3a75857ced48302bf0b8a8dc049796aTimo Sirainen<EM>config</EM> does not begin with a <CODE>/</CODE>, then it is taken to be a
28c75d59f1d1a7caeb85635964f3881c0038eb23Timo Sirainenpath relative to the <A HREF="mod/core.html#serverroot">ServerRoot</A>. The
28c75d59f1d1a7caeb85635964f3881c0038eb23Timo Sirainendefault is <CODE>conf/httpd.conf</CODE>.
28c75d59f1d1a7caeb85635964f3881c0038eb23Timo Sirainen
28c75d59f1d1a7caeb85635964f3881c0038eb23Timo Sirainen<DT><CODE>-C</CODE> <EM>"directive"</EM>
d694b6009574ee6e3cfaee3834cbdbcd431affb0Timo Sirainen<DD>Process the given apache "directive" (just as if it had been part of a
d694b6009574ee6e3cfaee3834cbdbcd431affb0Timo Sirainenconfiguration file) <STRONG>before</STRONG> actually reading the regular configuration files.
d694b6009574ee6e3cfaee3834cbdbcd431affb0Timo Sirainen
d694b6009574ee6e3cfaee3834cbdbcd431affb0Timo Sirainen<DT><CODE>-c</CODE> <EM>"directive"</EM>
6acd1a48e1377e74d3008288e5e95e006f41265cTimo Sirainen<DD>Process the given apache "directive" <STRONG>after</STRONG> reading
6acd1a48e1377e74d3008288e5e95e006f41265cTimo Sirainenall the regular configuration files.
0dffa25d211be541ee3c953b23566a1a990789dfTimo Sirainen
28c75d59f1d1a7caeb85635964f3881c0038eb23Timo Sirainen<DT><CODE>-X</CODE>
28c75d59f1d1a7caeb85635964f3881c0038eb23Timo Sirainen<DD>Run in single-process mode, for internal debugging purposes only; the
28c75d59f1d1a7caeb85635964f3881c0038eb23Timo Sirainendaemon does not detach from the terminal or fork any children. Do <EM>NOT</EM>
28c75d59f1d1a7caeb85635964f3881c0038eb23Timo Sirainenuse this mode to provide ordinary web service.
5012586ed3a75857ced48302bf0b8a8dc049796aTimo Sirainen
2be7df5df08ac4639ad83559ec5fcf552c84fb4aTimo Sirainen<DT><CODE>-v</CODE>
e28b4fc2b62be020156a857485b61842b3b5d791Timo Sirainen<DD>Print the version of httpd and its build date, and then exit.
e28b4fc2b62be020156a857485b61842b3b5d791Timo Sirainen
0dffa25d211be541ee3c953b23566a1a990789dfTimo Sirainen<DT><A NAME="version"><CODE>-V</CODE></A>
aef407f147034a569591c0f59593342a8c7b39eaTimo Sirainen<DD>Print the base version of httpd, its
28c75d59f1d1a7caeb85635964f3881c0038eb23Timo Sirainenbuild date, and a list of compile time settings which influence the
28c75d59f1d1a7caeb85635964f3881c0038eb23Timo Sirainenbehavior and performance of the apache server (<EM>e.g.</EM>,
701eb90460d6c57845dc4e0bf595a5d0b90b01c1Timo Sirainen<SAMP>-DUSE_MMAP_FILES</SAMP>),
701eb90460d6c57845dc4e0bf595a5d0b90b01c1Timo Sirainenthen exit.
701eb90460d6c57845dc4e0bf595a5d0b90b01c1Timo Sirainen
e3fabe8d0faa9aab7cae2d0eee9653f581a3061dTimo Sirainen<DT><A NAME="help"><CODE>-L</CODE></A>
31257b47d47510ceb093a6b218810a1a5b830c55Timo Sirainen<DD>
9686ada8061745b4b8753572f6c04b7a27a8544eTimo Sirainen
fefd62f9aaccecbc6011ecae359a3389668cbff5Timo SirainenGive a list of directives together with expected arguments and places
75bb83681e30d6a86109bbafdfe6b513c11124bcTimo Sirainenwhere the directive is valid, then exit.  (Apache 1.3.4 and
31257b47d47510ceb093a6b218810a1a5b830c55Timo Sirainenlater. Earlier versions used -l instead).
09b15d7b0619e8a1ad5a78b1f86b864a7f76b3c7Timo Sirainen
d70bf110f2f37ab5315a250c2367f164069755adAki Tuomi
d70bf110f2f37ab5315a250c2367f164069755adAki Tuomi<DT><CODE>-l</CODE></A>
d70bf110f2f37ab5315a250c2367f164069755adAki Tuomi<DD>
d70bf110f2f37ab5315a250c2367f164069755adAki Tuomi
e3fabe8d0faa9aab7cae2d0eee9653f581a3061dTimo SirainenGive a list of all modules compiled into the server, then exit.
28c75d59f1d1a7caeb85635964f3881c0038eb23Timo Sirainen(Apache 1.3.4 and later. Earlier versions used -h instead).<br>

Give a list of directives together with expected arguments and places
where the directive is valid, then exit. (Apache 1.2 to 1.3.3. Later
versions use -L instead).


<DT><CODE>-h</CODE>
<DD>

Print a list of the httpd options, then exit. (Apache 1.3.4 and
later. Earlier versions used -? instead).<br>

Give a list of all modules compiled into the server, then exit. (Up to
Apache 1.3.3. Later versions use -l instead).<br>


<DT><CODE>-S</CODE>
<DD>Show the settings as parsed from the config file (currently only
shows a breakdown of the vhost settings) but do not start the
server. (Up to Apache 1.3.3, this option also started the server).

<DT><CODE>-t</CODE>
<DD>Test the configuration file syntax (<EM>i.e.</EM>, read all configuration files
and interpret them) but do not start the server. If the configuration contains
errors, display an error message and exit with a non-zero exit status,
otherwise display "Syntax OK" and terminate with a zero exit status. This
command checks to see if all DocumentRoot entries exist and are directories.
For sites with many vhosts, this is expensive; consider the <CODE>-T</CODE>
command instead.

<DT><CODE>-T</CODE>
<DD>Test the configuration file syntax (<EM>i.e.</EM>, read all configuration files
and interpret them) but do not start the server. If the configuration contains
errors, display an error message and exit with a non-zero exit status,
otherwise display "Syntax OK" and terminate with a zero exit status. This
command does not perform any checking of the DocumentRoot entries.

<DT><CODE>-k</CODE> <EM>option</EM>
<DD>Windows only: signal Apache to restart or shutdown. <EM>option</EM>
is one of "shutdown" or "restart". (Apache 1.3.3 and later).

<DT><CODE>-?</CODE>
<DD>Print a list of the httpd options, and then exit (up to Apache
1.3.3. Later version use -h instead).

</DL>

<H2>Configuration files</H2>
The server will read three files for configuration directives. Any
directive may appear in any of these files. The the names of these
files are taken to be relative to the server root; this is set by the
<A HREF="mod/core.html#serverroot">ServerRoot</A> directive, the
<CODE>-d</CODE> command line flag, or (on Windows only) the registry
(see <A HREF="windows.html#run">Running Apache for Windows</A>).

Conventionally, the files are:
<DL>
<DT><CODE>conf/httpd.conf</CODE>
<DD>Contains directives that control the operation of the server daemon.
The filename may be overridden with the <CODE>-f</CODE> command line flag.

<DT><CODE>conf/srm.conf</CODE>
<DD>Contains directives that control the specification of documents that
the server can provide to clients. The filename may be overridden with
the <A HREF="mod/core.html#resourceconfig">ResourceConfig</A> directive.

<DT><CODE>conf/access.conf</CODE>
<DD>Contains directives that control access to documents.
The filename may be overridden with the
<A HREF="mod/core.html#accessconfig">AccessConfig</A> directive.
</DL>
However, these conventions need not be adhered to.
<P>
The server also reads a file containing mime document types; the filename
is set by the <A HREF="mod/mod_mime.html#typesconfig">TypesConfig</A>
directive,
and is <CODE>conf/mime.types</CODE> by default.

<H2>Log files</H2>
<H3>security warning</H3>
Anyone who can write to the directory where Apache is writing a
log file can almost certainly gain access to the uid that the server is
started as, which is normally root.  Do <EM>NOT</EM> give people write
access to the directory the logs are stored in without being aware of
the consequences; see the <A HREF="misc/security_tips.html">security tips</A>
document for details.
<H3>pid file</H3>

On startup, Apache saves the process id of the parent httpd process to
the file <CODE>logs/httpd.pid</CODE>. This filename can be changed
with the <A HREF="mod/core.html#pidfile">PidFile</A> directive. The
process-id is for use by the administrator in restarting and
terminating the daemon: on Unix, a HUP or USR1 signal causes the
daemon to re-read its configuration files and a TERM signal causes it
to die gracefully; on Windows, use the -k command line option instead.
For more information see the <A HREF="stopping.html">Stopping and
Restarting</A> page.

<P>
If the process dies (or is killed) abnormally, then it will be necessary to
kill the children httpd processes.

<H3>Error log</H3>

The server will log error messages to a log file, by default
<CODE>logs/error_log</CODE> on Unix or <CODE>logs/error.log</CODE> on
Windows and OS/2. The filename can be set using the <A
HREF="mod/core.html#errorlog">ErrorLog</A> directive; different error
logs can be set for different <A
HREF="mod/core.html#virtualhost">virtual hosts</A>.

<H3>Transfer log</H3>

The server will typically log each request to a transfer file, by
default <CODE>logs/access_log</CODE> on Unix or
<CODE>logs/access.log</CODE> on Windows and OS/2. The filename can be
set using a <A
HREF="mod/mod_log_config.html#transferlog">TransferLog</A> directive
or additional log files created with the <A
HREF="mod/mod_log_config.html#customlog">CustomLog</A> directive;
different transfer logs can be set for different <A
HREF="mod/core.html#virtualhost">virtual hosts</A>.

<!--#include virtual="footer.html" -->
</BODY>
</HTML>