| <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> |
| <HTML> |
| <HEAD> |
| <TITLE>Using Apache with Microsoft Windows</TITLE> |
| </HEAD> |
| |
| <!-- Background white, links blue (unvisited), navy (visited), red (active) --> |
| <BODY |
| BGCOLOR="#FFFFFF" |
| TEXT="#000000" |
| LINK="#0000FF" |
| VLINK="#000080" |
| ALINK="#FF0000" |
| > |
| <!--#include virtual="header.html" --> |
| |
| <H1 ALIGN="CENTER">Using Apache With Microsoft Windows</H1> |
| |
| <P>This document explains how to install, configure and run |
| Apache 2.0 under Microsoft Windows. If you find any bugs, or wish |
| to contribute in other ways, please use our |
| <A HREF="http://www.apache.org/bugs/">bug reporting page.</A></P> |
| |
| <P>Most of this document assumes that you are installing Windows from a |
| binary distribution. If you want to compile Apache yourself (possibly |
| to help with development, or to track down bugs), see |
| <A HREF="win_compiling.html">Compiling Apache for Microsoft Windows</A>. |
| |
| <HR> |
| |
| <UL> |
| <LI><A HREF="#req">Requirements</A> |
| <LI><A HREF="#down">Downloading Apache for Windows</A> |
| <LI><A HREF="#inst">Installing Apache for Windows (binary install)</A> |
| <LI><A HREF="#run">Running Apache for Windows</A> |
| <LI><A HREF="#use">Using Apache for Windows</A> |
| <LI><A HREF="#cmdline">Running Apache for Windows from the Command Line</A> |
| <LI><A HREF="#service">Running Apache for Windows as a Service</A> |
| <LI><A HREF="#signal">Signalling Console Apache when running</A> |
| <LI><A HREF="#signalsrv">Signalling Service Apache when running</A> |
| <LI><A HREF="win_compiling.html">Compiling Apache for Microsoft Windows</A> |
| </UL> |
| |
| <HR> |
| |
| <H2><A NAME="req">Requirements</A></H2> |
| |
| <P>Apache 2.0 is designed to run on Windows NT 4.0 and Windows 2000. The |
| binary installer will only work with the x86 family of processors, such |
| as Intel's. Apache may also run on Windows 95 and 98, but these have not |
| been tested, and are never recommended for production servers. In all |
| cases TCP/IP networking must be installed.</P> |
| |
| <P>If running on Windows 95, the "Winsock2" upgrade MUST BE INSTALLED. |
| "Winsock2" for Windows 95 is available |
| <A HREF="http://www.microsoft.com/windows95/downloads/">here</A>.</P> |
| |
| <P>If running on NT 4.0, installing Service Pack 3 or 6 is recommended, as |
| Service Pack 4 created known issues with TCPIP/WinSock integrety that |
| were resolved in later Service Packs.</P> |
| |
| <P><STRONG>Warning: as of alpha 2.0a4 Windows 95 (and possibly 98) do not |
| run at all. Please don't let that stop you, however, from contributing |
| the fixes required to make that platform run successfully.</STRONG></P> |
| |
| <H2><A NAME="down">Downloading Apache for Windows</A></H2> |
| |
| <P>Information on the latest version of Apache can be found on the |
| Apache web server at <A HREF="http://www.apache.org/httpd"> |
| http://www.apache.org/httpd</A>. This will list the current release, |
| any more recent alpha or beta-test releases, together with details of |
| mirror web and anonymous ftp sites.</P> |
| |
| <P>You should download the version of Apache for Windows with the |
| <CODE>.exe</CODE> extension. This is a single file containing Apache, |
| ready to install and run. There may also be a <CODE>.zip</CODE> file |
| containing the source code, to compile Apache yourself. (If there is |
| no <SAMP>.zip</SAMP> file, the source will be available in a |
| <SAMP>.tar.gz</SAMP> file but this will contain Unix line endings. You |
| will have to convert at least the <SAMP>.mak</SAMP> and |
| <SAMP>.dsp</SAMP> files to have DOS line endings before MSVC will |
| understand them).</P> |
| |
| <P><STRONG>Notice: alpha versions are not distributed in binary form (as |
| an .exe ready-to-run version). You must use the Microsoft Visual C++ |
| compiler version 5 or 6 (bundled in VisualStudio 97 and 98). Read |
| <A HREF="win_compiling.html">Compiling Apache for Microsoft Windows</A> |
| for compilation/installation instructions.</STRONG></P> |
| |
| <H2><A NAME="inst">Installing Apache for Windows</A></H2> |
| |
| <P>Run the Apache <SAMP>.exe</SAMP> file you downloaded above. This will |
| ask for:</P> |
| |
| <UL> |
| |
| <LI>the directory to install Apache into (the default is |
| <CODE>\Program Files\Apache Group\Apache</CODE> although you can |
| change this to any other directory) |
| |
| <LI>the start menu name (default is "Apache Web Server") |
| |
| <LI>the installation type. The "Typical" option installs |
| everything except the source code. The "Minimum" option does not |
| install the manuals or source code. Choose the "Custom" install if |
| you want to install the source code. |
| |
| </UL> |
| |
| <P>During the installation, Apache will configure the files in the |
| <SAMP>conf</SAMP> directory for your chosen installation |
| directory. However if any of the files in this directory already exist |
| they will <STRONG>not</STRONG> be overwritten. Instead the new copy of |
| the corresponding file will be left with the extension |
| <SAMP>.default</SAMP>. So, for example, if |
| <SAMP>conf\httpd.conf</SAMP> already exists it will not be altered, |
| but the version which would have been installed will be left in |
| <SAMP>conf\httpd.conf.default</SAMP>. After the installation has |
| finished you should manually check to see what in new in the |
| <SAMP>.default</SAMP> file, and if necessary update your existing |
| configuration files.</P> |
| |
| <P>Also, if you already have a file called <SAMP>htdocs\index.html</SAMP> |
| then it will not be overwritten (no <SAMP>index.html.default</SAMP> |
| file will be installed either). This should mean it a safe to install |
| Apache over an existing installation (but you will have to stop the |
| existing server running before doing the installation, then start the |
| new one after the installation is finished).</P> |
| |
| <P>After installing Apache, you should edit the configuration files in |
| the <SAMP>conf</SAMP> directory as required. These files will be |
| configured during the install ready for Apache to be run from the |
| directory where it was installed, with the documents served from the |
| subdirectory <SAMP>htdocs</SAMP>. There are lots of other options |
| which should be set before you start really using Apache. However to |
| get started quickly the files should work as installed.</P> |
| |
| <H2><A NAME="run">Running Apache for Windows</A></H2> |
| |
| There are two ways you can run Apache: |
| |
| <UL> |
| <LI>As a <A HREF="#service">"service"</A> (available on Windows NT/2000 only). |
| This is the best option if you want Apache to automatically start when you |
| machine boots, and to keep Apache running when you log-off. |
| <LI>From a <A HREF="#cmdline">console window</A>. This is the only option |
| available for Windows 95/98 users, and MUST be used by Windows NT/2000 |
| users before to attempting to run as a service. |
| </UL> |
| |
| <P>To run Apache from a console window, select the "Start Apache as |
| console app" option from the Start menu (in Apache 1.3.4 and earlier, |
| this option was called "Apache Server"). This will open a console |
| window and start Apache running inside it. The window will remain |
| active until you stop Apache. To stop Apache running, either select |
| the "Shutdown Apache console app" icon option from the Start menu |
| (this is not available in Apache 1.3.4 or earlier), or see <A |
| HREF="#signal">Signalling Console Apache when Running</A> for how |
| to control Apache from the command line.</P> |
| |
| <P>If the Apache console window closes immediately (or unexpectedly), |
| run the "Command Prompt" from the Start Menu - Programs list. Change |
| to the folder to which you installed Apache, type the command apache, |
| and read the error message. Then change to the logs folder, and review |
| the error.log file for configuration mistakes. If you accepted the |
| defaults when you installed Apache, the commands would be:</P> |
| |
| <PRE> |
| c: |
| cd "\program files\apache group\apache" |
| apache |
| <SAMP>Wait for Apache to exit, or press Ctrl+C</SAMP> |
| cd logs |
| more <error.log |
| </PRE> |
| |
| <P><STRONG>Complete the steps above before you proceed to attempt to |
| start Apache as a Window NT/2000 service!</STRONG></P> |
| |
| <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 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 control |
| line with:</P> |
| |
| <PRE> |
| NET START APACHE |
| NET STOP APACHE |
| </PRE> |
| |
| <P>See <A HREF="#signalsrv">Signalling Service Apache when Running</A> |
| for more information on installing and controlling Apache services.</P> |
| |
| <P><STRONG>Apache, unlike many other Windows NT/2000 services, logs any |
| errors to it's 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.</STRONG></P> |
| |
| <P>After starting Apache running (either in a console window or as a |
| service) if will be listening to port 80 (unless you changed the |
| <SAMP>Port</SAMP>, <SAMP>Listen</SAMP> or <SAMP>BindAddress</SAMP> |
| directives in the configuration files). To connect to the server and |
| access the default page, launch a browser and enter this URL:</P> |
| |
| <PRE> |
| http://localhost/ |
| </PRE> |
| |
| <P>This should respond with a welcome page, and a link to the Apache |
| manual. If nothing happens or you get an error, look in the |
| <SAMP>error_log</SAMP> file in the <SAMP>logs</SAMP> directory. |
| If your host isn't connected to the net, you may have to use |
| this URL:</P> |
| |
| <PRE> |
| http://127.0.0.1/ |
| </PRE> |
| |
| <P>Once your basic installation is working, you should configure it |
| properly by editing the files in the <SAMP>conf</SAMP> directory. |
| Again, if you change the configuration of the Windows NT/2000 |
| service for Apache, first attempt to start it from the command |
| line to assure that the service starts with no errors.</P> |
| |
| <P>Because Apache <EMP>CANNOT</EMP> share the same port with another |
| TCPIP application, you may need to stop or uninstall certain |
| services first. These include (but are not limited to) other |
| web servers, and firewall products such as BlackIce. If you can |
| only start Apache with these services disabled, reconfigure either |
| Apache or the other product so that they do not listen on the |
| same TCPIP ports.</P> |
| |
| <H2><A NAME="use">Configuring Apache for Windows</A></H2> |
| |
| <P>Apache is configured by files in the <SAMP>conf</SAMP> |
| directory. These are the same as files used to configure the Unix |
| version, but there are a few different directives for Apache on |
| Windows. See the <A HREF="./">Apache documentation</A> for all the |
| available directives.</P> |
| |
| <P>The main differences in Apache for Windows are:</P> |
| |
| <UL> |
| <LI><P>Because Apache for Windows is multithreaded, it does not use a |
| separate process for each request, as Apache does with |
| Unix. Instead there are usually only two Apache processes running: |
| a parent process, and a child which handles the requests. Within |
| the child each request is handled by a separate thread. |
| <P> |
| |
| So the "process"-management directives are different: |
| <P><A |
| HREF="mod/core.html#maxrequestsperchild">MaxRequestsPerChild</A> |
| - Like the Unix directive, this controls how many requests a |
| process will serve before exiting. However, unlike Unix, a |
| process serves all the requests at once, not just one, so if |
| this is set, it is recommended that a very high number is |
| used. The recommended default, <CODE>MaxRequestsPerChild |
| 0</CODE>, does not cause the process to ever exit. |
| <STRONG> |
| Warning: The server configuration file is reread when the |
| new child process is started. If you have modified httpd.conf, |
| the new child may not start or you may receive unexpected results. |
| </STRONG> |
| <P><A HREF="mod/core.html#threadsperchild">ThreadsPerChild</A> - |
| This directive is new, and tells the server how many threads it |
| should use. This is the maximum number of connections the server |
| can handle at once; be sure and set this number high enough for |
| your site if you get a lot of hits. The recommended default is |
| <CODE>ThreadsPerChild 50</CODE>.</P> |
| <LI><P>The directives that accept filenames as arguments now must use |
| Windows filenames instead of Unix ones. However, because Apache |
| uses Unix-style names internally, you must use forward slashes, not |
| backslashes. Drive letters can be used; if omitted, the drive with |
| the Apache executable will be assumed.</P> |
| <LI><P>Apache for Windows contains the ability to load modules at runtime, |
| without recompiling the server. If Apache is compiled normally, it |
| will install a number of optional modules in the |
| <CODE>\Apache\modules</CODE> directory. To activate these, or other |
| modules, the new <A HREF="mod/mod_so.html#loadmodule">LoadModule</A> |
| directive must be used. For example, to active the status module, |
| use the following (in addition to the status-activating directives |
| in <CODE>access.conf</CODE>):</P> |
| <PRE> |
| LoadModule status_module modules/ApacheModuleStatus.dll |
| </PRE> |
| <P>Information on <A HREF="mod/mod_so.html#creating">creating loadable |
| modules</A> is also available.</P> |
| <LI><P>Apache can also load ISAPI Extensions (<EM>i.e.</EM>, Internet Server |
| Applications), such as those used by Microsoft's IIS, and other |
| Windows servers. <A HREF="mod/mod_isapi.html">More information |
| is available.</A> Note that Apache <EMP>CANNOT</EMP> load ISAPI |
| Filters. |
| </UL> |
| |
| <H2><A NAME="service">Running Apache for Windows as a Service</A></H2> |
| |
| <P><STRONG>Note: The -n option to specify a service name is only available |
| with Apache 1.3.7 and later. Earlier versions of Apache only support |
| the default service name 'Apache'.</STRONG></P> |
| |
| <P>You can install Apache as a Windows NT service as follows: |
| |
| <PRE> |
| apache -k install -n "service name" |
| </PRE> |
| |
| To install a service to use a particular configuration, specify the |
| configuration file when the service is installed: |
| |
| <PRE> |
| apache -k install -n "service name" -f "\my server\conf\my.conf" |
| </PRE> |
| |
| To remove an Apache service, use |
| |
| <PRE> |
| apache -k uninstall -n "service name" |
| </PRE> |
| |
| The default "service name", if one is not specified, is "Apache".</P> |
| |
| <P>Once a service is installed, you can use the <SAMP>-n</SAMP> 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> |
| |
| <PRE> |
| apache -n "service name" -t |
| </PRE> |
| |
| <P>To start a console Apache using a service's configuration file:</P> |
| |
| <PRE> |
| apache -n "service name" |
| </PRE> |
| |
| <P><STRONG>Important Note on service dependencies:</STRONG></P> |
| |
| <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: |
| |
| <PRE> |
| Run regedt32 |
| Select <U>W</U>indow - "HKEY_LOCAL_MACHINE on Local Machine" from the menu |
| Double-click to open the SYSTEM, then the CurrentControlSet keys |
| Scroll down and click on the Apache servicename |
| Select <U>E</U>dit - Add <U>V</U>alue... from the menu |
| Fill in the Add Value dialog with |
| <U>V</U>alue Name: DependOnGroup |
| <U>D</U>ata Type: REG_MULTI_SZ |
| and click OK |
| Leave the Multi-String Editor dialog empty and click OK |
| Select <U>E</U>dit - Add <U>V</U>alue... from the menu |
| Fill in the Add Value dialog with |
| <U>V</U>alue Name: DependOnService |
| <U>D</U>ata Type: REG_MULTI_SZ |
| and click OK |
| Type the following list (one per line) in the Multi-String Editor dialog |
| Tcpip |
| Afd |
| and click OK |
| </PRE> |
| |
| <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> |
| |
| <H2><A NAME="cmdline">Running Apache for Windows from the Command Line</A></H2> |
| |
| <P>The Start menu icons and the NT Service manager can provide a simple |
| interface for administering Apache. But in some cases it is easier to |
| work from the command line.</P> |
| |
| <P>When working with Apache it is important to know how it will find the |
| configuration files. You can specify a configuration file on the command line |
| in two ways: |
| |
| <UL> |
| <LI>-f specifies a path to a particular configuration file |
| </UL> |
| <PRE> apache -f "c:\my server\conf\my.conf"</PRE> |
| <PRE> apache -f test\test.conf</PRE> |
| <UL> |
| <LI>-n specifies the configuration file of an installed Apache service (Apache 1.3.7 and later) |
| </UL> |
| <PRE> apache -n "service name"</PRE> |
| |
| In these cases, the proper ServerRoot should be set in the configuration file.</P> |
| |
| <P>If you don't specify a configuration file name with -f or -n, Apache will |
| use the file name compiled into the server, usually "conf/httpd.conf". Invoking |
| Apache with the -V switch will display this value labeled as SERVER_CONFIG_FILE. |
| Apache will then determine its ServerRoot by trying the following, in this order:</P> |
| |
| <UL> |
| <LI>A ServerRoot directive via a -C switch. |
| <LI>The -d switch on the command line. |
| <LI>Current working directory |
| <LI>A registry entry, created if you did a binary install. |
| <LI>The server root compiled into the server. |
| </UL> |
| |
| <P>The server root compiled into the server is usually "/apache". |
| invoking apache with the -V switch will display this value |
| labeled as HTTPD_ROOT.</P> |
| |
| <P>When invoked from the start menu, Apache is usually passed no arguments, |
| so using the registry entry is the preferred technique for console Apache.</P> |
| |
| <P>During a binary installation, a version-specific registry key is created |
| in the Windows registry: |
| |
| <PRE> |
| HKEY_LOCAL_MACHINE\Software\Apache Group\Apache\1.3.7 |
| |
| HKEY_LOCAL_MACHINE\Software\Apache Group\Apache\2.0a3 |
| </PRE> |
| |
| <P>This key is compiled into the server and can enable you to test |
| new versions without affecting the current version. Of course |
| you must take care not to install the new version on top of the |
| old version in the file system.</P> |
| |
| <P>If you did not do a binary install then Apache will in some |
| scenarios complain that about the missing registry key. This |
| warning can be ignored if it otherwise was able to find its |
| configuration files.</P> |
| |
| <P>The value of this key is the "ServerRoot" directory, containing the |
| <SAMP>conf</SAMP> directory. When Apache starts it will read the |
| <SAMP>httpd.conf</SAMP> file from this directory. If this file |
| contains a <SAMP>ServerRoot</SAMP> directive which is different from |
| the directory obtained from the registry key above, Apache will forget |
| the registry key and use the directory from the configuration file. |
| If you copy the Apache directory or configuration files to a new |
| location it is vital that you update the <SAMP>ServerRoot</SAMP> |
| directory in the <SAMP>httpd.conf</SAMP> file to the new location. |
| |
| <P>To run Apache from the command line as a console application, use the |
| following command: |
| |
| <PRE> |
| apache |
| </PRE> |
| |
| Apache will execute, and will remain running until it is stopped by pressing |
| control-C.</P> |
| |
| <H2><A NAME="signalsrv">Signalling Service Apache when running</A></H2> |
| |
| <P>On Windows NT, multiple instances of Apache can be run as services. |
| Signal an Apache service to start, restart, or shutdown as follows:</P> |
| |
| <PRE> |
| apache -n "service name" -k start |
| apache -n "service name" -k restart |
| apache -n "service name" -k shutdown |
| </PRE> |
| |
| <P>In addition, you can use the native NT NET command to |
| start and stop Apache services as follows:</P> |
| |
| <PRE> |
| NET START "service name" |
| NET STOP "service name" |
| </PRE> |
| |
| <H2><A NAME="signal">Signalling Console Apache when running</A></H2> |
| |
| <P>On Windows 95, Apache runs as a console application. You can tell a |
| running Apache to stop by opening another console window and typing:</P> |
| |
| <PRE> |
| apache -k shutdown |
| </PRE> |
| |
| <P>This should be used instead of pressing Control-C in the running |
| Apache console window, because it lets Apache end any current |
| transactions and cleanup gracefully.</P> |
| |
| <P>You can also tell Apache to restart. This makes it re-read the |
| configuration files. Any transactions in progress are allowed to |
| complete without interruption. To restart Apache, run</P> |
| |
| <PRE> |
| apache -k restart |
| </PRE> |
| |
| <P>Note for people familiar with the Unix version of Apache: these |
| commands provide a Windows equivalent to <CODE>kill -TERM |
| <EM>pid</EM></CODE> and <CODE>kill -USR1 <EM>pid</EM></CODE>. The command |
| line option used, <CODE>-k</CODE>, was chosen as a reminder of the |
| "kill" command used on Unix.</P> |
| |
| <!--#include virtual="footer.html" --> |
| </BODY> |
| </HTML> |
| |