You are viewing a plain text version of this content. The canonical link for it is here.
Posted to cvs@httpd.apache.org by sl...@apache.org on 2001/01/28 00:32:50 UTC

cvs commit: httpd-2.0/docs/manual install.html invoking.html

slive       01/01/27 15:32:43

  Modified:    docs/manual install.html invoking.html
  Log:
  - Remove documentation on command line options from invoking.html
    since the man pages are now in the html docs.
  - Move information on "starting the server" from install.html to
    a more proper location "invoking.html"
  - Add a few more details here and there.
  
  Revision  Changes    Path
  1.31      +0 -78     httpd-2.0/docs/manual/install.html
  
  Index: install.html
  ===================================================================
  RCS file: /home/cvs/httpd-2.0/docs/manual/install.html,v
  retrieving revision 1.30
  retrieving revision 1.31
  diff -u -d -b -u -r1.30 -r1.31
  --- install.html	2000/12/21 22:35:55	1.30
  +++ install.html	2001/01/27 23:32:34	1.31
  @@ -183,84 +183,6 @@
   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
  
  
  
  1.31      +88 -171   httpd-2.0/docs/manual/invoking.html
  
  Index: invoking.html
  ===================================================================
  RCS file: /home/cvs/httpd-2.0/docs/manual/invoking.html,v
  retrieving revision 1.30
  retrieving revision 1.31
  diff -u -d -b -u -r1.30 -r1.31
  --- invoking.html	2000/11/28 21:46:50	1.30
  +++ invoking.html	2001/01/27 23:32:36	1.31
  @@ -15,185 +15,102 @@
   <!--#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
  -&lt;IfDefine&gt; 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>
  +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>
   
  -</DL>
  +<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>When Apache is used under Windows, the following additional 
  -command line options are available.</p>
  +<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>
   
  -<dl>
  +<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>
   
  -<dt><code>-n</code> <em>name</em></dt>
  -<dd>Set service name and use its ServerConfigFile.</dd>
  +<h3><a name="errors">Errors During Start-up</a></h3>
   
  -<DT><CODE>-k</CODE> <EM>option</EM>
  -<DD>Signal Apache to restart or shutdown. <EM>option</EM> 
  -is one of "shutdown" or "restart".
  +<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>
   
  -<dt><code>-i</code></dt>
  -<dd>Install an Apache service</dd>
  +<h3><a name="boot">Starting at Boot-Time</a></h3>
   
  -<dt><code>-u</code></dt>
  -<dd>Uninstall an Apache Service</dd>
  +<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>
   
  -</dl>
  +<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" -->