This field accepts a comma separated list of *Host names*, *IP addresses* or *IP ranges*. In the last two cases, both IPv4 and IPv6 addresses are valid entries.
Documentation
Virtual Server: Rules
Besides the connection handler set for the rule, there are other parameters that can be set in order to customize the rule behavior. This menu offers the following tabs:
-
Rule: this is the rule type.
-
Handler: Specifies which handler should manage the requests that match the rule.
-
Transforms: Transofmration of output stream on the fly (encoding, and HTTP header alteration).
-
Caching: Specifies content expiration and caching policies.
-
Security: in this section one can configure Access Restrictions and Authentication.
-
Restrictions: Specify connection timeouts, and also traffic shaping by setting an outbound traffic limit for this rule, specified in bytes per second.
Rule
Several rule types are available to fit the needs of specific tasks. Sometimes you will want to restrict the content delivery based on a user’s country of origin, sometimes you might want a behavior to be applied to a web directory, or you might be interested in modeling how the web server behaves if a request matches an existing file (or not).
There is a complete list of the types in the Rule Types section.
The behavior can be specified further by combining several basic rule-types into a complex rule. Complex rules can be defined by combining several basic types with the boolean operators AND, OR and NOT. For instance, we could define a rule that would apply to certain directories only if the request was made from a specific country. It would be as simple as defining a directory type rule AND a GeoIP type rule.
Handler
This allows to fine tune the behavior of any of the available handlers. Since so many options are available, refer to the complete list of handlers shipped with Cherokee.
Handlers are the modules that generate the information with which the server responds to a client’s request. By default Cherokee provides a number of them:
Transforms
The content sent by Cherokee can be processed before being sent.
Basically, you can apply encoders (or not), and alter HTTP headers by adding or removing the ones you choose.
Information Encoders
This tab is used to configure, on a per-rule basis, what encoders, if any, are to be applied.
You can set up the encoding method to use, and it shall be applied to whatever content is handled by the parent rule.
Whenever you set up a virtual server, creating a rule where gzip is enabled by default for the following file types: html, htm, txt, css and js is a good idea. You are encouraged to use this. Hardware is cheap. Bandwidth is not.
Header Operations
You can specify any given HTTP header and either assign a value or delete the header completely.
Caching
Cherokee allows to define per rule behaviors for content expiration and caching.
Content Expiration
This allows to manage the configuration of HTTP Cache headers used to identify cacheable content.
HTTP/1.1 defines caching methods in HTTP. Cherokee-Admin can automatically adjust the Cache-Control and Expire headers depending on the values you have configured. The available options are:
-
Not set: Does not write the caching headers.
-
1970: Corresponds to the Unix Epoch.
-
2038: Maximum date value representable in POSIX time.
-
Custom Value: set a value by hand.
Additionaly, if a content expiration option is set, it is possible to specify the way in which an intermediate cache should treat the content, for situations such as when the content is requested to Cherokee through an HTTP proxy. This is done through the Management by caches setting, that can be specified to any of the following values: Not set, Private, Public, No Cache.
If the setting is enabled, four additional parameters can be individually turned on and off to fine tune the behavior:
-
No Store: Prevents the retention of sensitive information. Caches must not store this content.
-
No Transform: Forbid intermediate caches from transforming the content.
-
Must Revalidate: The client must contact the server to revalidate the object.
-
Proxies Revalidate: Proxy servers must contact the server to revalidate the object.
Cache
Cherokee has very sophisticated caching mechanisms, allowing to cache anything (static files, dynamic content, or whatever) that passes by. You can read more into the specifics of this feature in the Front-line Cache documentation.
Three settings are available on a per-rule basis for the Content Caching section: Leave unset, Allow and Forbid.
The Leave unset option means that, whenever a rule is applied, it will not change the status of the caching setting that has been inherited from previously matched rules.
By default, contents that include cookies are not cached, but the setting to allowing cache on a rule gives you the possibility to disregard cookies using regular expressions (so that even that content can be cached), while a Forbid setting will guarantee that the matched rule will not be cached no matter what.
Security
This section will give access to access restriction settings and authentication settings.
Logging
Here we can specify whether or not the requests that match this rule should be logged. This can be useful in order to tidy up our log files, since some rule matches might not provide any relevant logging information
Access Restrictions
-
Only https:: This configuration entry determines that the directory will be served by the secure server (https) only. If you access directory /admin -or any sub-directory- through a non-secure connection Cherokee will report a 426 Upgrade Required error.
-
Allow From:: This parameter lets you set up which IP or IP ranges will be allowed to access the directory contents . 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.
Examples
-
Allow access only from the IPv6 localhost address
Allow from ::1
-
Allow access from the 127.0.0.0/8 network
Allow from 127.0.0.0/8
-
or it could also we written like
Allow from 127.0.0.0/255.0.0.0
-
It is also possible to use lists instead of a single IP or network range. And there is even the possibility of mixing IPv4 and IPv6 addresses and networks if you want
Allow from 192.168.0.0/16, ::1, 10.0.0.1, 3ffe:3200::/24
Authentication
This parameter allows to configure user/password protected entries. A validator has to be used in each Auth entry in order to specify the validation mechanism. The following validators are available:
-
plain - Plain text file
Uses a plain flat file to perform HTTP authentication.
-
htpasswd - Htpasswd file
Uses an htpasswd file to perform HTTP authentication.
-
htdigest - Htdigest file
Uses an htdigest-generated file to perform HTTP authentication.
-
ldap - LDAP server
Uses an LDAP directory to perform HTTP authentication.
-
mysql - MySQL server
Uses a MySQL database to perform HTTP authentication.
-
PAM - PAM Authentication
Uses PAM to perform HTTP authentication.
-
Fixed list - Authentication lists
Uses lists of users and passwords to perform HTTP authentication.
It is important to take into consideration that there are two different authentication mechanisms:
-
Basic
-
Digest
Some validators can only handle one of those mechanisms because of technical limitations. In case the module supports both of them, the interface allows to choose whether one or both are to be used.
Restriction
Both connection timeouts and bandwidth limits can be enforced through this tab.
Connections Timeout
This allows to apply a custom timeout to any connection matching the given rule.
Traffic Shaping
In order to limit the amount of traffic used for a specific rule you can set up a traffic shaper. By default no traffic shaping will occur, all possible network resources are used to facilitate the clients.
This parameter will not act globally, but per outgoing connection. Hence, 20 clients limited to 1kB/s will give 20kB/s as total outbound traffic. To limit the amount of traffic a value in Bytes per second should be entered.