Configuration File Structure

Location

Cheyenne's configuration file (httpd.cfg) must be in the same folder as Cheyenne binary or %cheyenne.r file, if run from sources.

Description

Cheyenne's configuration file uses a REBOL dialect as data storage format. This choice provides a simple format to read/write both for humans and for Cheyenne's config file parser. The file is structured using REBOL blocks in, at least, 3 sections.

Typical httpd.cfg file structure :

 modules [...]
 globals [...]
 default [...]

Minimal configuration file :

 modules [static]
 globals []
 default [root-dir %www/]

This minimal file would make Cheyenne serve only static content from Cheyenne's www/ local folder.

Modules Section

Modules are the heart of Cheyenne's server abilities, they work in conjunction to provide all the features. This section lists all the loaded modules in given order of loading. You can comment or uncomment (using a semicolon) the ones you want. Usually, just keep the default list unless you know exactly what you're doing, this list is critical to the well-behaviour of Cheyenne.

Each module brings its own set of configuration directives. Be aware of that when removing a module from the list, you might loose some directives and trigger syntax errors when loading the configuration file.

Note that the embed module, if activated, will disable all the other ones (required for proper working of embedded mode).

A typical module list will look like this:

 modules [
     userdir
     internal
     extapp
     static
     upload
     action
     fastcgi
     rsp
     ssi
     alias
     socket
 ;   embed
 ]

Globals Section

The globals section contains all the directives that apply globally on all virtual hosts or not related to virtual hosts. For example, the BIND? and BIND-EXTERN? directives are used to associate an handler with one or several file extensions, making them processed automatically by Cheyenne.

Typical directives in globals section:

 listen [80 8000]               ;-- listen to ports 80 & 8000

 bind SSI to [.shtml .shtm]     ;-- process files with .shtml or .shtm suffix with SSI module
 bind-extern CGI to .cgi        ;-- process files with .cgi suffix with CGI worker handler
 bind-extern RSP to .rsp        ;-- process files with .rsp suffix with RSP worker handler

 worker-libs [
     %libs/mysql-protocol.r     ;-- load this library in all worker processes when launched
 ]

Default Section

This section defines the default configuration for requests that don't match any other virtual host. It acts a "catch all" net to avoid sending an HTTP error to clients requesting e.g., a not defined sub-domain. It has the same syntax rules as other Host sections (see below).

This section is not mandatory, but it is often used when setting up a new Cheyenne instance before deciding on the domain(s) name to use.

Host Section

Host sections are used to define virtual hosts. You should at least have one defined (or having a default section defined) for Cheyenne to be able to serve content. You can add as much virtual hosts as you wish in the configuration file, there's no explicit limit.

A host section is defined as a virtual host identifier followed by a configuration block.

Minimal Host section definition:

 domain.com [
     root-dir %www/          ;-- defines the root folder for this virtual host
 ]

The virtual host identifier can be:

• a domain: domain.com
• a sub-domain: www.domain.com, my.long.sub.domain.com
• a domain or sub-domain with a port number: domain.com:8000, demo.domain.com:443
• an IP address: 1.2.3.4
• an IP address with a port number: "1.2.3.4:8000"

Notice the double quoting for the last option, it's mandatory to avoid a syntax error

The root-dir directive is the only mandatory part in a virtual host definition. It can be a relative or absolute path (don't forget the % prefix). Put your static content to be served for that virtual host, in that folder. The root of your folder will be accessible from http://domain.com/.

If you want that a default file be served or a default script be called when the requests ends with a slash (no explicit target resource), add a default directive listing the default files to be searched for when required.

Here's a more sophisticated example of virtual host definition:

 softinnov.org [
     root-dir %/c/dev/si-org/       ;-- root folder using an absolute path
     default %index.shtml           ;-- default file when no target
     disable-log                    ;-- HTTP access logs disabled for this virtual host
     debug                          ;-- debug mode activated for RSP scripts

     alias "/test" %show.rsp        ;-- map /test path to %show.rsp script
     socket-app "/chat.rsp" chat    ;-- declare a web socket application

     on-status-code [               ;-- capture some HTTP code
        404  "/404.rsp"             ;-- redirect 404 return codes to a custom script
     ]

     webapp [                       ;-- RSP webapp definition
         virtual-root "/testapp"    ;-- URL path associated to this webapp
         root-dir %www/testapp/     ;-- root folder of the webapp
         auth "/testapp/login.rsp"  ;-- webapp protection activated (authentication required)
         ;debug                     ;-- debug mode commented (disactivated)
         timeout 02:00:00           ;-- RSP session timeout changed to 2h (instead of 20mn)
     ]
 ]

Have a look in the Options pages to see what directives are available to populate the configuration file.