Advanced Configuration

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.

Having said that, let's proceed to describe the configuration file format. It is basically a text file that contains a tree where final 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 Cherokee 0.6 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!mime_files List Path list to mime type files
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.0
Minimal Cherokee/0.0.0
OS Cherokee/0.0.0 (UNIX)
Full Cherokee/0.0.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.

Key Type Description
vserver!default!document_root Path Document Root path
vserver!default!user_dir String User's web directory (for ~ requests)
vserver!default!domain! id String Domain name, admits wildcards
vserver!default!error_handler String Defines the error handler module
vserver!default!directory_index List String list: Directory indexes
vserver!default!ssl_certificate_file Path TLS/SSL certificate file
vserver!default!ssl_certificate_key_file Path TLS/SSL certificate key file
vserver!default!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:

Directories, Requests and Regular Expressions

These entries are located inside Virtual Servers. They basically specify the behavior of the web server by setting up how to handle each request based on the requested object and parameters.

There are three kinds of entry. All three of them admit the same parameters, and depending on each case, the entry is followed by the directory name, the extension list or the regular expression:

Directory:

The directory specifies how to handle its contents.

Example: the root directory of the default virtual host would be represented by

vserver!default!directory!/

Extension:

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

Eg: the JPG extensions is

vserver!default!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!default!request!^a.*\.php$

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

So, 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/