== link:index.html[Index] -> link:cookbook.html[Cookbook]
///////////////////////////////////////////////////////////////////
Last checked:
* Cherokee 1.2.2b
///////////////////////////////////////////////////////////////////

Cookbook: Matching domain and subdomains with Cherokee
------------------------------------------------------

Knowing how to match a domain or subdomain name is important to
configure the behavior of your web server. The way in which HTTP
redirections are performed, or what content is delivered to whom is
determined by such matches.

The order in which the virtual servers are listed determines what
domain names are matched. The purpose of this recipe is to document
what to do *after* these matches have been determined.

Host Match
~~~~~~~~~~

As it was mentioned before, Cherokee can handle any number of virtual
servers. The list of defined virtual servers can be reviewed and
manipulated, and the order in which the virtual servers are listed is
very significant. Whenever Cherokee receives a request, the list is
evaluated from top to bottom, and the first virtual server that
matches the given request will be the one used to handle the connection.

The domain matching method can be selected through the `Host Match`
tab of any virtual server. The available options are:

. Match Nickname: which will use the nick name that has been defined
  for the virtual server.

. Wildcards: which will use a list of names, each of which can contain
  the wildcard characters `?` (one character) and `*` (one or more
  characters).

. Regular Expressions: which will use a list of provided regular
  expressions. Group matching is allowed, so this one can be very
  handy.

. Server IP: the match is performed according to the IP/Subnet.

Additionally, a combination of two such methods can be used, and it
will be evaluated as a logical OR. This can be useful on some rare
occasions, but is usually not needed.


Dictating the behavior based on the match
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

You could always define a virtual servers for each subdomain of a
given domain name. Modeling the behavior in such scenario is trivial,
since you would know exactly what you wanted to accomplish on each
case. But lets assume you want to define a single entry point to
handle a specific subdomain for all your virtual servers.

You can do this by using the `Regular Expression` method to match the
host. For instance, if you set the match of that virtual server to
something like `^admin\.(.*)$` it will store a replacement variable
with the name of your domain (without the `admin.` prefix).

Then, you'd have to set the default rule of the virtual server to
`Redirection`, with the expression `^/(.*)$` that stores the whole
request. Finally, just adding the following substitution would allow
you to redirect every such request to the `admin` webdirectory within
each of your virtual servers: `http://^1/admin/$1`

This is very useful if all your virtual servers would behave in a
similar fashion, providing an `/admin` directory to handle such
requests. When this is not the case, you can still avoid creating
multiple virtual servers for a given domain name.

You can configure self contained virtual servers using behavior rules
which dictate site behavior based on domain name matching.  Behaviour
rules can match against HTTP headers, such as the Host: header (Host:
admin.example.com in this case). Be advised that although such
self-contained configuration is achievable, it is less efficient than
defining different virtual servers. This is due to the fact that
virtual server evaluation is performed in one step for any given
virtual server request, while performing a domain comparison on each
rule can be cumbersome.
