Index → Configuration

Virtual Server

Virtual Server is an abstraction mechanism that allows you to define a custom number of parameters and rules that have to be applied to one or more domains.

In a Cherokee server there must be at least one virtual server named default, and there is no maximum number. It is important to know that this server cannot be deleted.

When the server receives a request it will try to match the domain name specified in the virtual server that should handle it. In case no virtual server matches the request, default will be used.

Three main options are accessible through this menu:

Virtual Server List
Add new Virtual Server
Clone Virtual Server

Cloning a Virtual Server is simply a matter of selecting a target name and a source virtual server currently present. Every setting will be duplicated. From then onwards changes applied to any of them, be it the original or the copied Virtual Servers, will only apply to the implicated one. This is a great way to set up complex domains, since you can use the existing ones as templates to be refined with further work.

To add a new Virtual Server you have to enter the server name and a valid Document Root directory.

Document Root

This directive sets the directory from which Cherokee will serve files. The set of rules is checked from the highest to the lowest possible priority. Once a rule is matched, the server appends the path from the requested URL to the document root to make the path to the document. If it is a directory, this information is used. If other rules apply to a parent directory, those are applied as well without overwriting the original behavior:
```
        http://www.example.com/index.html refers to /var/www/index.html
```
This might seem complicated but it's actually simple to understand. For example suppose you had a directory called /secret that was protected with authentication, and there was also a rule with higher priority for /secret/cgi that only specified to use the CGI handler. Under these circumstances, if a request was received for /secret/cgi/something then the CGI handler would be taken and it would inherit the authentication specified for /secret.
Name

Name is an alias. The domain names handled by the virtual server should be specified later in the virtual server details page.

The Virtual Server List is by far the most interesting of these three main options. It gives an overview of the existing virtual servers, and allows to configure in detail every possible setting.

A detailed explanation of every tab follows.

Basics

Virtual Server nickname

The name that will be used to identify the virtual server.
Document Root

Path to use as root directory for the virtual server.
Directory Indexes

The DirectoryIndex directive sets the list of resources to look for when the client requests an index of the directory by specifying a / at the end of the directory name. Several URLs may be given, in which case the server will return the first one that it finds. If none of the resources exist, the server will reply according to the handler behavior.

Note that the documents do not need to be relative to the directory:
```
        index.html,index.txt,/cgi-bin/index.pl
```
would cause the CGI script /cgi-bin/index.pl to be executed if neither index.html nor index.txt existed in a directory.

There is a special case in which the directory index entry starts with a slash. For example, /cgi-bin/index.pl. In that case, it will use it as the object accessible under that public address of the same virtual server, so it will take care about the possible configuration of the /cgi-bin/ directory and/or the pl extension.
Keep-alive

This flag is enabled by default. It is used to enable or disable Keep-alive connections on a per-virtual-server basis. Keeping persisting connections has dramatic effects both in speed, but very high traffic loads can suffer because less connections are available for any given moment.

Domain names

This section allows to define the list of domains that the virtual server implements.

It can accept either FQDN (Fully Qualified Domain Names) or wild card entries.

For instance

          example.com
        *.example.org

Note that you should probably keep in mind the way this list is interpreted in order to avoid future problems. Whenever Cherokee recieves a request for a specific domain, it evaluates the Domain list of every defined virtual host in the order defined by the priorities of such hosts. When it finds a match, it stops the evaluation and starts matching the specific rules from that virtual host to send the apropriate response.

If no domain name matches the request, Cherokee re-evaluates the list of virtual hosts trying to match the request against the Nicknames, also using the priorities defined by the virtual host order.

Only after failing both with the domain names and the nicknames will Cherokee issue the failure.

Behavior

This sections allows to define a set of rules to define how the server should handle the different requests. A summary of the existing rules is presented, containing several fields of information:

Target: web target of the rule, be it a path, a file type, etc.
Type: Rule type. These will be explained in the following paragraphs.
Handler: The handler that manages the requests that match this rule. Read on for further details.
Auth: Indicates if authentication is used for this rule. This can be set up through the Rule Entry menu.
Enc: Indicates if any encoding is applied to the rule.
Exp: Indicates if expiration headers are configured for the rule.
Final: If this flag is present it means that no other rules will be applied after this one, even if the request also matches other rules with lower priority.

These rules can be defined based on the directory that the request targets, the extension of the file that it is requesting, or a regular expression that may match the request. This is the list of available rule types:

Directory: The entry Directory encloses a group of directives which will apply only to the named directory and sub-directories of that directory.
Extensions: The entry Extensions doesn't care about directories, it will just look for the extension of the object requested.
Regular Expressions: The Request entry provides a powerful way to apply custom options to requests. It is a complement for the Directory and Extension entries. Basically, there are two differences between them:
- It uses regular expressions to define the requests in which the configuration will be applied.
- These entries are able to use the connection parameters (both pathinfo and query string). In this way it is possible to set rules based on parameter values.
Header: This type of rule is used to modify the behavior in response to the contents of HTTP headers. A regular expression is needed to match against. This kind of rule can be used to provide alternative contents to a specific type of users. For example, it can check if the HTTP referrer header refferences specific domains to allow or deny the delivery of the requested information.
File Exists: This type of rule will only be applied if a certain file (or a file among a list of provided file names) is present. An I/O cache specific setting for the rule can be configured in the Rule tab. If enabled, it will speed up the file detection during the rule evaluation. This improves performance but is not recommended when the directory contents change dynamically. This type of rule can also be used to match any file. For example, it can be configured to serve static files and fall through to another rule if the HTTP request is for a resource of dynamic nature.
HTTP method: These rules are applied whenever the selected HTTP method is used. You can configure these to respond to a request of type GET, POST, HEAD, PUT, OPTIONS, DELETE, TRACE, CONNECT, COPY, LOCK, MKCOL, MOVE, NOTIFY, POLL, PROPFIND, PROPPATCH, SEARCH, SUBSCRIBE, UNLOCK or UNSUBSCRIBE.
GeoIP: If GeoIP support is present, this type of rules can be added. The GeoIP library has to be present at build time for this to happen. If enabled, specific behavior can be offered depending on the country of origin of the requests to the web server. Note that the country is determined by matching the IPs to the actual list of countries handled by the library, so the usage of proxies on the user side will render this resolution mechanism inaccurate. An initial country must be added to the rule, and more selections can be added in further steps.

It is very important to know that these rules are prioritized. The higher its priority is, the sooner they are checked. You could think of a network routing table, it is quite similar. You can set the relative priorities among the rules by simply dragging and dropping them in the desired position (if you click on the rule name, you will be redirected to the rule's configuration options; if you click anywhere else, you will be able to drag and drop it into the desired position).

Each of these behavior rules must specify which is the handler that the server should use to reply to the requests that match the rule. Handlers are the modules that generate the information with which the server responds a client's request. By default Cherokee provides a number of them:

common - List & Send

Combines both Static Content and Only listing handlers functionality to behave similarly to common web servers, it will display directory listings when a directory is requested and serve the requested files.
Static Content - Static Content

This is the file handler and it serves files straight from the file system.
dirlist - Only listing:

Displays a directory content list when a directory is requested, but it does not allow to download any content.
redir - Redirection

Perform simple and/or complex redirections using regexes.
cgi - CGI Execution

Executes CGI programs.
fcgi - FastCGI Server Support

Communicates with FastCGI servers.
scgi - SCGI Server Support

Communicates with SCGI servers.
Server Info - Server Info

Provide some configurable information about the server.
Generic balancer - Generic balancer

Select one of the available mechanisms to distribute the load (locally or remotely).
Remote Administration - Remote Administration

Implements an administration interface to work with cherokee-tweak.

The selection of any one of the rule targets will offer new configuration options through the Rule Entry menu.

Each of the mentioned handlers can be fine-tuned through that menu. Refer to each handler's documentation if you are interested in the available settings.

Note

It is quite easy to fully specify a virtual server's behavior having just some notions of Cherokee's way of working. However, there might be some corner cases where Cherokee will behave in a manner that could not seem obvious at first. Every doubt can be easily cleared by simple understanding in full detail the way a rule is applied. For instance lets suppose there is an Extension type rule configured to handle PHP files. If a request is made for http://example.com/index.php/what/ever, this rule WOULD NOT be applied at first because the request doesn't end with the appropriate extension: it has some adittional path information. However, if there is a Default rule configured that is managed by the List and Send handler, things would work. This is because the Default rule would catch any unmatched requests, and the List and Send handler would notice the PATHINFO part of the request. It would then split the request in two parts, separating the PHP file from the appended information, and would then evaluate once more the list of rules. This time the request would end in .php and thus it would match the Extension rule meant to handle PHP files.

Personal Webs

This options allows to setup the name of a subdirectory inside the users' home directory that will be used as document root for personal web content. For instance, if /foo was specified, a user bar could publish the content of _{/foo at the relative URL /}bar This option is disabled if the Directory name field is empty.

Error Handler

Several mechanisms exist to handle errors.

Default errors
Custom redirections
Closest match

Using the Custom redirections error handler we can easily redirect errors to a custom path or website.

The Closest match error handler should never fail to deliver something. If a requested resource is not available, the closest match will be sent. The only exception to this is when nothing at all is at Cherokee's disposal, in which case a standard http error is sent.

Logging

The loggers are a type of Cherokee modules to write the server log information using different destinations and/or formats:

Destination: File, syslog, program execution and standard error output.
Format: Combined (Apache compatible), NCSA or W3C

If a virtual server doesn't have a logger set up it will not log anything.

By default Cherokee ships three loggers implementing three different logging formats:

combined - Combined Log Format

Logging using the Apache log format. It is the de facto standard nowadays.
ncsa - NCSA Log Format

Logging using the NCSA log format.
w3c - W3C Log Format

Logging using the W3C log format.

Security

The virtual server must be configured with the path to the certificate before using secure connections (https). There is a document which might help to generate SSL keys and that should provide tips and information on how to configure SSL, TLS and certificates.

Cherokee fully supports the usage of different certificates for each virtual server in a given host by it using SNI as defined in RFC 3546.

If you want HTTPS to work, you must remember this:

Providing the PEM-encoded files is mandatory for both Certificate and Certificate key fields. Providing the CA List and the Client Certs is optional. The trusted CA certificates file should be a single file with all the certificates concatenated. The Client Certs, also PEM-encoded, is used to check the client certificates.
If you have several virtual servers, the Security section must be configured for every one of them. At the moment you cannot have some with HTTPS and some without. This makes sense, since by enabling the feature in any one of them you are opening the HTTPS port in your host, and receiving HTTPS requests for a virtual server that does not provide the service would not be handled in a coherente manner. None of the alternatives is very elegant in design: falling back to HTTP, issuing an error that is likely to restart the HTTPS handshake, etc. This behavior, however, might change in the future depending on the popularity of any proposed mechanisms.