- Remove documentation on command line options from invoking.html

time synchronization system on your Unix box, or whatever the

equivalent on NT would be.

<H3>Starting and Stopping the Server</H3>

To start the server, simply run <CODE>httpd</CODE>. This will look for

<CODE>httpd.conf</CODE> in the location compiled into the code (by

default <CODE>/usr/local/apache/conf/httpd.conf</CODE>). If

this file is somewhere else, you can give the real

location with the -f argument. For example:

<PRE>

    /usr/local/apache/httpd -f /usr/local/apache/conf/httpd.conf

</PRE>

If all goes well this will return to the command prompt almost

immediately.  This indicates that the server is now up and running. If

anything goes wrong during the initialization of the server you will

see an error message on the screen.

If the server started ok, you can now use your browser to

connect to the server and read the documentation. If you are running

the browser on the same machine as the server and using the default

port of 80, a suitable URL to enter into your browser is

<PRE>

    http://localhost/

</PRE>

<P>

Note that when the server starts it will create a number of

<EM>child</EM> processes to handle the requests. If you started Apache

as the root user, the parent process will continue to run as root

while the children will change to the user as given in the httpd.conf

file.

<P>

If when you run <CODE>httpd</CODE> it complained about being unable to

"bind" to an address, then either some other process is already using

the port you have configured Apache to use, or you are running httpd

as a normal user but trying to use a port below 1024 (such as the

default port 80).

<P>

If the server is not running, read the error message displayed

when you run httpd. You should also check the server

error_log for additional information (with the default configuration,

this will be located in the file <CODE>error_log</CODE> in the

<CODE>logs</CODE> directory).

<P>

If you want your server to continue running after a system reboot, you

should add a call to <CODE>httpd</CODE> to your system startup files

(typically <CODE>rc.local</CODE> or a file in an

<CODE>rc.<EM>N</EM></CODE> directory). This will start Apache as root.

Before doing this ensure that your server is properly configured

for security and access restrictions.

<P>

To stop Apache send the parent process a TERM signal. The PID of this

process is written to the file <CODE>httpd.pid</CODE> in the

<CODE>logs</CODE> directory (unless configured otherwise).  Do not

attempt to kill the child processes because they will be renewed by

the parent.  A typical command to stop the server is:

<PRE>

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

</PRE>

<P>

For more information about Apache command line options, configuration

and log files, see <A HREF="invoking.html">Starting Apache</A>. For a

reference guide to all Apache directives supported by the distributed

modules, see the <A HREF="mod/directives.html">Apache directives</A>.

<H2>Compiling Support Programs</H2>

In addition to the main <CODE>httpd</CODE> server which is compiled

time synchronization system on your Unix box, or whatever the

equivalent on NT would be.

<H3>Starting and Stopping the Server</H3>

To start the server, simply run <CODE>httpd</CODE>. This will look for

<CODE>httpd.conf</CODE> in the location compiled into the code (by

default <CODE>/usr/local/apache/conf/httpd.conf</CODE>). If

this file is somewhere else, you can give the real

location with the -f argument. For example:

<PRE>

    /usr/local/apache/httpd -f /usr/local/apache/conf/httpd.conf

</PRE>

If all goes well this will return to the command prompt almost

immediately.  This indicates that the server is now up and running. If

anything goes wrong during the initialization of the server you will

see an error message on the screen.

If the server started ok, you can now use your browser to

connect to the server and read the documentation. If you are running

the browser on the same machine as the server and using the default

port of 80, a suitable URL to enter into your browser is

<PRE>

    http://localhost/

</PRE>

<P>

Note that when the server starts it will create a number of

<EM>child</EM> processes to handle the requests. If you started Apache

as the root user, the parent process will continue to run as root

while the children will change to the user as given in the httpd.conf

file.

<P>

If when you run <CODE>httpd</CODE> it complained about being unable to

"bind" to an address, then either some other process is already using

the port you have configured Apache to use, or you are running httpd

as a normal user but trying to use a port below 1024 (such as the

default port 80).

<P>

If the server is not running, read the error message displayed

when you run httpd. You should also check the server

error_log for additional information (with the default configuration,

this will be located in the file <CODE>error_log</CODE> in the

<CODE>logs</CODE> directory).

<P>

If you want your server to continue running after a system reboot, you

should add a call to <CODE>httpd</CODE> to your system startup files

(typically <CODE>rc.local</CODE> or a file in an

<CODE>rc.<EM>N</EM></CODE> directory). This will start Apache as root.

Before doing this ensure that your server is properly configured

for security and access restrictions.

<P>

To stop Apache send the parent process a TERM signal. The PID of this

process is written to the file <CODE>httpd.pid</CODE> in the

<CODE>logs</CODE> directory (unless configured otherwise).  Do not

attempt to kill the child processes because they will be renewed by

the parent.  A typical command to stop the server is:

<PRE>

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

</PRE>

<P>

For more information about Apache command line options, configuration

and log files, see <A HREF="invoking.html">Starting Apache</A>. For a

reference guide to all Apache directives supported by the distributed

modules, see the <A HREF="mod/directives.html">Apache directives</A>.

<H2>Compiling Support Programs</H2>

In addition to the main <CODE>httpd</CODE> server which is compiled

<!--#include virtual="header.html" -->

<H1 ALIGN="CENTER">Starting Apache</H1>

<h2>Starting Apache On Windows</h2>

<ul>

<li><a href="#windows">Starting Apache on Windows</a></li>

<li><a href="#unix">Starting Apache on Unix</a>

<ul>

<li><a href="#errors">Errors During Start-up</a></li>

<li><a href="#boot">Starting at Boot-Time</a></li>

<li><a href="#info">Additional Information</a></li>

</ul>

</li>

</ul>

<hr>

<h2><a name="windows">Starting Apache On Windows</a></h2>

<p>On Windows, Apache is normally run as a service on Windows NT, or

as a console application on Windows 95. For details, see <A

HREF="platform/windows.html#run">running Apache for Windows</A>.</p>

<h2>Starting Apache on Unix</h2>

<h2><a name="unix">Starting Apache on Unix</a></h2>

<p>On Unix, the <code>httpd</code> program is run as a daemon

which executes continuously in the background to handle requests.

A shell script called <code>apachectl</code> is provided which

can be used to control the daemon process.  This shell script

can often be used as an init script to start <code>httpd</code>

on system boot, or it can be called directly with the options

listed below.</p>

<p>On Unix, the <a href="programs/httpd.html">httpd</a> program is run

as a daemon which executes continuously in the background to handle

requests.</p>

<p>If the <a href="mod/core.html#port">Port</a> specified in the

configuration file is the default of 80, then it is necessary to have

root privileges in order to start apache.  If Apache will not start

and no error messages are printed to the console, be sure to check the

<a href="mod/core.html#errorlog">ErrorLog</a> for a report of

the problem.  See also the debugging instructions outlined in

the Apache <a href="misc/FAQ.html">FAQ</a>.</p>

<h2>apachectl Command Line Options</h2>

<dl>

<dt><code>start</code></dt> <dd>Start <code>httpd</code>.  If

additional command line options need to be passed to

<code>httpd</code> (see below), then the <code>HTTPD</code> variable

at the top of the <code>apachectl</code> script should be edited to

include them.</dd>

<dt><code>stop</code></dt>

<dd>Stop <code>httpd</code> by issuing the kill signal to the

parent <code>httpd</code> process, whose process ID is contained

in the file pointed to by the 

<a href="mod/mpm_common.html#pidfile">PidFile</a> directive.</dd>

<dt><code>restart</code></dt>

<dd>Restart <code>httpd</code> if it is running by sending a 

<code>SIGHUP</code>

signal to the parent process.  If the server is not running, then

it will be started.  <code>apachectl</code> will refuse to

restart the server if there is a syntax error in the configuration

files (see <code>configtest</code> below).</dd>

<dt><code>graceful</code></dt> <dd>Restart <code>httpd</code> if it is

running by sending a <code>SIGWINCH</code> signal to the parent

process.  This type of restart is less disruptive to current clients.

If the server is not running, then it will be

started. <code>apachectl</code> will refuse to restart the server if

there is a syntax error in the configuration files.</dd>

<dt><code>fullstatus</code></dt>

<dd>Show a screen indicating the status of the Apache processes.

This option requires the presence of <code>lynx</code>, and

for <a href="mod/mod_status.html">mod_status</a> to be enabled.</dd>

<dt><code>status</code></dt>

<dd>A shorter form of the <code>fullstatus</code> display.

This option requires the presence of <code>lynx</code>, and

for <a href="mod/mod_status.html">mod_status</a> to be enabled.</dd>

<dt><code>configtest</code></dt>

<dd>Do a syntax test of the Apache configuration files.  See

the <code>httpd -t</code> command line option below.</dd>

<dt><code>help</code></dt>

<dd>Show a help screen.</dd>

</dl>

<p>For additional information on the effects of the various

<code>apachectl</code> options, see the documentation on <a

href="stopping.html">stopping and restarting Apache</a>.</p>

<H2>httpd Command Line Options</H2>

The following options are recognized on the httpd command line:

<DL>

<DT><CODE>-d</CODE> <EM>directory</EM>

<DD>Set the initial value for the

<A HREF="mod/core.html#serverroot">ServerRoot</A> variable to

<EM>directory</EM>. This can be overridden by the ServerRoot command

in the configuration file. The default is

<CODE>/usr/local/apache</CODE> on Unix, <CODE>/apache</CODE> on

Windows and <CODE>/os2httpd</CODE> on OS/2.

<DT><CODE>-D</CODE> <EM>name</EM>

<DD>Define a name for use in in 

<A HREF="mod/core.html#ifdefine">IfDefine</A> directives.

This option can be used to optionally enable certain functionality in the

configuration file, or to use a common configuration for

several independent hosts, where host specific information is enclosed in

<IfDefine> sections.

<DT><CODE>-f</CODE> <EM>file</EM>

<DD>Execute the commands in the <EM>file</EM> on startup. If

<EM>config</EM> does not begin with a <CODE>/</CODE>, then it is taken to be a

path relative to the <A HREF="mod/core.html#serverroot">ServerRoot</A>. The

default is <CODE>conf/httpd.conf</CODE>.

<DT><CODE>-C</CODE> <EM>"directive"</EM> 

<DD>Process the given apache "directive" (just as if it had been part

of a configuration file) <STRONG>before</STRONG> actually reading the

regular configuration files.

<DT><CODE>-c</CODE> <EM>"directive"</EM>

<DD>Process the given apache "directive" <STRONG>after</STRONG> reading

all the regular configuration files.

<DT><CODE>-v</CODE>

<DD>Print the version of httpd and its build date, and then exit.

<DT><A NAME="version"><CODE>-V</CODE></A>

<DD>Print the base version of httpd, its

build date, and a list of compile time settings which influence the

behavior and performance of the apache server (<EM>e.g.</EM>,

<SAMP>-DUSE_MMAP_FILES</SAMP>),

then exit.

<DT><A NAME="help"><CODE>-L</CODE></A>

<DD>Give a list of directives together with expected arguments and places

where the directive is valid, then exit.

<DT><CODE>-l</CODE></A>

<DD>Give a list of all modules compiled into the server, then exit.

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

<DD>Print a list of the httpd command line options, then exit.

<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.<br>

To check and print a summary of the current virtual host settings,

use <code>-t -D DUMP_VHOSTS</code>.</dd>

<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>-R</code> <em>directory</em></dt>

<dd>If Apache is compiled with <code>SHARED_CORE</code>, then this

directive can be used to specify an alternate location for shared

object files.</dd>

</DL>

<p>When Apache is used under Windows, the following additional 

command line options are available.</p>

<dl>

<dt><code>-n</code> <em>name</em></dt>

<dd>Set service name and use its ServerConfigFile.</dd>

<DT><CODE>-k</CODE> <EM>option</EM>

<DD>Signal Apache to restart or shutdown. <EM>option</EM> 

is one of "shutdown" or "restart".

<dt><code>-i</code></dt>

<dd>Install an Apache service</dd>

<dt><code>-u</code></dt>

<dd>Uninstall an Apache Service</dd>

</dl>

configuration file is the default of 80 (or any other port below

1024), then it is necessary to have root privileges in order to start

apache, so that it can bind to this privileged port.  Once the server

has started and performed a few preliminary activities such as opening

its log files, it will launch several <em>child</em> processes which

do the work of listening for and answering requests from clients.  The

main <code>httpd</code> process continues to run as the root user, but

the child processes run as a less privileged user.  This is controlled

by the selected <a href="mpm.html">Multi-Processing Module</a>.</p>

<p>The first thing that <code>httpd</code> does when it is invoked is

to locate and read the <a href="configuring.html">configuration

file</a> <code>httpd.conf</code>.  The location of this file is set at

compile-time, but it is possible to specify its location at run time

using the <code>-f</code> command-line option as in</p>

<blockquote><code> /usr/local/apache/bin/httpd -f

/usr/local/apache/conf/httpd.conf </code></blockquote>

<p>As an alternative to invoking the <code>httpd</code> binary

directly, a shell script called <a

href="programs/apachectl.html">apachectl</a> is provided which can be

used to control the daemon process with simple commands such as

<code>apachectl start</code> and <code>apachectl stop</code>.</p>

<p>If all goes well during startup, the server will detach from the

terminal and the command prompt will return almost immediately.

This indicates that the server is up and running.  You can then

use your browser to connect to the server and view the test

page in the <a href="mod/core.html#documentroot">DocumentRoot</a>

directory and the local copy of the documentation linked from

that page.</p>

<h3><a name="errors">Errors During Start-up</a></h3>

<p>If Apache suffers a fatal problem during startup, it will write a

message describing the problem either to the console or to the <a

href="mod/core.html#errorlog">ErrorLog</a> before exiting.  One of the

most common error messages is "<code>Unable to bind to Port

...</code>".  This message is usually caused by either:</p>

<ul>

<li>Trying to start the server on a privileged port when not

logged in as the root user; or</li>

<li>Trying to start the server when there is another instance

of Apache or some other web server already bound to the same Port.</li>

</ul>

<p>For further trouble-shooting instructions, consult the Apache <a

href="misc/FAQ.html">FAQ</a>.</p>

<h3><a name="boot">Starting at Boot-Time</a></h3>

<p>If you want your server to continue running after a system reboot,

you should add a call to <code>httpd</code> or <code>apachectl</code>

to your system startup files (typically <code>rc.local</code> or a

file in an <code>rc.N</code> directory). This will start Apache as

root. Before doing this ensure that your server is properly configured

for security and access restrictions.  The <code>apachectl</code>

script is designed so that it can often be linked directly as an init

script, but be sure to check the exact requirements of your system.</p>

<h3><a name="info">Additional Information</a></h3>

<p>Additional information about the command-line options of <a

href="programs/httpd.html">httpd</a> and <a

href="programs/apachectl.html">apachectl</a> as well as other support

programs included with the server is available on the <a

href="programs/">Server and Supporting Programs</a> page.  There is

also documentation on all the <a href="mod/">modules</a> included with

the Apache distribution and the <a

href="mod/directives.html">directives</a> that they provide.</p>

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