Documentation

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