<!--
  Copyright (C) Igor Sysoev
  Copyright (C) Nginx, Inc.
  -->

<!DOCTYPE article SYSTEM "../../../dtd/article.dtd">

<article name="nginx for Windows"
         link="/en/docs/windows.html"
         lang="en"
         rev="3">

<section>

<para>
Version of nginx for Windows uses the native Win32 API (not the Cygwin emulation
layer).
Only the <c-func>select</c-func> connection processing method is currently used,
so high performance and scalability should not be expected.
Due to this and some other known issues version of nginx for Windows
is considered to be a <i>beta</i> version.
At this time, it provides almost the same functionality as a UNIX version
of nginx except for
XSLT filter, image filter, GeoIP module, and embedded Perl language.
</para>

<para>
To install nginx/Windows, <link doc="../download.xml">download</link>
the latest mainline version distribution (<mainline_version/>),
since the mainline branch of nginx contains all known fixes.
Then unpack the distribution, go to the
nginx-<mainline_version/>
directory, and run <command>nginx</command>.
Here is an example for the drive C: root directory:

<programlisting>
cd c:\
unzip nginx-<mainline_version/>.zip
cd nginx-<mainline_version/>
start nginx
</programlisting>

Run the <command>tasklist</command> command-line utility
to see nginx processes:

<programlisting>
C:\nginx-<mainline_version/>&gt;tasklist /fi "imagename eq nginx.exe"

Image Name           PID Session Name     Session#    Mem Usage
=============== ======== ============== ========== ============
nginx.exe            652 Console                 0      2 780 K
nginx.exe           1332 Console                 0      3 112 K
</programlisting>

One of the processes is the master process and another is the worker process.
If nginx does not start, look for the reason in
the error log file <path>logs\error.log</path>.
If the log file has not been created, the reason for this should be reported
in the Windows Event Log.
If an error page is displayed instead of the expected page, also look
for the reason in the <path>logs\error.log</path> file.
</para>

<para>
nginx/Windows uses the directory where it has been run as the prefix
for relative paths in the configuration.
In the example above, the prefix is
<path>C:\nginx-<mainline_version/>\</path>.
Paths in a configuration file must be specified in UNIX-style using
forward slashes:

<programlisting>
access_log   logs/site.log;
root         C:/web/html;
</programlisting>
</para>

<para>
nginx/Windows runs as a standard console application (not a service),
and it can be managed using the following commands:

<table note="yes">

<tr>
<td width="20%">nginx -s stop</td>
<td>fast shutdown</td>
</tr>

<tr>
<td>nginx -s quit</td>
<td>graceful shutdown</td>
</tr>

<tr>
<td>nginx -s reload</td>
<td>
changing configuration,
starting new worker processes with a new configuration,
graceful shutdown of old worker processes
</td>
</tr>

<tr>
<td>nginx -s reopen</td>
<td>re-opening log files</td>
</tr>

</table>
</para>

</section>

<section id="known_issues"
        name="Known issues">

<list type="bullet">

<listitem>
Although several workers can be started, only one of them
actually does any work.
</listitem>

<listitem>
A worker can handle no more than 1024 simultaneous connections.
</listitem>

<listitem>
The cache and other modules which require shared memory support do not work
on Windows Vista and later versions due to
address space layout randomization being enabled in these Windows versions.
</listitem>

<listitem>
The UDP proxy functionality is not supported.
</listitem>

</list>

</section>

<section id="possible_future_enhancements"
        name="Possible future enhancements">

<list type="bullet">

<listitem>
Running as a service.
</listitem>

<listitem>
Using the I/O completion ports as a connection processing method.
</listitem>

<listitem>
Using multiple worker threads inside a single worker process.
</listitem>

</list>

</section>

</article>