slive 01/01/27 14:36:07
Modified: htdocs/manual invoking.html install.html.en 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. This could still use more work, but it is a start. Suggestions welcome. Revision Changes Path 1.33 +92 -207 httpd-docs-1.3/htdocs/manual/invoking.html Index: invoking.html =================================================================== RCS file: /home/cvs/httpd-docs-1.3/htdocs/manual/invoking.html,v retrieving revision 1.32 retrieving revision 1.33 diff -u -d -b -u -r1.32 -r1.33 --- invoking.html 2001/01/03 18:41:38 1.32 +++ invoking.html 2001/01/27 22:36:07 1.33 @@ -15,221 +15,106 @@ <!--#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> +HREF="windows.html#run">running Apache for Windows</A>.</p> -<p>On Unix, the <code>httpd</code> program is run as a daemon which -executes continuously in the background to handle requests. It is -possible to invoke Apache by the Internet daemon <CODE>inetd</CODE> -each time a connection to the HTTP service is made (use the <A -HREF="mod/core.html#servertype">ServerType</A> directive) but this is -not recommended.</p> +<h2><a name="unix">Starting Apache on Unix</a></h2> -<p>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. It is possible to have Apache invoked by the Internet daemon +<CODE>inetd</CODE> each time a connection to the HTTP service is made +using the <A HREF="mod/core.html#servertype">ServerType</A> directive, +but this is not recommended.</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>Command line options</H2> -The following options are recognized on the httpd command line: -<DL> -<DT><CODE>-d</CODE> <EM>serverroot</EM> -<DD>Set the initial value for the -<A HREF="mod/core.html#serverroot">ServerRoot</A> variable to -<EM>serverroot</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 -<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>config</EM> -<DD>Execute the commands in the file <EM>config</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>-X</CODE> -<DD>Run in single-process mode, for internal debugging purposes only; the -daemon does not detach from the terminal or fork any children. Do <EM>NOT</EM> -use this mode to provide ordinary web service. - -<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><CODE>-L</CODE> -<DD> - -Give a list of directives together with expected arguments and places -where the directive is valid, then exit. (Apache 1.3.4 and -later. Earlier versions used -l instead). - - -<DT><CODE>-l</CODE> -<DD> - -Give a list of all modules compiled into the server, then exit. -(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><A NAME="help"><CODE>-h</CODE></A> -<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). +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 Apache's <a href="server-wide.html#process">process creation +directives</a>.</p> -<DT><CODE>-?</CODE> -<DD>Print a list of the httpd options, and then exit (up to Apache -1.3.3. Later versions use -h instead). +<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> -<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> +<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> -<p>When Apache is used under Windows, the following additional -command line options are available.</p> +<h3><a name="errors">Errors During Start-up</a></h3> -<dl> +<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>-n</code> <em>name</em></dt> -<dd>Set service name and use its ServerConfigFile.</dd> +<h3><a name="boot">Starting at Boot-Time</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 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> -<dt><code>-i</code></dt> -<dd>Install an Apache service</dd> +<h3><a name="info">Additional Information</a></h3> -<dt><code>-u</code></dt> -<dd>Uninstall an Apache Service</dd> +<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> -</dl> <!--#include virtual="footer.html" --> </BODY> 1.31 +0 -78 httpd-docs-1.3/htdocs/manual/install.html.en Index: install.html.en =================================================================== RCS file: /home/cvs/httpd-docs-1.3/htdocs/manual/install.html.en,v retrieving revision 1.30 retrieving revision 1.31 diff -u -d -b -u -r1.30 -r1.31 --- install.html.en 2000/12/18 17:27:03 1.30 +++ install.html.en 2001/01/27 22:36:07 1.31 @@ -178,84 +178,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
