| <?xml version="1.0" encoding="UTF-8" ?> |
| <!DOCTYPE manualpage SYSTEM "../style/manualpage.dtd"> |
| <?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?> |
| |
| <manualpage> |
| <relativepath href=".." /> |
| <parentdocument href="./">Platform Specific Notes</parentdocument> |
| |
| <title>Running Apache for Windows as a Service</title> |
| |
| <summary> |
| |
| <p>Apache can be run as a service on Windows NT/2000. (There is |
| also some HIGHLY EXPERIMENTAL support for similar behavior on |
| <a href="#win95svc">Windows 95/98</a>, introduced with Apache |
| 1.3.13).</p> |
| |
| <p>Installing Apache as a service should only be done once you |
| can successfully run it in a console window. See <a |
| href="windows.html">Using Apache with Microsoft Windows</a> |
| before you attempt to install or run Apache as a service. |
| Changes to the <code>httpd.conf</code> file should always be |
| followed by starting Apache as a console window. If this |
| succeeds, the service should succeed.</p> |
| |
| <note><strong>Prior to version 1.3.13, the configuration was |
| <em>not tested</em> prior to performing the |
| installation</strong>, and a lack of service dependencies often |
| caused the console window to succeed, but the service would |
| still fail. See <a href="#service">below</a> if you are having |
| problems running a version of Apache prior to 1.3.13 to resolve |
| the issue. If you have this problem with version 1.3.13 or |
| greater, first try uninstalling (<code>-u</code>) and re-installing |
| (<code>-i</code>) the Apache service.</note> |
| |
| <p>To start Apache as a service, you first need to install it |
| as a service. Multiple Apache services can be installed, each |
| with a different name and configuration. To install the default |
| Apache service named "Apache", run the "Install Apache as |
| Service (NT only)" option from the Start menu. Once this is |
| done you can start the "Apache" service by opening the Services |
| window (in the Control Panel), selecting Apache, then clicking |
| on Start. Apache will now be running, hidden in the background. |
| You can later stop Apache by clicking on Stop. As an |
| alternative to using the Services window, you can start and |
| stop the "Apache" service from the command line with</p> |
| |
| <example> |
| NET START APACHE<br /> |
| NET STOP APACHE |
| </example> |
| |
| <p>See <a href="#signal">Controlling Apache as a Service</a> |
| for more information on installing and controlling Apache |
| services.</p> |
| |
| <note><title>Note</title> |
| Apache, unlike many other Windows NT/2000 services, |
| logs any errors to its own error.log file in the logs folder |
| within the Apache server root folder. You will <em>not</em> |
| find Apache error details in the Windows NT Event |
| Log.</note> |
| |
| <p>After starting Apache as a service (or if you have trouble |
| starting it) you can test it using the same <a |
| href="windows.html#cmdline">procedure</a> as for running in a |
| console window. Remember to use the command:</p> |
| |
| <example> |
| apache -n "service name" |
| </example> |
| |
| <p>to assure you are using the service's configuration.</p> |
| |
| </summary> |
| |
| <section id="service"> |
| |
| <title>Running Apache for Windows as a Service</title> |
| |
| <note><strong>The <code>-n</code> option to specify a service |
| name is only available with Apache 1.3.7 and later.</strong> |
| Earlier versions of Apache only support the default service name |
| "Apache".</note> |
| |
| <p>You can install Apache as a Windows NT service as |
| follows:</p> |
| |
| <example> |
| apache -i -n "service name" |
| </example> |
| |
| <p>To install a service to use a particular configuration, |
| specify the configuration file when the service is |
| installed:</p> |
| |
| <example> |
| apache -i -n "service name" -f "\my server\conf\my.conf" |
| </example> |
| |
| <p>To remove an Apache service, use:</p> |
| |
| <example> |
| apache -u -n "service name" |
| </example> |
| |
| <p>The default "service name", if one is not specified, is |
| "Apache".</p> |
| |
| <p>Once a service is installed, you can use the <code>-n</code> |
| option, in conjunction with other options, to refer to a |
| service's configuration file. For example:</p> |
| |
| <p>To test a service's configuration file:</p> |
| |
| <example> |
| apache -n "service name" -t |
| </example> |
| |
| <p>To start a console Apache using a service's configuration |
| file:</p> |
| |
| <example> |
| apache -n "service name" |
| </example> |
| |
| </section> |
| |
| <section id="depends"> |
| |
| <title>Important Note on service dependencies:</title> |
| |
| <p>Prior to Apache release 1.3.13, the dependencies required to |
| successfully start an installed service were not configured. |
| After installing a service using earlier versions of Apache, |
| you must follow these steps:</p> |
| |
| <example> |
| Run regedt32 <br /> |
| Select Window - "HKEY_LOCAL_MACHINE on Local Machine" from the menu <br /> |
| Double-click to open the SYSTEM, then the CurrentControlSet keys <br /> |
| Scroll down and click on the Apache servicename <br /> |
| Select Edit - Add Value... from the menu <br /> |
| Fill in the Add Value dialog with <br /> |
|     Value Name: DependOnGroup <br /> |
|     Data Type: REG_MULTI_SZ <br /> |
|     and click OK <br /> |
| Leave the Multi-String Editor dialog empty and click OK <br /> |
| Select Edit - Add Value... from the menu <br /> |
| Fill in the Add Value dialog with <br /> |
|     Value Name: DependOnService <br /> |
|     Data Type: REG_MULTI_SZ <br /> |
|     and click OK <br /> |
| Type the following list (one per line) in the Multi-String Editor dialog <br /> |
|     Tcpip <br /> |
|     Afd <br /> |
|     and click OK <br /> |
| </example> |
| |
| <p>If you are using COM or DCOM components from a third party |
| module, ISAPI, or other add-in scripting technologies such as |
| ActiveState Perl, you may also need to add the entry Rpcss to |
| the DependOnService list. To avoid exposing the TCP port 135 |
| when it is unnecessary, Apache does not create that entry upon |
| installation. Follow the directions above to find or create the |
| DependOnService value, double click that value if it already |
| exists, and add the Rpcss entry to the list.</p> |
| |
| </section> |
| |
| <section id="account"> |
| |
| <title>User Account for Apache Service to Run As (NT/2000)</title> |
| |
| <p>When Apache is first installed as a service (e.g. with the |
| <code>-i</code> option) it will run as user "System" (the LocalSystem |
| account). There should be few issues if all resources for the |
| web server reside on the local system, but it has broad |
| security privileges to affect the local machine!</p> |
| |
| <note>LocalSystem is a very privileged account locally, so you |
| shouldn't run any shareware applications there. However, it |
| has no network privileges and cannot leave the machine via |
| any NT-secured mechanism, including file system, named pipes, |
| DCOM, or secure RPC.</note> |
| |
| <p><strong>NEVER grant network privileges to the SYSTEM |
| account!</strong> Create a new user account instead, grant the |
| appropriate privileges to that user, and use the the "Log On |
| As:" option. Select the Start Menu -> Settings -> Control |
| Panel -> Services -> apache service ... and click the |
| "Startup" button to access this setting.</p> |
| |
| <note>A service that runs in the context of the LocalSystem account |
| inherits the security context of the SCM. It is not |
| associated with any logged-on user account and does not have |
| credentials (domain name, user name, and password) to be used |
| for verification.</note> |
| |
| <p>The SYSTEM account has no privileges to the network, so |
| shared pages or a shared installation of Apache is invisible to |
| the service. If you intend to use <em>any</em> network |
| resources, the following steps should help:</p> |
| |
| <ul> |
| <li>Select Apache from the Control Panel's Service dialog and |
| click Startup.</li> |
| |
| <li>Verify that the service account is correct. You may wish |
| to create an account for your Apache services.</li> |
| |
| <li>Retype the password and password confirmation.</li> |
| |
| <li>Go to User Manager for Domains.</li> |
| |
| <li>Click on Policies from the title bar menu, and select |
| User Rights.</li> |
| |
| <li>Select the option for Advanced User Rights.</li> |
| |
| <li> |
| In the drop-down list, verify that the following rights |
| have been granted to the selected account: |
| |
| <ul> |
| <li>Act as part of the operating system</li> |
| |
| <li>Back up files and directories</li> |
| |
| <li>Log on as a service</li> |
| |
| <li>Restore files and directories</li> |
| </ul> |
| </li> |
| |
| <li>Confirm that the selected account is a member of the |
| Users group.</li> |
| |
| <li>Confirm the selected account has access to all |
| <code>document</code> and <code>script</code> |
| directories (minimally read and browse access).</li> |
| |
| <li>Confirm the selected account has read/write/delete access |
| to the Apache <code>logs</code> directory!</li> |
| </ul> |
| |
| <p>If you allow the account to log in as a user, then you can |
| log in yourself and test that the account has the privileges to |
| execute the scripts, read the web pages, and that you can start |
| Apache in a console window. If this works, and you have |
| followed the steps above, Apache should execute as a service |
| with no problems.</p> |
| |
| <note><strong>Error code 2186</strong> is a good indication |
| that you need to review the "Log On As" configuration, since |
| the server can't access a required network resource.</note> |
| |
| </section> |
| |
| <section id="trouble"> |
| |
| <title>Troubleshooting Apache for Windows as a Service</title> |
| |
| <p>When starting Apache as a service you may encounter an error |
| message from Windows service manager. For example if you try to |
| start Apache using the Services applet in Windows Control Panel |
| you may get the following message:</p> |
| |
| <example> |
| Could not start the apache service on \\COMPUTER <br /> |
| Error 1067; The process terminated unexpectedly. |
| </example> |
| |
| <p>You will get this error if there is any problem starting |
| Apache. In order to see what is causing the problem you should |
| follow the instructions for <a |
| href="windows.html#cmdline">Running Apache for Windows from the |
| Command Line</a>.</p> |
| |
| <p>Also, Apache 1.3.13 now records startup errors in the |
| Application Event Log under Windows NT/2000, if Apache is run |
| as a service. Run the Event Viewer and select Log ... |
| Application to see these events.</p> |
| |
| <note><strong>Check the Application Event Log with the Event |
| Viewer in case of any problems, even if no error message pops |
| up to warn you that an error occured.</strong></note> |
| |
| </section> |
| |
| <section id="cmdline"> |
| |
| <title>Running Apache for Windows from the Command Line</title> |
| |
| <p>For details on controlling Apache service from the command |
| line, please refer to <a href="windows.html#cmdline">console |
| command line</a> section.</p> |
| |
| </section> |
| |
| <section id="signal"> |
| |
| <title>Controlling Apache as a Service</title> |
| |
| <p>Multiple instances of Apache can be installed and run as |
| services. Signal an installed Apache service to start, restart, |
| or shutdown/stop as follows:</p> |
| |
| <example> |
| apache -n "service name" -k start <br /> |
| apache -n "service name" -k restart <br /> |
| apache -n "service name" -k shutdown <br /> |
| apache -n "service name" -k stop |
| </example> |
| |
| <p>For the default "Apache" service, the <code>-n</code> Apache |
| option is still required, since the <code>-k</code> commands without |
| the <code>-n</code> option are directed at Apache running in a console |
| window. The quotes are only required if the service name contains spaces.</p> |
| |
| <note><strong>Note the <code>-k stop</code> alias for the |
| <code>-k shutdown</code> command was introduced in Apache version |
| 1.3.13.</strong> Earlier versions of Apache will only recognize the |
| <code>-k shutdown</code> option. Prior to 1.3.3, Apache did not |
| recognize <em>any</em> <code>-k</code> options at all!</note> |
| |
| <p>In addition, you can use the native NT <code>NET</code> command |
| to start and stop Apache services as follows:</p> |
| |
| <example> |
| NET START "service name" <br /> |
| NET STOP "service name" |
| </example> |
| |
| <p>Again, quotes are only required if the service name contains |
| spaces.</p> |
| |
| </section> |
| |
| <section id="win95svc"> |
| |
| <title>HIGHLY EXPERIMENTAL Windows 95/98 Service</title> |
| |
| <note><strong>The service options for Windows 95 and 98 are |
| only available with Apache 1.3.13 and later.</strong> Earlier |
| versions of Apache only supported Apache in a console window |
| for Windows 95/98.</note> |
| |
| <p>There is some support for Apache on Windows 95/98 to behave |
| in a similar manner as a service on Windows NT/2000. It is |
| <em>highly experimental</em>, if it works (at all) the Apache |
| Sofware Foundation will not attest to its reliability or |
| future support. Proceed at your own risk!</p> |
| |
| <p>Once you have confirmed that Apache runs correctly at the <a |
| href="windows.html#cmdline">Command Prompt</a> you can install, |
| control and uninstall it with the same commands as the Windows |
| NT/2000 version.</p> |
| |
| <p>There are, however, significant differences that you should |
| note:</p> |
| |
| <p>Apache will attempt to start and if successful it will run |
| in the background. If you run the command</p> |
| |
| <example> |
| Apache -n "service name" -k start |
| </example> |
| |
| <p>via a shortcut on your desktop, for example, then if the |
| service starts successfully a console window will flash up but |
| immediately disappears. If Apache detects any errors on startup |
| such as a incorrect entries in the <code>httpd.conf</code> file, |
| then the console window will remain visible. This will display |
| an error message which will be useful in tracking down the cause |
| of the problem.</p> |
| |
| <p>Windows 95/98 does not support <code>NET START</code> or |
| <code>NET STOP</code> commands so you must use Apache's Service |
| Control options at a command prompt. You may wish to set up a |
| shortcut for each of these commands so that you can just choose |
| it from the start menu or desktop to perform the required action.</p> |
| |
| <p>Apache and Windows 95/98 offer no support for running the |
| Apache service as a specific user with network privileges. In |
| fact, Windows 95/98 offers no security on the local machine, |
| either. This is the simple reason that the Apache Software |
| Foundation never endorses the use of Windows 95/98 as a public |
| httpd server. These facilities exist only to assist the user in |
| developing web content and learning the Apache server, and |
| perhaps as a intranet server on a secured, private network.</p> |
| |
| </section> |
| |
| </manualpage> |
| |
