Apache HTTP Server

Using Apache with Cygwin

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 [email protected] 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.

• History of Apache for Cygwin
• Differences from Apache for Windows (native)
• Requirements
• Downloading Apache for Cygwin
• Configuring and Installing Apache for Cygwin
• Using Win32 native socket implementation instead
• Running Apache for Cygwin
• Running Apache for Cygwin as a Service

History of Apache for Cygwin

Cygwin support for Apache began with Apache 1.2.6 and Cygwin b18.

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.

Differences from Apache for Windows (native)

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"

  # 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.

Requirements

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.

Downloading Apache for Cygwin

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.

Configuring and Installing Apache for Cygwin

Apache on Cygwin is configured and compiled the same way as on most Unix systems. Refer to the general configuration and installation documents for details.

There are three ways to configure and build Apache for Cygwin, depending on how additional Apache modules should be used:

• Static linked version

  To build a static linked version of httpd including additional modules, use the following commands in the shell:

    $ cd apache_1.3.x
    $ ./configure [--enable-module=module|--add-module=/path/to/module]
    $ make
  

  This will produce the required extra libraries or object files for module and link everything to src/httpd.exe.

• Shared core, DLL linked version ('one-for-all' version)

  To build a DLL version of httpd including additional modules, use the following commands:

    $ cd apache_1.3.x
    $ ./configure --enable-rule=SHARED_CORE \
         [--enable-module=module|--add-module=/path/to/module]
    $ make
    $ make install
  

  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:

  • First build Apache's shared core as follows:

      $ cd apache_1.3.x
      $ ./configure --enable-rule=SHARED_CORE --enable-module=so \
           [--enable-module=module|--add-module=/path/to/module] \
           [--enable-shared=module]
      $ make
    

    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.

  • Add configuration directives to conf/httpd.conf to load and activate shared DLL modules at runtime:

      # httpd.conf
      [...]
      LoadModule foo_module   libexec/mod_foo.dll
      AddModule mod_foo.c
      [...]
    

• Using apxs to create shared DLL modules

  To make the extending httpd with shared DLL modules easier, you can use apxs.

  Make sure you have configured $CFG_LDFLAGS_SHLIB within apxs to include the --shared directive and the path to the shared code DLL cyghttpd.dll.

  After performing make install you will probably have the following lines within your apxs:

    # apxs
    [...]
    my $CFG_LD_SHLIB      = q(dllwrap --export-all --output-def libhttpd.def --implib libhttpd.a --driver-name gcc);          # substituted via Makefile.tmpl
    my $CFG_LDFLAGS_SHLIB = q(-g); # substituted via Makefile.tmpl 
    my $CFG_LIBS_SHLIB    = q();        # substituted via Makefile.tmpl 
    [...]
  

  Change these to reflect the new compile options needed for shared DLL modules as follows:

    # apxs
    [...]
    my $CFG_LD_SHLIB      = q(gcc);          # substituted via Makefile.tmpl
    my $CFG_LDFLAGS_SHLIB = q(-g --shared); # substituted via Makefile.tmpl 
    my $CFG_LIBS_SHLIB    = q(/path/to/cyghttpd.dll);        # substituted via Makefile.tmpl 
    [...]
  

  Now you should be able to create a shared DLL module from a mod_foo.c source file with:

    $ apxs -c mod_foo.c -o mod_foo.dll
  

  Place the resulting DLL in Apache's libexec directory, so the dlopen() function within the compiled in mod_so.c module can find and load it at runtime.

Using Win32 native socket implementation instead

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:

  $ cd apache_1.3.x
  $ ./configure --enable-rule=CYGWIN_WINSOCK [...]
  $ make

Using Win32 native socket calls is intended for performance reasons and as a hybrid way to interact with the underlying native socket implementation.

Running Apache for Cygwin

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:

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

Running Apache for Cygwin as a Service

Apache on Cygwin can be invoked as a Windows NT or Windows 2000 service. Cygwin has its own cygrunsrv.exe facility to define, remove, start, and stop services as follows:

• Installing Apache as a new Service

  Use the following statement to install httpd.exe as a new service:

    $ cygrunsrv -I service_name-p /usr/local/apache/bin/httpd.exe [-a arguments] \
        [-e VAR=VALUE] [-t auto|manual] [-u user] [-w passwd]
  

  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>.

Apache HTTP Server