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

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