Configuration
*************

Supported options
=================

The recipe supports the following options:

mainconfig
    location of apache configuration (ex: /etc/apache2/apache2.conf). if no
    value is provided we use the location of the config file from build recipe

bind
    Hostname and port on which Apache will listen for requests.
    Syntax is [hostname][:port].  Defaults to 80.
    If hostname is omitted then Apache will bind to all available
    interfaces.

backends
    Specifies the backend or backends which will process the
    requests. The syntax for backends::

     <hostname>[/<path>]:<ip address>:<port>

    If multiple backends are specified then each backend must include
    a hostname.

zope2_vhm_map
    Defines a virtual host mapping for Zope servers. This is a list of
    **hostname:ZODB location** entries which specify the location inside
    Zope where the website for a virtual host lives.
    The syntax for zope servers:

    <hostname>:<path>

log_format
    Specify the log format of apache (combined, common) , common is the default

etag
    Specify the format of the ETag to be generated (if any, eg: "MTime Size")

resources
    Specify directories to be mapped within the virtual host as static
    resource directories. For example::

      images:%{buildout:directory}/parts/my.theme/browser/images
      css:%{buildout:directory}/parts/my.theme/browser/css
      js:%{buildout:directory}/parts/my.theme/browser/js

resource-expires
    Configure expires for static resources matching a certain filename
    pattern. For example::

      \.(ico|pdf|flv|jpg|jpeg|png|gif|js|css|swf)$:"access plus 2 days"

resource-headers:
    Configure extra headers for static resources matching a certain filename
    pattern. For example::

      \.(ico|pdf|flv|jpg|jpeg|png|gif|js|css|swf)$:Cache-Control:"max-age=172800, public, must-revalidate"

redirects:
    Defines apache VirtualHost redirect. This is a list of
    **hostname:target_hostname** entries. Redirect is always permanent and
    redirects root folder only. 
    target_hostname must match hostname defined in backends.
    For example:

    www.plone.org:plone.org  
    (in this case all requests to www.plone.org are redirected to plone.org 
    which has to be defined in backends parameter)

extras
    Specify extra options to be included in the generated vhost configuration.


Example usage
=============



We'll start by creating a buildout that uses the recipe::

    >>> write('buildout.cfg',
    ... """
    ... [buildout]
    ... parts = apacheconfig
    ...
    ... [apacheconfig]
    ... recipe = plone.recipe.apache:config
    ... mainconfig = /usr/local/apache/config/httpd.conf
    ... bind = 80
    ... backends = plone.org:127.0.0.1:3128
    ... zope2_vhm_map = plone.org:/plone
    ... redirects = www.plone.org:plone.org
    ... resources = 
    ...    docs:${buildout:directory}/plone/recipe/apache/doctests
    ...    tests:${buildout:directory}/plone/recipe/apache/doctests
    ... resource-expires = 
    ...    \.(txt)$:"access plus 1 day"
    ...    \.(py)$:"access plus 2 weeks"
    ... resource-headers = 
    ...    \.(txt|py)$:Cache-Control:"max-age=3600, public, must-revalidate"
    ... """)

Running the buildout gives us::


    >>> print system(buildout)
    Installing apacheconfig.
    ...

