## Index → Development info

## Development: cherokee.conf

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

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:

### 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!bind!#!port | Number | Listen to a TCP port. # is a sequential 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/1.0
Minimal | Cherokee/1.0.0
OS | Cherokee/1.0.0 (UNIX)
Full | Cherokee/1.0.00 b5077 (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 precaution 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 ! priority ! match`

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

Directory

  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

Extension

  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

Requests

  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$

Header

  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

Default

  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 | zip encoder. 0|1 to define disabled|enabled.

Example

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

htdigest, htpasswd, plain
Key | Type | Description
--- | --- | ---
auth!passwdfile | String | Full path to the passwords' file. htdigest|htpasswd|plain

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.

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.

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 *.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!5!nick = example
          vserver!5!domains!1 = *.example.com
          vserver!5!domains!2 = *.example.org
          vserver!5!rule!10!directory!/!handler = fcgi
          vserver!5!rule!10!directory!/!priority = 1
          vserver!5!rule!10!directory!/!allow_from = 127.0.0.1,::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 = ldap.example.com
      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

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

They follow the format: ``source ! {source number} ! {key}``

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

Examples:

- 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

### Balancers

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.

Example

      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