IndexDevelopment info

Development: cherokee.conf


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.

The default location for Cherokee configuration files is `/etc/cherokee`, but this may vary based on distribution or installation parameters.

If you are completely sure about what you are doing, you can modify it by hand. We recommend you not to do so, since everything can be handled from cherokee-admin and a lot of security measures and consistency checks are made to ensure you end up with a well formed cherokee.conf file.

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

Let's see a basic example
    server!bind!1!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 the current Cherokee release handles:


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!bind!#!port Number Listen to a TCP port. # is a secuential number since many ports can be listened at once.
server!bind!#!tls Bool on|off: whether the listened port # is 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_lapse Number Time between log flushes
server!nonces_cleanup_lapse Number Time between Nonces clean ups
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.98
Minimal Cherokee/0.98.0
OS Cherokee/0.98.0 (UNIX)
Full Cherokee/0.98.0 b2721 (UNIX)

`server!thread_policy` parameters

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

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.

Virtual servers are stored in a numbered list. The starting number does not really matter. What matters is that the list will be interpreted in an orderly fashion to prioritize some virtual servers over others, which can be of use depending on the way these are defined. The only precuation to take is making sure there are no repeated priorities, since the behavior in these cases in undefined.

Key Type Description
vserver!1!nick = default String The name of the Virtual Server
vserver!1!document_root Path Document Root path
vserver!1!user_dir String Users' web directory (for ~ requests)
vserver!1!domain! `id` String Domain name, admits wildcards
vserver!1!error_handler String Defines the error handler module
vserver!1!directory_index List String list: Directory indexes
vserver!1!ssl_certificate_file Path TLS/SSL certificate file
vserver!1!ssl_certificate_key_file Path TLS/SSL certificate key file
vserver!1!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 ! order ! rule ! prioriry ! match

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


The directory specifies how to handle its contents.

Example: an entry with priority 20, setting the properties for the icons directory of the default virtual host would be represented by:

      vserver!1!nick = default
      vserver!1!rule!20!match!type = directory
      vserver!1!rule!20!match!directory = /icons

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

Eg: the JPG extensions is:

      vserver!1!rule!30!match!type = extensions
      vserver!1!rule!30!match!extensions = jpg,jpeg

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

Eg: requests beginning with a and PHP extension:

      vserver!1!rule!40!match!type = request
      vserver!1!rule!40!match!request = ^a.*\.php$

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

Eg: check whether the Referer header matches a specific host:

      vserver!1!rule!50!match!type = header
      vserver!1!rule!50!match!header = Referer
      vserver!1!rule!50!match!match = .+\.example\.com

This rules matches every request. There must be a default rule configured at the end of the rule list to handle the requests that did not match any other rule. The end of the list means the smallest priority value in relative terms. It doesn't have to be 1 necessarily.

Eg: Default rule for the default virtual server:

      vserver!1!rule!1!match = default
      vserver!1!rule!1!handler = common
      vserver!1!rule!1!handler!iocache = 0

The `!encoder` configuration entry allows to configure encoding plug-ins. Each entry applies to a specific rule.

Parameter Description
deflate deflate encoder. 0|1 to define disabled|enabled.
gzip gzip encoder. 0|1 to define disabled|enabled.
   vserver!1!rule!100!encoder!deflate = 1
   vserver!1!rule!100!encoder!gzip = 1
   vserver!1!rule!100!match = extensions
   vserver!1!rule!100!match!extensions = html

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. Accepted validarot modules are htdigest, htpasswd, ldap, mysql, pam, plain. 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

Some validators have extra configuration keys.

Table: htdigest, htpasswd, plain
Key Type Description
auth!passwdfile String Full path to the passwords' file. htdigest|htpasswd|plain
Table: mysql
Key Type Description
auth!host String MySQL host.
auth!database String Database name.
auth!user String Database user.
auth!passwd String Database password.
auth!port Number Port number of the service.
auth!query String
auth!use_md5_passwd Bool Encrypt the passwords with MD5.
Table: ldap
Key Type Description
auth!server String IP or hostname of the LDAP server.
auth!port Number Port number of the service.
auth!base_dn String Base distinguished name.
auth!bind_dn String User
auth!bind_pw String Password
auth!filter String LDAP search filter.
auth!tls Bool Indicates TLS based integrity
auth!ca_file String Cert file. Must be provided if TLS is enabled.
Table: authlist
Key Type Description
auth String name of the validator module: authlist
auth!list!#!password String Password for entry number #
auth!list!#!user String User for entry number #

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!1!nick = default
        vserver!1!rule!10!directory!/!handler = common
  • The * and * domains are restricted to be accessed from the local loop interface, and have to be handled as a FastCGI:

        vserver!5!nick = example
        vserver!5!domains!1 = *
        vserver!5!domains!2 = *
        vserver!5!rule!10!directory!/!handler = fcgi
        vserver!5!rule!10!directory!/!priority = 1
        vserver!5!rule!10!directory!/!allow_from =,::1
  • Rules can be defined that return custom errors using the HTTP error handler: custom error.

        vserver!10!rule!100!handler = custom_error
        vserver!10!rule!100!handler!error = 400
  • ISO images should be handled as files and are protected by a htdigest file using only Digest authentication:

        vserver!1!nick = default
        vserver!1!rule!100!extensions!iso,ISO!handler = file
        vserver!1!rule!100!extensions!iso,ISO!auth = htdigest
        vserver!1!rule!100!extensions!iso,ISO!auth!realm = My secret isos
        vserver!1!rule!100!extensions!iso,ISO!auth!methods = digest
        vserver!1!rule!100!extensions!iso,ISO!auth!passwdfile = /var/passwd/isos.htdigest
  • Authenticated directory with htpasswd validator:

    vserver!10!rule!500!auth = htpasswd
    vserver!10!rule!500!auth!methods = basic
    vserver!10!rule!500!auth!passwdfile = /var/www/passwd.htpasswd
    vserver!10!rule!500!auth!realm = secret
    vserver!10!rule!500!match = directory
    vserver!10!rule!500!match!directory = /auth
    vserver!10!rule!500!match!final = 0
    vserver!10!rule!500!only_secure = 0
  • Same example, using mysql validator:

    vserver!10!rule!500!auth = mysql
    vserver!10!rule!500!auth!database = auth_users
    vserver!10!rule!500!auth!host = localhost
    vserver!10!rule!500!auth!methods = basic,digest
    vserver!10!rule!500!auth!passwd = db_passwd
    vserver!10!rule!500!auth!port = 3306
    vserver!10!rule!500!auth!query = SELECT password FROM auth_users WHERE username= '${user}'
    vserver!10!rule!500!auth!realm = secret
    vserver!10!rule!500!auth!use_md5_passwd = 1
    vserver!10!rule!500!auth!user = db_user
    vserver!10!rule!500!match = directory
    vserver!10!rule!500!match!directory = /auth
    vserver!10!rule!500!match!final = 0
    vserver!10!rule!500!only_secure = 0
  • Same thing with ldap validator:

    vserver!10!rule!500!auth = ldap
    vserver!10!rule!500!auth!base_dn = Example DN
    vserver!10!rule!500!auth!bind_dn = Directory Manager
    vserver!10!rule!500!auth!bind_pw = secretpassword
    vserver!10!rule!500!auth!methods = basic
    vserver!10!rule!500!auth!port = 389
    vserver!10!rule!500!auth!realm = secret
    vserver!10!rule!500!auth!server =
    vserver!10!rule!500!auth!tls = 0
    vserver!10!rule!500!match = directory
    vserver!10!rule!500!match!directory = /auth
    vserver!10!rule!500!match!final = 0
    vserver!10!rule!500!only_secure = 0


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


  • Apache format logs to the regular files:

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

Information sources

Key Type Description
nick String Alias to identify the source
env String Variable to be set in the environment
host String host:port or path to unix socket
interpreter String command to launch the service if any
type Type host | interpreter
timeout Number spawning timeout specified in seconds


  • PHP configured for FastCGI through Unix socket

    source!1!env!PHP_FCGI_CHILDREN = 5
    source!1!host = /tmp/cherokee-php.sock
    source!1!interpreter = /usr/bin/php-cgi -b /tmp/cherokee-php.sock
    source!1!nick = php
    source!1!type = interpreter
  • Or via host:port as remote host:

    source!1!host = localhost:1234
    source!1!interpreter = /usr/bin/php-cgi -b /tmp/cherokee-php.sock
    source!1!type = host


The balancers must define the information sources to be used. For the ones defined in the examples above, using round robin from within the FastCGI handler, the following example would apply.

vserver!10!rule!600!handler = fcgi
vserver!10!rule!600!handler!balancer = round_robin
vserver!10!rule!600!handler!balancer!source!1 = 1
vserver!10!rule!600!match = extensions
vserver!10!rule!600!match!extensions = php
vserver!10!rule!600!match!final = 1

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/

Reverse Proxy

The reverse proxy , like everything in Cherokee, is modular. It is configured as any other of the modules that use load balancers.

You need to define a balancing strategy, the information source to be used by the balancer and, optionally, any expression matches that you might wish to rewrite in the headers before relaying the connection.

This is a basic example:

server!bind!1!port = 1234

# The proxy configuration
vserver!1!nick = default
vserver!1!document_root = /tmp
vserver!1!rule!1!match = default
vserver!1!rule!1!handler = proxy
vserver!1!rule!1!handler!header_hide!1 = server
vserver!1!rule!1!handler!balancer = round_robin
vserver!1!rule!1!handler!balancer!source!1 = 1

# URL rewrite
vserver!1!rule!1!handler!rewrite_request!1!regex = ^/(.+).png$
vserver!1!rule!1!handler!rewrite_request!1!substring = /$1.jpg
vserver!1!rule!1!handler!rewrite_request!2!regex = ^/test/(.+)$ /$1.jpg
vserver!1!rule!1!handler!rewrite_request!2!substring = /test.php?$1

# The information source
source!1!type = host
source!1!host = localhost:9090
Can you improve this entry?