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


git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@87877 13f79535-47bb-0310-9956-ffa450edef68

1 files changed, 88 insertions, 171 deletions

diff --git a/docs/manual/invoking.html.en b/docs/manual/invoking.html.en
index 49746bfcc1..9f42048c62 100644
--- a/docs/manual/invoking.html.en
+++ b/docs/manual/invoking.html.en
@@ -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>
-
-</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" -->