granicus.if.org Git - apache/blob - docs/manual/platform/windows.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>Using Apache with Microsoft Windows</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">Using Apache with Microsoft Windows</h1>
  17
  18     <p>This document explains how to install, configure and run
  19     Apache 2.0 under Microsoft Windows. If you find any bugs, or
  20     wish to contribute in other ways, please use our <a
  21     href="http://httpd.apache.org/bug_report.html">bug reporting page.</a></p>
  22
  23     <p>Most of this document assumes that you are installing
  24     Windows from a binary distribution. If you want to compile
  25     Apache yourself (possibly to help with development, or to track
  26     down bugs), see <a href="win_compiling.html">Compiling Apache
  27     for Microsoft Windows</a>.</p>
  28
  29     <p><strong>At this time, support for Windows 95, 98 and ME is
  30     incomplete. Apache 2.0 is not expected to work on those
  31     platforms at this time.</strong> If you are interested in
  32     helping with that effort, please see the developer's site for
  33     information on <a href="http://dev.apache.org/">how to get
  34     involved</a>. Support will likely be provided at some point in
  35     the future, and patches to allow Apache to work on 95, 98 and
  36     ME are welcome!</p>
  37     <hr />
  38
  39     <ul>
  40       <li><a href="#req">Requirements</a></li>
  41
  42       <li><a href="#down">Downloading Apache for Windows</a></li>
  43
  44       <li><a href="#inst">Installing Apache for Windows (binary
  45       install)</a></li>
  46
  47       <li><a href="#run">Running Apache for Windows</a></li>
  48
  49       <li><a href="#use">Using Apache for Windows</a></li>
  50
  51       <li><a href="#cmdline">Running Apache for Windows from the
  52       Command Line</a></li>
  53
  54       <li><a href="win_service.html">Running Apache for Windows as
  55       a Service</a></li>
  56
  57       <li><a href="win_service.html#signal">Controlling Apache as a
  58       Service</a></li>
  59
  60       <li><a href="win_compiling.html">Compiling Apache for
  61       Microsoft Windows</a></li>
  62     </ul>
  63     <hr />
  64
  65     <h2><a id="req" name="req">Requirements</a></h2>
  66
  67     <p>Apache 2.0 is designed to run on Windows NT 4.0 and Windows
  68     2000. The binary installer will only work with the x86 family
  69     of processors, such as Intel's. Apache may also run on Windows
  70     95, 98 and ME, but these are not tested, and are never
  71     recommended for production servers. In all cases TCP/IP
  72     networking must be installed.</p>
  73
  74     <p>If running on Windows 95, the "Winsock2" upgrade MUST BE
  75     INSTALLED. "Winsock2" for Windows 95 is available <a
  76     href="http://www.microsoft.com/windows95/downloads/">here</a>.</p>
  77
  78     <p>If running on NT 4.0, installing Service Pack 3 or 6 is
  79     recommended, as Service Pack 4 created known issues with TCP/IP
  80     and WinSock integrity that were resolved in later Service
  81     Packs.</p>
  82
  83     <h2><a id="down" name="down">Downloading Apache for
  84     Windows</a></h2>
  85
  86     <p>Information on the latest version of Apache can be found on
  87     the Apache web server at <a
  88     href="http://httpd.apache.org/">http://httpd.apache.org/</a>.
  89     This will list the current release, any more recent alpha or
  90     beta-test releases, together with details of mirror web and
  91     anonymous ftp sites.</p>
  92
  93     <p>You should download the version of Apache for Windows with
  94     the <code>.msi</code> extension. This is a single Microsoft
  95     Installer file containing Apache, ready to install and run.
  96     There is a seperate <code>.zip</code> file containing _only_
  97     the source code, to compile Apache yourself with the Microsoft
  98     Visual C++ (Visual Studio) tools.</p>
  99
 100     <h2><a id="inst" name="inst">Installing Apache for
 101     Windows</a></h2>
 102
 103     <p>Run the Apache <samp>.msi</samp> file you downloaded above.
 104     This will ask for:</p>
 105
 106     <ul>
 107       <li>the directory to install Apache into (the default is
 108       <code>\Program Files\Apache Group\Apache</code> although you
 109       can change this to any other directory)</li>
 110
 111       <li>the start menu name (default is "Apache Web Server")</li>
 112
 113       <li>the installation type. The "Typical" option installs
 114       everything except the source code. The "Minimum" option does
 115       not install the manuals or source code. Choose the "Custom"
 116       install if you want to install the source code.</li>
 117     </ul>
 118
 119     <p>During the installation, Apache will configure the files in
 120     the <samp>conf</samp> directory for your chosen installation
 121     directory. However if any of the files in this directory
 122     already exist they will <strong>not</strong> be overwritten.
 123     Instead the new copy of the corresponding file will be left
 124     with the extension <samp>.default</samp>. So, for example, if
 125     <samp>conf\httpd.conf</samp> already exists it will not be
 126     altered, but the version which would have been installed will
 127     be left in <samp>conf\httpd.conf.default</samp>. After the
 128     installation has finished you should manually check to see what is
 129     in new in the <samp>.default</samp> file, and if necessary
 130     update your existing configuration files.</p>
 131
 132     <p>Also, if you already have a file called
 133     <samp>htdocs\index.html</samp> then it will not be overwritten
 134     (no <samp>index.html.default</samp> file will be installed
 135     either). This should mean it a safe to install Apache over an
 136     existing installation (but you will have to stop the existing
 137     server running before doing the installation, then start the
 138     new one after the installation is finished).</p>
 139
 140     <p>After installing Apache, you should edit the configuration
 141     files in the <samp>conf</samp> directory as required. These
 142     files will be configured during the install ready for Apache to
 143     be run from the directory where it was installed, with the
 144     documents served from the subdirectory <samp>htdocs</samp>.
 145     There are lots of other options which should be set before you
 146     start really using Apache. However to get started quickly the
 147     files should work as installed.</p>
 148
 149     <h2><a id="run" name="run">Running Apache for Windows</a></h2>
 150     There are two ways you can run Apache:
 151
 152     <ul>
 153       <li>As a <a href="win_service.html#service">"service"</a>
 154       (available on Windows NT/2000, or a pseudo-service on Windows
 155       95, 98 or ME). This is the best option if you want Apache to
 156       automatically start when you machine boots, and to keep
 157       Apache running when you log-off.</li>
 158
 159       <li>From a <a href="#cmdline">console window</a>. This MUST
 160       be used by any administrator to test before to attempting to
 161       run as a service.</li>
 162     </ul>
 163
 164     <p>To run Apache from a console window, select the "Start
 165     Apache as console app" option from the Start menu (in Apache
 166     1.3.4 and earlier, this option was called "Apache Server").
 167     This will open a console window and start Apache running inside
 168     it. The window will remain active until you stop Apache. To
 169     stop Apache running, either select the "Shutdown Apache console
 170     app" icon option from the Start menu (this is not available in
 171     Apache 1.3.4 or earlier), or see <a href="#signal">Signalling
 172     Console Apache when Running</a> for how to control Apache from
 173     the command line.</p>
 174
 175     <p>If the Apache console window closes immediately (or
 176     unexpectedly), run the "Command Prompt" from the Start Menu -
 177     Programs list. Change to the folder to which you installed
 178     Apache, type the command apache, and read the error message.
 179     Then change to the logs folder, and review the error.log file
 180     for configuration mistakes. If you accepted the defaults when
 181     you installed Apache, the commands would be:</p>
 182 <pre>
 183   c:
 184   cd "\program files\apache group\apache"
 185   apache
 186   <samp>Wait for Apache to exit, or press Ctrl+C</samp>
 187   cd logs
 188   more &lt;error.log
 189 </pre>
 190
 191     <p><strong>Complete the steps above before you proceed to
 192     attempt to start Apache as a Window NT/2000
 193     service!</strong></p>
 194
 195     <p>To start Apache as a service, you first need to install it
 196     as a service. Multiple Apache services can be installed, each
 197     with a different name and configuration. To install the default
 198     Apache service named "Apache", run the "Install Apache as
 199     Service (NT only)" option from the Start menu. Once this is
 200     done you can start the "Apache" service by opening the Services
 201     window (in the Control Panel), selecting Apache, then clicking
 202     on Start. Apache will now be running in the background. You can
 203     later stop Apache by clicking on Stop. As an alternative to
 204     using the Services window, you can start and stop the "Apache"
 205     service from the control line with:</p>
 206 <pre>
 207   NET START APACHE
 208   NET STOP APACHE
 209 </pre>
 210
 211     <p>See <a href="#signalsrv">Signalling Service Apache when
 212     Running</a> for more information on installing and controlling
 213     Apache services.</p>
 214
 215     <p><strong>Apache, unlike many other Windows NT/2000 services,
 216     logs any errors to its own error.log file in the logs folder
 217     within the Apache server root folder. You will <em>not</em>
 218     find Apache error details in the Windows NT Event
 219     Log.</strong></p>
 220
 221     <p>After starting Apache running (either in a console window or
 222     as a service) it will be listening to port 80 (unless you
 223     changed the <samp>Listen</samp> directive in the configuration
 224     files). To connect to the server and access the default page,
 225     launch a browser and enter this URL:</p>
 226 <pre>
 227   http://localhost/
 228 </pre>
 229
 230     <p>This should respond with a welcome page, and a link to the
 231     Apache manual. If nothing happens or you get an error, look in
 232     the <samp>error_log</samp> file in the <samp>logs</samp>
 233     directory. If your host isn't connected to the net, you may
 234     have to use this URL:</p>
 235 <pre>
 236   http://127.0.0.1/
 237 </pre>
 238
 239     <p>Once your basic installation is working, you should
 240     configure it properly by editing the files in the
 241     <samp>conf</samp> directory. Again, if you change the
 242     configuration of the Windows NT/2000 service for Apache, first
 243     attempt to start it from the command line to assure that the
 244     service starts with no errors.</p>
 245
 246     <p>Because Apache <em>CANNOT</em> share the same port with
 247     another TCPIP application, you may need to stop or uninstall
 248     certain services first. These include (but are not limited to)
 249     other web servers, and firewall products such as BlackIce. If
 250     you can only start Apache with these services disabled,
 251     reconfigure either Apache or the other product so that they do
 252     not listen on the same TCPIP ports.</p>
 253
 254     <h2><a id="use" name="use">Configuring Apache for
 255     Windows</a></h2>
 256
 257     <p>Apache is configured by files in the <samp>conf</samp>
 258     directory. These are the same as files used to configure the
 259     Unix version, but there are a few different directives for
 260     Apache on Windows. See the <a href="../">Apache
 261     documentation</a> for all the available directives.</p>
 262
 263     <p>The main differences in Apache for Windows are:</p>
 264
 265     <ul>
 266       <li>
 267         <p>Because Apache for Windows is multithreaded, it does not
 268         use a separate process for each request, as Apache does
 269         with Unix. Instead there are usually only two Apache
 270         processes running: a parent process, and a child which
 271         handles the requests. Within the child each request is
 272         handled by a separate thread.</p>
 273
 274         <p>So the "process"-management directives are
 275         different:</p>
 276
 277         <p><a
 278         href="../mod/mpm_common.html#maxrequestsperchild">MaxRequestsPerChild</a>
 279         - Like the Unix directive, this controls how many requests
 280         a process will serve before exiting. However, unlike Unix,
 281         a process serves all the requests at once, not just one, so
 282         if this is set, it is recommended that a very high number
 283         is used. The recommended default, <code>MaxRequestsPerChild
 284         0</code>, does not cause the process to ever exit.
 285         <strong>Warning: The server configuration file is reread
 286         when the new child process is started. If you have modified
 287         httpd.conf, the new child may not start or you may receive
 288         unexpected results.</strong></p>
 289
 290         <p><a
 291         href="../mod/mpm_common.html#threadsperchild">ThreadsPerChild</a>
 292         - This directive is new, and tells the server how many
 293         threads it should use. This is the maximum number of
 294         connections the server can handle at once; be sure and set
 295         this number high enough for your site if you get a lot of
 296         hits. The recommended default is <code>ThreadsPerChild
 297         50</code>.</p>
 298       </li>
 299
 300       <li>
 301         <p>The directives that accept filenames as arguments now
 302         must use Windows filenames instead of Unix ones. However,
 303         because Apache uses Unix-style names internally, you must
 304         use forward slashes, not backslashes. Drive letters can be
 305         used; if omitted, the drive with the Apache executable will
 306         be assumed.</p>
 307       </li>
 308
 309       <li>
 310         <p>Apache for Windows contains the ability to load modules
 311         at runtime, without recompiling the server. If Apache is
 312         compiled normally, it will install a number of optional
 313         modules in the <code>\Apache\modules</code> directory. To
 314         activate these, or other modules, the new <a
 315         href="../mod/mod_so.html#loadmodule">LoadModule</a>
 316         directive must be used. For example, to active the status
 317         module, use the following (in addition to the
 318         status-activating directives in
 319         <code>access.conf</code>):</p>
 320 <pre>
 321     LoadModule status_module modules/mod_status.so
 322 </pre>
 323
 324         <p>Information on <a
 325         href="../mod/mod_so.html#creating">creating loadable
 326         modules</a> is also available.</p>
 327       </li>
 328
 329       <li>
 330         <p>Apache can also load ISAPI Extensions (<em>i.e.</em>,
 331         Internet Server Applications), such as those used by
 332         Microsoft's IIS, and other Windows servers. <a
 333         href="../mod/mod_isapi.html">More information is
 334         available.</a> Note that Apache <em>CANNOT</em> load ISAPI
 335         Filters.</p>
 336       </li>
 337
 338       <li>When running CGI scripts, the method Apache uses to find
 339       the interpreter for the script is configurable using the <a
 340       href="../mod/core.html#scriptinterpretersource">ScriptInterpreterSource</a>
 341       directive.</li>
 342
 343       <li>Since it is often difficult to manage files with names
 344       like <code>.htaccess</code> under windows, you may find it
 345       useful to change the name of this configuration file using
 346       the <a
 347       href="../mod/core.html#accessfilename">AccessFilename</a>
 348       directive.</li>
 349     </ul>
 350
 351     <h2><a id="service" name="service">Running Apache for Windows
 352     as a Service</a></h2>
 353
 354     <p><strong>Note: The -n option to specify a service name is
 355     only available with Apache 1.3.7 and later. Earlier versions of
 356     Apache only support the default service name
 357     'Apache'.</strong></p>
 358
 359     <p>You can install Apache as a Windows NT service as
 360     follows:</p>
 361 <pre>
 362     apache -k install -n "service name"
 363 </pre>
 364
 365     <p>To install a service to use a particular configuration,
 366     specify the configuration file when the service is
 367     installed:</p>
 368 <pre>
 369     apache -k install -n "service name" -f "\my server\conf\my.conf"
 370 </pre>
 371
 372     <p>To remove an Apache service, use</p>
 373 <pre>
 374     apache -k uninstall -n "service name"
 375 </pre>
 376
 377     <p>The default "service name", if one is not specified, is
 378     "Apache".</p>
 379
 380     <p>Once a service is installed, you can use the <samp>-n</samp>
 381     option, in conjunction with other options, to refer to a
 382     service's configuration file. For example:</p>
 383
 384     <p>To test a service's configuration file:</p>
 385 <pre>
 386     apache -n "service name" -t
 387 </pre>
 388
 389     <p>To start a console Apache using a service's configuration
 390     file:</p>
 391 <pre>
 392     apache -n "service name"
 393 </pre>
 394
 395     <p><strong>Important Note on service dependencies:</strong></p>
 396
 397     <p>Prior to Apache release 1.3.13, the dependencies required to
 398     successfully start an installed service were not configured.
 399     After installing a service using earlier versions of Apache,
 400     you must follow these steps:</p>
 401 <pre>
 402     Run regedt32
 403     Select <u>W</u>indow - "HKEY_LOCAL_MACHINE on Local Machine" from the menu
 404     Double-click to open the SYSTEM, then the CurrentControlSet keys
 405     Scroll down and click on the Apache servicename
 406     Select <u>E</u>dit - Add <u>V</u>alue... from the menu
 407     Fill in the Add Value dialog with
 408         <u>V</u>alue Name: DependOnGroup
 409         <u>D</u>ata Type: REG_MULTI_SZ
 410         and click OK
 411     Leave the Multi-String Editor dialog empty and click OK
 412     Select <u>E</u>dit - Add <u>V</u>alue... from the menu
 413     Fill in the Add Value dialog with
 414         <u>V</u>alue Name: DependOnService
 415         <u>D</u>ata Type: REG_MULTI_SZ
 416         and click OK
 417     Type the following list (one per line) in the Multi-String Editor dialog
 418         Tcpip
 419         Afd
 420         and click OK
 421 </pre>
 422
 423     <p>If you are using COM or DCOM components from a third party
 424     module, ISAPI, or other add-in scripting technologies such as
 425     ActiveState Perl, you may also need to add the entry Rpcss to
 426     the DependOnService list. To avoid exposing the TCP port 135
 427     when it is unnecessary, Apache does not create that entry upon
 428     installation. Follow the directions above to find or create the
 429     DependOnService value, double click that value if it already
 430     exists, and add the Rpcss entry to the list.</p>
 431
 432     <h2><a id="cmdline" name="cmdline">Running Apache for Windows
 433     from the Command Line</a></h2>
 434
 435     <p>The Start menu icons and the NT Service manager can provide
 436     a simple interface for administering Apache. But in some cases
 437     it is easier to work from the command line.</p>
 438
 439     <p>When working with Apache it is important to know how it will
 440     find the configuration files. You can specify a configuration
 441     file on the command line in two ways:</p>
 442
 443     <ul>
 444       <li>-f specifies a path to a particular configuration
 445       file</li>
 446     </ul>
 447 <pre>
 448     apache -f "c:\my server\conf\my.conf"
 449     apache -f test\test.conf
 450 </pre>
 451
 452     <ul>
 453       <li>-n specifies the configuration file of an installed
 454       Apache service (Apache 1.3.7 and later)</li>
 455     </ul>
 456 <pre>
 457     apache -n "service name"
 458 </pre>
 459
 460     <p>In these cases, the proper ServerRoot should be set in the
 461     configuration file.</p>
 462
 463     <p>If you don't specify a configuration file name with -f or
 464     -n, Apache will use the file name compiled into the server,
 465     usually "conf/httpd.conf". Invoking Apache with the -V switch
 466     will display this value labeled as SERVER_CONFIG_FILE. Apache
 467     will then determine its ServerRoot by trying the following, in
 468     this order:</p>
 469
 470     <ul>
 471       <li>A ServerRoot directive via a -C switch.</li>
 472
 473       <li>The -d switch on the command line.</li>
 474
 475       <li>Current working directory</li>
 476
 477       <li>A registry entry, created if you did a binary
 478       install.</li>
 479
 480       <li>The server root compiled into the server.</li>
 481     </ul>
 482
 483     <p>The server root compiled into the server is usually
 484     "/apache". invoking apache with the -V switch will display this
 485     value labeled as HTTPD_ROOT.</p>
 486
 487     <p>When invoked from the start menu, Apache is usually passed
 488     no arguments, so using the registry entry is the preferred
 489     technique for console Apache.</p>
 490
 491     <p>During a binary installation, a version-specific registry
 492     key is created in the Windows registry:</p>
 493 <pre>
 494   HKEY_LOCAL_MACHINE\Software\Apache Group\Apache\1.3.7
 495
 496   HKEY_LOCAL_MACHINE\Software\Apache Group\Apache\2.0a3
 497 </pre>
 498
 499     <p>This key is compiled into the server and can enable you to
 500     test new versions without affecting the current version. Of
 501     course you must take care not to install the new version on top
 502     of the old version in the file system.</p>
 503
 504     <p>If you did not do a binary install then Apache will in some
 505     scenarios complain that about the missing registry key. This
 506     warning can be ignored if it otherwise was able to find its
 507     configuration files.</p>
 508
 509     <p>The value of this key is the "ServerRoot" directory,
 510     containing the <samp>conf</samp> directory. When Apache starts
 511     it will read the <samp>httpd.conf</samp> file from this
 512     directory. If this file contains a <samp>ServerRoot</samp>
 513     directive which is different from the directory obtained from
 514     the registry key above, Apache will forget the registry key and
 515     use the directory from the configuration file. If you copy the
 516     Apache directory or configuration files to a new location it is
 517     vital that you update the <samp>ServerRoot</samp> directory in
 518     the <samp>httpd.conf</samp> file to the new location.</p>
 519
 520     <p>To run Apache from the command line as a console
 521     application, use the following command:</p>
 522 <pre>
 523     apache
 524 </pre>
 525
 526     <p>Apache will execute, and will remain running until it is
 527     stopped by pressing control-C.</p>
 528
 529     <h2><a id="signalsrv" name="signalsrv">Signalling Service
 530     Apache when running</a></h2>
 531
 532     <p>On Windows NT, multiple instances of Apache can be run as
 533     services. Signal an Apache service to start, restart, or
 534     shutdown as follows:</p>
 535 <pre>
 536     apache -n "service name" -k start
 537     apache -n "service name" -k restart
 538     apache -n "service name" -k shutdown
 539 </pre>
 540
 541     <p>In addition, you can use the native NT NET command to start
 542     and stop Apache services as follows:</p>
 543 <pre>
 544     NET START "service name"
 545     NET STOP "service name"
 546 </pre>
 547
 548     <h2><a id="signal" name="signal">Signalling Console Apache when
 549     running</a></h2>
 550
 551     <p>On Windows 95, Apache runs as a console application. You can
 552     tell a running Apache to stop by opening another console window
 553     and typing:</p>
 554 <pre>
 555     apache -k shutdown
 556 </pre>
 557
 558     <p>This should be used instead of pressing Control-C in the
 559     running Apache console window, because it lets Apache end any
 560     current transactions and cleanup gracefully.</p>
 561
 562     <p>You can also tell Apache to restart. This makes it re-read
 563     the configuration files. Any transactions in progress are
 564     allowed to complete without interruption. To restart Apache,
 565     run</p>
 566 <pre>
 567     apache -k restart
 568 </pre>
 569
 570     <p>Note for people familiar with the Unix version of Apache:
 571     these commands provide a Windows equivalent to <code>kill -TERM
 572     <em>pid</em></code> and <code>kill -USR1 <em>pid</em></code>.
 573     The command line option used, <code>-k</code>, was chosen as a
 574     reminder of the "kill" command used on Unix.</p>
 575     <!--#include virtual="footer.html" -->
 576   </body>
 577 </html>
 578