<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-type" content="text/html; charset=utf-8" />
<meta http-equiv="Content-Language" content="en-us" />
<meta name="ROBOTS" content="ALL" />
<meta http-equiv="imagetoolbar" content="no" />
<meta name="MSSmartTagsPreventParsing" content="true" />
<meta name="Keywords" content="cherokee web server httpd http" />
<meta name="Description" content="Cherokee is a flexible, very fast, lightweight Web server. It is implemented entirely in C, and has no dependencies beyond a standard C library. It is embeddable and extensible with plug-ins. It supports on-the-fly configuration by reading files or strings, TLS/SSL (via GNUTLS or OpenSSL), virtual hosts, authentication, cache friendly features, PHP, custom error management, and much more." />
<link href="media/css/cherokee_doc.css" rel="stylesheet" type="text/css" media="all" />
</head>
<body>
<h2 id="_a_href_index_html_index_a_8594_a_href_cookbook_html_cookbook_a"><a href="index.html">Index</a> → <a href="cookbook.html">Cookbook</a></h2>
<div class="sectionbody">
</div>
<h2 id="_cookbook_maintenance">Cookbook: Maintenance</h2>
<div class="sectionbody">
<div class="paragraph"><p>This recipe will show how to seamlessly switch the webserver to
maintenance mode. By that it is understood that no existing
connections should be interrupted, but new connections should be
notified of the situation. This could be done serving some generic
static content.</p></div>
<div class="paragraph"><p>All this is easily achieved by Cherokee thanks to its
<a href="other_goodies.html#zero-downtime">Zero Downtime</a> mechanism.</p></div>
<div class="paragraph"><p>We will be showing a couple of use cases. The first one is mostly to
illustrate the general process and will be set to serve a custom HTTP
Error. It is very simple and straightforward, but is also pretty
useless in a production environment. The second use case will be more
advanced. It will be useful to serve a static maintenance message to
the public while the administrator will retain the ability to see the
actual changes.</p></div>
<h3 id="basic">Basic Example</h3><div style="clear:left"></div>
<div class="paragraph"><p>The steps are fairly simple:</p></div>
<div class="ulist"><ul>
<li>
<p>
Create a new virtual host, a copycat, that can handle the same
domain(s) as the ones managed by the host to be put offline. In this
example it is cloed as <em>copy</em>.
</p>
<div class="imageblock">
<div class="content">
<img src="media/images/cookbook_maintenance_copy.png" alt="media/images/cookbook_maintenance_copy.png" />
</div>
<div class="image-title">Cloned virtual server</div>
</div>
</li>
<li>
<p>
Don’t forget to set up the domains handled by the virtual host.
</p>
<div class="imageblock">
<div class="content">
<img src="media/images/cookbook_maintenance_domain.png" alt="media/images/cookbook_maintenance_domain.png" />
</div>
<div class="image-title">Domains</div>
</div>
<div class="tableblock">
<table rules="all"
width="100%"
frame="border"
cellspacing="0" cellpadding="4">
<caption class="title">Accepted Domains</caption>
<col width="100%" />
<thead>
<tr>
<th align="left" valign="top">Domain pattern</th>
</tr>
</thead>
<tbody>
<tr>
<td align="left" valign="top"><p class="table">example.*</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">intranet_example</p></td>
</tr>
</tbody>
</table>
</div>
</li>
<li>
<p>
Also remember setting up whatever response you will be requiring (a
custom error, some static content, and so on). We will be setting up
the <a href="modules_handlers_custom_error.html">HTTP error</a> handler to
give a <tt>503: Service unavailable' message. This is done through the
`Handler</tt> tab.
</p>
<div class="imageblock">
<div class="content">
<img src="media/images/cookbook_maintenance_error.png" alt="media/images/cookbook_maintenance_error.png" />
</div>
<div class="image-title">Handler</div>
</div>
</li>
<li>
<p>
After this operation, we you should have a sole rule in the copied
virtual server managed by the HTTP Error handler.
</p>
<div class="imageblock">
<div class="content">
<img src="media/images/cookbook_maintenance_rule.png" alt="media/images/cookbook_maintenance_rule.png" />
</div>
<div class="image-title">Rules</div>
</div>
</li>
<li>
<p>
The <tt>Error Handler</tt> tab should specify <tt>Custom redirections</tt> in the
<tt>Error Handling hook</tt> section.
</p>
<div class="imageblock">
<div class="content">
<img src="media/images/cookbook_maintenance_result.png" alt="media/images/cookbook_maintenance_result.png" />
</div>
<div class="image-title">Error Handler</div>
</div>
</li>
<li>
<p>
Make sure the copycat is positioned above the original virtual host,
effectively having a higher priority for it. By default the new
virtual hosts are positioned on top of the rest. Just make sure you
don’t inadvertently change the relative priorities.
</p>
</li>
<li>
<p>
Make a <strong>graceful restart</strong>.
</p>
</li>
</ul></div>
<div class="paragraph"><p>This can be done from the SAVE dialog. By doing this, the existing
connections to the original virtual host will be preserved and will
eventually end upon completion. At the same time, new requests will be
delivered to its copycat and will be handled according to its
specified behavior. If you don’t want this behavior you can always
make a <strong>hard restart</strong>, effectively shutting down every existing
connection.</p></div>
<div class="paragraph"><p>By now you are almost done. Now you can make whatever changes were
needed to the original host without affecting the incoming
connections.</p></div>
<div class="paragraph"><p>Remember to reverse the process once you are done. You’ll only have to
delete the copycat or position it below the real virtual host.</p></div>
<h3 id="advanced1">Advanced Example: Static message</h3><div style="clear:left"></div>
<div class="ulist"><ul>
<li>
<p>
The first two steps are the same: create a copycat, and make it handle
the same domains.
</p>
</li>
<li>
<p>
Our virtual host will have only two rules. The first one will match
against a maintenance directory that will be managed by the "List &
Send" handler. Enabling IO/Cache and Encoding will be a plus here
since the contents are static by definition. You should probably
configure the <tt>Directory indexes</tt> in the <tt>Basics</tt> tab of the virtual
host for the <tt>List & Send</tt> handler to work properly. The second one
will be the the <tt>Default</tt> rule that will be redirecting every
request to the first rule as an internal redirection.
</p>
<div class="imageblock">
<div class="content">
<img src="media/images/cookbook_maintenance_advanced_rules.png" alt="media/images/cookbook_maintenance_advanced_rules.png" />
</div>
<div class="image-title">Rule list</div>
</div>
</li>
<li>
<p>
The <tt>Default</tt> rule should be managed by the <tt>Redirection</tt> handler.
.Redirections
</p>
</li>
</ul></div>
<div class="tableblock">
<table rules="all"
width="100%"
frame="border"
cellspacing="0" cellpadding="4">
<col width="30%" />
<col width="70%" />
<thead>
<tr>
<th align="left" valign="top">Type </th>
<th align="left" valign="top">Regular Expression</th>
</tr>
</thead>
<tbody>
<tr>
<td align="left" valign="top"><p class="table">Internal</p></td>
<td align="left" valign="top"><p class="table">.*</p></td>
</tr>
</tbody>
</table>
</div>
<div class="paragraph"><p>+
<span class="image">
<img src=":media/images/cookbook_maintenance_advanced_redir.png" alt=":media/images/cookbook_maintenance_advanced_redir.png" />
</span></p></div>
<div class="paragraph"><p>This set up will result in every request being redirected to the
maintenance directory.</p></div>
<h3 id="advanced2">Advanced Example: Staff review</h3><div style="clear:left"></div>
<div class="paragraph"><p>By now you should be able of switching the server to and from
maintenance mode.</p></div>
<div class="paragraph"><p>The next essential feature needed is to allow specific users to be
able to access the original site, not the maintenance version, so that
they can view the changes reflected while they are working.</p></div>
<div class="paragraph"><p>The tweaking here has to take place in the original virtual
server. The steps are also fairly simple.</p></div>
<div class="ulist"><ul>
<li>
<p>
In this example we will be adding a new imaginary domain to the list
of domains managed by the virtual host. This domain should be
accessible from our intranet only. For the purpose of this document,
it will be we will use <em>intranet_example</em>.
</p>
<div class="imageblock">
<div class="content">
<img src="media/images/cookbook_maintenance_advanced_domains.png" alt="media/images/cookbook_maintenance_advanced_domains.png" />
</div>
<div class="image-title">Host Matches</div>
</div>
<div class="admonitionblock">
<table><tr>
<td class="icon">
<div class="title">Note</div>
</td>
<td class="content">As mentioned in the <a href="config_virtual_servers.html">Virtual Servers</a>
section, you should keep in mind the way the domain lists are
interpreted. Whenever Cherokee receives a request for a specific
domain, it evaluates the <tt>Domain list</tt> of every defined virtual host
in the order defined by the priorities of such hosts. If no domain
name matches the request, Cherokee re-evaluates the list of virtual
hosts as before, trying to match the request against the <tt>Nicknames</tt>.
Only after failing both with the domain names and the nicknames will
Cherokee issue the failure.</td>
</tr></table>
</div>
</li>
<li>
<p>
And we will add this domain to our /etc/hosts file as an alias for
the real server.
</p>
<div class="listingblock">
<div class="content">
<pre><tt>10.0.0.118 intranet_example</tt></pre>
</div></div>
<div class="paragraph"><p>In this case we are using the IP address assigned to the server in our
intranet, and this will grant access from our computer to the original
site whether the copycat is present or not.</p></div>
<div class="paragraph"><p>You might want to reflect such configuration in a private DNS in case
you need more flexibility, restrict access to specific IP ranges and
similar security measures, but the principles are the same.</p></div>
</li>
</ul></div>
</div>
<div id="footer">
<div id="footer-text">
</div>
</div>
</body>
</html>
