Caudium

Introduction

Caudium is an Internet server that provides HTTP and SSL/TLS protocol services. Caudium is written in C and Pike, which is an interpreted object oriented language originially designed for use in MUDs (multiuser dimensions). The use of Pike enables the server to be quickly and easily extended and allows Caudium to provide powerful dynamic content features as well as easy to use web based configuration. The use of an interpreted language does not sacrifice the server's execution speed and shortens the development path from writing the code to its actual use. For details about Pike please take a look at the Pike site

This document assumes that the reader has experience working in UnixUnix® environments, as well as access to C development tools (cc or gcc, make, etc). The Caudium software has been successfully compiled in most popular unix environments, including Solaris, *BSD, Linux, HPUX and MacOS X.

Because Caudium is partially written in Pike, it stands to reason that we must have a working copy of Pike installed any the system we want to run Caudium on. For the most part, Pike is fairly easy to build and install, and there is a helpful mailing list, pike@roxen.com if you run into problems.

Install any prerequisite software packages.

The following external software libraries are strictly optional, however the presence of certain packages enables many useful features available in the Caudium software. You should install those packages before you begin to compile the Pike package. As long as you install these libraries in a reasonably standard location (/usr, /usr/local , etc), the Pike configuration process should be able to find them. If you have installed a package, and the Pike configuration process isn't able to find it, you may have to provide a little assistance, through the use of environment variables such as CF LAGS and LDFLAGS, or command line arguments to the configure command.

The following list contains some recommended software that is useful when using Caudium, roughly listed in order of importance:

• GNU gmp (required for SSL support, and bundled with most releases of Pike)
• Database Libraries (required for database access, choose any that match the type of databases you'll be using), such as Mysql, SQLite, Postgres, Oracle or ODBC.
• Graphics Libraries (required for image manipulation, again choose those file formats that you anticipate using), such as lib tiff, jpeg, freeetype, zlib, etc.
• zlib
• GDBM
• Java (experimental support)

$ wget http://pike.ida.liu.se/download/pub/pike/all/7.6.xxx/Pike-v7.6.xxx.tar.gz

Unpack Pike

$ gzip -d Pike-v7.6.xxx.tar.gz
$ tar xf Pike-v7.6.xxx.tar

Enter Pike source directory.

$ cd pike-7.2.xxx 
$ cd src

Build Pike.

$ make

You should make a note of the output of the configure process, in order to be sure that it was able to find all of the optional software libraries you installed previously. If the configure process isn't able to find a library you installed, such as Mysql, you can use the following environment variables to assist the process, as shown in the example below (bash syntax):

# if you want to force the use of a particular compiler such as cc
$ CC=cc

$ CFLAGS="-I/usr/local/mysql/include" LDFLAGS="-L/usr/local/mysql/lib" 
$ export CC CFLAGS LDFLAGS

# required to force configure to look for things again
rm config.cache

$ make

There are also a number of command line arguments that you can provide to the configure process in order to specify file locations, enable features and alter the configuration process. To see the available options, enter the following command:

$ make CONFIGUREARGS="--help"

Assuming that the configuration process went smoothly, Pike will build automatically once the configure process completes.

Depending on the speed of your computer, this can take anywhere from 2-3 minutes to an hour. If the make process winds down without any major errors, you should be all set to continue.

Run make install [as root]

You should keep an eye on the build process, in order to make sure that there are no problems or errors. Once the pike interpreter is built, you can install it. The default location for installing Pike is in /usr/local/pike/pike-version. Symbolic links are made from that location to the /usr/local/bin directory for the pike command. If you're paranoid, you may run

$ make test

to run a rather large series of validation tests against the interpreter you just built. In most cases, however, that's not necessary unless you run into problems running the Caudium software.

To intall Pike, you need to run the following command from the src/ directory as root:

$ make install

You should see a series of messages and finally a message indicating that Pike was successfully installed. You can verify this by running the pike interpreter from a command line:

$ /usr/local/bin/pike 
Pike v7.2 release XXX running Hilfe v2.0 (Incremental Pike Frontend) 
> exit(0); 
Terminal closed.  

This lets you know that you've got yourself a functioning pike interpreter. Now we can continue on to the installation of Caudium itself.

As the alternative to the process outlined above you may install the pre-packaged versions of Pike if they exist for your operating system.

Download Caudium

$ wget http://ftp.caudium.net/caudium/source/caudium-1.4.18.tar.gz

Unpack Caudium

$ gzip -d caudium-1.4.18.tar.gz 
$ tar xf caudium-1.4.18.tar

Enter Caudium directory

Run configure

$ ./configure

At the end of the configuration process, you'll get a report of potential problems you might encounter with the particular combination of Pike and feature support available on your system. For the most part, this information is informative and won't prevent you from getting a working Caudium, though it might describe some limitations you'll get if you continue.

Should the configure process fail to find a working copy of Pike or if you want to use a different version than that found by the configure script, you can use the following command line to configure Caudium:

$ ./configure --prefix=/usr/local --with-pike=/usr/local/bin/mypike

Note that it is important that the prefix (/usr/local) above is the same as the prefix of the Pike you want to use.

Run make

$ make

If the make process completes without any major problems, you can move on to the installation process.

Run make install

$ make install

The default installation location is /usr/local/caudium. If you want to install Caudium in a different location, you can use the --prefix=/my/location agument to the configure command.

Change to the Caudium server directory

$ cd /usr/local/caudium/server

Run the Caudium installer.

$ ./install

You'll be asked to answer some questions, including the hostname and port to run the configuration interface on. You will also be prompted to enter a configuration username and select a password. Upon completion, point a web browser at http://yourserver:yourport/ to begin the configuration process.

The /usr/local/caudium directory contains all of the software needed to run Caudium, with the exception of the pike binary, which is linked from its actual location. As long as you don't move your Pike from its installed location, you should be able to move the /usr/local/caudium directory anyplace that's convenient (such as /opt/caudium or /export/home/caudium). Inside the caudium directory are a number of subdirectories:

These directories contain data that is used during the operation of the server, and should not be al tered:

The Configuration Interface

Caudium is configured through a web based configuration interface. The interface allows you to manage all aspects of the Caudium server, including (but not limited to) adding/modifying/deleting virtual servers, server restart/shutdown and performance monitoring.

Caudium operation is highly modular. Most functionality of the server is provided by server modules written in the Pike programming language. A module can provide any number of services, ranging from authentication to filesystem services to new markup tags. The Caudium distribution contains a large number of modules ranging from commonplace to highly exotic.

Services are provided by Caudium through one or more virtual servers. A virtual server can be thought of as hosting of a single website and provides a set of services on a particular host and port. Caudium is able to provide IP-less virtual hosting in which the Host header used by the HTTP protocol (version 1.0 and newer). IP-less virtual hosting allows you to serve multiple distinct websites from a single IP address. You may have as many virtual servers as you wish running on a single instance of Caudium.

The Caudium configuration interface consists of 4 tabs: Virtual Servers, Global Configuration, Log and Actions. The Virtual Servers tab allows you to manage your virtual servers, preferences and the modules used by each virtual server. The Global Configuration Tab is used to manage global settings used by the Caudium server, such as the server module search path and debug log locations. The Log tab provides a convenient tool for monitoring log messages that are placed in the server's debug log. Finally, the Actions tab provide saccess to a number of Wizard based tools for managing your server, such as viewing server status, server shutdown and other tasks.

Create a new virtual server

Most of the global settings should be fine as defaults, so the first thing you should do once you log in is create a new virtual server. To do this, you need to select the Virtual Servers tab in the configuration interface.

At the bottom of the screen, you'll see a number of buttons. One of these buttons is "New Virtual Server." Click on this button.

A dialog box should appear prompting you for a name for the virtual server (you may select anything you'd like, recommendations are the hostname that the server will be providing services for, or per haps a description of the content to be served). Note that the name must obey the file naming rules of the underlying Operating System since that name will be used to create the log directory for the virtual server.

The other bit of information you'll need to think about is the type of virtual server you want to create. Caudium provides a number of preconfigured "virtual server templates" that have some preselected modules. The template you choose will depend on the type of service you want to provide (SSL vs Web, CGI capability, etc). You can always change the capabilities of you virtual server by adding or deleting modules and changing settings. Pick a template from the drop-down list and click the "Create" button.

After a few moments, you'll be presented with a view of your new virtual server. This information is presented in a "folding tab" view, where you can unfold different levels of information "drill down" to the available settings which may lie several layers deep.

When you create a new virtual server, Caudium will "unfold" the options that are most necessary for creating a useful server. Typically, these options include a host and port to listen to, and a filesystem mountpoint and search path. You probably will want to have at least one filesystem mounted at /, otherwise people will get a file not found error if they browse to yourwebsiteaddress:port/.

The filesystem search path is the location in the host's real filesystem where the files you want to be served are located. For now, you can think of this in terms of Apache's "ServerRoot". This isn't strictly correct, for as we'll see later, you can have more than one filesystem mounted at once, each serving files from a different location in the real filesystem.

Provide values for these (as well as any other relevant) options and choose "Save," which is located at the bottom of the settings page. At the top of the settings list, you should see a bit of information letting you know the server is up and running on the port(s) you specified.

This is probably a good point to discuss some of the unique features of the Caudium module system. Caudium defines a number of module "types." Each type of module serves a different function and a module may belong to one or more types. Each request to your virtual server from a client passes through the modules in your virtual server in a specific order. The request starts out at the first pass modules (in case of multiple modules of a given type, there is a priority you can set in the configuration interface serves to provide the order they're used) and ending up at the last try modules if it's not been caught and handled previously.

Location modules return data based on a particular location in the virtual server's "filesystem". Location modules are mounted on a particular location in the virtual filesystem of a virtual serve r. Typically, location modules provide the filesystem, real or otherwise, for a virtual server. Other location modules might redirect to another URL based on the file requested in a filesystem.

Parser modules provide tag and container markup for the RXML server side markup language. A parser module can provide any number of tags or containers.

Authentication modules provide means for validating authentication requests. Examples of authentication modules include NIS authentication, SMB/NT authentication and LDAP authentication.

First and last try modules are passed the client request first and last respectively. They may "catch" the request and handle it themselves, or they can pass the request on down the list of modules, optionally modifying the request as they do. "Last try" modules are typically used to return an error to the client, as no other module was able to handle the request.

Additionally, certain types of modules may appear more than once on a virtual server, providing "stacked" services. An example of this might be a server with multiple parser modules, with each module providing one or more additional markup entities. Another example might be a virtual server with multiple "location" modules, providing different data based on location, just as multiple filesystems may be mounted at once on a unix system.

You may add modules to a virtual server at any point by clicking on the "Add module" button located at the bottom of the virtual server settings page. A list of available modules will be generated, each with a brief description of the functionality they provide. You can select a module to be added by clicking on the module's title bar. The newly added module will be added to the virtual server's configuration tree.

All of this talk about modules and paths and virtual filesystems might seem a little confusing now, but it actually makes it very simple to create complex website structures with very little effort. Stick with it and you'll be richly rewarded in return!

Starting/Stopping and reloading the server

The Caudium server is started by running the start.sh script in the caudium/server/ directory.

$ cd /usr/local/caudium/server 
$ ./start-caudium

Starting the Caudium world wide web server 
… 
Debug information is being written to logs/debug/default.1

The start-caudium script supports a number of options, all of which may be viewed by running the following command:

$ ./start-caudium --help

The Caudium server is typically shut down or restarted by using the Restart option found in the "Actions" tab of the configuration interface.

You may also force Caudium to reload its configuration files (which may be edited by had or script if necessary) by sending the caudium proces the HUP signal.

$ kill -HUP [caudium pid]

By this stage of the game, you should have a working copy of Caudium, hopefully serving some content to your web browsers. From here, the possibilities are endless, whether you want to use the power of RXML to create dynamic websites, or create modules that provide exciting new functionality, or sim ply want a high performance webserver that's easy to configure and maintain.

Below is a list of useful internet resources that can help you on your way toward Caudium mastery. Good luck and happy serving!

http://www.caudium.net -- The official Caudium Project website
http://source.riverweb.com -- The Caudium/Roxen module source
http://pike.lysator.liu.se -- The official Pike lan guage website
caudium-general@caudium.net -- The Caudium mailing list
pike@roxen.com -- The Pike mailing list

28 January 2002, updated 16 April 2012 Bill Welliver bill@welliver.org