Cherokee Quickstart
Many users have told us that they would love to have some more documentation about Cherokee. One of the tasks before relasing 0.8 (which is almost ready by now) is documenting.
Yesterday I wrote a small tutorial that will be part of the documentation. It is a simple walkthrough to set up a couple of virtual servers, basic authentication (PAM and flat) and some redirections.
It will be available at the official site as soon as we make the release, at http://cherokee-project.com/doc
Here it is for now. No screenshots and not much styling in my blog, sorry. It’s just a quick cut&paste. There’s a lot of other stuff I should be documenting instead of blogging ;)
Configuration Quickstart
This section briefly describes the whole administration web interface provided by cherokee-admin. This is the only recommended way of configuring Cherokee. If you are looking for development information, you should refer to the appropriate section, especially cherokee.conf file specification.
We will first show a quick overview of the available options, followed by a simple walkthrough. You can learn more about the options in their specific documentation entries.
Overview
- General: There are a number of entries that specify the most significant configuration options such as the port – or ports – that the server will listen to, the default timeout, whether to support keep-alive connections and so on.
- Virtual servers: If you want your web server to work with more than one domain you will have to create Virtual servers other than the default one. Each one will have a completely independent configuration: paths, behavior, logging facilities, etc.
- Encoding: The encoders allow to transform whatever information the server is sending as a response of a request, no matter what handler is generating it.
- Icons: Associate icon images with one or more file extensions. Used to offer directory listings.
- Mime Types: Manage MIME types.
- Advanced: This is to configure the most complex parameters of the server and how it interacts with the operating system. If you are unsure about any of the options here, better not mingle with them. Default values should work just fine.
Walkthrough
There is very little set up you must do to have a perfectly functional web server out of the box. Cherokee‘s default configuration can be used to serve any typical PHP-driven dynamic website.
If you have a specific need, you should check out the recipes present in the Cookbook section of the documentation. Among other subjects, you can find information about Cherokee optimizations, setting up efficient Authentication mechanisms, or configuring several popular application frameworks.
In this tutorial we will be setting up a system with a couple of virtual servers, PHP support, some redirection rules and a simple authentication mechanism.
To follow this walkthrough you need to be running cherokee-admin. This is an administration tool, so you will need system administrator rights.
# cherokee-admin Cherokee Web Server 0.8.0 (Aug 6 2008): Listening on port 9090, TLS disabled, IPv6 disabled, using epoll, 1024 fds system limit, max. 507 connections, single thread, 1016 fds Server 0.8.0 running.. PID=19611
Now you can access the administration interface simply by opening your web browser and visiting http://localhost:9090
If your user doesn’t have enough privileges you will be notified. Also if no configuration file exists you will be prompted to create one with the default settings.
That is a good starting point. Right now your web server will not be running yet. We will only be using two of the available tabs to adjust some more settings: General and Virtual Servers.
Of course, once we’re done we will have to apply our changes and launch the server. The configuration changes must be submitted to the server, be it automatically if possible or by using the appropriate form submitting buttons. But no change is reflected in the configuration file until you Apply the changes. You can be sure of not damaging anything while playing around with cherokee-admin. At least not until you Apply the changes. Note that, if the Cherokee server is running, the applied modifications will also affect the instance being executed.
We will only be modifying the Server Permissions. It usually is a poor choice to run services with super user privileges. Set both User and Group to www-data. Your system might already have another user account specifically for the purpose of running a webserver. Use that instead if so, or create the www-data user if you don’t already have one.
Next is the Virtual Servers tab.
When you start, you will only have one virtual server called default. You can begin by cloning it as example. While you are at it you should also append the following line to your /etc/hosts file (in Windows you will find this as %WINDIR%\system32\drivers\etc\hosts).
127.0.0.1 example.net example.org
This is to allow your system to resolve requests for example.net or example.org locally. Of course, once you are out in the Wild (you know, in the Internet), you will need proper DNS records.
- default
- We will leave default untouched except for the document root path, which we will change. This is done through the Basics tab. You could create by hand /var/www/default for example and set it up in the appropriate field.
If you access your machine by IP or a DNS resolution points in that direction for any particular domain, the contents of your document root directory will be exposed (/var/www by default unless you changed that during the build process). Whenever there is no match for a virtual server specifically defined in your list, the default virtual server will be the one responding.
Right now any file with the php extension will be served after being processed by the PHP interpreter (you should have php-cgi installed in your system for this, though).
Any requested file would be sent. If a directory is requested, a file called index.php or index.html will be served if it is present (the search will be performed in that order; you can configure this in the Basics tab). If not, a directory listing is offered instead. If you would want to prevent this behavior but would like to keep up serving whatever content is requested directly, simply change the List & Send handler for the Static Content handler.
- example
- For now this virtual server is an exact copy of the untouched default virtual server. Create some new directories /var/wwww/example and /var/wwww/example/auth, and configure the first one as default document root path.
Next, setup example.net and example.com in the Domain names tab. We’ll erase everything in the Targets list within the Behavior tab, except the default rule. With this we’ll only be able to serve static content.
Accessing the URL http://example.org should now show a list of available files and directories under /var/www/example/.
Now lets password protect the auth directory. Add a new Directory class rule pointing to /auth. Then, through the Security tab, add a Validation Mechanism under Authentication.
The field Realm is mandatory. Lets set it as Secured Area. If you choose PAM and impose no more restrictions, only users with a local account in your system will be able to access the secured zone at http://example.net/auth Other mechanisms would work in a similar fashion but with their specific requirements. For example, had you chosen Plain text file instead of PAM you would have had to specify a Password File. For example, it could have been /var/www/passwords.txt with the following contents:
testuser1:password1 testuser2:password2
Note that the rule must not be flagged as Final, or else no other rules will be applied afterwards and no access will be given to any contents. This is because at this point we have not defined any handler for the /auth rule and nothing would be served.
Refer to the Cookbook for detailed examples on the different options.
Lastly, lets configure a redirection rule by choosing a “Regular Expression” as the new rule type. Type the following regex: ^/rss.*$ Then, within the Handler selection tab specify a target: /feed
And voilà! A request of the form http://example.net/rss2 would be redirected to http://example.net/feed
Note that the Type of the Redirection is External. This means the server will instruct the requesting web client to fetch the redirected URL, which means the client will allways know what the final URL is. This also means the redirection can be done to servers other than your own. If it were internal, the redirection would be invisible (no URL rewrite), but if it was done to an external server the Virtual Domain setting wouldn’t apply and your default virtual domain would have to handle the connection. Having the theoretical content hosted elsewhere, an error would occur.
A much more general redirection could be one using these values:
- Regular Expression
- ^/(.*)$
- Substitution
- http://www.example.com/example.net/$1
Note that this rule would have to be external since example.com is not among the domains managed by our configuration.
This would redirect every petition to a site hosted under http://example.com/example.net. For instance, the request for http://example.net/image.jpg would return http://example.com/example.net/image.jpg
You can follow any responses to this entry through the RSS 2.0 feed. You can leave a response, or trackback from your own site.
I use ubuntu. there is a problem with the line that works abrir cherokee-admin. and either I am doing if it well.
look
root@Kame-House:~# Cherokee-admin Cherokee Web Server 0.8.0 (Agosto 6 2008): Escuchar en el puerto 9090, TLS discapacitados, minusválidos IPv6, usando epoll, 1024 FDS sistema de límite máximo. 507 connections, single thread, 1016 fds Server 0.8.0 running.. 507 conexiones, de un solo hilo, FDS 1016 Server 0.8.0 corriendo .. PID=19611 PID = 19611
bash: error de sintaxis cerca de token no esperado `(‘
and pardon by my English. I am Mexican.
this is the only place that has useful information.
thanks
mmmm sorry, I’m stupid, because I write in the shell with the traslation tool activated.
then I writed this:
root@Kame-House:~# cherokee-admin
bash: cherokee-admin: orden no encontrada
well, I install the other packages that I find in synaptic tool.
but nothing happens.
Hi Samira. Don’t worry about the language. Actually Spanish is my mother language ;)
Cherokee-Admin didn’t exist until Cherokee 0.6. The release currently packaged in Debian (etch) and Ubuntu (Hardy) predates that. Debian Lenny and Sid, and Ubuntu 8.10 already include Cherokee 0.7.2.
However I would strongly recommend to use our latest release (currently 0.8.1, and 0.9 in development) since it is much much better. The best release ever by far! :)
By the way, I posted this before releasing 0.8. Since then we have upgraded the documentation available online, and these contents plus screenshots are officially here: http://www.cherokee-project.com/doc/config_quickstart.html
thank you very much,
I install cherokee of the repositorios, because in the page tells that was better.
and thank you for answer me. aiozzzzz
bye
pardon to ask as much
but not yet works cherokee-admin to me.
Istart to unload with this line:
root@Kame-House:~# wget http://www.cherokee-project.com/cherokee-last-tarball -O -| tar zxvf -
later I did what in the page tells:
Configure the package for your system:
./configure –localstatedir=/var
./configure –prefix=/usr
./configure –sysconfdir=/etc
./configure –with-wwwroot=/var/www
Compile the package:
make
Install the programs and any data files:
make install
all works very well, until, I wrote:
root@Kame-House:~# cherokee-admin
cherokee-admin: symbol lookup error: cherokee-admin: undefined symbol: cherokee_init
I think could works in this way:
root@Kame-House:~# sudo cherokee-admin
cherokee-admin: symbol lookup error: cherokee-admin: undefined symbol: cherokee_init
but it didn’t do it.
Something had to go deffinitely wrong during the installation. Note that you should only do “configure” once (or else only the last time will count), like this for instance:
“./configure –localstatedir=/var –prefix=/usr –sysconfdir=/etc –with-wwwroot=/var/www”
Anyway, could you joing the mailing list and report your error there? I’m sure we’ll get you up and running in no time ;) The URL is: http://lists.cherokee-project.com/listinfo/cherokee
Try as I may, I can not get a Virtual Server running.
I am using 0.11.6
Ubuntu 9.04 Jaunty
Your instructions here are for windows but I am running ubuntu and I can not for the life of me find the host file to edit
Can you assist in almost non geek language?
@Lee: 0.11.6 is quite old now. We’re currently on 0.99.24, which is still not ready for Windows. On Linux it runs awfully well ;)
I recommend you come by our mailing list, where we’ll be able to assist you properly and you might find solutions to your problem that were posted in the past: http://lists.octality.com/listinfo/cherokee