1 <?xml version="1.0" encoding="UTF-8" ?>
2 <!DOCTYPE manualpage SYSTEM "../style/manualpage.dtd">
3 <?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
6 <relativepath href=".." />
8 <title>Using Apache with Microsoft Windows</title>
12 <p>This document explains how to install, configure and run
13 Apache 2.0 under Microsoft Windows. If you find any bugs, or
14 wish to contribute in other ways, please use our <a
15 href="http://httpd.apache.org/bug_report.html">bug reporting page.</a></p>
17 <p>Most of this document assumes that you are installing
18 Windows from a binary distribution. If you want to compile
19 Apache yourself (possibly to help with development, or to track
20 down bugs), see <a href="win_compiling.html">Compiling Apache
21 for Microsoft Windows</a>.</p>
23 <p><strong>At this time, support for Windows 95, 98 and ME is
24 incomplete. Apache 2.0 is not expected to work on those
25 platforms at this time.</strong> If you are interested in
26 helping with that effort, please see the developer's site for
27 information on <a href="http://dev.apache.org/">how to get
28 involved</a>. Support will likely be provided at some point in
29 the future, and patches to allow Apache to work on 95, 98 and
36 <title>Requirements</title>
38 <p>Apache 2.0 is designed to run on Windows NT 4.0 and Windows
39 2000. The binary installer will only work with the x86 family
40 of processors, such as Intel's. Apache may also run on Windows
41 95, 98 and ME, but these are not tested, and are never
42 recommended for production servers. In all cases TCP/IP
43 networking must be installed.</p>
45 <p>If running on Windows 95, the "Winsock2" upgrade MUST BE
46 INSTALLED. "Winsock2" for Windows 95 is available <a
47 href="http://www.microsoft.com/windows95/downloads/">here</a>.</p>
49 <p>If running on NT 4.0, installing Service Pack 3 or 6 is
50 recommended, as Service Pack 4 created known issues with TCP/IP
51 and WinSock integrity that were resolved in later Service
58 <title>Downloading Apache for Windows</title>
60 <p>Information on the latest version of Apache can be found on
61 the Apache web server at <a
62 href="http://httpd.apache.org/">http://httpd.apache.org/</a>.
63 This will list the current release, any more recent alpha or
64 beta-test releases, together with details of mirror web and
65 anonymous ftp sites.</p>
67 <p>You should download the version of Apache for Windows with
68 the <code>.msi</code> extension. This is a single Microsoft
69 Installer file containing Apache, ready to install and run.
70 There is a seperate <code>.zip</code> file containing <em>only</em>
71 the source code, to compile Apache yourself with the Microsoft
72 Visual C++ (Visual Studio) tools.</p>
78 <title>Installing Apache for Windows</title>
80 <p>Run the Apache <code>.msi</code> file you downloaded above.
81 This will ask for:</p>
84 <li>the directory to install Apache into (the default is
85 <code>\Program Files\Apache Group\Apache</code> although you
86 can change this to any other directory)</li>
88 <li>the start menu name (default is "Apache Web Server")</li>
90 <li>the installation type. The "Typical" option installs
91 everything except the source code. The "Minimum" option does
92 not install the manuals or source code. Choose the "Custom"
93 install if you want to install the source code.</li>
96 <p>During the installation, Apache will configure the files in
97 the <code>conf</code> directory for your chosen installation
98 directory. However if any of the files in this directory
99 already exist they will <em>not</em> be overwritten.
100 Instead the new copy of the corresponding file will be left
101 with the extension <code>.default</code>. So, for example, if
102 <code>conf\httpd.conf</code> already exists it will not be
103 altered, but the version which would have been installed will
104 be left in <code>conf\httpd.conf.default</code>. After the
105 installation has finished you should manually check to see what is
106 in new in the <code>.default</code> file, and if necessary
107 update your existing configuration files.</p>
109 <p>Also, if you already have a file called
110 <code>htdocs\index.html</code> then it will not be overwritten
111 (no <code>index.html.default</code> file will be installed
112 either). This should mean it a safe to install Apache over an
113 existing installation (but you will have to stop the existing
114 server running before doing the installation, then start the
115 new one after the installation is finished).</p>
117 <p>After installing Apache, you should edit the configuration
118 files in the <code>conf</code> directory as required. These
119 files will be configured during the install ready for Apache to
120 be run from the directory where it was installed, with the
121 documents served from the subdirectory <code>htdocs</code>.
122 There are lots of other options which should be set before you
123 start really using Apache. However to get started quickly the
124 files should work as installed.</p>
130 <title>Running Apache for Windows</title>
132 <p>There are two ways you can run Apache:</p>
135 <li><p>As a <a href="win_service.html#service">"service"</a>
136 (available on Windows NT/2000, or a pseudo-service on Windows
137 95, 98 or ME). This is the best option if you want Apache to
138 automatically start when you machine boots, and to keep
139 Apache running when you log-off.</p></li>
141 <li><p>From a <a href="#cmdline">console window</a>. This MUST
142 be used by any administrator to test before to attempting to
143 run as a service.</p></li>
146 <p>To run Apache from a console window, select the "Start
147 Apache as console app" option from the Start menu (in Apache
148 1.3.4 and earlier, this option was called "Apache Server").
149 This will open a console window and start Apache running inside
150 it. The window will remain active until you stop Apache. To
151 stop Apache running, either select the "Shutdown Apache console
152 app" icon option from the Start menu (this is not available in
153 Apache 1.3.4 or earlier), or see <a href="#signal">Signalling
154 Console Apache when Running</a> for how to control Apache from
155 the command line.</p>
157 <p>If the Apache console window closes immediately (or
158 unexpectedly), run the "Command Prompt" from the Start Menu -
159 Programs list. Change to the folder to which you installed
160 Apache, type the command apache, and read the error message.
161 Then change to the <code>logs</code> folder, and review the
162 <code>error.log</code> file for configuration mistakes.
163 If you accepted the defaults when you installed Apache,
164 the commands would be:</p>
168 cd "\program files\apache group\apache" <br />
170 Wait for Apache to exit, or press Ctrl+C <br />
175 <p><strong>Complete the steps above before you proceed
176 to attempt to start Apache as a Window NT/2000
177 service!</strong></p>
179 <p>To start Apache as a service, you first need to install it
180 as a service. Multiple Apache services can be installed, each
181 with a different name and configuration. To install the default
182 Apache service named "Apache", run the "Install Apache as
183 Service (NT only)" option from the Start menu. Once this is
184 done you can start the "Apache" service by opening the Services
185 window (in the Control Panel), selecting Apache, then clicking
186 on Start. Apache will now be running in the background. You can
187 later stop Apache by clicking on Stop. As an alternative to
188 using the Services window, you can start and stop the "Apache"
189 service from the control line with:</p>
192 NET START APACHE <br />
196 <p>See <a href="#signalsrv">Signalling Service Apache when
197 Running</a> for more information on installing and controlling
200 <note><strong>Apache, unlike many other Windows NT/2000 services,
201 logs any errors to its own <code>error.log</code> file in the
202 <code>logs</code> folder within the Apache server root folder.
203 You will <em>not</em> find Apache error details in the Windows
204 NT Event Log.</strong></note>
206 <p>After starting Apache running (either in a console window or
207 as a service) it will be listening to port 80 (unless you
208 changed the <directive module="mpm_common">Listen</directive> directive in the configuration
209 files). To connect to the server and access the default page,
210 launch a browser and enter this URL:</p>
216 <p>This should respond with a welcome page, and a link to the
217 Apache manual. If nothing happens or you get an error, look in
218 the <code>error_log</code> file in the <code>logs</code>
219 directory. If your host isn't connected to the net, you may
220 have to use this URL:</p>
226 <p>Once your basic installation is working, you should
227 configure it properly by editing the files in the
228 <code>conf</code> directory. Again, if you change the
229 configuration of the Windows NT/2000 service for Apache, first
230 attempt to start it from the command line to assure that the
231 service starts with no errors.</p>
233 <p>Because Apache <em>CANNOT</em> share the same port with
234 another TCPIP application, you may need to stop or uninstall
235 certain services first. These include (but are not limited to)
236 other web servers, and firewall products such as BlackIce. If
237 you can only start Apache with these services disabled,
238 reconfigure either Apache or the other product so that they do
239 not listen on the same TCPIP ports.</p>
245 <title>Configuring Apache for Windows</title>
247 <p>Apache is configured by files in the <code>conf</code>
248 directory. These are the same as files used to configure the
249 Unix version, but there are a few different directives for
250 Apache on Windows. See the <a href="../">Apache
251 documentation</a> for all the available directives.</p>
253 <p>The main differences in Apache for Windows are:</p>
257 <p>Because Apache for Windows is multithreaded, it does not
258 use a separate process for each request, as Apache does
259 with Unix. Instead there are usually only two Apache
260 processes running: a parent process, and a child which
261 handles the requests. Within the child each request is
262 handled by a separate thread.</p>
264 <p>So the "process"-management directives are
267 <p><directive module="mpm_common">MaxRequestsPerChild</directive>
268 - Like the Unix directive, this controls how many requests
269 a process will serve before exiting. However, unlike Unix,
270 a process serves all the requests at once, not just one, so
271 if this is set, it is recommended that a very high number
272 is used. The recommended default, <code>MaxRequestsPerChild
273 0</code>, does not cause the process to ever exit.</p>
275 <note type="warning"><strong>Warning: The server configuration
276 file is reread when the new child process is started. If you
277 have modified <code>httpd.conf</code>, the new child may not
278 start or you may receive unexpected results.</strong></note>
280 <p><directive module="mpm_common">ThreadsPerChild</directive>
281 - This directive is new, and tells the server how many
282 threads it should use. This is the maximum number of
283 connections the server can handle at once; be sure and set
284 this number high enough for your site if you get a lot of
285 hits. The recommended default is <code>ThreadsPerChild
290 <p>The directives that accept filenames as arguments now
291 must use Windows filenames instead of Unix ones. However,
292 because Apache uses Unix-style names internally, you must
293 use forward slashes, not backslashes. Drive letters can be
294 used; if omitted, the drive with the Apache executable will
299 <p>Apache for Windows contains the ability to load modules
300 at runtime, without recompiling the server. If Apache is
301 compiled normally, it will install a number of optional
302 modules in the <code>\Apache\modules</code> directory. To
303 activate these, or other modules, the new <directive
304 module="mod_so">LoadModule</directive>
305 directive must be used. For example, to active the status
306 module, use the following (in addition to the
307 status-activating directives in
308 <code>access.conf</code>):</p>
311 LoadModule status_module modules/mod_status.so
315 href="../mod/mod_so.html#creating">creating loadable
316 modules</a> is also available.</p>
320 <p>Apache can also load ISAPI Extensions (<em>i.e.</em>,
321 Internet Server Applications), such as those used by
322 Microsoft's IIS, and other Windows servers. <a
323 href="../mod/mod_isapi.html">More information is
324 available.</a> Note that Apache <em>CANNOT</em> load ISAPI
329 <p>When running CGI scripts, the method Apache uses to find
330 the interpreter for the script is configurable using the
331 <directive module="mod_core">ScriptInterpreterSource</directive>
336 <p>Since it is often difficult to manage files with names
337 like <code>.htaccess</code> under windows, you may find it
338 useful to change the name of this configuration file using
339 the <directive module="mod_core">AccessFilename</directive>
346 <section id="service">
348 <title>Running Apache for Windows as a Service</title>
350 <note><strong>The <code>-n</code> option to specify a service name
351 is only available with Apache 1.3.7 and later. Earlier versions of
352 Apache only support the default service name
353 "Apache".</strong></note>
355 <p>You can install Apache as a Windows NT service as
359 apache -k install -n "service name"
362 <p>To install a service to use a particular configuration,
363 specify the configuration file when the service is
367 apache -k install -n "service name" -f "\my server\conf\my.conf"
370 <p>To remove an Apache service, use</p>
373 apache -k uninstall -n "service name"
376 <p>The default "service name", if one is not specified, is
379 <p>Once a service is installed, you can use the <code>-n</code>
380 option, in conjunction with other options, to refer to a
381 service's configuration file. For example:</p>
383 <p>To test a service's configuration file:</p>
386 apache -n "service name" -t
389 <p>To start a console Apache using a service's configuration
393 apache -n "service name"
396 <p><strong>Important Note on service dependencies:</strong></p>
398 <p>Prior to Apache release 1.3.13, the dependencies required to
399 successfully start an installed service were not configured.
400 After installing a service using earlier versions of Apache,
401 you must follow these steps:</p>
405 Select Window - "HKEY_LOCAL_MACHINE on Local Machine" from the menu <br />
406 Double-click to open the SYSTEM, then the CurrentControlSet keys <br />
407 Scroll down and click on the Apache servicename <br />
408 Select Edit - Add Value... from the menu <br />
409 Fill in the Add Value dialog with <br />
410     Value Name: DependOnGroup <br />
411     Data Type: REG_MULTI_SZ <br />
412     and click OK <br />
413 Leave the Multi-String Editor dialog empty and click OK <br />
414 Select Edit - Add Value... from the menu <br />
415 Fill in the Add Value dialog with <br />
416     Value Name: DependOnService <br />
417     Data Type: REG_MULTI_SZ <br />
418     and click OK <br />
419 Type the following list (one per line) in the Multi-String Editor dialog <br />
420     Tcpip <br />
421     Afd <br />
422     and click OK
425 <p>If you are using COM or DCOM components from a third party
426 module, ISAPI, or other add-in scripting technologies such as
427 ActiveState Perl, you may also need to add the entry Rpcss to
428 the DependOnService list. To avoid exposing the TCP port 135
429 when it is unnecessary, Apache does not create that entry upon
430 installation. Follow the directions above to find or create the
431 DependOnService value, double click that value if it already
432 exists, and add the Rpcss entry to the list.</p>
436 <section id="cmdline">
438 <title>Running Apache for Windows from the Command Line</title>
440 <p>The Start menu icons and the NT Service manager can provide
441 a simple interface for administering Apache. But in some cases
442 it is easier to work from the command line.</p>
444 <p>When working with Apache it is important to know how it will
445 find the configuration files. You can specify a configuration
446 file on the command line in two ways:</p>
449 <li><code>-f</code> specifies a path to a particular
450 configuration file</li>
454 apache -f "c:\my server\conf\my.conf" <br />
455 apache -f test\test.conf
459 <li><code>-n</code> specifies the configuration file of
460 an installed Apache service (Apache 1.3.7 and later)</li>
464 apache -n "service name"
467 <p>In these cases, the proper <directive module="mod_core"
468 >ServerRoot</directive> should be set in the configuration file.</p>
470 <p>If you don't specify a configuration file name with <code>-f</code> or
471 <code>-n</code>, Apache will use the file name compiled into the server,
472 usually "<code>conf/httpd.conf</code>". Invoking Apache with the
473 <code>-V</code> switch will display this value labeled as
474 <code>SERVER_CONFIG_FILE</code>. Apache
475 will then determine its <directive module="mod_core"
476 >ServerRoot</directive> by trying the following, in
480 <li>A <code>ServerRoot</code> directive via a
481 <code>-C</code> switch.</li>
483 <li>The <code>-d</code> switch on the command line.</li>
485 <li>Current working directory</li>
487 <li>A registry entry, created if you did a binary
490 <li>The server root compiled into the server.</li>
493 <p>The server root compiled into the server is usually
494 "<code>/apache</code>". invoking apache with the <code>-V</code> switch
495 will display this value labeled as <code>HTTPD_ROOT</code>.</p>
497 <p>When invoked from the start menu, Apache is usually passed
498 no arguments, so using the registry entry is the preferred
499 technique for console Apache.</p>
501 <p>During a binary installation, a version-specific registry
502 key is created in the Windows registry:</p>
505 HKEY_LOCAL_MACHINE\Software\Apache Group\Apache\1.3.7 <br />
507 HKEY_LOCAL_MACHINE\Software\Apache Group\Apache\2.0a3
510 <p>This key is compiled into the server and can enable you to
511 test new versions without affecting the current version. Of
512 course you must take care not to install the new version on top
513 of the old version in the file system.</p>
515 <p>If you did not do a binary install then Apache will in some
516 scenarios complain that about the missing registry key. This
517 warning can be ignored if it otherwise was able to find its
518 configuration files.</p>
520 <p>The value of this key is the <directive module="mod_core"
521 >ServerRoot</directive> directory, containing the <code>conf</code>
522 directory. When Apache starts it will read the <code>httpd.conf</code>
523 file from this directory. If this file contains a
524 <directive module="mod_core">ServerRoot</directive> directive which
525 is different from the directory obtained from the registry key above,
526 Apache will forget the registry key and use the directory from the
527 configuration file. If you copy the Apache directory or configuration
528 files to a new location it is vital that you update the
529 <directive module="mod_core">ServerRoot</directive> directory
530 in the <code>httpd.conf</code> file to the new location.</p>
532 <p>To run Apache from the command line as a console
533 application, use the following command:</p>
539 <p>Apache will execute, and will remain running until it is
540 stopped by pressing control-C.</p>
544 <section id="signalsrv">
546 <title>Signalling Service Apache when running</title>
548 <p>On Windows NT, multiple instances of Apache can be run as
549 services. Signal an Apache service to start, restart, or
550 shutdown as follows:</p>
553 apache -n "service name" -k start <br />
554 apache -n "service name" -k restart <br />
555 apache -n "service name" -k shutdown
558 <p>In addition, you can use the native NT <code>NET</code> command
559 to start and stop Apache services as follows:</p>
562 NET START "service name" <br />
563 NET STOP "service name"
568 <section id="signal">
570 <title>Signalling Console Apache when running</title>
572 <p>On Windows 95, Apache runs as a console application. You can
573 tell a running Apache to stop by opening another console window
580 <p>This should be used instead of pressing Control-C in the
581 running Apache console window, because it lets Apache end any
582 current transactions and cleanup gracefully.</p>
584 <p>You can also tell Apache to restart. This makes it re-read
585 the configuration files. Any transactions in progress are
586 allowed to complete without interruption. To restart Apache,
593 <note>Note for people familiar with the Unix version of Apache:
594 these commands provide a Windows equivalent to <code>kill -TERM
595 <em>pid</em></code> and <code>kill -USR1 <em>pid</em></code>.
596 The command line option used, <code>-k</code>, was chosen as a
597 reminder of the "<code>kill</code>" command used on Unix.</note>