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

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

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