IndexDevelopment 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!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!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.8
Minimal Cherokee/0.8.0
OS Cherokee/0.8.0 (UNIX)
Full Cherokee/0.8.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.

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:

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

Here are a few examples about how this notation works:

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:

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/