LDP
/
LDP
mirror of https://github.com/tLDP/LDP
0
1
Fork 0
Code Releases Activity
LDP/LDP/howto/docbook/Caudium-HOWTO/Caudium-HOWTO.xml

3166 lines
130 KiB
XML
Raw Blame History

<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
]>
<book id="index">
<bookinfo>
<title>Caudium HOWTO</title>
<author>
<firstname>David</firstname>
<surname>Gourdelier</surname>
<contrib>And other contributors</contrib>
<affiliation>
<orgname>Caudium Group</orgname>
<address>
<email>vida at caudium dot net</email>
</address>
</affiliation>
</author>
<copyright>
<year>2002</year>
<holder>The Caudium Group.</holder>
</copyright>
<pubdate>September 2002</pubdate>
<revhistory id="revhistory">
<revision>
<revnumber>2.2</revnumber>
<date>2002-09-20</date>
<authorinitials>dg</authorinitials>
<revremark>
Few more fixes, document now contains images and icons.
See revision history for more information.
</revremark>
</revision>
<revision>
<revnumber>2.1</revnumber>
<date>2002-06-14</date>
<authorinitials>dg</authorinitials>
<revremark>
Document is now well-formed XML, one more example.
See revision history for more information.
</revremark>
</revision>
<revision>
<revnumber>2.0</revnumber>
<date>2002-06-14</date>
<authorinitials>Tab</authorinitials>
<revremark>
Converted to DocBook XML 4.1.2.
See revision history for more information.
</revremark>
</revision>
<revision>
<revnumber>1.0</revnumber>
<date>2002-06-06</date>
<authorinitials>dg</authorinitials>
<revremark>
Initial release
</revremark>
</revision>
<revision>
<revnumber>0.91</revnumber>
<date></date>
<revremark>
Indentation of the SGML document and one more paragraph.
See revision history for more.
</revremark>
</revision>
<revision>
<revnumber>0.9</revnumber>
<date></date>
<revremark>
This Howto is going into stable state.
See the revision history for more information.
</revremark>
</revision>
<revision>
<revnumber>0.05</revnumber>
<date>2002-04-04</date>
<revremark>
This HOWTO is in the DocBook format.
See the revision history for more information.
</revremark>
</revision>
<revision>
<revnumber>0.04</revnumber>
<date></date>
<revremark>
Added Introduction and license.
See the revision history for more information.
</revremark>
</revision>
<revision>
<revnumber>0.03</revnumber>
<date></date>
<revremark>
Added some useful corrections.
See the revision history for more information.
</revremark>
</revision>
<revision>
<revnumber>0.02</revnumber>
<date></date>
<revremark>
Minor correction in other answers.
See the revision history for more information.
</revremark>
</revision>
<revision>
<revnumber>0.01</revnumber>
<date>2002-03-11</date>
<revremark>
Initial revision.
See the revision history for more information.
</revremark>
</revision>
</revhistory>
<abstract>
<para>
This is the Caudium HOWTO. This document will give an overview of the Caudium server. New users will learn how to set a basic virtual server up. More experienced users will find useful tips on development and optimization. Finally at the end I give some documentation on Caudium top priorities for people who want to contribute.
</para>
</abstract>
</bookinfo>
<toc></toc>
<chapter id="copyright">
<title>License</title>
<para>
Permission is granted to copy, distribute and/or modify this document under the terms of the <ulink url="http://www.gnu.org/copyleft/fdl.html#SEC1">GNU Free Documentation License</ulink>, Version 1.1 or any later version published as by the Free Software Foundation; with no Invariant Sections, with no Front-Cover Texts, and with no Back-Cover Texts. A copy of the license can be found in <xref linkend="gfdl" />.
</para>
<para>
This document is a volunteer effort. Feel free to improve and make
changes. If you catch any mistakes, please correct them.
</para>
</chapter>
<chapter id="Overview">
<title>Overview</title>
<sect1 id="whatiscaudium">
<title>What is Caudium?</title>
<para>
Caudium is a Web server based on a fork of the <ulink url="http://www.roxen.com/">Roxen Challenger 1.3 WebServer</ulink>. Like Roxen, Caudium is written in <ulink url="http://pike.roxen.com/">Pike</ulink> with parts written in C for performance reasons. Pike is an interpreted language developed by Frederik H&#xFC;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.
</para>
<para>
Caudium features include:
</para>
<itemizedlist>
<listitem><para>
Single-process architecture.
</para></listitem>
<listitem><para>
Optional multi-threaded mode.
</para></listitem>
<listitem><para>
Backwards compatible with Roxen 1.3 on the API and RXML level.
</para></listitem>
<listitem><para>
Runs on many Unix-like systems (GNU/Linux, FreeBSD, OpenBSD, NetBSD, Solaris, AIX, Darwin/MacOS X).
</para></listitem>
<listitem><para>
Web based interface for easy administration.
</para></listitem>
<listitem><para>
Built in SSL capabilities. Enabling SSL on Caudium is as easy as filing a web form.
</para></listitem>
<listitem><para>
Written in Pike. Unlike most web servers, you don't need to learn C or C++ and those pesky details like memory allocation to enhance the server's capabilities.
</para></listitem>
<listitem><para>
Extensible with custom modules.
</para></listitem>
<listitem><para>
Powerful API.
</para></listitem>
<listitem><para>
Lots of standard modules distributed with the server, including an FTP server, the CAMAS web mail application, and the UltraLog log analysis tool. The <quote>module</quote> directory in Caudium 1.2 with CAMAS contains 192 code-only files. Most of the modules are in a single file.
</para></listitem>
<listitem><para>
RXML language. RXML stands for Roxen eXtensible Markup Language and is a set of tags, containers and simple programming language constructs that you put in your HTML source. Those tags and containers will be interpreted at run-time by Caudium. This allows non-programmers to do development.
</para></listitem>
<listitem><para>
XML language. Using Sablotron, Caudium can render XML pages processed with XSLT, DOM and XPath. You can find more information on Sablotron on <ulink url="http://www.gingerall.com/">http://www.gingerall.com/</ulink>. It allows you to use pages designed for Apache mod_xslt in Caudium without modifications. Also the output of these generated pages can also be parsed by our RXML parser before sending the result to the client.
</para></listitem>
</itemizedlist>
</sect1>
<sect1 id="fork">
<title>Caudium vs Roxen: Why a fork?</title>
<para>
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.
</para>
</sect1>
<sect1 id="apache">
<title>Comparing Caudium with Apache</title>
<para>
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.
</para>
</sect1>
<sect1 id="advantages">
<title>Advantages of Caudium</title>
<itemizedlist>
<listitem><para>
Stable multi-threaded programming (Roxen has been multi-threaded since 1994).
</para></listitem>
<listitem><para>
Mostly written in an interpreted, object-oriented, language - Pike:
<itemizedlist>
<listitem><para>
Easy to program and extend. Just imagine if you could code extensions to the Apache core in PHP or Perl.
</para></listitem>
<listitem><para>
No buffer overflows, segmentation faults or any other problems of that nature.
</para></listitem>
<listitem><para>
RealNetworks is still using Roxen 1.3 as their main web platform for its stability and speed.
</para></listitem>
</itemizedlist>
</para></listitem>
<listitem><para>
Low level API available for end-users.
</para></listitem>
<listitem><para>
RXML tags.
</para></listitem>
<listitem><para>
Lots of modules.
</para></listitem>
<listitem><para>
Backwards compatible with Roxen 1.3.
</para></listitem>
<listitem><para>
Different. If you are a Linux or BSD user for some time you already know the most used is not always the best.
</para></listitem>
<listitem><para>
Caudium won't run under win32 (thus letting us more time for useful things). However some people are trying to port it using cygwin without code modification.
</para></listitem>
<listitem><para>
Embedded PHP4 support.
</para></listitem>
</itemizedlist>
</sect1>
<sect1 id="disadvantages">
<title>Disadvantages of Caudium</title>
<itemizedlist>
<listitem><para>
Too small of a community, and quite unknown in web server world. One example of the problem you may have is if you write Pike code for Caudium, and your hosting company doesn't support Pike, and you don't have root access to your server. Of course, it is possible to compile Pike on your account and run Caudium without the superuser privileges.
</para></listitem>
<listitem><para>
RIS (Roxen Internet Software) owns Pike, but this is likely to change in the not-so-distant future.
</para></listitem>
<listitem><para>
Needs more testing for exotic modules or modules we don't use often. Example of such modules include htaccess support.
</para></listitem>
<listitem><para>
Too little documentation. One example is the lack of documentation about FastCGI support.
</para></listitem>
<listitem><para>
CGI performance on busy CGI based sites was lackluster -- no one will take the time to rewrite CGIs. This seems to be somewhat resolved with Pike 7.2/Caudium 1.2.
</para></listitem>
<listitem>
<para>
It is sometimes impossible to get some features when you are a normal user because configuration is only accessible with the <abbrev>CIF.</abbrev> (Configuration InterFace). And the <abbrev>CIF.</abbrev> is accessible only by the admin (this is being taken care of in the development series of the server). Here is list of day to day problems submitted by Chris Davies:
</para>
<blockquote><para>
Webmasters like to use mod_rewrite in the .htaccess files to protect their sites from leeching, etc. Yes, there is referrerdeny and browserdeny, but these are accessible to the System Administrator, not the casual web user. On Apache, one can easily specify rules on a per directory basis. This isn't easy in Caudium, however, it is rare that someone would have more than two or three different conditions.
</para></blockquote>
<blockquote><para>
Now, for people that are running their own server, many of these issues disappear. Administration and adding servers is much easier. I'm not sure I agree with the templates, but perhaps an Apache Template could be tweaking beyond that to the System Administrator. In most cases, Apache has SSI turned on for shtml files -- getting the exec command enabled to mimic this in Caudium is not a task for the beginner. The maze of options to find that one setting will certainly frustrate anyone getting started.
</para></blockquote>
</listitem>
<listitem><para>
A graphical interface is not always the best. To create a virtual server with Apache, you have to copy and paste five lines. If you use the Caudium Interface it will take you more than one minute. And if you want to change Caudium text file directly, you will have to write sed script.
</para></listitem>
</itemizedlist>
</sect1>
</chapter>
<chapter id="gettingpackages">
<title>Getting packages</title>
<sect1 id="debian">
<title>How to get packages for Debian GNU/Linux</title>
<para>
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:
<programlisting><computeroutput>
deb http://grendel.firewall.com/debian/caudium/1.2 unstable main
</computeroutput></programlisting>
This location is mirrored in other locations, so you can also use:
<programlisting><computeroutput>
deb http://ftp.oav.net/caudium unstable main
deb ftp://ftp.oav.net/caudium unstable main
</computeroutput></programlisting>
</para>
<para>
If you want php4 Debian package for Caudium, you can do:
<programlisting><computeroutput>
# su -
# apt-get update
# apt-get install -f caudium caudium-modules \
caudium-ultralog caudium-pixsl caudium-dev
</computeroutput></programlisting>
And then grab the PHP4 sources:
<programlisting><computeroutput>
# exit
$ cd /usr/src; apt-get source -d php4; apt-get build-dep php4
</computeroutput></programlisting>
If you don't have devscripts and debhelper installed, install them now. Then enter the /usr/src/php-4* directory and do:
<programlisting><computeroutput>
$ debuild binary
<!-- Does this also install the binary, or just build it? If only
build, then it would be nice to add the installation instructions to
complete this section. -->
</computeroutput></programlisting>
After some time and some coffee you should have php4 packages for Apache, CGI and your fresh Caudium.
</para>
</sect1>
<sect1 id="freebsd">
<title>How to get packages for FreeBSD</title>
<para>
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.
</para>
<note>
<para>
Caudium 1.2 and Pike 7.2 are available as ports tarballs at
<ulink url="ftp://ftp.oav.net/pkg_freebsd/ports.tar.gz">ftp://ftp.oav.net/pkg_freebsd/ports.tar.gz</ulink>.
If you take the latest ports from this site use the following command:
</para>
<programlisting><computeroutput>
$ 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
</computeroutput></programlisting>
<para>
Another note, since Caudium and Pike have been added recently to FreeBSD
port tree, you must have an up to date port tree.
See the FreeBSD handbook at <ulink url="http://www.freebsd.org/handbook/cvsup.html">http://www.freebsd.org/handbook/cvsup.html</ulink>
about cvsup handling.
</para>
</note>
<para>
As root, go to <filename class="directory">/usr/ports/www/caudium10</filename> to install
current stable version, <filename class="directory">/usr/ports/www/caudium12</filename> to
install the next stable version in Release Candidate process, or
<filename class="directory">/usr/ports/www/caudium-dev</filename> 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.
</para>
<para>
Here is the current Pike / Caudium options supported by the current port :
<itemizedlist>
<listitem><para>
<constant>WITH_MOST</constant> : Install the FreeType1 and FreeType2 support.
</para></listitem>
<listitem><para>
<constant>WITH_OPTIMIZED_CFLAGS</constant> : Add some performance flags to the compiler.
</para></listitem>
<listitem><para>
<constant>WITH_TTF</constant> : Install the FreeType1 support.
</para></listitem>
<listitem><para>
<constant>WITH_FREETYPE</constant> : Install the FreeType2 support.
</para></listitem>
<listitem><para>
<constant>WITH_MYSQL</constant> : Install the MySQL support.
</para></listitem>
<listitem><para>
<constant>WITH_POSTGRES</constant> : Install the PostgreSQL support.
</para></listitem>
<listitem><para>
<constant>WITH_MSQL</constant> : Install mSQL support.
</para></listitem>
<listitem><para>
<constant>WITH_UNIXODBC</constant> : Install UnixODBC support (incompatible option with <constant>WITH_IODBC</constant>).
</para></listitem>
<listitem><para>
<constant>WITH_IODBC</constant> : Install iODBC support (incompatible option with <constant>WITH_UNIXODBC</constant>).
</para></listitem>
<listitem><para>
<constant>WITH_SANE</constant> : Install SANE backend.
</para></listitem>
<listitem><para>
<constant>WITH_PDF</constant> : Install PDF support
</para></listitem>
<listitem><para>
<constant>WITH_MESA</constant>/<constant>HAVE_MESA</constant> : Install MesaGL support.
</para></listitem>
<listitem><para>
<constant>HAVE_GNOME</constant>/<constant>WANT_GNOME</constant> : Install GNOME support.
</para></listitem>
</itemizedlist>
There are some options related only to Pike, like the GNOME / Mesa ones that are uninteresting
to Caudium, but exist for Pike support.
</para>
<para>
A little example on how to install Caudium on FreeBSD :
<programlisting><computeroutput>
# 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
#
</computeroutput></programlisting>
Now if you need to install PHP4 support for Caudium, just go to <filename class="directory">/usr/ports/www/caudium_php4</filename> and do a make install clean as well.
</para>
</sect1>
<sect1 id="solaris">
<title>How to get packages for Solaris</title>
<para>
Bill Welliver has made some packages. They are available on
<ulink url="http://hww3.riverweb.com/dist/">Riverweb</ulink> and mirrored
to <ulink url="ftp://ftp.oav.net/caudium/pkg/solaris/">Oav.net</ulink>.
</para>
</sect1>
<sect1 id="camassrc">
<title>How to get CAMAS from CVS/source</title>
<para>
To get CAMAS from the CVS, go to the <ulink url="http://camas.caudium.net/">CAMAS web site</ulink> and follow the link.
</para>
</sect1>
</chapter>
<chapter id="creating">
<title>Creating your first server</title>
<sect1 id="installing">
<title>Installing Caudium from sources</title>
<para>
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.
</para>
<note><para>
To take a CVS source snapshot of Pike 7.2+, you will need to have a preinstalled Pike (any version) on your system in order to compile the fresh CVS checkout. This is because the CVS sources need to pre-process certain parts of the sources with some special Pike scripts. Downloading a tarball from the RIS site (always outdated) will free you from the requirement of having the Pike installed before compiling the CVS snapshot.
</para></note>
<para>
For more information, see the quick start guide at <ulink url="http://caudium.net/">http://caudium.net/</ulink>.
</para>
</sect1>
<sect1 id="starting">
<title>Starting</title>
<para>
The first time you install Caudium from the sources, you will need to type the following commands:
</para>
<programlisting><computeroutput>
# su -
# cd /usr/local/caudium
# ./install
</computeroutput></programlisting>
<para>
This script will allow you to give login information for the Configuration InterFace (<abbrev>CIF.</abbrev>), the web based configuration interface, and the port address for the <abbrev>CIF.</abbrev>. But if you want to start Caudium manually, you don't need to use install, just use the <command>start</command> script. This script will fork Caudium once and restart it automatically if it dies. A consequence is that if you kill <command>start</command>, the server will always be running but it will not restart if it dies.
</para>
<para>
There are many useful options to <command>start</command>. The first is <option>--help</option>. Here is a non-exhaustive list of options:
</para>
<itemizedlist>
<listitem><para>
<option>--once</option>: Do not fork Caudium and output debug to stdout (screen). If you hit <keycombo action="press"><keycap>CTRL</keycap><keycap>C</keycap></keycombo>, Caudium will be killed
</para></listitem>
<listitem><para>
<option>-t</option>: Display all Pike calls
</para></listitem>
<listitem><para>
<option>--gdb</option>: Run Caudium inside gdb, useful only for developers.
</para></listitem>
<listitem><para>
<option>--with-threads</option>: Run Caudium with threads (run better on *BSD and Solaris)
</para></listitem>
<listitem><para>
<option>--without-threads</option>: The opposite of <option>--with-threads</option>. It doesn't mean that the Pike scripts/modules aren't able to use threads. It merely means that the Caudium core server will not use threaded handler backend.
</para></listitem>
<listitem><para>
<option>--with-keep-alive</option>: Enable keep-alive in HTTP. In the
old days of the web, the HTTP protocol was simple but not efficient:
one connection was made for each objects requested by a client. That
means a web browser made 20 connections to the webserver if there was
19 images on a webpage and the HTML page itself. This result in
a lot of overhead and response time delay. With keep alive, the server
don't close the connection for each objects so the browser can request
several objects with one HTTP connection and does not need to
reconnect each time. As a result, the website seems to be faster for
the client and the webserver can handle more users.
<note><para>
Currently, the keep-alive option doesn't work with CAMAS (I use CAMAS-1.1.7-DEV, Caudium 1.2RC1). Generally speaking, it is also not ready for production use. Here is a comment from Xavier Beaudouin: <blockquote><para>keep-alive is somewhat buggy on Caudium. My test shows that high number of connections on keep-alived Caudium show some random dropped returns. I do not recommend using keep-alive. If you'd like keep-alive a "black box" like redline seems the best solution... but expensive.</para></blockquote>
</para></note>
</para></listitem>
<listitem><para>
<option>--config-dir=DIR</option>: Allows you to specify where your configuration
files are, where <quote>DIR</quote> is the name of the directory holding the configuration
files (typically <computeroutput>/usr/local/caudium/configurations/</computeroutput>).
This is a very useful option. For example you can start several Caudium instances
with different configurations by using different configuration
directories. This is also useful if you put the configuration files in a non-standard
directory:
<computeroutput>
/usr/local/caudium/server/start --config-dir=/home/david/etc/my_caudium_configuration/
</computeroutput>
For Apache users, this is the equivalent of the <option>-f</option> option but points to
the directory that contains the files.
</para></listitem>
</itemizedlist>
<para>
Finally, the most important thing is debug log files. These files are stored in <filename class="directory">../logs/debug</filename> (relative to <filename class="directory">/usr/local/caudium/server</filename> in our example). The current log file is named <filename>default.1</filename>. The log file from the last Caudium start is <filename>default.2</filename> and so on. If you didn't enable debug, these files are always used but contain very few messages.
</para>
<note><para>
The location of files may be different on your system if you are
using a prepackaged version of the software.
</para></note>
</sect1>
<sect1 id="stopping">
<title>Stopping from command line</title>
<para>
There are two ways to stop Caudium:
<itemizedlist>
<listitem><para>
Kill Caudium with a <option>-9</option> signal. If you do this Caudium will restart. Actually it will be restarted by the start script.
</para></listitem>
<listitem><para>
Kill Caudium (with kill(1)'s default TERM signal) . In this case, Caudium will stop cleanly. If you use Caudium 1.2 and later, you can use the <command>caudiumctl</command> command. A man page for <command>caudiumctl</command> should be available on your system.
</para></listitem>
</itemizedlist>
<note><para>In both cases Caudium will stop only after a few moments.</para></note>
</para>
<para>
On Debian GNU/Linux, you can use the following commands to manipulate the server status:
</para>
<programlisting><computeroutput>
# /etc/init.d/caudium stop
# /etc/init.d/caudium start
# /etc/init.d/caudium restart
</computeroutput></programlisting>
</sect1>
<sect1 id="directory">
<title>Directory organization</title>
<itemizedlist>
<listitem>
<para>
configurations:
</para>
<para>
Contains the config files used by the <abbrev>CIF.</abbrev>. These files use the XML syntax. You don't have to modify them by hand. If for some reason you do, make sure to do it when Caudium is stopped because they will get overwritten with the server's current configuration when the server is stopped. An alternate method is to edit the file, then send the HUP signal to the Caudium process. Another method is to use the <abbrev>CIF.</abbrev>: Go into <option>Action</option> -&gt; <option>Maintenance</option> -&gt; <option>Reload configurations from disk</option>. This will cause Caudium to reload its configuration from disk. As you may have guessed, each file has the name of the corresponding virtual server. One file however has a special name - <filename>Global_Variables</filename>. This file contains information about Caudium's global variables (See the Global Variables tab in the <abbrev>CIF.</abbrev>).
</para>
</listitem>
<listitem>
<para>
logs:
</para>
<para>
Contains useful information such as debug log, virtual server logs, start/stop status. See also <xref linkend="starting" />.
</para>
</listitem>
<listitem>
<para>
readme:
</para>
<para>
It's all in the name.
</para>
</listitem>
<listitem>
<para>
server:
</para>
<para>
This directory contains the actual server.
</para>
<itemizedlist>
<listitem>
<para>
base_server:
</para>
<para>
Contains the server core Pike code: API, <abbrev>CIF.</abbrev>, etc. Newbies should not modify these files.
</para>
</listitem>
<listitem>
<para>
bin:
</para>
<para>
First binary code that is run when you use the start script. There are also some Pike scripts running as CGIs and without Caudium API.
</para>
</listitem>
<listitem>
<para>
caudium-images:
</para>
<para>
This directory contains Caudium static images from the Caudium Group, such as the <quote>powered by</quote> series.
</para>
</listitem>
<listitem>
<para>
config_actions:
</para>
<para>
These are files used in the <option>Action</option> tab on the <abbrev>CIF.</abbrev>. You may use some of these functions in your code.
</para>
</listitem>
<listitem>
<para>
etc:
</para>
<para>
Caudium includes files used by the Caudium core and its modules. For example, it contains .html files for error messages. Two directories are important for a module developer:
</para>
<itemizedlist>
<listitem>
<para>
include:
</para>
<para>
Put your .h files here.
</para>
</listitem>
<listitem>
<para>
module:
</para>
<para>
Put your module files here (.pmod). Pike module files are used to provide two-level functions/class/methods for your modules. When you modify any of these files, you must restart the server.
</para>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para>
fonts:
</para>
<para>
Contains some compatibility fonts with some older versions. The new directory is nfonts.
</para>
</listitem>
<listitem>
<para>
languages:
</para>
<para>
Some basic language translations for time/date.
</para>
</listitem>
<listitem>
<para>
lib:
</para>
<para>
Some of the C code used to speed Caudium up. This code is a set of dynamic libraries (.so).
</para>
</listitem>
<listitem>
<para>
modules:
</para>
<para>
Contains Caudium modules. These are all the modules you see when you click <command>Add Module</command> after you have selected one of your servers in the <abbrev>CIF.</abbrev>. Browsing this directory will be useful to understand Caudium.
<itemizedlist>
<listitem>
<para>
3rdparty:
</para>
<para>
This special directory contains third party modules for Caudium. These may be useful but are provided without any warranty and will not be maintained by the Caudium Group but they may be by the individuals who wrote them.
</para>
</listitem>
</itemizedlist>
</para>
</listitem>
<listitem>
<para>
more_modules:
</para>
<para>
Some modules that meet a specific need, are not up-to-date, or are humorous.
</para>
</listitem>
<listitem>
<para>
nfonts:
</para>
<para>
Fonts for graphical things like &lt;gtext&gt; and &lt;gbutton&gt;.
You can have several types of properties like bold or italic for the same font name.
</para>
</listitem>
<listitem>
<para>
Perl:
</para>
<para>
Needed to run Perl scripts within Caudium. At the time of writing this document, Perl support is broken, and we will be pleased to get help on this issue.
</para>
</listitem>
<listitem>
<para>
protocols:
</para>
<para>
Contains protocol modules (for handling HTTP, FTP and the like).
</para>
</listitem>
<listitem>
<para>
server_templates:
</para>
<para>
The templates you can choose from when you create a new a virtual server.
</para>
</listitem>
<listitem>
<para>
unfinished_modules:
</para>
<para>
For modules in development.
</para>
</listitem>
</itemizedlist>
</listitem>
</itemizedlist>
<para>
You can also see <filename>readme/README</filename> relative to <filename class="directory">/usr/local/caudium</filename> in our example.
</para>
</sect1>
<sect1 id="upgrade">
<title>Upgrading Caudium</title>
<para>
Upgrading Caudium is simple. You should install it as if for the first time. That is, get the new sources, unpack them, run <computeroutput>./configure; make; make install</computeroutput> 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.
</para>
<para>
If you use a package system, just use the upgrading features of your packaging system.
</para>
</sect1>
<sect1 id="cifconf">
<title>Configuration InterFace (<abbrev>CIF.</abbrev>)</title>
<para>
The <abbrev>CIF.</abbrev> is where the administrator manages the server. When you first login it looks like this.
</para>
<mediaobject>
<imageobject>
<imagedata fileref="images/cif_1stpage.png" format="PNG" />
</imageobject>
<imageobject>
<imagedata fileref="images/cif_1stpage.png" format="EPS" />
</imageobject>
<textobject>
<phrase>The first page on the CIF</phrase>
</textobject>
<caption>
<para>The first page you will see when you login on the CIF.</para>
</caption>
</mediaobject>
<para>
In the CIF, you'll find four tabs:
</para>
<orderedlist>
<listitem>
<para>
<guimenu>
<inlinemediaobject>
<imageobject>
<imagedata fileref="images/virtual_servers.png" format="PNG" />
</imageobject>
<imageobject>
<imagedata fileref="images/virtual_servers.png" format="EPS" />
</imageobject>
<textobject>
<phrase>Virtual Servers</phrase>
</textobject>
</inlinemediaobject>
</guimenu>
</para>
<para>
The server(s) you have created in this Caudium installation. This is where you will tune each server configuration.
</para>
</listitem>
<listitem>
<para>
<guimenu>
<inlinemediaobject>
<imageobject>
<imagedata fileref="images/global_variables.png" format="PNG" />
</imageobject>
<imageobject>
<imagedata fileref="images/global_variables.png" format="EPS" />
</imageobject>
<textobject>
<phrase>Global Variables</phrase>
</textobject>
</inlinemediaobject>
</guimenu>
</para>
<para>
The configuration variables that affect Caudium as a whole, including all virtual servers.
</para>
</listitem>
<listitem>
<para>
<guimenu>
<inlinemediaobject>
<imageobject>
<imagedata fileref="images/event_log.png" format="PNG" />
</imageobject>
<imageobject>
<imagedata fileref="images/event_log.png" format="EPS" />
</imageobject>
<textobject>
<phrase>Event Log</phrase>
</textobject>
</inlinemediaobject>
</guimenu>
</para>
<para>
The log file output as a nice looking log. Note however, that neither errors nor startup events are displayed in the event log. This means developers should always look in the plain log file.
</para>
</listitem>
<listitem>
<para>
<guimenu>
<inlinemediaobject>
<imageobject>
<imagedata fileref="images/actions.png" format="PNG" />
</imageobject>
<imageobject>
<imagedata fileref="images/actions.png" format="EPS" />
</imageobject>
<textobject>
<phrase>Actions</phrase>
</textobject>
</inlinemediaobject>
</guimenu>
</para>
<para>
Some actions you may take on you servers such as shutting down Caudium or generating an SSL certificate. This allows you to avoid some of the command line stuff.
</para>
</listitem>
</orderedlist>
<para>
As the <abbrev>CIF.</abbrev> 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
<guibutton>
<inlinemediaobject>
<imageobject>
<imagedata fileref="images/more_options.png" format="PNG" />
</imageobject>
<imageobject>
<imagedata fileref="images/more_options.png" format="EPS" />
</imageobject>
<textobject>
<phrase>more options</phrase>
</textobject>
</inlinemediaobject>
</guibutton> 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.
</para>
<para>
One of these controls is the
<guibutton>
<inlinemediaobject>
<imageobject>
<imagedata fileref="images/reload_module.png" format="PNG" />
</imageobject>
<imageobject>
<imagedata fileref="images/reload_module.png" format="EPS" />
</imageobject>
<textobject>
<phrase>reload module</phrase>
</textobject>
</inlinemediaobject>
</guibutton> 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.
</para>
</sect1>
<sect1 id="adding">
<title>Adding your first server</title>
<para>
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 <abbrev>CIF.</abbrev> login/password.
</para>
<note><para>
A virtual server allows you to have several servers running on
the same port. For example you can have www.foo.com and www.foo.org running
on the same port and machine. This is why it is called virtual server.
</para></note>
<para>
To create your first server, log into the web based <abbrev>CIF.</abbrev>. Click on the
<guimenu>Virtual Servers</guimenu> tab, then the
<guibutton>
<inlinemediaobject>
<imageobject>
<imagedata fileref="images/new_virtual_server.png" format="PNG" />
</imageobject>
<imageobject>
<imagedata fileref="images/new_virtual_server.png" format="EPS" />
</imageobject>
<textobject>
<phrase>new virtual server</phrase>
</textobject>
</inlinemediaobject>
</guibutton> button.
</para>
<para>
Here, you are prompted for the server name:
<mediaobject>
<imageobject>
<imagedata fileref="images/cif_newserver.png" format="PNG" />
</imageobject>
<imageobject>
<imagedata fileref="images/cif_newserver.png" format="EPS" />
</imageobject>
</mediaobject>
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 <option>Basic server</option>, and
click <guibutton>OK</guibutton>.
</para>
<sect2 id="servervariables">
<title>Server variables</title>
<para>
Now you'll see the Virtual Servers page again. As you can see, you have two
different folders to work on: <guisubmenu>Server variables</guisubmenu> (<xref linkend="cif_ports" />) and <guisubmenu>File system</guisubmenu> (<xref linkend="cif_filesystem" />).
<figure id="cif_ports">
<title>Ports in the CIF</title>
<mediaobject>
<imageobject>
<imagedata fileref="images/cif_ports.png" format="PNG" />
</imageobject>
<imageobject>
<imagedata fileref="images/cif_ports.png" format="EPS" />
</imageobject>
</mediaobject>
</figure>
<figure id="cif_filesystem">
<title>Filesystem in the CIF</title>
<mediaobject>
<imageobject>
<imagedata fileref="images/cif_filesystem.png" format="PNG" />
</imageobject>
<imageobject>
<imagedata fileref="images/cif_filesystem.png" format="EPS" />
</imageobject>
</mediaobject>
</figure>
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.
</para>
<para>
In server variables, go into <guisubmenu>Listen ports</guisubmenu> and choose <guibutton>Configure a new
port</guibutton>. Use the default values, choose <guibutton>Use these values</guibutton>, and click
<guibutton>
<inlinemediaobject>
<imageobject>
<imagedata fileref="images/save.png" format="PNG" />
</imageobject>
<imageobject>
<imagedata fileref="images/save.png" format="EPS" />
</imageobject>
<textobject>
<phrase>save</phrase>
</textobject>
</inlinemediaobject>
</guibutton>. Now select the URL of your site, and select <guibutton>Continue</guibutton>. 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.
</para>
<para>
Under your server name, you'll see the status of your server. If it
contains the word <quote>Open</quote> in blue everything is okay, and you can continue
with configuring the file system.
</para>
<para>
If it contains the words <quote>Not open</quote> in red, there is a problem. You can go
into the Event Log via the <abbrev>CIF.</abbrev> tab to investigate. If you have an error <guiicon>
<inlinemediaobject>
<imageobject>
<imagedata fileref="images/err_3.png" format="PNG" />
</imageobject>
<imageobject>
<imagedata fileref="images/err_3.png" format="EPS" />
</imageobject>
<textobject>
<phrase>error icon</phrase>
</textobject>
</inlinemediaobject>
</guiicon>
<errorname>Failed to open socket on 0:80 (already bound ?)</errorname>, 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
<footnote>
<para>
To identify you can use lsof(8). If you want to know which programs
listen on port 80 just issue the following command as root<note><para>You need to be root if lsof has been compiled with the HASSECURITY option which is the default for some GNU/Linux distributions</para></note>:
</para>
<programlisting><computeroutput>
# lsof -i TCP:80
</computeroutput></programlisting>
<para>
Here is the result:
</para>
<programlisting><computeroutput>
COMMAND PID USER FD TYPE DEVICE SIZE NODE NAME
caudium 1001 root 12u IPv4 3993 TCP *:www (LISTEN)
</computeroutput></programlisting>
</footnote>.
To restart Caudium, go into <menuchoice><guimenu>Action</guimenu><guisubmenu>Shutdown</guisubmenu><guisubmenu>Shutdown Caudium</guisubmenu><guimenuitem>Restart Caudium</guimenuitem></menuchoice>. Wait a few seconds, and when prompted, select <guimenu>Virtual Servers</guimenu>. Now select your
server, and you should have the word <quote>Open</quote> in blue.
</para>
<note>
<title>In the <abbrev>CIF.</abbrev> you may wonder what are those two different protocols http and http2?</title>
<para>
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.
</para>
</note>
</sect2>
<sect2 id="selectingfs">
<title>Selecting file system</title>
<para>
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.
</para>
<para>
Caudium file systems use the Unix philosophy of mount point, rather than
<constant>c:</constant>, <constant>d:</constant>, 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:
</para>
<example>
<title>Your user filesystem.</title>
<programlisting><computeroutput>
/home/customers/customer1
/home/customers/customer2
/home/customers/bigcustomer3
/home/friends/franck
/home/friends/bertrand
/home/friends/didier
</computeroutput></programlisting>
</example>
<para>
And suppose your URL is http://www.iteam.org/.
</para>
<para>
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.
</para>
<para>
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.
</para>
<para>
Now let's return to our setup. Go into the <option>File System</option> module, and select
<option>NONE/ mounted on /</option> -&gt; <option>Path</option> -&gt; <option>Search Path</option>.
Here you will decide which of
your directories will be available when someone hits the root of your
server. Write, for example, <userinput>/home</userinput>.
</para>
<para>
You can now launch your favorite browser to the URL of your site and
enjoy.
</para>
<para>
If you don't want visitors to get a listing of your files for
security reasons, you can disable listing by setting <option>Directory Settings</option> -&gt;
<option>Enable directory listing per default</option> to <option>No</option>. Next you have to hit the
<option>More options</option> button, and then reload the module. Don't forget to click
<option>Save</option>. It is possible to put one of two <quote>magic files</quote> in any directory to
make it browsable/not browsable despite the setting in the <abbrev>CIF.</abbrev> for that particular file system:
</para>
<programlisting><computeroutput>
.www_browsable - the directory will always be browsable
.www_not_browsable - the directory will never be browsable
</computeroutput></programlisting>
<para>
Finally, to allow bigcustomer3 to get to his URL, go to <option>File System</option> -&gt; <option>Copy
Module</option>. Next, go to <option>Path</option> -&gt; <option>Search Path</option> and type
<userinput>/home/customers/bigcustomer3</userinput>, then type <userinput>/bigcustomer3</userinput> in
<option>Mount point</option>.
</para>
<para>
The <xref linkend="cif_filesystem_example" /> shows the output you
should have.
<figure id="cif_filesystem_example">
<title>Example of output</title>
<mediaobject>
<imageobject>
<imagedata fileref="images/cif_filesystem_example.png" format="PNG" />
</imageobject>
<imageobject>
<imagedata fileref="images/cif_filesystem_example.png" format="EPS" />
</imageobject>
</mediaobject>
</figure>
</para>
<note>
<para>
If you created these files/directories after you point Caudium to
your site, it is safe to go in the <option>Actions</option> tab, then to <option>Cache</option> -&gt;
<option>Cache status</option> -&gt; <option>Flush caches</option>.
</para>
</note>
</sect2>
<sect2 id="creatingavs">
<title>Creating a virtual server</title>
<para>
A web server is usually running on a single port and on a single IP
address. So how can someone have different sites on this single port and
single IP? The solution is to tell Caudium that the server is different
based on the URL. This is the task of the Virtual Hosting module. As this
module is not present in the Generic template we use, you will have to add
it. Just use the <option>Add module</option> button, and click the image named <quote>Virtual
Host Matcher</quote>.
</para>
<para>
You are now able to do redirection with the help of regular expressions. If
you don't know what regular expressions (<quote>regexp</quote> for short) are, check the
man page for regexp, see Pike/Perl manual, or maybe buy a book on regular
expressions. To write these redirections based on the URL, go into <option>Regular
expression rewrite rules</option> and add the following rule:
</para>
<example>
<title>A simple virtual hosting regular expression.</title>
<programlisting><computeroutput>
www\.virtualhost\.com www.virtualhost.com
</computeroutput></programlisting>
</example>
<example>
<title>A better and quicker regular expression.</title>
<programlisting><computeroutput>
^www\.virtualhost\.com$|^virtualhost\.com$ www.virtualhost.com
</computeroutput></programlisting>
</example>
<para>
Save and type this command on your command line in order to get your
browser resolving www.virtualhost.com:
</para>
<programlisting><computeroutput>
# echo "127.0.0.1 www.virtualhost.com" >> /etc/hosts.
</computeroutput></programlisting>
<para>
You now have to add another virtual server with the button <option>New Virtual
Server</option> at the root of the virtual server tab. Put <userinput>Virtual host</userinput> as the
server name and choose the <option>Generic server</option> configuration type. Go into
<option>Server variables</option> -&gt; <option>Server URL</option> and type <userinput>http://www.virtualhost.com/</userinput>. You should see:
</para>
<para>
This server is handled by the port in my first virtual server. Server URL:
http://www.virtualhost.com/
</para>
<para>
Change the file system root and /tmp in <option>File system</option> -&gt; <option>NONE/ mounted on /</option>
-&gt; <option>Paths</option> -&gt; <option>Search path</option>.
</para>
<para>
You can now point your favorite browser to http://localhost/ and
http://www.virtualhost.com/ and see the result.
</para>
<para>
If you have an error telling you www.virtualhost.com is unknown check your host file.
</para>
<para>
For more information about virtual hosting, see the Virtual-Web Mini-HOWTO
available at the <ulink url="http://www.tldp.org/">LDP</ulink> or in
<computeroutput>/usr/share/doc/HOWTO</computeroutput> or
<computeroutput>/usr/doc/HOWTO</computeroutput> under Debian GNU/Linux.
</para>
</sect2>
</sect1>
</chapter>
<chapter id="customizing">
<title>Customizing your server</title>
<sect1 id="secure">
<title>How to run Caudium as a non-privileged user; How to secure Caudium</title>
<para>
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.
</para>
<para>
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:
</para>
<orderedlist numeration="arabic">
<listitem>
<para>
Find a good user name. This user name should be a normal user with the least privileges. Lots of distributions already have a special account for this. Common names include <quote>www</quote>, <quote>www-data</quote>, <quote>httpd</quote>, <quote>nobody</quote> (Caudium on Debian GNU/Linux runs as www-data:www-data by default). We don't recommend <quote>nobody</quote> though; to quote Theo de Raadt: <blockquote><para>The user <quote>nobody</quote> has historically been doing too much. If you could break into the user <quote>nobody</quote>, you could cause great damage.</para></blockquote>
</para>
</listitem>
<listitem>
<para>
Change the owner of the files which Caudium needs to write to. These include:
</para>
<itemizedlist>
<listitem>
<para>
Caudium internal log file (default.*).
</para>
</listitem>
<listitem>
<para>
Per virtual server log file.
</para>
</listitem>
<listitem>
<para>
All caches.
</para>
</listitem>
<listitem>
<para>
The configurations files (they are written by the <abbrev>CIF.</abbrev>).
</para>
</listitem>
</itemizedlist>
<para>
On a Caudium source install the following command should do the job:
</para>
<programlisting><computeroutput>
# chown -R www-data.www-data logs/ var/
argument_cache/ bgcache/ configurations/ server/*.pem server
</computeroutput></programlisting>
<para>
Here is the result:
</para>
<programlisting><computeroutput>
$ ls -l
total 32
drwxr-sr-x 6 www-data www-data 4096 Feb 13 23:17 argument_cache
drwxr-sr-x 2 www-data www-data 4096 Feb 19 09:27 bgcache
drwxr-sr-x 2 www-data www-data 4096 Mar 4 22:28 configurations
drwxr-sr-x 4 root staff 4096 Feb 13 23:16 local
drwxr-sr-x 7 www-data www-data 4096 Mar 3 11:50 logs
drwxr-sr-x 2 root staff 4096 Feb 13 23:16 readme
drwxr-sr-x 19 www-data www-data 4096 Feb 19 20:13 server
drwxr-sr-x 2 www-data www-data 4096 Mar 3 19:28 var
$ id www-data
uid=33(www-data) gid=33(www-data) groups=33(www-data)
</computeroutput></programlisting>
<para>
If users are allowed to log on the server, you might also change the
permissions of the logs directory.
</para>
<para>
If you have a Caudium specific distribution for your system (such as Debian GNU/Linux) check manually.
</para>
</listitem>
<listitem>
<para>
Don't forget to change the permissions of any script/directory you made
and for which Caudium needs to write to in your public filesystem.
</para>
</listitem>
<listitem>
<para>
Log into the <abbrev>CIF.</abbrev>, go in the main <option>Global variables</option> tab, then in
<option>Change uid and gid</option> type the uid:gid data you choose. We typed <userinput>33:33</userinput>
in our example. You can also type a login name and group name: <userinput>www-data:www-data</userinput>.
You can also enable the <option>Change uid and gid permanently</option> option but be sure to read the documentation first.</para>
</listitem>
</orderedlist>
<para>
I will now speak about general security measures you can take if you are
very strict about security.
</para>
<orderedlist numeration="arabic">
<listitem>
<para>
Don't allow users to execute scripts that are part of the server.
</para><para>
As Caudium is a single process server, it is possible to stop it, restart
it, access it, etc. with a user script. This include pike scripts, pike tag,
and PHP modules for Caudium.
</para>
<para>
If you do want to let your users run scripts, you can always use
CGI, or better uniscript (in this case it will be transparent to the user), in
order to run a script in a separate process using the fork(2) system call.
This will decrease the performance of Caudium but the security has a price,
and it is up to you to decide how much you want to pay.
</para>
<note><para>Uniscript is a CGI-like wrapper. It will execute programs
as if they were CGI scripts but unlike CGI, it does not require you
to put these programs under a specific directory like /cgi-bin/. For
example each user can have his or her CGI script in his or her directory.
Moreover Caudium can execute them with the uid of the owner.
</para></note>
</listitem>
<listitem>
<para>
Don't use anything you don't need. Remove any modules you don't need in your virtual server.
</para>
</listitem>
<listitem>
<para>
Physically restrict access to the <abbrev>CIF.</abbrev>. Don't access it from the Internet if
possible. Few people know this, but it is now possible to see SSL
connections in clear text with a man-in-the-middle attack.
The <application>dsniff</application> software contains all the tools and explanation for this.
</para>
</listitem>
<listitem>
<para>
Turn off these options:
</para>
<itemizedlist>
<listitem>
<para>
<option>Global Variables</option> -&gt; <option>show_internals</option>.
</para>
</listitem>
<listitem>
<para>
<option>Global Variables</option> -&gt; <option>Version numbers</option> -&gt; <option>Show Caudium Version Number</option>.
</para>
</listitem>
<listitem>
<para>
<option>Global Variables</option> -&gt; <option>Version numbers</option> -&gt; <option>Show Pike Version Number</option>.
</para>
</listitem>
</itemizedlist>
<para>
Turn off any debug options specific to a module. These
options are for developers, and they don't have security in
mind when they debug output.
<blockquote><attribution>Grendel</attribution>
<para>
Actually, this is security through obscurity and doesn't
increase the security of the server.
</para>
</blockquote>
</para>
</listitem>
<listitem>
<para>
Output Caudium's log files to a separate partition. <filename class="directory">/var</filename> is a good choice for
that purpose.
</para>
</listitem>
<listitem>
<para>
Check the Caudium web site for patches.
</para>
</listitem>
<listitem>
<para>
If your job relies on your web server security, check the Caudium source.
</para>
</listitem>
</orderedlist>
</sect1>
<sect1 id="benchmark">
<title>How to benchmark a web server</title>
<para>
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.
</para>
<para>
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 <command>uptime</command>:
</para>
<para>
<computeroutput>
22:39:49 up 2:22, 5 users, load average: 0.01, 0.01, 0.00
</computeroutput>
</para>
<para>
And an extract from the top(1) man page:
</para>
<para>
<quote>
The load averages are the average number of process ready to run during
the last 1, 5 and 15 minutes
</quote>
</para>
<para>
So the lower your load average is, the better for the other
programs on your machine.
</para>
<para>
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.
</para>
<para>
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
<xref linkend="tune" /> 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.
</para>
<para>
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).
</para>
</sect1>
<sect1 id="tune">
<title>How to tune your system for best Caudium performances</title>
<sect2 id="linuxtune">
<title>Linux</title>
<para>
Until a Linux guru has time to make some nice documentation, here is
something that came from PureFtpd software :
</para>
<para>
<programlisting><computeroutput>
o Increase your system max descriptors numbers :
# echo 60000 > /proc/sys/fs/file-max
# echo 180000 > /proc/sys/fs/inode-max
# ulimit -n 60000
o mount your filesystems with the "noatime" option
o make sure your disks holding the logs are "fast enough"
o You can tweak a bit your TCP/IP stack :
# echo 0 > /proc/sys/net/ipv4/tcp_syncookies
# echo 0 > /proc/sys/net/ipv4/tcp_ecn
# echo 0 > /proc/sys/net/ipv4/tcp_timestamps
# echo 0 > /proc/sys/net/ipv4/tcp_window_scaling
</computeroutput></programlisting>
</para>
<para>
Finally don't forget to compile Pike with <option>--with-max-fd=60000</option> (already done in Debian packages).
</para>
<warning>
<title>Warning from Caudium people</title>
<itemizedlist>
<listitem>
<para>Personally deactivate window scaling seems to be a bad idea.</para>
</listitem>
<listitem>
<para>This needs some touches. 2.2 and 2.4 options are mixed above very badly. Also, turning off ECN might do you more harm than gain.</para>
</listitem>
</itemizedlist>
</warning>
<para>
Also see <ulink url="http://linuxperf.nl.linux.org/">LinuxPerf</ulink>, and <ulink url="http://linuxperf.nl.linux.org/general/kerneltuning.html">LinuxPerf kernel tuning section</ulink>.
</para>
</sect2>
<sect2 id="freebsdtune">
<title>FreeBSD</title>
<para>
Here are the optimizations you can try on your servers. They are provided without any warranty.
</para>
<note>
<para>All this is for FreeBSD 4.2 or more recent.</para>
</note>
<para>
First, check to see if your filesystems use <option>Soft Updates</option>:
<programlisting><computeroutput>
# tunefs -p /dev/da0s1a
tunefs: soft updates: (-n) disabled
tunefs: maximum contiguous block count: (-a) 15
tunefs: rotational delay between contiguous blocks: (-d) 0 ms
tunefs: maximum blocks per file in a cylinder group: (-e) 2048
tunefs: average file size: (-f) 16384
tunefs: average number of files in a directory: (-s) 64
tunefs: minimum percentage of free space: (-m) 8%
tunefs: optimization preference: (-o) time
</computeroutput></programlisting>
If <option>soft updates</option> are set to <option>disabled</option> it may be a good idea to enable them.
We do not recommend you enable them on "/" filesystem on servers machines, there are issues and in general this is not recommended by the FreeBSD team.
If you can unmount the others filesystems do this and remount them later:
<programlisting><computeroutput>
# tunefs -n enable /dev/"whatever"
</computeroutput></programlisting>
If you cannot unmount the others filesystem, drop into single mode (do a <command>shutdown now</command> or a <command>boot -s</command>) and then type:
<programlisting><computeroutput>
# tunefs -n enable "filesystem"
</computeroutput></programlisting>
I suggest /usr or /var.
In the fstab you can add <userinput>,async</userinput> to the options of all filesystems. As for soft updates we do not recommend that on server machines for the root (/) filesystem.
</para>
<para>
In <filename>/boot/loader.conf</filename> add the following:
<programlisting><computeroutput>
kern.ipc.maxsockets="5000"
kern.ipc.nmbclusters="65536"
</computeroutput></programlisting>
If you have ATA (IDE / UltraDMA) disks you can add also in <filename>/boot/loader.conf</filename>:
<programlisting><computeroutput>
hw.ata.wc="1"
</computeroutput></programlisting>
Then in <filename>/etc/sysctl.conf</filename> you can add:
<programlisting><computeroutput>
vfs.vmiodirenable=1
kern.ipc.maxsockbuf=2097152
kern.ipc.somaxconn=8192
kern.ipc.maxsockets=16424
kern.maxfiles=65536
kern.maxfilesperproc=32768
net.inet.tcp.rfc1323=1
net.inet.tcp.delayed_ack=0
net.inet.tcp.sendspace=65535
net.inet.tcp.recvspace=65535
net.inet.udp.recvspace=65535
net.inet.udp.maxdgram=57344
net.local.stream.recvspace=65535
net.local.stream.sendspace=65535
</computeroutput></programlisting>
And then reboot (or for <filename>/etc/sysctl.conf</filename> use the sysctl(8) tool to setup this by hand.
</para>
<para>
Another way to have good performance is to make a custom kernel, with the minimum of drivers and processor support. A maxuser size = size of memory (for example you have 512M of RAM, then set the maxusers value in your kernel configuration variable to 512).
Add Posix 1003.1b real time extensions to the kernel with:
<programlisting><computeroutput>
options P1003_1B #Posix P1003_1B real-time extensions
options _KPOSIX_PRIORITY_SCHEDULING
</computeroutput></programlisting>
Enable the SMP options (only for FreeBSD 4.x, the FreeBSD 5.0 is now automatic).
</para>
<para>
For French users, check these URLs :
</para>
<itemizedlist>
<listitem>
<para>
<ulink url="http://gcu-squad.org/?viewtip+&amp;tip_id=59">http://gcu-squad.org/?viewtip+&amp;tip_id=59</ulink>.
</para>
</listitem>
<listitem>
<para>
<ulink url="http://gcu-squad.org/?viewtip+&amp;tip_id=54">http://gcu-squad.org/?viewtip+&amp;tip_id=54</ulink>.
</para>
</listitem>
</itemizedlist>
</sect2>
<sect2 id="suntune">
<title>Solaris 2.x</title>
<para>
Most of the optimization values are in <filename>/etc/system</filename> file. This file is read by
the kernel when it is loading. Please notice that the following optimization is focused on Solaris 8 machines
with at least 256M of RAM.
<programlisting><computeroutput>
* A comment is started by a star '*'
*
* 1 maxusers per mega of ram. This machine has 512M then maxusers = 512
set maxusers=512
set hires_tick=1
set rlim_fd_max=10000
set rlim_fd_cur=4096
*set tcp:tcp_conn_hash_size=8192
* Don't setup this if you don't have more than 256M of RAM
set bufhwm=48000
* Folling are used to delay page reaping with databases.
set fastscan = 32000
set slowscan = 200
set maxpgio = 280
set lotsfree = 1024
set desfree = 512
set minfree = 128
set autoup = 280
* Hash buffer sizes during Specweb testing
set tcp:tcp_conn_hash_size = 2097152
* Nic Interface
set hme:hme_adv_100fdx_cap=1
set hme:hme_adv_100hdx_cap=0
set hme:hme_adv_10fdx_cap=0
set hme:hme_adv_10hdx_cap=0
set hme:hme_adv_autoneg_cap=0
* To prevent buffer overflow
set noexec_user_stack=1
set noexec_user_stack_log=1
</computeroutput></programlisting>
Please notice that Solaris needs fast disks. If you have IDE / UDMA disks,
double check they are recent. For example the disks in Ultra 5 / 10
machines are snail slow, and slow down the whole machine when you make read
write operation. Please consider getting faster disks.
</para>
<para>
Also, if you use software raid (Solaris Disk Suite) you will have optimal
performance if you have more than one SCSI controller in the machine.
</para>
<para>
Another good read is the well known <ulink url="http://sunsite.uakom.sk/sunworldonline/common/cockcroft.letters.html">document</ulink> from Adrian Cockroft about tuning Solaris.
Sunhelp.org has also a good <ulink url="http://sunhelp.org/info-faq.ph">section</ulink> about tuning.
Finally, you can read a network guide at <ulink url="http://www.sean.de/Solaris/tune.html">http://www.sean.de/Solaris/tune.html</ulink>.
</para>
</sect2>
</sect1>
<sect1 id="useyourownfonts">
<title>How to use your own fonts</title>
<para>
Use the xdumpfont program in the tool directory of Caudium's sources.
This program will convert your X fonts to Caudium fonts.
</para>
<para>
If your Pike supports TrueType Fonts, (type <userinput>pike --features</userinput> and check if <constant>Image.TTF</constant> is available) you can import TTF font by copying them into <filename>/usr/local/caudium/server/fonts/ttf</filename>.
</para>
</sect1>
<sect1 id="UltraLogworking">
<title>How to get UltraLog working</title>
<para>
See the Caudium documentation project at <ulink url="http://caudium.info/">http://caudium.info/</ulink>, and <ulink url="http://daviesinc.com/modules/docs/ultralog.rxml">http://daviesinc.com/modules/docs/ultralog.rxml</ulink>.
</para>
</sect1>
</chapter>
<chapter id="developing">
<title>Developing with Caudium</title>
<sect1 id="firstrxml">
<title>Your first RXML file</title>
<para>
You can try this code. This is a basic one with only four tags/containers.
You should go to
<ulink url="http://caudium.info/">http://caudium.info/</ulink> and download
the Roxen 1.3 documentation.
</para>
<example>
<title>Some simple RXML tags.</title>
<programlisting>
&lt;html&gt;
&lt;comment&gt;You have to put bgcolor for gtext to work properly&lt;/comment&gt;
&lt;body bgcolor="#FFFFFF"&gt;
&lt;h1&gt;Basic RXML examples&lt;/h1&gt;
&lt;table border="1"&gt;
&lt;tr&gt;
&lt;td&gt;This is a list of all RXML tags&lt;/td&gt;
&lt;td&gt;&lt;list-tags&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;/table&gt;
&lt;table border="1"&gt;
&lt;tr&gt;
&lt;td&gt;Gtext render text as graphic&lt;/td&gt;
&lt;td&gt;&lt;gtext scale=0.5&gt;This is a gif/png graphic&lt;/gtext&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Last modification of this page&lt;/td&gt;
&lt;td&gt;&lt;modified&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;/table&gt;
&lt;/body&gt;
&lt;/html&gt;
</programlisting>
</example>
</sect1>
<sect1 id="thePiketag">
<title>The Pike tag</title>
<para>
For a complete tutorial and reference manual on Pike, see
<ulink url="http://pike.oav.net/">http://pike.oav.net/</ulink>.
</para>
<para>
The Pike tag allows you to easily insert Pike code into your HTML page &#xE0; 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.
</para>
<para>
To do this, you have to load a module in your server. Just select <option>Load
module</option> in the <abbrev>CIF.</abbrev> and click the <quote>Pike tag</quote> 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:
</para>
<example>
<title>The PHP documentation as a Pike tag.</title>
<programlisting>
&lt;html&gt;
&lt;body bgcolor="#FFFFFF"&gt;
&lt;h2&gt;Escaping from HTML&lt;/h2&gt;
&lt;p&gt;
There is one way of escaping from HTML and entering "Pike code mode"
&lt;br /&gt;
&lt;Pike&gt;
output("This is the simplest, and SGML processing instruction");
&lt;/Pike&gt;
&lt;/p&gt;
&lt;h2&gt;Instruction separation&lt;/h2&gt;
&lt;p&gt;
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:
&lt;br /&gt;
&lt;Pike&gt;
output ("This is a test");
&lt;/Pike&gt;
&lt;br /&gt;
&lt;Pike&gt; output ("This is a test"); &lt;/Pike&gt;
&lt;/p&gt;
&lt;h2&gt;Comments&lt;/h2&gt;
&lt;p&gt;
Pike supports C, C++ but not Unix shell-style comments. For example:
&lt;Pike&gt;
string tests = "This is a test&lt;br /&gt;"; // 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;
&lt;/Pike&gt;
&lt;/p&gt;
&lt;h2&gt;Melding RXML and Pike&lt;/h2&gt;
You will never see this in PHP.
<footnote> <para>In fact you can... just compile PHP for Caudium :)</para></footnote>
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.
&lt;p&gt;
&lt;gtext scale=0.5&gt;
&lt;Pike&gt;
string output = "";
for(int I = 1; I &lt; 255; I++)
output += I + "-";
return output;
&lt;/Pike&gt;
&lt;/gtext&gt;
&lt;/p&gt;
&lt;/body&gt;
&lt;/html&gt;
</programlisting>
</example>
<para>
The problem with using this is that you will soon see it is not powerful:
</para>
<itemizedlist>
<listitem>
<para>
The code will become an ugly mixture of data and code even if you use an object
orientation method. The more your project grows, the less you will be able
to produce something useful.
</para>
</listitem>
<listitem>
<para>
The URL will require plenty of those <quote>&amp;</quote> symbols and you will have a lot of files
without real organization.
</para>
</listitem>
<listitem>
<para>
The performance will not be the best.
</para>
</listitem>
<listitem>
<para>
This can be considered as a security risk for servers that are opened
to unknown users (eg. public web servers).
</para>
</listitem>
</itemizedlist>
<para>
The next step is to write your first Pike script.
</para>
</sect1>
<sect1 id="firstPikescript">
<title>Your first Pike script</title>
<para>
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.
</para>
<para>
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
<ulink url="http://www.tldp.org/">http://www.tldp.org/</ulink>.
</para>
<para>
Here, we will run Pike scripts internally within Caudium. To achieve this,
you have to load another module in your server by selecting <option>Load module</option>
in the <abbrev>CIF.</abbrev>. 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 <quote>Pike script support</quote> if you use a graphical
browser.
</para>
<para>
You can now create a .pike file containing, for example,
</para>
<example>
<title>A basic Pike script.</title>
<programlisting>
// 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 = "&lt;html&gt;&lt;body&gt;The id object contain some "
"very useful information&lt;br /&gt;";
html += sprintf("The id->variables contain a list of "
"arguments given to this script %O\n", id->variables);
return html;
}
</programlisting>
</example>
<para>
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:
</para>
<example>
<title>A real world script.</title>
<programlisting>
/* 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);
}
</programlisting>
</example>
<para>
But you can also create some powerful scripts:
</para>
<example>
<title>A script for the power user.</title>
<programlisting>
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("&lt;pre&gt;");
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&lt;/pre&gt;");
id[0]->close();
destruct(id[0]);
}
</programlisting>
</example>
<para>
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 <function>read</function> and
<function>write</function> 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,
<function>http_pipe_in_progress</function>. 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
<function>http_pipe_in_progress</function>.
</para>
<para>
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.
</para>
<para>
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.
</para>
<note>
<para>
The Caudium API is available at
<ulink url="http://caudium.net/">http://caudium.net/</ulink>. You should also
read the Roxen 1.3 PDF available at
<ulink url="http://caudium.info/">http://caudium.info/</ulink>.
Pike scripts are blocking, and allow your users to run scripts with
the same privilege as the server. Blocking means that the server will
be stalled if a socket from a pike script is stalled (usually waiting for
something). This applies even if you use non-blocking sockets
in your script. You don't have this problem with modules.
</para>
</note>
</sect1>
<sect1 id="firstmodule">
<title>Your first module</title>
<para>
With a custom module you can do all sorts of things:
</para>
<itemizedlist>
<listitem>
<para>
You can create a professional quality administration center very easily.
</para>
</listitem>
<listitem>
<para>
You don't need any more <quote>&amp;</quote> symbols in the URL.
</para>
</listitem>
<listitem>
<para>
You can also use <option>per user variables</option>, also known as <option>session variables</option>.
</para>
</listitem>
<listitem>
<para>
You'll get better performance since the module is part of the server.
</para>
</listitem>
<listitem>
<para>
You can separate big projects into different modules, and do calls
between different modules. This way, your project is not a big complex
of messy code, but a set of simple, easy to extend code modules.
</para>
</listitem>
<listitem>
<para>
You can separate data from code by using tags and containers. This also
allows you to delegate the appearance to your webmaster, and lets you focus
on the important code.
</para>
</listitem>
<listitem>
<para>
You can easily share your code with the Caudium community. If your code
is good and useful, it can become part of the Caudium distribution. This way
more people will test it, you will have more feedback, and some people may
help you with your project, and may even maintain it.
</para>
</listitem>
</itemizedlist>
<para>
There are different types of modules, for example:
</para>
<itemizedlist>
<listitem>
<para>
Location:
</para>
<para>
This is the most common module, your code is called when
the user hits the URL you specify in the mount point.
</para>
</listitem>
<listitem>
<para>
Parser:
</para>
<para>
Your code is called when Caudium parse a file containing
the tags and/or containers you define.
</para>
</listitem>
<listitem>
<para>
Authentication:
</para>
<para>
Used to authenticate users with, for example, LDAP,
shadow, or SQL.
</para>
</listitem>
<listitem>
<para>
Directory:
</para>
<para>
For indexing files in a directory.
</para>
</listitem>
<listitem>
<para>
First module:
</para>
<para>
Module that is called just after the authentication
module, thus letting you handle the whole request before normal processing.
</para>
</listitem>
</itemizedlist>
<para>
There are other module types. For a complete reference see the Roxen 1.3
Programmer's Guide at
<ulink url="http://caudium.info/">http://caudium.info/</ulink>.
</para>
<para>
For an example on how to write a container, see <filename>fnord.pike</filename> in
<filename class="directory">/Caudium/sources</filename>. Because the location module is a must, here is another
example:
</para>
<example>
<title>A sample module.</title>
<programlisting>
// 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 &lt;who /&gt; 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 &lt;module.h&gt;
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", "&lt;html&gt;&lt;body&gt;&lt;p&gt;",
"The code to output before who", TYPE_STRING);
defvar("codeafterwho", "&lt;/p&gt;&lt;/body&gt;&lt;/html&gt;", "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&lt;br /&gt; for better output
result = replace(result, "\n","\n&lt;br /&gt;");
return http_string_answer(QUERY(codebeforewho)+result+QUERY(codeafterwho));
}
</programlisting>
</example>
<para>
Put this code in <filename>../local/modules/who.pike</filename> relative to
<filename class="directory">/usr/local/caudium/server</filename>
in our example. Log into the <abbrev>CIF.</abbrev>, if it is not
the case and go into the main <option>Action</option> tab -&gt; <option>Cache</option> -&gt;
<option>Flush caches</option>. Check the <option>Module cache</option> check the box and press
<option>Next</option>, then <option>OK</option>.
</para>
<para>
Come back to the main <option>Virtual servers</option> tab and choose one of your
servers. Do <option>Add module</option> and select the <option>who</option> module. If you don't have the
who module, check your events log.
</para>
<para>
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 <option>Reload</option> button
to get the changes. It takes about one second and if there was a
compilation error the old copy remains for users.
</para>
</sect1>
<sect1 id="backtrace">
<title>How to use a backtrace</title>
<para>
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 <xref linkend="firstmodule" />?
If so take it and check it works. Now change the line
<computeroutput>string command = QUERY(path2who)+" "+QUERY(options2who);</computeroutput> to <computeroutput>string command = 0;</computeroutput>.
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 <option>More options</option> button in the <abbrev>CIF.</abbrev> and
reload the module. Check that the <option>Global Variables</option> -&gt; <option>show_internals</option> option
is set to yes, and try your module. You will have an error which should look like this:
</para>
<informalexample>
<programlisting>
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()
</programlisting>
</informalexample>
<para>
This seems awful but it is not. The first line is the error in itself:
<informalexample>
<programlisting>
"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)
</programlisting>
</informalexample>
where the error occurred. <function>find_file</function> 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 <footnote><para>Pike can't display contents of an object but can display any other types.</para></footnote>.
Next line is the function (<function>low_get_file</function> in <filename>configuration.pike</filename>) that has
called <function>find_file</function> in <filename>who.pike</filename>. 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.
</para>
</sect1>
<sect1 id="printsomethingtodebuglogfile">
<title>How to print something to debug log file</title>
<para>
With Caudium you can output something to the web page or to the debug log file
located in <filename>../logs/debug/default.*</filename>. 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:
<programlisting>
write("my message to log file\n");
</programlisting>
It is also usually useful to use <function>sprintf</function> to format what you want to output:
<programlisting>
int i = 2; write(sprintf("i=%d\n", i));
</programlisting>
This line will output <computeroutput>i=2</computeroutput>, but it is better when you output array or mapping,
as Pike is able to print them in a human-comprehensible format:
<programlisting>
array a = ({ "test", "test2", 2 }); write(sprintf("a=%O\n", a));
</programlisting>
Which will output:
<programlisting>
a = ({ /* 2 elements */
"test",
"test2"
})
</programlisting>
</para>
<note>
<para>
the %O format is very useful since it can output any type from
int to mapping. The only type you can't format is object.
</para>
</note>
</sect1>
</chapter>
<chapter id="helpCaudiumcommunity">
<title>How to help the Caudium community</title>
<para>
Caudium is a great product, but even with the best programmers in the world it
would be nothing if you didn't help us. This doesn't necessarily mean working
for Caudium twelve hours a day but thinking of it for a few seconds.
</para>
<para>
The next paragraph is mainly for users who just want to help us without getting
involved too much.
</para>
<sect1 id="promoteCaudium">
<title>How to promote Caudium</title>
<para>
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:
</para>
<itemizedlist>
<listitem>
<para>
Try it, and give us feedback about your experience.
</para>
</listitem>
<listitem>
<para>
Write some documentation. Without documentation, a project is useless.
</para>
</listitem>
<listitem>
<para>
Recommend Caudium to some people you know. You don't really have to tell
them to try it now or they will die, just tell him about it. If other
people tell them the same thing, chances are that they will install it.
When these people install Caudium, they will look for documentation.
</para>
</listitem>
<listitem>
<para>
Mention Caudium in newsgroups/web sites telling them what you think of it.
</para>
</listitem>
<listitem>
<para>
Translate documentation.
</para>
</listitem>
</itemizedlist>
<para>
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.
</para>
<para>
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.
</para>
</sect1>
<sect1 id="writedoc">
<title>How to write documentation</title>
<para>
There are two types of documentation needed for Caudium:
</para>
<itemizedlist>
<listitem>
<para>
Press articles.
</para>
<para>
You can write press articles about Caudium.
</para>
<note>
<title>
Note for French writers:
</title>
<para>
You can contact us for that.
</para>
</note>
<para>
This type of documentation is usually not really helpful since few in the
community will read it. It is useful mainly for advertising (even if you
made a very technical article, this is useful).
</para>
</listitem>
<listitem>
<para>
Documentation available from Internet.
</para>
<para>
This type of documentation is a must; Caudium can't exist
without it. This documentation will help Caudium's newbies,
and will also be useful for developers. One good way to
start with Caudium is using the Roxen 1.3 documentation. The
developers should also see the autodoc. These are in-line
documents made in the sources, and available as formatted
HTML output at <ulink
url="http://caudium.net/">http://caudium.net/</ulink>.
</para>
<para>
There is also a lack for a more in-depth documentation for
developer. Examples include how to code non-blocking
sockets, how to use a backtrace, how to use the
<function>do_output_tag</function>, and when should I put <parameter>thread_safe=1</parameter>. I
remember spending hours trying to understand some
of these things on IRC without any documentation
available. This sort of documentation should be written by
one of the top developers.
</para>
<para>
This documentation is written using XSLT, but if you don't
know it, that's not a problem. Give us whatever format you
want, we will translate it. It is the same for the
language. If you don't speak English, you can write it in
your own language and we will translate. We will also proof-read
your work carefully in order to correct any typos or inaccuracies
you might leave.
</para>
<para>
To write this type of documentation, contact the person in charge of the
documentation project, ice at caudium dot net.
</para>
</listitem>
</itemizedlist>
</sect1>
<sect1 id="CVSaccount">
<title>How to get a CVS account</title>
<para>
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.
</para>
<para>
To get a CVS account, come on IRC or send a mail to kiwi at caudium dot net and
explain your plan.
</para>
</sect1>
<sect1 id="testCaudium">
<title>How to test Caudium</title>
<para>
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 <option>-P</option> testsuite option (the information on
this CVS repository is on <ulink url="http://caudium.net/">http://caudium.net/</ulink>.)
Note that this test suite is not maintained, and needs some work.
</para>
</sect1>
<sect1 id="bugreport">
<title>How to send a bug report</title>
<para>
To send a bug report, copy/paste the error from Caudium's log file (including
backtrace, see <xref linkend="backtrace" />), your configuration, and the context in
which it happened.
</para>
<para>
Go to <ulink url="http://caudium.net/">http://caudium.net/</ulink> and choose bug tracking on the left and follow the instructions.</para>
</sect1>
</chapter>
<chapter>
<title>Revision History/Credits/The End</title>
<sect1>
<title>Revision History</title>
<itemizedlist>
<listitem>
<para>Version 2.2 : September 20, 2002</para>
<para><simplelist>
<member>Added images and icons.</member>
<member>Better use of Docbook.</member>
<member>Updates in the FreeBSD ports section.</member>
<member>Few more fixes.</member>
</simplelist></para>
</listitem>
<listitem>
<para>Version 2.1 : June 26, 2002</para>
<para><simplelist>
<member>Little language and cosmetic corrections.</member>
<member>Added the script for image selection in the your first Pike script.</member>
<member>Corrections in the FreeBSD ports section.</member>
<member>The file is now well-formed XML.</member>
</simplelist></para>
</listitem>
<listitem>
<para>Version 2.0 : June 14, 2002</para>
<para><simplelist>
<member>LDP Review of documentation.</member>
<member>Added cross reference to full GFDL in Appendix A.</member>
<member>Converted to Docbook XML 4.1.2.</member>
<member>Removed editing notations that are corrected.</member>
<member>Corrected links to LDP (Linux Documentation Project).</member>
<member>Made sentence level corrections-spelling, grammar, etc.</member>
</simplelist></para>
</listitem>
<listitem>
<para>Version 1.0 : June 6, 2002</para>
<para><simplelist>
<member>Initial Release</member>
<member>Submitted to the LDP</member>
</simplelist></para>
</listitem>
<listitem>
<para>Version 0.91 : May 22, 2002</para>
<para><simplelist>
<member>The SGML source is now the authoritative source</member>
<member>The SGML source is now correctly indented</member>
<member>Many little SGML changes in the document</member>
<member>Added the Upgrading Caudium paragraph</member>
<member>Added a note about the start script config-dir option</member>
</simplelist></para>
</listitem>
<listitem>
<para>Version 0.9 : May 7, 2002</para>
<para><simplelist>
<member>Better HTML conformance to avoid Caudium crash on caudium.info.</member>
<member>Inserting the notes from Kiwi, Grendel and other into the document.</member>
<member>Removed all TODO and #define sections.</member>
<member>Completed the test suite section.</member>
<member>Added the contributors section.</member>
<member>Now docbook2ps and docbook2pdf correctly parse the SGML file.</member>
</simplelist></para>
</listitem>
<listitem>
<para>Version 0.05 : April 4, 2002</para>
<para>This HOWTO is in Docbook format. Thanks to Thomas Marteau.</para>
</listitem>
<listitem>
<para>Version 0.04 : March 26, 2002</para>
<para><simplelist>
<member>Added Introduction and license.</member>
<member>Added a note in "Your first pike script".</member>
<member>Corrected typo in paragraph number.</member>
<member>Re-organization of the document.</member>
</simplelist></para>
</listitem>
<listitem>
<para>Version 0.03 : March 22, 2002</para>
<para>More Caudium disadvantages and some useful corrections from people at the Caudium general mailing list.</para>
<para>Answers:
<simplelist>
<member>How to get UltraLog working.</member>
<member>How to benchmark a web server.</member>
<member>How to use a backtrace.</member>
<member>How to print something to debug log file.</member>
<member>How to get CAMAS from cvs/source.</member>
</simplelist></para>
</listitem>
<listitem>
<para>Version 0.02 : March 18, 2002</para>
<para>Minor correction in other answers.</para>
<para>Answers:
<simplelist>
<member>How to run Caudium as a non-privileged user.</member>
<member>How to secure Caudium.</member>
<member>How to tune Caudium for best performance.</member>
<member>How to get packages for Debian GNU/Linux.</member>
<member>How to get packages for FreeBSD.</member>
<member>How to get packages for Solaris.</member>
<member>How to use your own fonts.</member>
<member>How to help Caudium Community.</member>
</simplelist></para>
</listitem>
<listitem>
<para>Version 0.01 : March 11, 2002</para>
<para>Initial revision. Plain text format.</para>
</listitem>
</itemizedlist>
</sect1>
<sect1>
<title>Credits and contributors</title>
<para>Here is the list of people that helped me in one way or another to
get this HOWTO written:
</para>
<simplelist>
<member>Joe Follansbee &lt;joef at compelinteractive dot com&gt;</member>
<member>Grammar, spelling and syntax cleanup.</member>
<member>Bill Welliver &lt;Bill.Welliver at fairchildsemi dot com&gt;</member>
<member>Minor changes.</member>
<member>Chris Davies &lt;mcd at daviesinc dot com&gt;</member>
<member>Major contribution to the Caudium's disadvantages, many little fixes and spelling corrections.</member>
<member>Martin Friese &lt;mf at bauko dot bv dot tu-berlin dot de&gt;</member>
<member>Update in the platform section.</member>
<member>Xavier Beaudouin &lt;kiwi at oav dot net&gt;</member>
<member>All tuning sections, cosmetics changes.</member>
<member>Marek Habersack &lt;grendel at caudium dot net&gt;</member>
<member>Minor fixes and latex conversion.</member>
<member>Thomas Marteau &lt;marteaut at tuxfamily dot org&gt;</member>
<member>Minor fixes and SGML conversion.</member>
<member>John Wenger &lt;JohnWenger at EarthLink dot Net&gt;</member>
<member>Editing, review and comments.</member>
</simplelist>
</sect1>
<sect1>
<title>The End</title>
<para>Thanks for reading. I hope this HOWTO will help you
discover Caudium's power. And remember this quotation:
<blockquote><attribution>Dick Brandon</attribution>
<para>Documentation is like sex: when it is good, it is very, very good; and
when it is bad, it is better than nothing.</para>
</blockquote>
</para>
<para>If you have any questions about this documentation, contact me at <email>vida at caudium dot net</email> or the Caudium general mailing list at <email>general at oav dot net</email></para>
</sect1>
</chapter>
<appendix id="gfdl">
<title>GNU Free Documentation License</title>
<!-- - GNU Project - Free Software Foundation (FSF) -->
<!-- LINK REV="made" HREF="mailto:webmasters@gnu.org" -->
<!-- sect1>
<title>GNU Free Documentation License</title -->
<para>Version 1.1, March 2000</para>
<blockquote>
<para>Copyright (C) 2000 Free Software Foundation, Inc.
59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
Everyone is permitted to copy and distribute verbatim copies
of this license document, but changing it is not allowed.</para>
</blockquote>
<sect1 id="gfdl-0">
<title>PREAMBLE</title>
<para>The purpose of this License is to make a manual, textbook,
or other written document "free" in the sense of freedom: to
assure everyone the effective freedom to copy and redistribute it,
with or without modifying it, either commercially or
noncommercially. Secondarily, this License preserves for the
author and publisher a way to get credit for their work, while not
being considered responsible for modifications made by
others.</para>
<para>This License is a kind of "copyleft", which means that
derivative works of the document must themselves be free in the
same sense. It complements the GNU General Public License, which
is a copyleft license designed for free software.</para>
<para>We have designed this License in order to use it for manuals
for free software, because free software needs free documentation:
a free program should come with manuals providing the same
freedoms that the software does. But this License is not limited
to software manuals; it can be used for any textual work,
regardless of subject matter or whether it is published as a
printed book. We recommend this License principally for works
whose purpose is instruction or reference.</para>
</sect1>
<sect1 id="gfdl-1">
<title>APPLICABILITY AND DEFINITIONS</title>
<para>This License applies to any manual or other work that
contains a notice placed by the copyright holder saying it can be
distributed under the terms of this License. The "Document",
below, refers to any such manual or work. Any member of the
public is a licensee, and is addressed as "you".</para>
<para>A "Modified Version" of the Document means any work
containing the Document or a portion of it, either copied
verbatim, or with modifications and/or translated into another
language.</para>
<para>A "Secondary Section" is a named appendix or a front-matter
section of the Document that deals exclusively with the
relationship of the publishers or authors of the Document to the
Document's overall subject (or to related matters) and contains
nothing that could fall directly within that overall subject.
(For example, if the Document is in part a textbook of
mathematics, a Secondary Section may not explain any mathematics.)
The relationship could be a matter of historical connection with
the subject or with related matters, or of legal, commercial,
philosophical, ethical or political position regarding
them.</para>
<para>The "Invariant Sections" are certain Secondary Sections
whose titles are designated, as being those of Invariant Sections,
in the notice that says that the Document is released under this
License.</para>
<para>The "Cover Texts" are certain short passages of text that
are listed, as Front-Cover Texts or Back-Cover Texts, in the
notice that says that the Document is released under this
License.</para>
<para>A "Transparent" copy of the Document means a
machine-readable copy, represented in a format whose specification
is available to the general public, whose contents can be viewed
and edited directly and straightforwardly with generic text
editors or (for images composed of pixels) generic paint programs
or (for drawings) some widely available drawing editor, and that
is suitable for input to text formatters or for automatic
translation to a variety of formats suitable for input to text
formatters. A copy made in an otherwise Transparent file format
whose markup has been designed to thwart or discourage subsequent
modification by readers is not Transparent. A copy that is not
"Transparent" is called "Opaque".</para>
<para>Examples of suitable formats for Transparent copies include
plain ASCII without markup, Texinfo input format, LaTeX input
format, SGML or XML using a publicly available DTD, and
standard-conforming simple HTML designed for human modification.
Opaque formats include PostScript, PDF, proprietary formats that
can be read and edited only by proprietary word processors, SGML
or XML for which the DTD and/or processing tools are not generally
available, and the machine-generated HTML produced by some word
processors for output purposes only.</para>
<para>The "Title Page" means, for a printed book, the title page
itself, plus such following pages as are needed to hold, legibly,
the material this License requires to appear in the title page.
For works in formats which do not have any title page as such,
"Title Page" means the text near the most prominent appearance of
the work's title, preceding the beginning of the body of the
text.</para>
</sect1>
<sect1 id="gfdl-2">
<title>VERBATIM COPYING</title>
<para>You may copy and distribute the Document in any medium,
either commercially or noncommercially, provided that this
License, the copyright notices, and the license notice saying this
License applies to the Document are reproduced in all copies, and
that you add no other conditions whatsoever to those of this
License. You may not use technical measures to obstruct or
control the reading or further copying of the copies you make or
distribute. However, you may accept compensation in exchange for
copies. If you distribute a large enough number of copies you
must also follow the conditions in section 3.</para>
<para>You may also lend copies, under the same conditions stated
above, and you may publicly display copies.</para>
</sect1>
<sect1 id="gfdl-3">
<title>COPYING IN QUANTITY</title>
<para>If you publish printed copies of the Document numbering more
than 100, and the Document's license notice requires Cover Texts,
you must enclose the copies in covers that carry, clearly and
legibly, all these Cover Texts: Front-Cover Texts on the front
cover, and Back-Cover Texts on the back cover. Both covers must
also clearly and legibly identify you as the publisher of these
copies. The front cover must present the full title with all
words of the title equally prominent and visible. You may add
other material on the covers in addition. Copying with changes
limited to the covers, as long as they preserve the title of the
Document and satisfy these conditions, can be treated as verbatim
copying in other respects.</para>
<para>If the required texts for either cover are too voluminous to
fit legibly, you should put the first ones listed (as many as fit
reasonably) on the actual cover, and continue the rest onto
adjacent pages.</para>
<para>If you publish or distribute Opaque copies of the Document
numbering more than 100, you must either include a
machine-readable Transparent copy along with each Opaque copy, or
state in or with each Opaque copy a publicly-accessible
computer-network location containing a complete Transparent copy
of the Document, free of added material, which the general
network-using public has access to download anonymously at no
charge using public-standard network protocols. If you use the
latter option, you must take reasonably prudent steps, when you
begin distribution of Opaque copies in quantity, to ensure that
this Transparent copy will remain thus accessible at the stated
location until at least one year after the last time you
distribute an Opaque copy (directly or through your agents or
retailers) of that edition to the public.</para>
<para>It is requested, but not required, that you contact the
authors of the Document well before redistributing any large
number of copies, to give them a chance to provide you with an
updated version of the Document.</para>
</sect1>
<sect1 id="gfdl-4">
<title>MODIFICATIONS</title>
<para>You may copy and distribute a Modified Version of the
Document under the conditions of sections 2 and 3 above, provided
that you release the Modified Version under precisely this
License, with the Modified Version filling the role of the
Document, thus licensing distribution and modification of the
Modified Version to whoever possesses a copy of it. In addition,
you must do these things in the Modified Version:</para>
<orderedlist numeration="upperalpha">
<listitem><para>Use in the Title Page
(and on the covers, if any) a title distinct from that of the
Document, and from those of previous versions (which should, if
there were any, be listed in the History section of the
Document). You may use the same title as a previous version if
the original publisher of that version gives permission.</para>
</listitem>
<listitem><para>List on the Title Page,
as authors, one or more persons or entities responsible for
authorship of the modifications in the Modified Version,
together with at least five of the principal authors of the
Document (all of its principal authors, if it has less than
five).</para>
</listitem>
<listitem><para>State on the Title page
the name of the publisher of the Modified Version, as the
publisher.</para>
</listitem>
<listitem><para>Preserve all the
copyright notices of the Document.</para>
</listitem>
<listitem><para>Add an appropriate
copyright notice for your modifications adjacent to the other
copyright notices.</para>
</listitem>
<listitem><para>Include, immediately
after the copyright notices, a license notice giving the public
permission to use the Modified Version under the terms of this
License, in the form shown in the Addendum below.</para>
</listitem>
<listitem><para>Preserve in that license
notice the full lists of Invariant Sections and required Cover
Texts given in the Document's license notice.</para>
</listitem>
<listitem><para>Include an unaltered
copy of this License.</para>
</listitem>
<listitem><para>Preserve the section
entitled "History", and its title, and add to it an item stating
at least the title, year, new authors, and publisher of the
Modified Version as given on the Title Page. If there is no
section entitled "History" in the Document, create one stating
the title, year, authors, and publisher of the Document as given
on its Title Page, then add an item describing the Modified
Version as stated in the previous sentence.</para>
</listitem>
<listitem><para>Preserve the network
location, if any, given in the Document for public access to a
Transparent copy of the Document, and likewise the network
locations given in the Document for previous versions it was
based on. These may be placed in the "History" section. You
may omit a network location for a work that was published at
least four years before the Document itself, or if the original
publisher of the version it refers to gives permission.</para>
</listitem>
<listitem><para>In any section entitled
"Acknowledgements" or "Dedications", preserve the section's
title, and preserve in the section all the substance and tone of
each of the contributor acknowledgements and/or dedications
given therein.</para>
</listitem>
<listitem><para>Preserve all the
Invariant Sections of the Document, unaltered in their text and
in their titles. Section numbers or the equivalent are not
considered part of the section titles.</para>
</listitem>
<listitem><para>Delete any section
entitled "Endorsements". Such a section may not be included in
the Modified Version.</para>
</listitem>
<listitem><para>Do not retitle any
existing section as "Endorsements" or to conflict in title with
any Invariant Section.</para>
</listitem>
</orderedlist>
<para>If the Modified Version includes new front-matter sections
or appendices that qualify as Secondary Sections and contain no
material copied from the Document, you may at your option
designate some or all of these sections as invariant. To do this,
add their titles to the list of Invariant Sections in the Modified
Version's license notice. These titles must be distinct from any
other section titles.</para>
<para>You may add a section entitled "Endorsements", provided it
contains nothing but endorsements of your Modified Version by
various parties--for example, statements of peer review or that
the text has been approved by an organization as the authoritative
definition of a standard.</para>
<para>You may add a passage of up to five words as a Front-Cover
Text, and a passage of up to 25 words as a Back-Cover Text, to the
end of the list of Cover Texts in the Modified Version. Only one
passage of Front-Cover Text and one of Back-Cover Text may be
added by (or through arrangements made by) any one entity. If the
Document already includes a cover text for the same cover,
previously added by you or by arrangement made by the same entity
you are acting on behalf of, you may not add another; but you may
replace the old one, on explicit permission from the previous
publisher that added the old one.</para>
<para>The author(s) and publisher(s) of the Document do not by
this License give permission to use their names for publicity for
or to assert or imply endorsement of any Modified Version.</para>
</sect1>
<sect1 id="gfdl-5">
<title>COMBINING DOCUMENTS</title>
<para>You may combine the Document with other documents released
under this License, under the terms defined in section 4 above for
modified versions, provided that you include in the combination
all of the Invariant Sections of all of the original documents,
unmodified, and list them all as Invariant Sections of your
combined work in its license notice.</para>
<para>The combined work need only contain one copy of this
License, and multiple identical Invariant Sections may be replaced
with a single copy. If there are multiple Invariant Sections with
the same name but different contents, make the title of each such
section unique by adding at the end of it, in parentheses, the
name of the original author or publisher of that section if known,
or else a unique number. Make the same adjustment to the section
titles in the list of Invariant Sections in the license notice of
the combined work.</para>
<para>In the combination, you must combine any sections entitled
"History" in the various original documents, forming one section
entitled "History"; likewise combine any sections entitled
"Acknowledgements", and any sections entitled "Dedications". You
must delete all sections entitled "Endorsements."</para>
</sect1>
<sect1 id="gfdl-6">
<title>COLLECTIONS OF DOCUMENTS</title>
<para>You may make a collection consisting of the Document and
other documents released under this License, and replace the
individual copies of this License in the various documents with a
single copy that is included in the collection, provided that you
follow the rules of this License for verbatim copying of each of
the documents in all other respects.</para>
<para>You may extract a single document from such a collection,
and distribute it individually under this License, provided you
insert a copy of this License into the extracted document, and
follow this License in all other respects regarding verbatim
copying of that document.</para>
</sect1>
<sect1 id="gfdl-7">
<title>AGGREGATION WITH INDEPENDENT WORKS</title>
<para>A compilation of the Document or its derivatives with other
separate and independent documents or works, in or on a volume of
a storage or distribution medium, does not as a whole count as a
Modified Version of the Document, provided no compilation
copyright is claimed for the compilation. Such a compilation is
called an "aggregate", and this License does not apply to the
other self-contained works thus compiled with the Document, on
account of their being thus compiled, if they are not themselves
derivative works of the Document.</para>
<para>If the Cover Text requirement of section 3 is applicable to
these copies of the Document, then if the Document is less than
one quarter of the entire aggregate, the Document's Cover Texts
may be placed on covers that surround only the Document within the
aggregate. Otherwise they must appear on covers around the whole
aggregate.</para>
</sect1>
<sect1 id="gfdl-8">
<title>TRANSLATION</title>
<para>Translation is considered a kind of modification, so you may
distribute translations of the Document under the terms of section
4. Replacing Invariant Sections with translations requires
special permission from their copyright holders, but you may
include translations of some or all Invariant Sections in addition
to the original versions of these Invariant Sections. You may
include a translation of this License provided that you also
include the original English version of this License. In case of
a disagreement between the translation and the original English
version of this License, the original English version will
prevail.</para>
</sect1>
<sect1 id="gfdl-9">
<title>TERMINATION</title>
<para>You may not copy, modify, sublicense, or distribute the
Document except as expressly provided for under this License. Any
other attempt to copy, modify, sublicense or distribute the
Document is void, and will automatically terminate your rights
under this License. However, parties who have received copies, or
rights, from you under this License will not have their licenses
terminated so long as such parties remain in full
compliance.</para>
</sect1>
<sect1 id="gfdl-10">
<title>FUTURE REVISIONS OF THIS LICENSE</title>
<para>The Free Software Foundation may publish new, revised
versions of the GNU Free Documentation License from time to time.
Such new versions will be similar in spirit to the present
version, but may differ in detail to address new problems or
concerns. See <ulink
url="http://www.gnu.org/copyleft/">http://www.gnu.org/copyleft/</ulink>.</para>
<para>Each version of the License is given a distinguishing
version number. If the Document specifies that a particular
numbered version of this License "or any later version" applies to
it, you have the option of following the terms and conditions
either of that specified version or of any later version that has
been published (not as a draft) by the Free Software Foundation.
If the Document does not specify a version number of this License,
you may choose any version ever published (not as a draft) by the
Free Software Foundation.</para>
</sect1>
<sect1 id="gfdl-11">
<title>How to use this License for your documents</title>
<para>To use this License in a document you have written, include
a copy of the License in the document and put the following
copyright and license notices just after the title page:</para>
<blockquote><para>
Copyright (c) YEAR YOUR NAME.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1
or any later version published by the Free Software Foundation;
with the Invariant Sections being LIST THEIR TITLES, with the
Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST.
A copy of the license is included in the section entitled "GNU
Free Documentation License".
</para></blockquote>
<para>If you have no Invariant Sections, write "with no Invariant
Sections" instead of saying which ones are invariant. If you have
no Front-Cover Texts, write "no Front-Cover Texts" instead of
"Front-Cover Texts being LIST"; likewise for Back-Cover
Texts.</para>
<para>If your document contains nontrivial examples of program
code, we recommend releasing these examples in parallel under your
choice of free software license, such as the GNU General Public
License, to permit their use in free software.</para>
</sect1>
</appendix>
</book>
View Git Blame Copy Permalink