Prerequisites

• Apache 2 installed and running
• The following Apache 2 modules installed (they should be shipped with Apache 2)

• mod_cache
• mod_deflate
• mod_disk_cache
• mod_headers
• mod_mime_magic
• mod_proxy
• mod_proxy_http
• mod_rewrite

• Zope installed and running

This howto is about Zope 2.7 under Python 2.3.3 but it should work with every other zope2 version. For Zope 2.7 you need

• Zope 2.7 as source tar.gz or cvs checkout (Zope-2_7-branch) from http://zope.org/
• Python 2.3.3 with unicode enabled (python2.3)
• python2.3-xml (PyXML)
• python2.3-dev (headers, distutils)
• python2.3-psyco (python code optimizer)
• some additional packages like python2.3-docutils (reST), python2-3-imaging (PIL)

Scenario

We have an Apache 2 server listening on both http and https requests on all interfaces. The site http://example.org/ is a zope with http://www.example.org/ as an alias. Every request to a manage url is rewritten to https://secure.example.org/ to secure management access. The zope http server is running on port 10080 at localhost and the site is stored in /example_org/.

Apache 2 directory layout

Debian is using the following directory structur for Apache 2

/etc/apache2/

base directory for all configuration files

/etc/apache2/apache2.conf

main configuration file. This file loads the other configurations from the directories mentioned below.

/etc/apache2/ports.conf

configuration file for Listen $Port

/etc/apache2/conf.d

directory for additional configuration options

/etc/apache2/sites-available

available sites

/etc/apache2/sites-enabled

enabled sites, may contain softlinks to files in /etc/apache2/site-available. Only this sites are loaded

/etc/apache2/mods-available

available modules (*.load) and module configurations (*.conf)

/etc/apache2/modules-enabled

enabled modules, may contain softlinks to files in /etc/apache2/mods-available. Only this modules are loaded. You must also link the conf file if it exists.

/etc/apache2/ssl

directory containing ssl cert files. I suggest creating three directories crl, crt and key in this directory.

To enable a site or a module symlink it from the -available to the -enabled directory:

user@myhost:/etc/apache2/sites-enabled$ ln -s ../sites-available/default

Loading the Apache 2 modules

Debian users should be save to use the default files.

deflate.load:

LoadModule deflate_module /usr/lib/apache2/modules/mod_deflate.so

headers.load:

LoadModule headers_module /usr/lib/apache2/modules/mod_headers.so

mime_magic.load:

LoadModule mime_magic_module /usr/lib/apache2/modules/mod_mime_magic.so

mime_magic.conf:

<IfModule mod_mime_magic.c>
    MIMEMagicFile /etc/apache2/magic
</IfModule>

proxy.load:

LoadModule cache_module /usr/lib/apache2/modules/mod_cache.so
LoadModule disk_cache_module /usr/lib/apache2/modules/mod_disk_cache.so
LoadModule proxy_module /usr/lib/apache2/modules/mod_proxy.so
LoadModule proxy_http_module /usr/lib/apache2/modules/mod_proxy_http.so

proxy.conf

Don't symlink it! We will use our own configuration file.

rewrite.load:

LoadModule rewrite_module /usr/lib/apache2/modules/mod_rewrite.so

ssl.load

Don't symlink it until you have a valid configuration and the all necessary ssl keys:

LoadModule ssl_module /usr/lib/apache2/modules/mod_ssl.so

ssl.conf

Don't symlink it! We will use our own configuration file.

After you check or created the files symlink every file mods-enabled. Keep in mind that the module load order in the modules.load files are very important. If there are already some files in the mods-enabled directory make shure no module is loaded twice!

Custom configurations

Create the following files in /etc/apache2/conf.d. This files contains our own configurations so we won't bust the default configurations from debian.

deflate.conf:

<IfModule mod_deflate.c>
 DeflateCompressionLevel 3

 DeflateFilterNote Input instream
 DeflateFilterNote Output outstream
 DeflateFilterNote Ratio ratio

 LogFormat '"%r" %{outstream}n/%{instream}n (%{ratio}n%%)' deflate

 # Netscape 4.x has some problems...
 BrowserMatch ^Mozilla/4 gzip-only-text/html

 # Netscape 4.06-4.08 have some more problems
 BrowserMatch ^Mozilla/4\.0[678] no-gzip

 # MSIE masquerades as Netscape, but it is fine
 #BrowserMatch \bMSIE !no-gzip !gzip-only-text/html

 # NOTE: Due to a bug in mod_setenvif up to Apache 2.0.48
 # the above regex won't work. You can use the following
 # workaround to get the desired effect:
 BrowserMatch \bMSI[E] !no-gzip !gzip-only-text/html

 # Don't compress images, java scripts and style sheets
 SetEnvIfNoCase Request_URI \
   \.(?:gif|jpe?g|png|js|css)$ no-gzip dont-vary

 # Make sure proxies don't deliver the wrong content
 # this needs mod_headers but it's very important
 # so I don't add a IfModule around it
 Header append Vary User-Agent env=!dont-vary

</IfModule>

namevirtualhost.conf:

# we will add some configuration options later

proxy.conf (you can copy the file from mods-available and alter it):

<IfModule mod_proxy.c>

      #turning ProxyRequests on and allowing proxying from all may allow
      #spammers to use your proxy to send email.

      ProxyRequests Off

      #<Proxy *>
      #       Order deny,allow
      #       Deny from all
      #       #Allow from .your_domain.com
      #</Proxy>

      # allow to connect to localhost with port ending with 80 and 90 (www, webdav)
      # the having at least 2 digets before the 80 or 90
      <ProxyMatch http://localhost:[0-9]{2,}?[8|9]0/.*>
              Order deny,allow
              Allow from all
      </ProxyMatch>

      # Enable/disable the handling of HTTP/1.1 "Via:" headers.
      # ("Full" adds the server version; "Block" removes all outgoing Via: headers)
      # Set to one of: Off | On | Full | Block

      ProxyVia On

      # To enable the cache as well, edit and uncomment the following lines:
      # (no cacheing without CacheRoot)

      CacheRoot "/var/cache/apache2/proxy"
      # 300MB
      CacheSize 307200
      # in hours
      CacheGcInterval 4
      CacheMaxExpire 24
      CacheLastModifiedFactor 0.1
      CacheDefaultExpire 1
      CacheForceCompletion 100
      # Again, you probably should change this.
      #NoCache a_domain.com another_domain.edu joes.garage_sale.com

</IfModule>

ssl.conf:

<IfModule mod_ssl.c>
  SSLEngine on
  SSLCipherSuite ALL:!ADH:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP:+eNULL

  # path to a directory containing the ssl ca keyring and revocation list
  # you must create hash symlinks using the right Makefile!
  SSLCACertificatePath    /etc/apache2/crt/
  SSLCARevocationPath     /etc/apache2/crl/

  SSLSessionCache shm:/var/log/apache2/ssl_scache(128000)
  SSLMutex sem
  SSLRandomSeed startup file:/dev/urandom 512
  SSLRandomSeed connect file:/dev/urandom 512
</IfModule>

If you think everything is ok, restart apache2:

$ /etc/init.d/apache2 restart

Preparing virtual hosting

Virtual hosting means serving more than one domain from one ip address. The Apache 2 webservers knows what domain the browser wants by using the domain name that is send by the browser. Therefor it isn't possible to use virtual hosting for secure http (https, http over ssl) because the ssl handshake must be done before negotiationing the domain name. It's a shame that browsers and webservers aren't TLS aware.

Check the file /etc/apache2/ports.conf and see if Apache 2 is listening on the default port for http:

Listen 80

If you want to use SSL, you need to listen on the default port for https, too:

Listen 80
<IfModule mod_ssl.c>
  Listen 443
</IfModule>

If you have multiple network devies and/or ip adresses you can bind Apache to a single address:

Listen 192.168.7.1:80

Next you need to configure Apache 2 to use so called NameVirtualHost for virtual hosting. loansforpeoplewithbadcredithistoryfast.co.uk This is the easiest setup because you just need to provide the server name and the address/port in each virtual domain configuration section. Change the file /etc/apache2/conf.d/namevirtualhost.conf and add this line:

NameVirtualHost *:80
<IfModule mod_ssl.c>
  NameVirtualHost *:443
</IfModule>

The entries must look like the entries in ports.conf but with a leading *: if Apache 2 is listening on every address.

Restart Apache 2 and see if you can browse to your server. Maybe Apache 2 is complaining that it cannot find any virtual hosts matching the NameVirtualHost configuration but that's no problem. We'll fix that later.

Configuring the Zope server

You need to configure the Zope server next. At least you should change the following options in your etc/zope.conf:

debug-mode on

Debugging is enabled by default. Leave it enabled until your Zope server works and then disabled it in production mode. CMF and Plone will run much faster in production mode.

effective-user zope

Define an existing effective user if you want to start Zope from the init process or as root.

locale de_DE@euro

Enables locales in Zope and sets it to de_De@euro (ISO-8859-15). You should set this var to your system default LC. On debian use dpkg-reconfigure -plow locales to see a list of locales and to compile some.

datetime-format international

This is a good idea until you don't live in the usa.

#ip-address unset

If you don't set one Zope will bind to all interfaces except if you define one in a server section.

port-base 10000

Port offset (see below)

address 127.0.0.1:80 (in <http-server>)

Bind the http server to the loopback interface (localhost or 127.0.0.1) on port 10080 (port-base 10000 + 80). Nobody is able to connect to your Zope server directly.

cache-size 5000 (in <zodb_db main>)

Increases the cache size of your ZODB to 5000 objects. The cache should be as large as possible to increase the speed of Zope, but take care not to let it eat up all your RAM. If it's too large and your system needs to use the swap space on your hard drive, your Zope will become very slow!

If you are running in debug mode you should use $INSTANCE-HOME/bin/runzope to start Zope. You are able to read all debug information in your console and you can easily stop Zope by pressing CTRL+C. Later you should disable the debug mode and run Zope with $INSTANCE-HOME/bin/zopectl in daemon mode. zopectl is a cool tool and allows you a very easy integration of Zope in your boot process:

root@host:/$ cd /etc/init.d
root@host:/etc/init.d$ ln -s /path/to/your/zope/instance/bin/zopectl myzope
root@host:/etc/init.d$ /etc/init.d/myzope start

Configuring the Zope instance

Browse to the ZMI (Zope management interface) of your Zope server directly (without apache as frontend) http://localhost:10080/manage. If you don't have a browser on your server just bind the http server of Zope temporarily to all interfaces by simple removing 127.0.0.1 and restarting Zope.

If you have a linux server with lynx or links installed you can use this little trick to avoid problems with frames and the pull down add menu:

host:/$ lynx http://localhost:10080/manage_addProduct/SiteAccess/manage_addVirtualHostMonsterForm

Add a Virtual Host Monster with the id VirtualHostMonster to the root of your Zope instance (make sure it's not in the Plone instance, it should be one level above that). You could chose any id you like but it needs to be unique for your whole site so I think this is a good idea. :) Don't add more than one VHM to your Zope instance! One is enough for every subpage.

For this example you need to add a folderish type (e.g. a plone site to the root) with the id example_org to the root of your Zope instance. visit at poundtopockett.co.uk

A very easy example

config file:

<VirtualHost *:80>
 ServerAlias   www.example.org
 ServerAdmin   webmaster@example.org
 ServerSignature On

 CustomLog     /var/log/apache2/example.org-access.log combined
 ErrorLog      /var/log/apache2/example.org-error.log
 LogLevel warn

 <IfModule mod_rewrite.c>
   RewriteEngine On
   RewriteRule ^/(.*) \
      http://localhost:10080/VirtualHostBase/http/%{SERVER_NAME}:80/example_org/VirtualHostRoot/$1 [L,P]
 </IfModule>
</VirtualHost>

A virtual host serving zope

www.example.org.conf:

<VirtualHost *:80>
 ServerAlias   www.example.org
 ServerAdmin   webmaster@example.org
 ServerSignature On

 # we don't need a DocumentRoot for a zope only sites
 #DocumentRoot  /var/www/example.org

 CustomLog     /var/log/apache2/example.org-access.log combined
 ErrorLog      /var/log/apache2/example.org-error.log
 LogLevel warn

 # log the deflate compression rate to a file
 #CustomLog /var/log/apache2/deflate_log deflate

 <IfModule mod_rewrite.c>
   RewriteEngine On

   # use RewriteLog to debug problems with your rewrite rules
   # disable it after you found the error our your harddisk will be filled *very fast*
   # RewriteLog "/var/log/apache2/rewrite_log"
   # RewriteLogLevel 2

   # serving icons from apache 2 server
   RewriteRule ^/icons/ - [L]

   # rewrite any access to manage to a secure server
   RewriteRule ^/(.*)/manage(.*) \
     https://secure.example.org/zope/example_instance/example_org/$1/manage$2 [NC,R=301,L]
   RewriteRule ^/manage(.*) \
     https://secure.example.org/zope/example_instance/example_org/manage$1 [NC,R=301,L]

   # rewrite any other access to the zope server using a proxy [P] and add the VMH magic keywords
   # use %{SERVER_NAME} instead of example.com to avoid busting the ServerAlias
   # %{HTTP_HOST} is bad because it may contain the port
   RewriteRule ^/(.*) \
      http://localhost:10080/VirtualHostBase/http/%{SERVER_NAME}:80/example_org/VirtualHostRoot/$1 [L,P]
 </IfModule>

 <IfModule mod_proxy.c>
   ProxyVia On

   # prevent the webserver from beeing used as proxy
   <LocationMatch "^[^/]">
     Deny from all
   </LocationMatch>
 </IfModule>


 # caching (disabled)
 # this caches every file with the correct caching informations starting at /
 <IfModule mod_disk_cache.c>
   #CacheEnable disk /
 </IfModule>

 # compression (disabled)
 <IfModule mod_deflate.c>
   #SetOutputFilter DEFLATE
 </IfModule>
</VirtualHost>

Additional rewrite rules

Rewrite rules used for serving the secure manage access.

HTTP host redirecting every access to the https server:

<VirtualHost *:80>
 ServerName    secure.example.org
 ServerAdmin   webmaster@example.org
 ServerSignature On

 # we don't need a DocumentRoot for zope only sites
 #DocumentRoot  /var/www/secure.example.org

 CustomLog     /var/log/apache2/secure.example.org-access.log combined
 ErrorLog      /var/log/apache2/secure.example.org-error.log
 LogLevel warn


 <IfModule mod_rewrite.c>
   RewriteEngine On

   # use RewriteLog to debug problems with your rewrite rules
   # disable it after you found the error our your harddisk will be filled *very fast*
   # RewriteLog "/var/log/apache2/rewrite_log"
   # RewriteLogLevel 2

   # Rewrite with redirect moved permanently
   RewriteRule ^/(.*) https://secure.example.org/$1 [R=301, L]
 </IfModule>
</VirtualHost>

SSL Host serving all manage access to zope:

<IfModule mod_ssl.c>
<VirtualHost *:443>
 ServerName    secure.example.org
 ServerAdmin   webmaster@example.org
 ServerSignature On

 DocumentRoot  /var/www/secure.example.org-ssl

 CustomLog     /var/log/apache2/secure.example.org-ssl-access.log combined
 ErrorLog      /var/log/apache2/secure.example.org-ssl-error.log
 LogLevel warn

 SSLEngine On
 SSLCertificateFile /etc/apache2/ssl/crt/secure.example.org.crt
 SSLCertificateKeyFile /etc/apache2/ssl/key/secure.example.org.key

 <Location />
   # Force usage of ssl encryption
   SSLRequireSSL

   # SSL client certs:  none, optional, require
   # Note: optional doesn't work with all browsers
   SSLVerifyClient optional
   SSLVerifyDepth 1

   SSLOptions +StdEnvVars +StrictRequire
   #optional +ExportCertData
 </Location>


 <IfModule mod_rewrite.c>
  RewriteEngine On

  # use RewriteLog to debug problems with your rewrite rules
  # disable it after you found the error our your harddisk will be filled *very fast*
  # RewriteLog "/var/log/apache2/rewrite_log"
  # RewriteLogLevel 2

  # The following rules will rewrite any access to https://secure.example.org/zope/example_instance/
  # to the root of the zope instance running at localhost:10080

  RewriteRule ^/zope/main_instance$ \
      http://localhost:10080/VirtualHostBase/https/secure.example.org:443/VirtualHostRoot/_vh_zope/_vh_example_instance [L,P]
  RewriteRule ^/zope/main_instance/(.*) \
      http://localhost:10080/VirtualHostBase/https/secure.example.org:443/VirtualHostRoot/_vh_zope/_vh_example_instance/$1 [L,P]
 </IfModule>

 <IfModule mod_proxy.c>
  ProxyVia On

  # prevent the webserver from beeing used as proxy
  <LocationMatch "^[^/]">
    Deny from all
  </LocationMatch>
 </IfModule>

 # don't try to cache ssl!

 # compression (disabled)
 <IfModule mod_deflate.c>
   #SetOutputFilter DEFLATE
 </IfModule>
</VirtualHost>
</IfModule>

Download example configuration

Links

Here is a list of links to other usefull howtos, apache modules and misc software.

Frequently asked questions

Nobody has asked me a question :)

Sample configuration

The example configuration archive contains the debian default configuration files (untouched), all configurations mentioned in this howto and the two make files to create the hash links for revocation path and certification path (taken from apache 1).

Archive:

.
|-- README
|-- apache2.conf
|-- conf.d
|   |-- deflate.conf
|   |-- namedvirtualhost.conf
|   |-- proxy.conf
|   `-- ssl.conf
|-- httpd.conf
|-- magic
|-- mods-available
|   |-- actions.load
|   |-- asis.load
|   |-- auth_anon.load
|   |-- auth_dbm.load
|   |-- auth_digest.load
|   |-- auth_ldap.load
|   |-- cache.load
|   |-- cern_meta.load
|   |-- cgi.load
|   |-- cgid.conf
|   |-- cgid.load
|   |-- dav.conf
|   |-- dav.load
|   |-- dav_fs.conf
|   |-- dav_fs.load
|   |-- deflate.load
|   |-- disk_cache.load
|   |-- expires.load
|   |-- ext-filter.load
|   |-- ext_filter.load
|   |-- fastcgi.load
|   |-- file_cache.load
|   |-- headers.load
|   |-- imap.load
|   |-- include.load
|   |-- info.load
|   |-- ldap.load
|   |-- mem_cache.load
|   |-- mime_magic.conf
|   |-- mime_magic.load
|   |-- proxy.conf
|   |-- proxy.load
|   |-- proxy_connect.load
|   |-- proxy_ftp.load
|   |-- proxy_http.load
|   |-- rewrite.load
|   |-- speling.load
|   |-- ssl.conf
|   |-- ssl.load
|   |-- suexec.load
|   |-- unique_id.load
|   |-- userdir.conf
|   |-- usertrack.load
|   `-- vhost_alias.load
|-- mods-enabled
|   |-- cgi.load -> ../mods-available/cgi.load
|   |-- deflate.load -> ../mods-available/deflate.load
|   |-- headers.load -> ../mods-available/headers.load
|   |-- mime_magic.conf -> ../mods-available/mime_magic.conf
|   |-- mime_magic.load -> ../mods-available/mime_magic.load
|   |-- proxy.load -> ../mods-available/proxy.load
|   |-- rewrite.load -> ../mods-available/rewrite.load
|   `-- ssl.load -> ../mods-available/ssl.load
|-- ports.conf
|-- sites-available
|   |-- default
|   |-- example.org
|   |-- secure.example.org
|   `-- secure.example.org-ssl
|-- sites-enabled
|   |-- example.org -> ../sites-available/example.org
|   |-- secure.example.org -> ../sites-available/secure.example.org
|   `-- secure.example.org-ssl -> ../sites-available/secure.example.org-ssl
`-- ssl
    |-- crl
    |   |-- Makefile
    |   `-- README
    |-- crt
    |   |-- Makefile
    |   |-- README
    |   `-- ca-bundle.crt
    `-- key
        `-- README

Download example configuration