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.7 handles:
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.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 |
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
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:
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 ! name ! 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: the entry with priority 20, setting the properties for the icons directory of the default virtual host would be represented by: vserver!default!rule!20!match!type = directory vserver!default!rule!20!match!directory = /icons |
---|---|
Extension: | It specifies a list of extensions and how they should be handled. Eg: the JPG extensions is: vserver!default!rule!30!match!type = extensions vserver!default!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!default!rule!40!match!type = request vserver!default!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!default!rule!50!match!type = header vserver!default!rule!50!match!header = Referer vserver!default!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 request that did not match any other rule. Eg: Default rule the 'default' virtual server: vserver!default!rule!default |
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:
The default virtual server uses the "common" handler as default choice for its root directory:
vserver!default!rule!directory!/!handler = common vserver!default!rule!directory!/!priority = 1
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!example!domains!1 = *.example.com vserver!example!domains!2 = *.example.org vserver!example!rule!directory!/!handler = fcgi vserver!example!rule!directory!/!priority = 1 vserver!example!rule!directory!/!allow_from = 127.0.0.1,::1
ISO images should be handled as files and are protected by a htdigest file using only Digest authentication:
vserver!default!rule!extensions!iso,ISO!handler = file vserver!default!rule!extensions!iso,ISO!priority = 1 vserver!default!rule!extensions!iso,ISO!auth = htdigest vserver!default!rule!extensions!iso,ISO!auth!realm = My secret isos vserver!default!rule!extensions!iso,ISO!auth!methods = digest vserver!default!rule!extensions!iso,ISO!auth!passwdfile = /var/passwd/isos.htdigest
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!default!logger = combined vserver!default!logger!access!type = file vserver!default!logger!access!filename = /var/log/cherokee.access.log vserver!default!logger!error!type = file vserver!default!logger!error!filename = /var/log/cherokee.error.log
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/