Description: 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.
Keywords: cherokee web server httpd http

## Index → Development info

## Development: Debugging Cherokee

### cherokee-admin

Cherokee Admin is written in Python. While making changes, you can use the `-x` or `--debug` parameter to see the Python back traces in the active console.

### cherokee

If you need to debug the behavior of the web server (or an application), there are some helpful tools available for you.

- To start with, if you are using gcc and you want to compile Cherokee with debug information just execute make like this:

        make V=1 CFLAGS="-O0 -gdb3"

  And then you will be able to execute under a debugger (gdb).

- You can use autoconf to set up Cherokee to use static modules:

        ./autogen.sh --localstatedir=/var --prefix=/usr --sysconfdir=/etc  \
        --with-wwwroot=/var/www --enable-static-module=all --enable-static \
        --enable-shared=no

- If you want a code backtrace printed each time an error message is generated, add the following `configure` parameter:

        --enable-backtraces

- You can also enable a cool feature: the CHEROKEE_TRACE environment variable to trace what is going on inside the server. To enable it you must add a special flag to your `configure` or `autogen.sh` statement:

        --enable-trace

  This will let you trace the behavior with a human-readable output.

  Note that by enabling tracing you will be making Cherokee a lot slower. Keep this in mind when deploying in production environments.

  Now, when you are going to launch the web server, just add the CHEROKEE_TRACE variable, with the desired options:

  cherokee# CHEROKEE_TRACE="common" cherokee

  Cherokee Web Server 1.0.0b5077 (May 12 2010): Listening on port ALL:80, TLS

  disabled, IPv6 enabled, using epoll, 1024 fds system limit, max. 505

  connections, caching I/O, 10 threads, 50 connections per thread, standard

  scheduling policy

  handler_common.c:0143 ( stat_file): /var/www//images/powered_by_cherokee.png, use_iocache=0 re=0

  handler_common.c:0190 ( cherokee_handler_common_new): request: /images/powered_by_cherokee.png, local: /var/www//images/powered_by_cherokee.png, exists 1

  handler_common.c:0236 ( cherokee_handler_common_new): going for handler_file

  handler_common.c:0143 ( stat_file): /var/www//images/default-bg.png, use_iocache=0 re=0

  handler_common.c:0190 ( cherokee_handler_common_new): request: /images/default-bg.png, local: /var/www//images/default-bg.png, exists 1

  handler_common.c:0236 ( cherokee_handler_common_new): going for handler_file

  handler_common.c:0143 ( stat_file): /var/www//images/cherokee-logo.png, use_iocache=0 re=0

  handler_common.c:0190 ( cherokee_handler_common_new): request: /images/cherokee-logo.png, local: /var/www//images/cherokee-logo.png, exists 1

  handler_common.c:0236 ( cherokee_handler_common_new): going for handler_file

  Of course, you can trace all the modules (handlers, loggers..) you need:

      CHEROKEE_TRACE="common,static,io_cache" /usr/bin/cherokee
      CHEROKEE_TRACE="all" /usr/bin/cherokee

  By default the environment variable contains a list of comma separated words, that point the server which parts and actions are interesting for your trace. Besides, there are a few special cases:

  Keyword | Description
  --- | ---
  all | Activates all the trace points
  time | Prints the time at the beginning of the line
  thread | Prints the thread ID
  from=<IP> | Restrict the tracing to the information generated by certain IP or Subnet.

- You can also access the functionality of CHEROKEE_TRACE through `cherokee-tweak`. Refer to the apropriate section of the documentation to learn more about this: cherokee-tweak.

- Lastly a utility is provided, `contrib/tracelor.py`, to provide further help to these tracing abilities. It is a little script that helps to read the tracing logs by colorizing the thread references and highlighting the words passed through the command line.

  An example of usage would be:

      CHEROKEE_TRACE=thread,all ./cherokee | ../contrib/tracelor.py iocache

  And it would yield a colorized output. Even if it is not terribly complicated, it is a handy script to trace the server more easily.