# Behavior configuration

There is a common group of parameters which modify the server behavior. These clauses can be used inside either Directory configuration or Extension configuration directives.

## Handler

This configuration entry specifies how the server should generate the information it will send to the client. There are a long list of possible handlers: file, dirlist, common, redir, etc.

The handlers distributed with the standard Cherokee package are described in this documentation. Anyway, all of those handlers are plug-ins, so if you are using a handler not cover by this documentation, it might be a third party plug-in.

### Examples

    Directory /images {
       Handler file
    }

## DocumentRoot

This directive sets the document root definition for the Web server. But if one encloses a DocumentRoot definition within a Directory block, one can associate a new DocumentRoot with the directory associated with a directory block.

### Examples

#### Global DocumentRoot

Setting the systemwide DocumentRoot places a DocumentRoot definition unenclosed in the configuration file:

    DocumentRoot /var/www/

#### Localized DocumentRoot

Assume there are some files inside /usr/share/icons that must be exported under the /icons directory. Enclosing a document root definition inside a directory block achieves the desired effect:

    Directory /icons {
        DocumentRoot /usr/share/icons
    }

## Allow From

This parameter lets you set up rules form allow access to the directory contents to some IP or IP ranges. The remote client IP will be checked with all the provided list and only if the IP matches with some of the rules the access will be allowed.

There are three possible entry types:

- IP addresses
- Host names
- IP ranges

In the two cases, both IPv4 and IPv6 addresses are valid.

### Examples

Allow access only from the IPv6 localhost address:

    Directory /secret1 {
       Allow from ::1
    }

Allow access from the 127.0.0.0/8 network:

    Directory /onlylocal {
       Allow from 127.0.0.0/8
    }

or it could also we written like:

    Directory /onlylocal {
       Allow from 127.0.0.0/255.0.0.0
    }

or:

    Directory /onlylocal {
       Allow from localhost
    }

This last example is slightly different. It allows just a single IP instead a range.

It is also possible to use lists instead of a single IP or network range. And ir is also possible to mix IPv4 and IPv6 addresses and networks if you want.

    Directory /secret {
       Allow from 192.168.0.0/16, ::1, 10.0.0.1, 3ffe:3200::/24
    }

## Auth

This parameter allows to configure user/password protected entries. A validator has to be used in each Auth entry in order to specify the validaton mechanism. Eg: PAM, htpasswd, htdigest, plain text, etc.

It accepts two kinds of validation schemes:

- Basic
- Digest

It is possible to specify the kind of validation allowed in a certain resource:

    Auth Basic

Allows only the basic scheme

    Auth Digest

Allows only the digest scheme

    Auth Basic, Digest

Allows both schemes

It is also possible to specify who is allowed to access the resource using the User entry.

This example descrives a directory /local which requires a valid user and password pair. This tuple will be checked using the PAM validator.

    Directory /local {
        Auth Basic {
           Name "Local users"
           Method pam
        }
    }

This example is similar to the previous one, but only the users root and alo are allowed to access the directory using any kind of authentication scheme.

    Directory /admin {
        Auth Basic, Digest {
           Name "Administration stuff"
           Method pam
           User root, alo
        }
    }

## OnlySecure

This configuration entry determines that the directory will be served by the secure server (https) only.

### Example

    Directory /admin {
        DocumentRoot /var/www/admin
        Handler common
        OnlySecure
    }

If you access directory /admin or any sub-directory, throught non-secure connection Cherokee will report a 426 Upgrade Required error.