Caudium is a Web server based on a fork of the Roxen Challenger 1.3 WebServer. Like Roxen, Caudium is written in Pike with parts written in C for performance reasons. Pike is an interpreted language developed by Frederik Hübinette and Roxen Internet Software (RIS), a Swedish company which also created the Roxen Web Server. Caudium, like Pike, is distributed under the terms of the GPL license; several companies and people are involved in its development.

Caudium features include:

Caudium is backward compatible with Roxen Challenger 1.3. It has all the Roxen 1.3 RXML tags and the Roxen 1.3 API, so, from a technical point of view, it is quite the same (although Caudium has many improvements over Roxen 1.3). The main legal difference between Roxen 1.3 and Caudium is that Roxen is property of Roxen Internet Software whereas Caudium is owned by its developers, The Caudium Group. There are many functional extensions, improvements and bug fixes over the original Roxen 1.3 code base from which Caudium was created. Here you may say it is not a problem since it is under GPL. The problem is that even it is licensed under the GPL, RIS may not include your patch in its CVS tree, you may not have a CVS account, so you can't really do all you want. The main reason for the fork, however, was that RIS didn't pay attention to the users' needs, and proceeded to make the new versions of the Roxen Web Server largely incompatible with the previous versions, to the point where one couldn't switch to the new version of the software without much effort put into conversion of the old source code. Rewriting huge portions of RXML/Pike code just to switch to a new version of the web server seemed to be quite counter-productive, and thus the Caudium Project was born.

Caudium differs from Apache in many ways including the directory structure, programming language, and type of configuration. Caudium has a fully integrated web interface, while Apache relies on editing text files directly. Moreover, any change to the Apache configuration requires a restart of the server, while Caudium sees the changes immediately after you save them from the web interface. There are also some differences in the vocabulary used in the configuration interface. Another difference is that Apache 1.3 uses a forked process model while Caudium uses threads or a monolithic process model, depending on the features present in the copy of Pike it uses. Caudium allows the programmer/user to easily extend the server using modules/scripts written in Pike that integrate tightly with the core server and, thus, create a more robust, faster and more intuitive entity than an Apache server augmented with a set of external dynamically loadable libraries. While changing anything in the source code of any Apache extension (or the server itself) requires recompilation, relinking and restarting of the whole server, Caudium allows one to add/remove/modify code without any interruption of the server operation. If you modify a module all you need to do to see the effects of your work is to reload the module in question using the configuration interface. Caudium's architecture also provides easy means of building highly dynamic web pages that use SQL, gdbm, Mird databases, LDAP, dynamically generated graphics (including business graphics modules) and more. The same effect can be achieved with Apache almost only by using external set of Perl, Python, or other language, scripts running as CGI or embedded using a dynamically loaded module. While allowing the programmer/designer to use CGI modules, Caudium offers more power when the source code is integrated with the Caudium core.

In Debian GNU/Linux Woody, also known as Debian 3.0, Caudium and Pike 7.0 and 7.2 are included in the distribution. If you use Woody, you will have Caudium 1.0 and Pike 7.0/7.2. If you use Sid you will have the latest Caudium and the latest Pike; these two packages are actively maintained by the Caudium community, and you will have frequent updates. If you want to test the latest Caudium under Woody, add this to your /etc/apt/sources.list:

deb http://grendel.firewall.com/debian/caudium/1.2 unstable main
      

This location is mirrored in other locations, so you can also use:

deb http://ftp.oav.net/caudium unstable main 
deb ftp://ftp.oav.net/caudium unstable main
      

If you want php4 Debian package for Caudium, you can do:

# su -
# apt-get update
# apt-get install -f caudium caudium-modules \ 
  caudium-ultralog caudium-pixsl caudium-dev
      

And then grab the PHP4 sources:

# exit
$ cd /usr/src; apt-get source -d php4; apt-get build-dep php4
      

If you don't have devscripts and debhelper installed, install them now. Then enter the /usr/src/php-4* directory and do:

$ debuild binary



      

After some time and some coffee you should have php4 packages for Apache, CGI and your fresh Caudium.

Caudium 1.0 and Pike 7.0 are in the official FreeBSD ports. There are also available as a binary package in the FreeBSD 4.7 CDROMs.

$ cd /tmp
$ fetch ftp://ftp.oav.net/pkg_freebsd/ports.tar.gz
Receiving ports.tar.gz (32468 bytes): 100%
32468 bytes transferred in 0.6 seconds (53.87 kBps)
$ su -
# cd /usr/
# tar xzf /tmp/ports.tar.gz
      

As root, go to /usr/ports/www/caudium10 to install current stable version, /usr/ports/www/caudium12 to install the next stable version in Release Candidate process, or /usr/ports/www/caudium-dev to install the current developer's version. The script will automatically fetch and install Pike, try to detect what library you've installed and compile all the necessary libs for Caudium and Pike.

Here is the current Pike / Caudium options supported by the current port :

There are some options related only to Pike, like the GNOME / Mesa ones that are uninteresting to Caudium, but exist for Pike support.

A little example on how to install Caudium on FreeBSD :

# cd /usr/ports/www/caudium12
# make WITH_MOST=yes WITH_MYSQL=yes WITH_OPTIMIZED_CFLAGS=yes install clean
===>  Extracting for caudium-1.2.6
>> Checksum OK for caudium-1.2.6.tar.gz.
===>   caudium-1.2.6 depends on executable: pike - found
===>   caudium-1.2.6 depends on executable: gmake - found
===>   caudium-1.2.6 depends on shared library: sablot.67 - found
[...] 
===>   Generating temporary packing list
***************************************************************
  If this is the first installation of Caudium, please go the 
  caudium's directory and execute the server/install script
  to finish the Caudium installation.

  If your are upgrading, just start caudium as usual.

  NOTE: there is an automatic starting script in etc/rc.d/
*************************************************************** 
===>   Registering installation for caudium-1.2.6
===>  SECURITY NOTE: 
      This port has installed the following startup scripts which may cause
      network services to be started at boot time.
/usr/local/etc/rc.d/caudium.sh.sample

      If there are vulnerabilities in these programs there may be a security
      risk to the system. FreeBSD makes no guarantee about the security of
      ports included in the Ports Collection. Please type 'make deinstall'
      to deinstall the port if this is a concern.

      For more information, and contact details about the security
      status of this software, see the following webpage: 
http://caudium.net/
===>  Cleaning for libiconv-1.7_5
===>  Cleaning for gdbm-1.8.0
===>  Cleaning for mird-1.0.7
===>  Cleaning for mysql-client-3.23.49
===>  Cleaning for autoconf-2.53
===>  Cleaning for autoconf213-2.13.000227_1
===>  Cleaning for automake14-1.4.5
===>  Cleaning for bison-1.35_1
===>  Cleaning for gettext-0.11.1_3
===>  Cleaning for gmake-3.79.1_1
===>  Cleaning for libtool-1.3.4_3
===>  Cleaning for m4-1.4_1
===>  Cleaning for nasm-0.98,1
===>  Cleaning for jpeg-6b_1
===>  Cleaning for tiff-3.5.7
===>  Cleaning for pexts-20020121
===>  Cleaning for pike72cvs-7.2.356_5
===>  Cleaning for libgmp-4.0.1
===>  Cleaning for freetype-1.3.1_2
===>  Cleaning for freetype2-2.0.9
===>  Cleaning for libmcrypt-2.5.0
===>  Cleaning for mhash-0.8.14
===>  Cleaning for expat-1.95.2
===>  Cleaning for Sablot-0.81_1
===>  Cleaning for caudium-1.2.6
#
     

Now if you need to install PHP4 support for Caudium, just go to /usr/ports/www/caudium_php4 and do a make install clean as well.

Bill Welliver has made some packages. They are available on Riverweb and mirrored to Oav.net.

To get CAMAS from the CVS, go to the CAMAS web site and follow the link.

You need to install Pike before you can install Caudium. The version of Pike is different depending on the Caudium version you want to install. For Caudium 1.0, use Pike 7.0; for Caudium 1.2, use Pike 7.2. You can find some Pike packages for the most popular systems: Debian GNU/Linux (Woody/Sid), FreeBSD, Solaris.

For more information, see the quick start guide at http://caudium.net/.

The first time you install Caudium from the sources, you will need to type the following commands:

# su -
# cd /usr/local/caudium
# ./install
    

This script will allow you to give login information for the Configuration InterFace (CIF.), the web based configuration interface, and the port address for the CIF.. But if you want to start Caudium manually, you don't need to use install, just use the start script. This script will fork Caudium once and restart it automatically if it dies. A consequence is that if you kill start, the server will always be running but it will not restart if it dies.

There are many useful options to start. The first is --help. Here is a non-exhaustive list of options:

Finally, the most important thing is debug log files. These files are stored in ../logs/debug (relative to /usr/local/caudium/server in our example). The current log file is named default.1. The log file from the last Caudium start is default.2 and so on. If you didn't enable debug, these files are always used but contain very few messages.

There are two ways to stop Caudium:

On Debian GNU/Linux, you can use the following commands to manipulate the server status:

# /etc/init.d/caudium stop
# /etc/init.d/caudium start
# /etc/init.d/caudium restart
    

You can also see readme/README relative to /usr/local/caudium in our example.

Upgrading Caudium is simple. You should install it as if for the first time. That is, get the new sources, unpack them, run ./configure; make; make install and that's all. The new Caudium installation will detect your old Caudium and keep all your old installation including your config files. The config files will be compatible with the new version so you will never have to begin the configuration task a second time. The old server directory will be saved as server.old and so the new one will be put in the classical server directory.

If you use a package system, just use the upgrading features of your packaging system.

The CIF. is where the administrator manages the server. When you first login it looks like this.

The first page you will see when you login on the CIF.

In the CIF, you'll find four tabs:

As the CIF. is quite easy to cope with, I will try to describe some of the hidden things you may need to know about. One of them is the button. This button is very useful. Furthermore, some Basic options will not be available unless you turn it on. With this option, you will have more control over Global Variables and some modules in Virtual Servers.

One of these controls is the button that you will have when you are in a module. This button will allow developers to check the new code of their modules without restarting Caudium. You should also know that very few options in some modules will not be activated unless you reload the module. So always reload a module when you think an option has not been read by Caudium.

In this section, I will give you a step-by-step tutorial on how to create your first site (virtual server) with Caudium. If you want to do something useful with Caudium, you have to create at least one virtual server. Without this first server, Caudium will not do anything. If you use your browser to access your server, you will only get a dialog box prompting for the CIF. login/password.

To create your first server, log into the web based CIF.. Click on the Virtual Servers tab, then the button.

Here, you are prompted for the server name:

Type in an easily identifiable name. You also have to select the configuration type. Depending on the configuration you choose, your server will have a different set of modules. In other words, your server will have different capabilities. For your first server, choose Basic server, and click OK.

7.1. Server variables

Now you'll see the Virtual Servers page again. As you can see, you have two different folders to work on: Server variables (Figure 4.1, “Ports in the CIF”) and File system (Figure 4.2, “Filesystem in the CIF”).

Figure 4.1. Ports in the CIF

Figure 4.2. Filesystem in the CIF

Server variables contain the URL of your site, and the port on which it will be available. File system describes the files/directories containing the .html and other files you want Caudium to serve.

In server variables, go into Listen ports and choose Configure a new port. Use the default values, choose Use these values, and click . Now select the URL of your site, and select Continue. You can now go back to the page displaying all of your modules, that is, where you were before you had gone into Server Variables.

Under your server name, you'll see the status of your server. If it contains the word “Open” in blue everything is okay, and you can continue with configuring the file system.

If it contains the words “Not open” in red, there is a problem. You can go into the Event Log via the CIF. tab to investigate. If you have an error Failed to open socket on 0:80 (already bound ?), you may have another program or Caudium itself already running on this port. To fix the problem, identify the program which is using this port, and restart Caudium ^[1]. To restart Caudium, go into Action → Shutdown → Shutdown Caudium → Restart Caudium. Wait a few seconds, and when prompted, select Virtual Servers. Now select your server, and you should have the word “Open” in blue.

In the CIF. you may wonder what are those two different protocols http and http2?

The difference is that http2 uses Caudium's internal memory cache while http is plain Pike http subsystem. So http2 is faster than http as you might expect. However, there are some issues on some specific sites.

7.2. Selecting file system

By selecting a file system, you tell Caudium which files it will send to people browsing your site. For those who know other web servers, please pay close attention to these explanations, because Caudium is quite different from other servers in this respect.

Caudium file systems use the Unix philosophy of mount point, rather than c:, d:, and so forth. The mount point concept allows you to put your files/directory under any URL you want without changing the files on your local file system. For example, assume you have the following local file system:

Example 4.1. Your user filesystem.

/home/customers/customer1
/home/customers/customer2
/home/customers/bigcustomer3
/home/friends/franck
/home/friends/bertrand
/home/friends/didier
        

And suppose your URL is http://www.iteam.org/.

With a default configuration, you would say that http://www.iteam.org points to /home/ so that you will have customer1 under http://www.iteam.org/customers/customer1, bertrand under http://www.iteam.org/friends/bertrand and bigcustomer3 under http://www.iteam.org/customers/bigcustomer3.

But bigcustomer3 gives you a lot of money and he asks you for an URL such as http://www.iteam.org/bigcustomer3. However, he doesn't want to be moved from /home/customers/bigcustomer3 because of his FTP client's configuration. Moreover, you can't move the other accounts. With the mount point philosophy, you just have to create another mount point saying that /home/customers/bigcustomer3 is mounted on /bigcustomer3 so that when someone uses http://www.iteam.org/bigcustomer3, Caudium will serve them files from /home/customers/bigcustomer3.

Now let's return to our setup. Go into the File System module, and select NONE/ mounted on / -> Path -> Search Path. Here you will decide which of your directories will be available when someone hits the root of your server. Write, for example, /home.

You can now launch your favorite browser to the URL of your site and enjoy.

If you don't want visitors to get a listing of your files for security reasons, you can disable listing by setting Directory Settings -> Enable directory listing per default to No. Next you have to hit the More options button, and then reload the module. Don't forget to click Save. It is possible to put one of two “magic files” in any directory to make it browsable/not browsable despite the setting in the CIF. for that particular file system:

.www_browsable - the directory will always be browsable
.www_not_browsable - the directory will never be browsable
      

Finally, to allow bigcustomer3 to get to his URL, go to File System -> Copy Module. Next, go to Path -> Search Path and type /home/customers/bigcustomer3, then type /bigcustomer3 in Mount point.

The Figure 4.3, “Example of output” shows the output you should have.

Figure 4.3. Example of output

Note

If you created these files/directories after you point Caudium to your site, it is safe to go in the Actions tab, then to Cache -> Cache status -> Flush caches.

www\.virtualhost\.com	www.virtualhost.com
         

^www\.virtualhost\.com$|^virtualhost\.com$ www.virtualhost.com
        

# echo "127.0.0.1   www.virtualhost.com" >> /etc/hosts.
      

Web servers are usually publicly accessible and represent your company, group or entity so there are chances you want to strengthen the security of this service.

As I already mentioned Caudium has a good security for public access behind mostly written in a script language. However Caudium runs as root by default. In the case a non-authorized user gains access to Caudium's process, he might gain root privileges. Consequently,a lot of web servers run as another user with minimal privileges. Doing this may require some work, as you will have to change the owner of all the files Caudium needs access to, so I give step-by-step instructions how to change those permissions:

I will now speak about general security measures you can take if you are very strict about security.

First, benchmarking a web server is not an easy thing. To benchmark a web server the time it will take to give a page is not important: you don't care if a user can have his page in 0.1 ms or in 0.05 ms as nobody can have such delays on the Internet.

What is important is the average time it will take when you have a maximum number of users on your site simultaneously. Another important thing is how much more time it will take when there are 2 times more users: a server that take 2 times more for 2 times more users is better than another that take 4 times more for the same amount of users. If you run more than a web server on your computer, you will also want to look at the load average and CPU time of your system. Here is a typical output of the command uptime:

22:39:49 up 2:22, 5 users, load average: 0.01, 0.01, 0.00

And an extract from the top(1) man page:

“ The load averages are the average number of process ready to run during the last 1, 5 and 15 minutes ”

So the lower your load average is, the better for the other programs on your machine.

Now comes the next problem: how can you stress your web server with a maximum number of connections when your client (the machine making the request) will usually not be able to cope with the server and with the number of users you have.

To do this, increase the number of sockets you can have on your system. Under some systems it is 1024, which is too low, see Section 3, “How to tune your system for best Caudium performances” for more information. The next thing to do is to have a good client program written with threads and non-blocking sockets. If you use a multi-fork program on a single client, it will never cope with any web server. It is also good to have several clients stressing the server together.

Last, if you want to compare two web servers, be sure that they are on the same hardware, OS, and network. The same holds for the client(s).

Use the xdumpfont program in the tool directory of Caudium's sources. This program will convert your X fonts to Caudium fonts.

If your Pike supports TrueType Fonts, (type pike --features and check if Image.TTF is available) you can import TTF font by copying them into /usr/local/caudium/server/fonts/ttf.

See the Caudium documentation project at http://caudium.info/, and http://daviesinc.com/modules/docs/ultralog.rxml.

You can try this code. This is a basic one with only four tags/containers. You should go to http://caudium.info/ and download the Roxen 1.3 documentation.

<html>
  <comment>You have to put bgcolor for gtext to work properly</comment>
  <body bgcolor="#FFFFFF">
    <h1>Basic RXML examples</h1>
    <table border="1">
      <tr>
        <td>This is a list of all RXML tags</td>
        <td><list-tags></td>
      </tr>
    </table>
    <table border="1">
      <tr>
        <td>Gtext render text as graphic</td>
        <td><gtext scale=0.5>This is a gif/png graphic</gtext></td>
      </tr>
      <tr>
        <td>Last modification of this page</td>
        <td><modified></td>
      </tr>
    </table>
  </body>
</html>
      

For a complete tutorial and reference manual on Pike, see http://pike.oav.net/.

The Pike tag allows you to easily insert Pike code into your HTML page à la PHP. This is a good way of learning Pike if you have a PHP background or if you want to do things very easily and don't worry about perfect results.

To do this, you have to load a module in your server. Just select Load module in the CIF. and click the “Pike tag” image. Then hit save and create an .html file where your public web files are. Since everybody tells me that PHP is easy, which is why it's so popular, I took the PHP examples and converted them to Pike. Here is the result:

<html>
  <body bgcolor="#FFFFFF">
    <h2>Escaping from HTML</h2>
    <p>
      There is one way of escaping from HTML and entering "Pike code mode"
      <br />
      <Pike>
	output("This is the simplest, and SGML processing instruction");
      </Pike>
    </p>
    <h2>Instruction separation</h2>
    <p>
      Instructions are separated the same as in C or Perl: 
      terminate each statement with a semicolon. 
      The closing tag (container, in fact) also implies the end of the statement,
      so the following are equivalent:
      <br />
      <Pike>
	output ("This is a test");
      </Pike>
      <br />
      <Pike> output ("This is a test"); </Pike>
    </p>
    <h2>Comments</h2>
    <p>
      Pike supports C, C++ but not Unix shell-style comments. For example:
      <Pike>
	string tests = "This is a test<br />";  // this is a one-line C++ style comment
	/* This is a multi line comment
         yet another line of comment */
	tests += "Yet another test";
	return tests;
      </Pike>
    </p>
    <h2>Melding RXML and Pike</h2>
    You will never see this in PHP.
    [2]
    This will create a .gif image of 1-2-...-255. 
    This took 0.4s on my Duron 750 the first time and 0.1s after.
    <p>
      <gtext scale=0.5>
	<Pike>
	  string output = "";
	  for(int I = 1; I < 255; I++) 
	    output += I + "-";
	  return output;
	</Pike>
      </gtext>
    </p>
  </body>
</html>
      

The problem with using this is that you will soon see it is not powerful:

The next step is to write your first Pike script.

A Pike script is quite like a Perl script. It is executed when the user tries to access it. So a Pike script is usually where your public web files are. This is a good choice if you already have a Perl background and want to try Pike.

You have two choices when doing this. You can execute Pike as a CGI script or internally within the server. If you don't know what CGI is, look up the Apache-Overview-HOWTO at http://www.tldp.org/.

Here, we will run Pike scripts internally within Caudium. To achieve this, you have to load another module in your server by selecting Load module in the CIF.. You now have the list of all modules available in Caudium. As you see, there are a lot of modules and reading this page should give you some ideas for future development. To select the Pike script module, just click on the image named “Pike script support” if you use a graphical browser.

You can now create a .pike file containing, for example,

// you have to inherit caudiumlib to have some basic things
// like the id object and response mapping
inherit "caudiumlib";

// the same as the main
// if you modify this script and you see that Caudium don't take your
// modification into account, reload the Pike script support module
// This is because Caudium uses a cache for performance reasons
string parse(object id)
{
  string html = "<html><body>The id object contain some "
  "very useful information<br />";
  html += sprintf("The id->variables contain a list of "
  "arguments given to this script %O\n", id->variables);
  return html;
}  
      

Pike scripts are usually used for little internal development. Pike scripts can be very useful in this case because you can create something with very little lines. Here is an example of such a script:

/* Here is a Pike script (not a Caudium module).
   This script is less than 20 lines (comments
   and blank lines excluded) and will randomly
   return one file to the web browser from a list of files.
   This script was kindly provided by Xavier Beaudouin */

// first we need to inherit from caudiumlib in order to get
// the parse, http_redirect functions and id object
// recognized.
inherit "caudiumlib";

// we declare an array of files
array (string)files;

// an ASCII text containing the name of a file
// on the real filesystem.
// Each file name in this file will be
// randomly return (the files name have to be on
// a separate line).
#define FILELIST "/list"

#define BASEDIR "/thepath2yourfiles/"

// this function is the constructor, it will be loaded first
void create () {
 // the array of strings 'files' will contain
 // all the files we serve provided the file
 // FILELIST list each file name on one line.
 files = Stdio.read_bytes(FILELIST)/"\n";
}

// if no_reload return 1, Caudium will cache the
// result of this script for maximum performances
// and will not execute it a second time.
// As a result, If you give the argument 
// ?reload=1 to your script, Caudium will 
// reload it. 
// This is useful to use cache for average
// content delivery unless you are doing
// developpement
int no_reload(object id)
{
 if(!id->variables->reload)
   return 1;
 return 0;
}

// As this is a simple pike script (CGI like), this function
// will be called by Caudium and should return a string that
// will be display to the client's browser.
// It can also return a mapping containing all the HTTP response
// (headers + text)
mapping parse(object id)
{
 // We randomly return one of the file we list in the FILELIST file
 // (relative to BASEDIR directory).
 // http_redirect will send a HTTP 301 header telling the browser
 // where to get randomly selected file.
 return http_redirect(BASEDIR + files[random(sizeof(files))],id);
}
      

But you can also create some powerful scripts:

inherit "caudiumlib";

string|mapping|object parse( object id )
{
  id->my_fd->write(id->clientprot + " 200 Ok\r\n");
  id->my_fd->write("Server: Caudium !\r\n");
  id->my_fd->write("Expires: 0\r\n");
  id->my_fd->write("Content-Type: text/html\r\n");
  id->my_fd->write("pragma: no-cache\r\n\r\n");
  id->my_fd->set_id( ({ id->my_fd }) );
  id->my_fd->set_nonblocking(0,send_data);
  return http_pipe_in_progress();
}

void send_data(array (object) id)
{

  id[0]->write("<pre>");
  id[0]->write("test......................\n");
  id[0]->write("test......................\n");
  id[0]->write("test......................\n");
  id[0]->write("sleep for 10 sec\n");
  sleep(10);
  id[0]->write("Done</pre>");
  id[0]->close();
  destruct(id[0]);
}
      

This example uses non-blocking sockets. my_fd is the file descriptor of the HTTP socket. Here we change the type of the HTTP socket from blocking sockets (default type) to non-blocking sockets. Non-blocking sockets are sockets that won't block the program waiting for data. Instead, a read and write function (the so-called callback functions) will be called automatically when there is some data to read or write to the HTTP socket. Moreover, we return here a special function, http_pipe_in_progress. This is because as the HTTP socket is set to non-blocking, Caudium won't be able to wait for processing the HTTP stuff like headers and so on. So we have to tell it not to wait for us and send a http_pipe_in_progress.

This mechanism is very useful when you have to do some communication with slow sockets on a single process server (multi-threaded one). In the case of a single process, when you wait for a socket it is all the server, which will wait. So all your users will be stalled. With non blocking sockets there is no problem anymore; the server won't wait for each socket. Example of such code includes CAMAS IMAP/NNTP clients. If you don't understand, don't worry, you usually don't have to understand these mechanisms.

However, the Pike script allows you to write some complex code it is not well suited for big projects. If this is the case, read the next paragraph and enjoy.

With a custom module you can do all sorts of things:

There are different types of modules, for example:

There are other module types. For a complete reference see the Roxen 1.3 Programmer's Guide at http://caudium.info/.

For an example on how to write a container, see fnord.pike in /Caudium/sources. Because the location module is a must, here is another example:

// It is intended to show a simple example of a location module.

// This module output the result of the who(1) command. It is not meant to
// be really useful since it would be better to do a <who /> tag thus
// having data in the HTML files and code here

// This variable is shown in the configuration interface as the
// version of the module.
string CVS_version = "$Id";

// Tell Caudium that this module is 'thread safe', that is, there is no
// request-specific data in global variables.
int thread_safe=1;

#include <module.h>
inherit "module";
// for the http_string_answer API
inherit "caudiumlib"; 
 
// Documentation:
 
constant module_type = MODULE_LOCATION;
constant module_name = "Who";
constant module_doc  = "Send the result of the who(1) command ";
constant module_unique = 1;

// The constructor of this module.
// This function is called each time you/Caudium load the module
void create()
{
  defvar("location", "/who", "Mount point", TYPE_LOCATION, 
  "The mount point of this module"); 
  /* each string have to be on a single
   line, don't do: "The mount point of
   this module".
   You can however do "The mount point of "
   "this module";
   */
  defvar("path2who", "/usr/bin/who", 
  "Path to the who command", TYPE_FILE);
  defvar("options2who", "-a", 
  "Options given to who", TYPE_STRING);
  defvar("codebeforewho", "<html><body><p>", 
  "The code to output before who", TYPE_STRING);
  defvar("codeafterwho", "</p></body></html>", "The code to output after who",
  TYPE_STRING);
}

// This function is called when a user access mount point
// path is the path to the URL he used
// id contains Caudium global variables such as browser name,...
mixed find_file(string path, object id)
{
  // get the contents of the CIF. variables path2who and options2who 
  // and put a single space between it.
  string command = QUERY(path2who)+" "+QUERY(options2who);
  // this will write the result of command to the debug log file
  // very useful for debug
  write(sprintf("command=%s\n", command));
  string result = Process.popen(command);
  // replacing \n by \n<br /> for better output
  result = replace(result, "\n","\n<br />");
  return http_string_answer(QUERY(codebeforewho)+result+QUERY(codeafterwho));
}
      

Put this code in ../local/modules/who.pike relative to /usr/local/caudium/server in our example. Log into the CIF., if it is not the case and go into the main Action tab -> Cache -> Flush caches. Check the Module cache check the box and press Next, then OK.

Come back to the main Virtual servers tab and choose one of your servers. Do Add module and select the who module. If you don't have the who module, check your events log.

You don't need to compile to have a working module. You don't even need to restart the web server. When you develop a module and change the code every 30 seconds, you just have to push the Reload button to get the changes. It takes about one second and if there was a compilation error the old copy remains for users.

A backtrace is text that will show you where your program come before the error. This is very useful for developers when they debug. The best is to take an example. Did you try the who module at the end of Section 4, “Your first module”? If so take it and check it works. Now change the line string command = QUERY(path2who)+" "+QUERY(options2who); to string command = 0;. This will create an error because we put an int into a string. If we want to do that, we have to cast it (for example, use (string) 0). If you have not done it yet, press the More options button in the CIF. and reload the module. Check that the Global Variables -> show_internals option is set to yes, and try your module. You will have an error which should look like this:

Caudium version: Caudium (Caudium/1.2.0)
Requested URL: /who

Error: Sprintf: Wrong type for argument 2: expected string, got int.
../local/modules/who.pike:76: 
CaudiumModule(Who,My first virtual server)->find_file("",object)
base_server/configuration.pike (version 1.91):1587: 
Configuration(My first virtual server)->low_get_file(object,0)
base_server/configuration.pike (version 1.91):1779: 
Configuration(My first virtual server)->get_file(object,0)
base_server/configuration.pike (version 1.91):1760: 
Configuration(My first virtual server)->handle_request(object)
protocols/http.pike (version 1.71):1549: unknown function()
protocols/http.pike (version 1.71):1610: 
unknown function(0,"GET /who HTTP/1.1\r\nHost: localhost\r\nUser-Agent:
Mozilla/5.0 (X11; U; Linux i686; en-US; rv:0.9.8) 
Gecko/20020214\r\nAccept: text/xml,application/xml,
application/xhtml+xml,text/html;q=0.9,text/plain"+[246])
/usr/local/pike/7.2.262/lib/modules/Stdio.pmod/module.pmod
(version 1.114):683:
Stdio.File("socket", "127.0.0.1 1260", 777 /* fd=-1 */)
->__stdio_read_callback()
      

This seems awful but it is not. The first line is the error in itself:

"Error: Sprintf: Wrong type for argument 2: expected string, got int."
The next line "../local/modules/who.pike:76: 
CaudiumModule(Who,My first virtual server)->find_file("",object)"
is the program (../local/modules/who.pike at line 76)
      

where the error occurred. find_file is the name of the function where the error occurred and you have also the arguments given to it. If you use the source, you see mixed find_file(string path, object id). So here path="" and id=object ^[3]. Next line is the function (low_get_file in configuration.pike) that has called find_file in who.pike. You also have its arguments and so on. This backtrace is very useful when the error doesn't come directly from your code but from another code before.

With Caudium you can output something to the web page or to the debug log file located in ../logs/debug/default.*. This way the end-user will not see any line you can output in your debug log file. Sending output to the debug log file is simple, just write to stdout:

write("my message to log file\n");
      

It is also usually useful to use sprintf to format what you want to output:

int i = 2; write(sprintf("i=%d\n", i));
      

This line will output i=2, but it is better when you output array or mapping, as Pike is able to print them in a human-comprehensible format:

array a = ({ "test", "test2", 2 }); write(sprintf("a=%O\n", a));
      

Which will output:

a = ({ /* 2 elements */
    "test",
    "test2"
})
      

Caudium, and Roxen problems are not technical. Instead, they are advertising and marketing. Caudium needs to become recognized. It could the best product in the world, but if nobody knows, it will not be used. To help Caudium to become recognized for its quality there are some simple things we can do together:

If you do this, you will help promote Caudium's success. Remember, one of Caudium disadvantages is that the community is too small right now.

The next paragraph is for people who want to get involved a little more, but don't have lot of time, and/or are not technically minded.

There are two types of documentation needed for Caudium:

Unlike other projects, it's relatively not much hassle to get access to Caudium cvs tree. Even if you are a beginner you can have cvs access; we just ask you not to change Caudium's core at the beginning.

To get a CVS account, come on IRC or send a mail to kiwi at caudium dot net and explain your plan.

There is a test suite for Caudium written in Expect which uses TCL and DejaGNU. If you want to use it, fetch it from Caudium's CVS repository with the -P testsuite option (the information on this CVS repository is on http://caudium.net/.) Note that this test suite is not maintained, and needs some work.

To send a bug report, copy/paste the error from Caudium's log file (including backtrace, see Section 5, “How to use a backtrace”), your configuration, and the context in which it happened.

Go to http://caudium.net/ and choose bug tracking on the left and follow the instructions.

Here is the list of people that helped me in one way or another to get this HOWTO written:

Thanks for reading. I hope this HOWTO will help you discover Caudium's power. And remember this quotation:

If you have any questions about this documentation, contact me at <vida at caudium dot net> or the Caudium general mailing list at <general at oav dot net>