Apache HTTP Server

This document explains how to install, configure and run
Apache 1.3 under the Cygwin
layer for Microsoft Windows. Cygwin is a POSIX.1 emulation
layer for 32-bit Microsoft Windows operating systems.

The Apache Group does not guarantee that this software will
work as documented, or even at all. If you find any bugs,
please document them on our bug reporting
page.

Latest development news, pre-compiled distribution binaries,
and third-party modules as DLLs, may be found at http://apache.dev.wapme.net/.
Contributions are highly welcome (please see TODO list);
please submit your code or suggestions to the bug report page,
or join the dev@httpd.apache.org mailing list.

The Win32 port of Apache is built
on its own, custom code within Apache to assure
interoperability with Windows operating systems. While it is
considered release quality, it is slower and less thoroughly
tested than the Unix ports. The Cygwin alternative uses the
well tested Unix code by using the Cygwin portability layer for
POSIX.1 emulation. The Cygwin port may suffer from gaps in
security or reliability due to the interaction of the Cygwin
compatibility layer with the native Windows API.

The Win32 port will be more
familiar to most Windows users. The Cygwin port (including the
build environment) will be more familiar to Unix admins and
developers. Due to these two different code bases, the security
and reliability of the two ports are unrelated to each other.
The Win32 port should be considered the more secure of the two
at this time. The Win32 port is recommended for most Windows
users, however the Cygwin port offers an extra layer of
compatibility for Unix developers.

Apache still performs best, and is most reliable, on Unix
platforms. First benchmarks have shown that the same Apache
setup on Cygwin performs about 30% slower than the
corresponding native Windows version.

Most of this document assumes that you have a working Cygwin
installation and want to compile Apache yourself from the
original distribution sources.

Due to licensing issues there has not been an official
binary distribution until Red Hat Inc. (who merged with Cygnus
Solutions Inc.) changed their Cygwin license to ensure compiled
executables do not fall under GPL license if the distributed
software is considered as open source.

Cygwin is supported in the official source distributions
from Apache 1.3.20 and later. Pre-compiled binaries for the
Cygwin platform (without the cygwin1.dll) will be
supplied at http://httpd.apache.org/
for each released version.

Both versions, Apache for Windows and Apache for Cygwin, are
designed to run on the same operating systems, the Windows NT
and Windows 2000 family. But there are considerable differences
between the two flavors.

While Apache for Windows is a native Windows port, Apache
for Cygwin relies on the Cygwin POSIX.1 emulation layer
provided by the cygwin1.dll dynamic library to
create a Unix compatible environment. Therefore we consider
Apache for Cygwin closer to the Unix side then to the Windows
side, even while it runs on Windows.

Most significant differences are the amount of changes to
the source code needed to compile and run Apache on the Cygwin
platform. While the native Windows port needs major changes and
platform specific additions, the Cygwin based port changes are
very small and most of the Unix source code can be used without
major changes on the Cygwin platform.

When to use Apache for Cygwin and/or Apache versus
Windows?
Apache for Cygwin is intended to be most useful if you want a
seamless transition from Unix systems to Windows systems for
your HTTP services.

If you are using Windows NT or Windows 2000 for development
and office purposes, but your productive HTTP server
environments are Unix based systems, you may use Apache for
Cygwin to develop on Windows and simply copy whole Apache
configurations (i.e.,httpd.conf) and
Perl (mod_perl), PHP (mod_php) or
Python (mod_snake) applications to your productive
Unix systems.

What about modules (mod_foo) for Apache
for Cygwin?
Apache for Cygwin can be built with most of the available
Apache modules with no or minimal changes. Many popular modules
have been compiled and tested with Apache for Cygwin, including
mod_dav, mod_ssl,
mod_php, mod_perl,
mod_gzip, and mod_jserv.

While there are developers who directly support the Windows
native port of Apache, very few module developers do. That is
why it is can be difficult to make a Unix-based Apache
installation with third-party modules work the same way on the
Windows side using the native port. Apache for Cygwin makes
this much easier.

What are the differences in the configuration
files?
While the Apache for Windows port uses Windows native path
names to refer files and directories, like

# httpd.conf (for Windows)
DocumentRoot "c:/apache/htdocs"

Apache for Cygwin can use unmodified POSIX style path names
like

# httpd.conf (for Cygwin)
DocumentRoot "/usr/local/apache/htdocs"

What about performance?
Apache for Cygwin is not as high-performance as Apache for
Windows on the same hardware.

This is to be expected, because Cygwin emulates a Unix
environment on a "foreign" operating system, while Apache for
Windows uses Windows code in its own native environment. First
benchmark results have shown that Apache for Cygwin is about
30% slower than native Apache for Windows counterpart.

This Apache 1.3 port for Cygwin is designed to run on
Windows NT 4.0 and Windows 2000, NOT on
Windows 95 or 98. Windows NT 4.0 and Windows 2000 have both
been successfully tested and approved. In all cases TCP/IP
networking must be installed.

Cygwin 1.x is required to compile and run this version.
Cygwin 1.3.9 and 1.3.10 have been tested and approved on both
supported OSes. We suggest using Cygwin 1.3.9-2 and higher.

Note:If you want to compile shared DLL
modules using apxs you will need
Cygwin 1.3.9-2 or higher version, which includes a version of
ld.exe with --auto-import support.

The Cygwin platform is supported out of the box by Apache
1.3.20 and later. This means there is no extra download
required for the Cygwin platform. The latest version of Apache
can be found on the Apache httpd web site at http://httpd.apache.org/.
The site lists the current release, any more recent development
versions, and information on any mirror sites.

What about Cygwin Net Distribution binaries?
Apache for Cygwin is also available as pre-compiled binary
package for the Cygwin Net Distribution available at
http://www.cygwin.com/ and it's
setup.exe
installation process.

This will produce the required extra libraries or object
files that hold all static linked code. Then
dllwrap and dlltool will export
all of those (including any additional module code) to the
shared cyghttpd.dll and create the
libhttpd.a import library which is required
for linking httpd.exe.

Note: After make install
is performed you will find the resulting core DLL module
cyghttpd.dll within
/usr/local/apache/libexec. This is due to the
installation process. Please move the file to Apache's
bin directory, i.e.

$ mv /usr/local/apache/libexec/cyghttpd.dll /usr/local/apache/bin

or to an other place inside your $PATH, i.e.
/usr/bin is used in the Cygwin Net Distribution
layout. The core DLL module cyghttpd.dll is the
only file that should reside in
/usr/local/apache/bin directory. All other
shared DLL modules mod_foo.dll should be
located in /usr/local/apache/libexec.

Shared DLL modules linked version

This method is ONLY supported using a
version of ld.exe which supports the
--auto-import option. Please see the
requirements section for more
information.

To build a dynamic loadable DLL version of
httpd which can load DLL modules on the fly
(at runtime), proceed as follows:

You will notice that there is a warning message
shown which lets you know that the shared core DLL
library src/cyghttpd.dll is missing while
trying to link the shared DLL modules
mod_foo.dll.

Unfortunately, during Apache's build process, the shared
modules are linked before the shared core import
library src/cyghttpd.dll has been made.
The shared modules depend on this import library, so
they cannot link for the first time you run
make.

Re-run make to build the shared module
DLLs and install the whole package to the installation
directory:

$ make
$ make install

All shared modules are placed into
libexec, including the shared core DLL
cyghttpd.dll. When Apache's
/bin/httpd is started, it has to dynamically
link cyghttpd.dll during runtime; that is
why you have to place the shared core DLL
cyghttpd.dll to the same directory where
httpd.exe resides, i.e.
/usr/local/apache/bin or an other place
in your $PATH.

Apache for Cygwin supports an option to use the Win32 native
socket calls instead of Cygwin's POSIX wrappers internally. To
use the Win32 native socket calls configure Apache for Cygwin
with the CYGWIN_WINSOCK configuration rule flag
as follows:

Apache on Cygwin can be started and stopped in the same
manner as on Unix systems. You may also use the apachectl tool
for starting and stopping Apache.

Starting Apache

If installed with the default Apache directory layout,
you can start httpd as follows:

$ /usr/local/apache/bin/httpd

An explicit background indicator (&) is
not required. The parent process is automatically detached
from the current terminal. Check the global
error_log to see if Apache started cleanly
without any major problems.

Stopping Apache

To stop Apache send at least a SIGTERM
signal to the parent httpd process:

$ kill -TERM `cat /usr/local/apache/logs/httpd.pid`

Gracefully Restarting Apache

In order to update configuration directives and reload
the httpd.conf configuration file, send a
SIGHUP to the parent httpd
process:

Where -a is used to pass command line
arguments (such as -DFOO defines) to
httpd.exe, and -e is used to pass
environment variables. If necessary you may use the
-t options to set the autostart configuration
for the service. If you want the new service to run under a
different userid, you will have to supply the
-u and -w options.

Starting Apache as a Service

After the new service is installed it can be started
using the following command:

$ cygrunsrv -S service_name

Check your process table and global
error_log file to ensure Apache has started
without any major problems.

Stopping an Apache Service

A running Apache service may be stopped using the
following command:

$ cygrunsrv -E service_name

This will stop all running httpd.exe
processes and shutdown the HTTP service for the
machine.

Removing an Apache Service

An installed Apache service may be removed from Windows
NT or Windows 2000 using the following command:

$ cygrunsrv -R service_name

This will remove your previously defined and installed
service from the machine.

Please refer to the man page for
cygrunsrv and the Cygwin mailing list for further
details of how services are invoked.

Any additional contributions to this document and the Cygwin
support for Apache are highly welcome. Please send them to
Stipe Tolj <tolj@wapme-systems.de>.