granicus.if.org Git - apache/blob - docs/manual/platform/win_service.html.en

   1 <?xml version="1.0" encoding="ISO-8859-1"?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
   3 <html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"><head><!--
   4         XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
   5               This file is generated from xml source: DO NOT EDIT
   6         XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
   7       --><title>Running Apache for Windows as a Service - Apache HTTP Server</title><link href="../style/css/manual.css" rel="stylesheet" media="all" type="text/css" title="Main stylesheet" /><link href="../style/css/manual-loose-100pc.css" rel="alternate stylesheet" media="all" type="text/css" title="No Sidebar - Default font size" /><link href="../style/css/manual-print.css" rel="stylesheet" media="print" type="text/css" /><link href="../images/favicon.ico" rel="shortcut icon" /></head><body id="manual-page"><div id="page-header"><p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/directives.html">Directives</a> | <a href="../faq/">FAQ</a> | <a href="../glossary.html">Glossary</a> | <a href="../sitemap.html">Sitemap</a></p><p class="apache">Apache HTTP Server Version 2.0</p><img alt="" src="../images/feather.gif" /></div><div class="up"><a href="./"><img title="&lt;-" alt="&lt;-" src="../images/left.gif" /></a></div><div id="path"><a href="http://www.apache.org/">Apache</a> &gt; <a href="http://httpd.apache.org/">HTTP Server</a> &gt; <a href="http://httpd.apache.org/docs-project/">Documentation</a> &gt; <a href="../">Version 2.0</a></div><div id="page-content"><div id="preamble"><h1>Running Apache for Windows as a Service</h1>
   8
   9     <p>Apache can be run as a service on Windows NT/2000. (There is
  10     also some HIGHLY EXPERIMENTAL support for similar behavior on
  11     <a href="#win95svc">Windows 95/98</a>, introduced with Apache
  12     1.3.13).</p>
  13
  14     <p>Installing Apache as a service should only be done once you
  15     can successfully run it in a console window. See <a href="windows.html">Using Apache with Microsoft Windows</a>
  16     before you attempt to install or run Apache as a service.
  17     Changes to the <code>httpd.conf</code> file should always be
  18     followed by starting Apache as a console window. If this
  19     succeeds, the service should succeed.</p>
  20
  21     <div class="note"><strong>Prior to version 1.3.13, the configuration was
  22     <em>not tested</em> prior to performing the
  23     installation</strong>, and a lack of service dependencies often
  24     caused the console window to succeed, but the service would
  25     still fail. See <a href="#service">below</a> if you are having
  26     problems running a version of Apache prior to 1.3.13 to resolve
  27     the issue. If you have this problem with version 1.3.13 or
  28     greater, first try uninstalling (<code>-u</code>) and re-installing
  29     (<code>-i</code>) the Apache service.</div>
  30
  31     <p>To start Apache as a service, you first need to install it
  32     as a service. Multiple Apache services can be installed, each
  33     with a different name and configuration. To install the default
  34     Apache service named "Apache", run the "Install Apache as
  35     Service (NT only)" option from the Start menu. Once this is
  36     done you can start the "Apache" service by opening the Services
  37     window (in the Control Panel), selecting Apache, then clicking
  38     on Start. Apache will now be running, hidden in the background.
  39     You can later stop Apache by clicking on Stop. As an
  40     alternative to using the Services window, you can start and
  41     stop the "Apache" service from the command line with</p>
  42
  43     <div class="example"><p><code>
  44       NET START APACHE<br />
  45       NET STOP APACHE
  46     </code></p></div>
  47
  48     <p>See <a href="#signal">Controlling Apache as a Service</a>
  49     for more information on installing and controlling Apache
  50     services.</p>
  51
  52     <div class="note"><h3>Note</h3>
  53     Apache, unlike many other Windows NT/2000 services,
  54     logs any errors to its own error.log file in the logs folder
  55     within the Apache server root folder. You will <em>not</em>
  56     find Apache error details in the Windows NT Event
  57     Log.</div>
  58
  59     <p>After starting Apache as a service (or if you have trouble
  60     starting it) you can test it using the same <a href="windows.html#cmdline">procedure</a> as for running in a
  61     console window. Remember to use the command:</p>
  62
  63     <div class="example"><p><code>
  64       apache -n "service name"
  65     </code></p></div>
  66
  67     <p>to assure you are using the service's configuration.</p>
  68
  69   </div><div id="quickview"><ul id="toc"><li><img alt="" src="../images/down.gif" /> <a href="#service">Running Apache for Windows as a Service</a></li><li><img alt="" src="../images/down.gif" /> <a href="#depends">Important Note on service dependencies:</a></li><li><img alt="" src="../images/down.gif" /> <a href="#account">User Account for Apache Service to Run As (NT/2000)</a></li><li><img alt="" src="../images/down.gif" /> <a href="#trouble">Troubleshooting Apache for Windows as a Service</a></li><li><img alt="" src="../images/down.gif" /> <a href="#cmdline">Running Apache for Windows from the Command Line</a></li><li><img alt="" src="../images/down.gif" /> <a href="#signal">Controlling Apache as a Service</a></li><li><img alt="" src="../images/down.gif" /> <a href="#win95svc">HIGHLY EXPERIMENTAL Windows 95/98 Service</a></li></ul></div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div><div class="section"><h2><a name="service" id="service">Running Apache for Windows as a Service</a></h2>
  70
  71
  72
  73     <div class="note"><strong>The <code>-n</code> option to specify a service
  74     name is only available with Apache 1.3.7 and later.</strong>
  75     Earlier versions of Apache only support the default service name
  76     "Apache".</div>
  77
  78     <p>You can install Apache as a Windows NT service as
  79     follows:</p>
  80
  81     <div class="example"><p><code>
  82       apache -i -n "service name"
  83     </code></p></div>
  84
  85     <p>To install a service to use a particular configuration,
  86     specify the configuration file when the service is
  87     installed:</p>
  88
  89     <div class="example"><p><code>
  90       apache -i -n "service name" -f "\my server\conf\my.conf"
  91     </code></p></div>
  92
  93     <p>To remove an Apache service, use:</p>
  94
  95     <div class="example"><p><code>
  96       apache -u -n "service name"
  97     </code></p></div>
  98
  99     <p>The default "service name", if one is not specified, is
 100     "Apache".</p>
 101
 102     <p>Once a service is installed, you can use the <code>-n</code>
 103     option, in conjunction with other options, to refer to a
 104     service's configuration file. For example:</p>
 105
 106     <p>To test a service's configuration file:</p>
 107
 108     <div class="example"><p><code>
 109       apache -n "service name" -t
 110     </code></p></div>
 111
 112     <p>To start a console Apache using a service's configuration
 113     file:</p>
 114
 115     <div class="example"><p><code>
 116       apache -n "service name"
 117     </code></p></div>
 118
 119   </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div><div class="section"><h2><a name="depends" id="depends">Important Note on service dependencies:</a></h2>
 120
 121
 122
 123     <p>Prior to Apache release 1.3.13, the dependencies required to
 124     successfully start an installed service were not configured.
 125     After installing a service using earlier versions of Apache,
 126     you must follow these steps:</p>
 127
 128     <div class="example"><p><code>
 129       Run regedt32 <br />
 130       Select Window - "HKEY_LOCAL_MACHINE on Local Machine" from the menu <br />
 131       Double-click to open the SYSTEM, then the CurrentControlSet keys <br />
 132       Scroll down and click on the Apache servicename <br />
 133       Select Edit - Add Value... from the menu <br />
 134       Fill in the Add Value dialog with <br />
 135           Value Name: DependOnGroup <br />
 136           Data Type: REG_MULTI_SZ <br />
 137           and click OK <br />
 138       Leave the Multi-String Editor dialog empty and click OK <br />
 139       Select Edit - Add Value... from the menu <br />
 140       Fill in the Add Value dialog with <br />
 141           Value Name: DependOnService <br />
 142           Data Type: REG_MULTI_SZ <br />
 143           and click OK <br />
 144       Type the following list (one per line) in the Multi-String Editor dialog <br />
 145           Tcpip <br />
 146           Afd <br />
 147           and click OK <br />
 148     </code></p></div>
 149
 150     <p>If you are using COM or DCOM components from a third party
 151     module, ISAPI, or other add-in scripting technologies such as
 152     ActiveState Perl, you may also need to add the entry Rpcss to
 153     the DependOnService list. To avoid exposing the TCP port 135
 154     when it is unnecessary, Apache does not create that entry upon
 155     installation. Follow the directions above to find or create the
 156     DependOnService value, double click that value if it already
 157     exists, and add the Rpcss entry to the list.</p>
 158
 159   </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div><div class="section"><h2><a name="account" id="account">User Account for Apache Service to Run As (NT/2000)</a></h2>
 160
 161
 162
 163     <p>When Apache is first installed as a service (e.g. with the
 164     <code>-i</code> option) it will run as user "System" (the LocalSystem
 165     account). There should be few issues if all resources for the
 166     web server reside on the local system, but it has broad
 167     security privileges to affect the local machine!</p>
 168
 169     <div class="note">LocalSystem is a very privileged account locally, so you
 170     shouldn't run any shareware applications there. However, it
 171     has no network privileges and cannot leave the machine via
 172     any NT-secured mechanism, including file system, named pipes,
 173     DCOM, or secure RPC.</div>
 174
 175     <p><strong>NEVER grant network privileges to the SYSTEM
 176     account!</strong> Create a new user account instead, grant the
 177     appropriate privileges to that user, and use the the "Log On
 178     As:" option. Select the Start Menu -&gt; Settings -&gt; Control
 179     Panel -&gt; Services -&gt; apache service ... and click the
 180     "Startup" button to access this setting.</p>
 181
 182     <div class="note">A service that runs in the context of the LocalSystem account
 183     inherits the security context of the SCM. It is not
 184     associated with any logged-on user account and does not have
 185     credentials (domain name, user name, and password) to be used
 186     for verification.</div>
 187
 188     <p>The SYSTEM account has no privileges to the network, so
 189     shared pages or a shared installation of Apache is invisible to
 190     the service. If you intend to use <em>any</em> network
 191     resources, the following steps should help:</p>
 192
 193     <ul>
 194       <li>Select Apache from the Control Panel's Service dialog and
 195       click Startup.</li>
 196
 197       <li>Verify that the service account is correct. You may wish
 198       to create an account for your Apache services.</li>
 199
 200       <li>Retype the password and password confirmation.</li>
 201
 202       <li>Go to User Manager for Domains.</li>
 203
 204       <li>Click on Policies from the title bar menu, and select
 205       User Rights.</li>
 206
 207       <li>Select the option for Advanced User Rights.</li>
 208
 209       <li>
 210         In the drop-down list, verify that the following rights
 211         have been granted to the selected account:
 212
 213         <ul>
 214           <li>Act as part of the operating system</li>
 215
 216           <li>Back up files and directories</li>
 217
 218           <li>Log on as a service</li>
 219
 220           <li>Restore files and directories</li>
 221         </ul>
 222       </li>
 223
 224       <li>Confirm that the selected account is a member of the
 225       Users group.</li>
 226
 227       <li>Confirm the selected account has access to all
 228       <code>document</code> and <code>script</code>
 229       directories (minimally read and browse access).</li>
 230
 231       <li>Confirm the selected account has read/write/delete access
 232       to the Apache <code>logs</code> directory!</li>
 233     </ul>
 234
 235     <p>If you allow the account to log in as a user, then you can
 236     log in yourself and test that the account has the privileges to
 237     execute the scripts, read the web pages, and that you can start
 238     Apache in a console window. If this works, and you have
 239     followed the steps above, Apache should execute as a service
 240     with no problems.</p>
 241
 242     <div class="note"><strong>Error code 2186</strong> is a good indication
 243     that you need to review the "Log On As" configuration, since
 244     the server can't access a required network resource.</div>
 245
 246   </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div><div class="section"><h2><a name="trouble" id="trouble">Troubleshooting Apache for Windows as a Service</a></h2>
 247
 248
 249
 250     <p>When starting Apache as a service you may encounter an error
 251     message from Windows service manager. For example if you try to
 252     start Apache using the Services applet in Windows Control Panel
 253     you may get the following message:</p>
 254
 255     <div class="example"><p><code>
 256       Could not start the apache service on \\COMPUTER <br />
 257       Error 1067; The process terminated unexpectedly.
 258     </code></p></div>
 259
 260     <p>You will get this error if there is any problem starting
 261     Apache. In order to see what is causing the problem you should
 262     follow the instructions for <a href="windows.html#cmdline">Running Apache for Windows from the
 263     Command Line</a>.</p>
 264
 265     <p>Also, Apache 1.3.13 now records startup errors in the
 266     Application Event Log under Windows NT/2000, if Apache is run
 267     as a service. Run the Event Viewer and select Log ...
 268     Application to see these events.</p>
 269
 270     <div class="note"><strong>Check the Application Event Log with the Event
 271     Viewer in case of any problems, even if no error message pops
 272     up to warn you that an error occured.</strong></div>
 273
 274   </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div><div class="section"><h2><a name="cmdline" id="cmdline">Running Apache for Windows from the Command Line</a></h2>
 275
 276
 277
 278     <p>For details on controlling Apache service from the command
 279     line, please refer to <a href="windows.html#cmdline">console
 280     command line</a> section.</p>
 281
 282   </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div><div class="section"><h2><a name="signal" id="signal">Controlling Apache as a Service</a></h2>
 283
 284
 285
 286     <p>Multiple instances of Apache can be installed and run as
 287     services. Signal an installed Apache service to start, restart,
 288     or shutdown/stop as follows:</p>
 289
 290     <div class="example"><p><code>
 291       apache -n "service name" -k start <br />
 292       apache -n "service name" -k restart <br />
 293       apache -n "service name" -k shutdown <br />
 294       apache -n "service name" -k stop
 295     </code></p></div>
 296
 297     <p>For the default "Apache" service, the <code>-n</code> Apache
 298     option is still required, since the <code>-k</code> commands without
 299     the <code>-n</code> option are directed at Apache running in a console
 300     window. The quotes are only required if the service name contains spaces.</p>
 301
 302     <div class="note"><strong>Note the <code>-k stop</code> alias for the
 303     <code>-k shutdown</code> command was introduced in Apache version
 304     1.3.13.</strong> Earlier versions of Apache will only recognize the
 305     <code>-k shutdown</code> option. Prior to 1.3.3, Apache did not
 306     recognize <em>any</em> <code>-k</code> options at all!</div>
 307
 308     <p>In addition, you can use the native NT <code>NET</code> command
 309     to start and stop Apache services as follows:</p>
 310
 311     <div class="example"><p><code>
 312       NET START "service name" <br />
 313       NET STOP "service name"
 314     </code></p></div>
 315
 316     <p>Again, quotes are only required if the service name contains
 317     spaces.</p>
 318
 319   </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div><div class="section"><h2><a name="win95svc" id="win95svc">HIGHLY EXPERIMENTAL Windows 95/98 Service</a></h2>
 320
 321
 322
 323     <div class="note"><strong>The service options for Windows 95 and 98 are
 324     only available with Apache 1.3.13 and later.</strong> Earlier
 325     versions of Apache only supported Apache in a console window
 326     for Windows 95/98.</div>
 327
 328     <p>There is some support for Apache on Windows 95/98 to behave
 329     in a similar manner as a service on Windows NT/2000. It is
 330     <em>highly experimental</em>, if it works (at all) the Apache
 331     Sofware Foundation will not attest to its reliability or
 332     future support. Proceed at your own risk!</p>
 333
 334     <p>Once you have confirmed that Apache runs correctly at the <a href="windows.html#cmdline">Command Prompt</a> you can install,
 335     control and uninstall it with the same commands as the Windows
 336     NT/2000 version.</p>
 337
 338     <p>There are, however, significant differences that you should
 339     note:</p>
 340
 341     <p>Apache will attempt to start and if successful it will run
 342     in the background. If you run the command</p>
 343
 344     <div class="example"><p><code>
 345       Apache -n "service name" -k start
 346     </code></p></div>
 347
 348     <p>via a shortcut on your desktop, for example, then if the
 349     service starts successfully a console window will flash up but
 350     immediately disappears. If Apache detects any errors on startup
 351     such as a incorrect entries in the <code>httpd.conf</code> file,
 352     then the console window will remain visible. This will display
 353     an error message which will be useful in tracking down the cause
 354     of the problem.</p>
 355
 356     <p>Windows 95/98 does not support <code>NET START</code> or
 357     <code>NET STOP</code> commands so you must use Apache's Service
 358     Control options at a command prompt. You may wish to set up a
 359     shortcut for each of these commands so that you can just choose
 360     it from the start menu or desktop to perform the required action.</p>
 361
 362     <p>Apache and Windows 95/98 offer no support for running the
 363     Apache service as a specific user with network privileges. In
 364     fact, Windows 95/98 offers no security on the local machine,
 365     either. This is the simple reason that the Apache Software
 366     Foundation never endorses the use of Windows 95/98 as a public
 367     httpd server. These facilities exist only to assist the user in
 368     developing web content and learning the Apache server, and
 369     perhaps as a intranet server on a secured, private network.</p>
 370
 371   </div></div><div id="footer"><p class="apache">Maintained by the <a href="http://httpd.apache.org/docs-project/">Apache HTTP Server Documentation Project</a></p><p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/directives.html">Directives</a> | <a href="../faq/">FAQ</a> | <a href="../glossary.html">Glossary</a> | <a href="../sitemap.html">Sitemap</a></p></div></body></html>