Internal Configuration

Introduction

Cherokee's configuration system is based on an internal text file format that the average user should not know about. This configuration file is read by the server and modified by the administration interface, so unless you are a Cherokee developer or a really advanced user, the following format description will not be very interesting to you.

Having said that, let's proceed to describe the configuration file format. It is basically a text file that contains a tree where final nodes contain values. Let's see a basic example:

    server!port = 80
    server!keepalive = 1

Most of the modules and plug-ins read a piece of the tree to configure themselves. It provides extremely flexible configuration capabilities for the price of a fairly complex text file. However, I would like to point out again that users should never read of modify the configuration file by hand, so it is a format that only developers should know about.

The following blocks will summarize the configuration keys that Cherokee '' handles:

Server

The server configuration keys define some of the server-wide properties, such as the user under which the server ought to run if it is run as root or whether to use keep-alive connections.

Key Type Description
server!port Number TCP port for HTTP
server!port_tls Number TCP port for HTTPS
server!max_fds Number Max open file descriptors
server!listen_queue Number Length of the listen queue
server!thread_number Number Number of threads
server!sendfile_min Number Minimum file size of using sendfile
server!sendfile_max Number Maximum file size of using sendfile
server!max_connection_reuse Number How many connections to reuse
server!ipv6 Bool Whether to use IPv6
server!timeout Number Connections timeout
server!log_flush_elapse Number Time between log flushes
server!keepalive Bool Allow keepalive connections
server!keepalive_max_requests Number How many keepalive reqs per connection
server!unix_socket Path Listen to a Unix socket
server!panic_action Path Path to cherokee-panic
server!chroot Bool Whether to use chroot
server!pid_file Path PID file
server!listen IP Listen NIC
server!poll_method String Which poll method it should use
server!server_tokens String Server identification: minor, minimal, os, full
server!thread_policy String Thread policy: fifo, rr, other
server!user String/Number Change effective user
server!group String/Number Change effective group
server!module_dir Path Path to the plug-in directory
server!module_deps Path Path to the plug-in inter-dependencies files

`server!server_tokens` parameters

Value Description
Product Cherokee
Minor Cherokee/0.0
Minimal Cherokee/0.0.0
OS Cherokee/0.0.0 (UNIX)
Full Cherokee/0.0.0 (UNIX) Ext/0.0 Ext2/0.0

`server!thread_policy` parameters

Value Description
fifo First in first out
rr Round Robin
other By default in Linux

Server Encoders

The `server!encoder` configuration branch allows to configure encode plug-ins. Each entry accepts a number of options:

Parameter Description
type Set the matching policy: deny_allow or allow_deny
allow List of extensions to encode
deny List of extensions that shouldn't be encoded

Example:

   server!encoder!gzip!allow = html,htm
   server!encoder!gzip!deny  = jpg,png,gz

Virtual Server

A virtual server contains the information related to one or more domains under the same configuration. In a Cherokee server there must be at least one virtual server named `default`, and there is no maximum number.

The prefix of this type of entry is `vserver`, and by far, it is the most common type of entry.

Key Type Description
vserver!default!document_root Path Document Root path
vserver!default!user_dir String User's web directory (for ~ requests)
vserver!default!domain! `id` String Domain name, admits wildcards
vserver!default!error_handler String Defines the error handler module
vserver!default!directory_index List String list: Directory indexes
vserver!default!ssl_certificate_file Path TLS/SSL certificate file
vserver!default!ssl_certificate_key_file Path TLS/SSL certificate key file
vserver!default!ssl_ca_list_file Path TLS/SSL CA list file

Besides these configuration keys there are a few other more complex that needs further explanation:

Defining a virtual server behavior

A virtual server behavior is basically defined by a rule list, which includes a number of rules against which each request will be checked.

There are a number of rules types, each one checking a different aspect of the request. The most usual rule types are the ones that checks the request URI: directories, extensions, regular expressions and headers.

All the rule types accept the same configuration sub-properties. However, the `match` property must be present in all the cases. It specifies which is the rule type and its properties.

The general syntax is:

vserver ! `name` ! rule ! `prioriry` ! match

The rule types plug-ins shipped within a standard Cherokee release include:

Directory

The directory specifies how to handle its contents. 

Example: the entry with priority 20, setting the properties for the
*icons* directory of the default virtual host would be represented
by:
      vserver!default!rule!20!match!type = directory
      vserver!default!rule!20!match!directory = /icons
Extension

It specifies a list of extensions and how they should be handled. 

Eg: the JPG extensions is:
      vserver!default!rule!30!match!type = extensions
      vserver!default!rule!30!match!extensions = jpg,jpeg
Requests

When a request matches a regular expression entry, it uses its configuration. 

Eg: requests beginning with 'a' and PHP extension:
      vserver!default!rule!40!match!type = request
      vserver!default!rule!40!match!request = ^a.*\.php$
Header

It tries to match a regular expression against a certain header entry. 

Eg: check whether the Referer header matches a specific host:
      vserver!default!rule!50!match!type = header
      vserver!default!rule!50!match!header = Referer
      vserver!default!rule!50!match!match = .+\.example\.com
Default

This rules matches every request. There must be a default rule configured at the end of the rule list to handle the request that did not match any other rule. 

Eg: Default rule the 'default' virtual server:
      vserver!default!rule!default

The following parameters are concatenated with any of the previous kinds of entry:

Key Type Description
priority Number Priority in the rules list
directory_root Path Special Directory Root for the request
allow_from List List of IP/Domain allowed to access the resource
handler String Handler (module) that handles the request
auth String Validator (module) that protects the resource
only_secure Bool Allow only secure (https) connections

The `auth` entry deserves a little more attention, actually. It restricts the access to some of the objects accessed by the web server based on a number of properties that are defined at its child properties:

Key Type Description
auth!methods List Allowed methods (basic, digest)
auth!realm String Realm of the resource
auth!users List List of allowed users

So, here are a few examples about how this notation works:

  • The default virtual server uses the "common" handler as default choice for its root directory: 

    vserver!default!rule!directory!/!handler = common
    vserver!default!rule!directory!/!priority = 1

  • The *.example.com and *.examples.org domains are restricted to be accessed from the local loop interface, and have to be handled as a FastCGI: 

    vserver!example!domains!1 = *.example.com
    vserver!example!domains!2 = *.example.org
    vserver!example!rule!directory!/!handler = fcgi
    vserver!example!rule!directory!/!priority = 1
    vserver!example!rule!directory!/!allow_from = 127.0.0.1,::1

  • ISO images should be handled as files and are protected by a htdigest file using only Digest authentication: 

    vserver!default!rule!extensions!iso,ISO!handler = file
    vserver!default!rule!extensions!iso,ISO!priority = 1
    vserver!default!rule!extensions!iso,ISO!auth = htdigest
    vserver!default!rule!extensions!iso,ISO!auth!realm = My secret isos
    vserver!default!rule!extensions!iso,ISO!auth!methods = digest
    vserver!default!rule!extensions!iso,ISO!auth!passwdfile = /var/passwd/isos.htdigest

Logs

The log files are defined as properties inside the Virtual Server hierarchy under a `logger` entry with the following properties:

Key Type Description
logger String Output format (validator name)
logger!access Node Defines the access log file
logger!error Node Defines the error log file

and then, both access and error accept a number of parameters depending on its property `type` which specifies where the logging information will be written. It can be either:

Logger writer Type Description
file Write a file
syslog Use the system logging mechanism
stderr Use the standard output
exec Execute a program with each line

If either `file` or `exec` is used, there is an additional parameter that has to be set. In the case of file, a sub-property named `filename` and for exec `command`.

Examples:

  • Apache format logs to the regular files: 

    vserver!default!logger = combined
    vserver!default!logger!access!type = file
    vserver!default!logger!access!filename = /var/log/cherokee.access.log
    vserver!default!logger!error!type = file
    vserver!default!logger!error!filename = /var/log/cherokee.error.log

Inclusion of Configuration

Sometimes it is nice to break out your configuration into several logical files to be more modular as well as more organized. You can use the `include` configuration to accomplish this. Here is an example:

    include = /etc/cherokee/advanced.conf

or even, it is possible to specify a directory to include all of its files:

    include = /etc/cherokee/mods-enabled/