Copyright © 2002 by The Caudium Group.
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.
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 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 Appendix A.
This document is a volunteer effort. Feel free to improve and make changes. If you catch any mistakes, please correct them.
Caudium is a Web server based on a fork of the Roxen Challenger 1.3 WebServer. Like Roxen, Caudium is written in Pike with parts written in C for performance reasons. Pike is an interpreted language developed by Frederik Hübinette and Roxen Internet Software (RIS), a Swedish company which also created the Roxen Web Server. Caudium, like Pike, is distributed under the terms of the GPL license; several companies and people are involved in its development.
Caudium features include:
Caudium is backward compatible with Roxen Challenger 1.3. It has all the Roxen 1.3 RXML tags and the Roxen 1.3 API, so, from a technical point of view, it is quite the same (although Caudium has many improvements over Roxen 1.3). The main legal difference between Roxen 1.3 and Caudium is that Roxen is property of Roxen Internet Software whereas Caudium is owned by its developers, The Caudium Group. There are many functional extensions, improvements and bug fixes over the original Roxen 1.3 code base from which Caudium was created. Here you may say it is not a problem since it is under GPL. The problem is that even it is licensed under the GPL, RIS may not include your patch in its CVS tree, you may not have a CVS account, so you can't really do all you want. The main reason for the fork, however, was that RIS didn't pay attention to the users' needs, and proceeded to make the new versions of the Roxen Web Server largely incompatible with the previous versions, to the point where one couldn't switch to the new version of the software without much effort put into conversion of the old source code. Rewriting huge portions of RXML/Pike code just to switch to a new version of the web server seemed to be quite counter-productive, and thus the Caudium Project was born.
Caudium differs from Apache in many ways including the directory structure, programming language, and type of configuration. Caudium has a fully integrated web interface, while Apache relies on editing text files directly. Moreover, any change to the Apache configuration requires a restart of the server, while Caudium sees the changes immediately after you save them from the web interface. There are also some differences in the vocabulary used in the configuration interface. Another difference is that Apache 1.3 uses a forked process model while Caudium uses threads or a monolithic process model, depending on the features present in the copy of Pike it uses. Caudium allows the programmer/user to easily extend the server using modules/scripts written in Pike that integrate tightly with the core server and, thus, create a more robust, faster and more intuitive entity than an Apache server augmented with a set of external dynamically loadable libraries. While changing anything in the source code of any Apache extension (or the server itself) requires recompilation, relinking and restarting of the whole server, Caudium allows one to add/remove/modify code without any interruption of the server operation. If you modify a module all you need to do to see the effects of your work is to reload the module in question using the configuration interface. Caudium's architecture also provides easy means of building highly dynamic web pages that use SQL, gdbm, Mird databases, LDAP, dynamically generated graphics (including business graphics modules) and more. The same effect can be achieved with Apache almost only by using external set of Perl, Python, or other language, scripts running as CGI or embedded using a dynamically loaded module. While allowing the programmer/designer to use CGI modules, Caudium offers more power when the source code is integrated with the Caudium core.
In Debian GNU/Linux Woody, also known as Debian 3.0, Caudium and Pike 7.0 and 7.2 are included in the distribution. If you use Woody, you will have Caudium 1.0 and Pike 7.0/7.2. If you use Sid you will have the latest Caudium and the latest Pike; these two packages are actively maintained by the Caudium community, and you will have frequent updates. If you want to test the latest Caudium under Woody, add this to your /etc/apt/sources.list:
If you want php4 Debian package for Caudium, you can do:
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.
As root, go to /usr/ports/www/caudium10 to install current stable version, /usr/ports/www/caudium12 to install the next stable version in Release Candidate process, or /usr/ports/www/caudium-dev to install the current developer's version. The script will automatically fetch and install Pike, try to detect what library you've installed and compile all the necessary libs for Caudium and Pike.
Here is the current Pike / Caudium options supported by the current port :
A little example on how to install Caudium on FreeBSD :
You need to install Pike before you can install Caudium. The version of Pike is different depending on the Caudium version you want to install. For Caudium 1.0, use Pike 7.0; for Caudium 1.2, use Pike 7.2. You can find some Pike packages for the most popular systems: Debian GNU/Linux (Woody/Sid), FreeBSD, Solaris.
For more information, see the quick start guide at http://caudium.net/.
The first time you install Caudium from the sources, you will need to type the following commands:
This script will allow you to give login information for the Configuration InterFace (CIF.), the web based configuration interface, and the port address for the CIF.. But if you want to start Caudium manually, you don't need to use install, just use the start script. This script will fork Caudium once and restart it automatically if it dies. A consequence is that if you kill start, the server will always be running but it will not restart if it dies.
There are many useful options to start. The first is --help. Here is a non-exhaustive list of options:
Finally, the most important thing is debug log files. These files are stored in ../logs/debug (relative to /usr/local/caudium/server in our example). The current log file is named default.1. The log file from the last Caudium start is default.2 and so on. If you didn't enable debug, these files are always used but contain very few messages.
There are two ways to stop Caudium:
On Debian GNU/Linux, you can use the following commands to manipulate the server status:
You can also see readme/README relative to /usr/local/caudium in our example.
Upgrading Caudium is simple. You should install it as if for the first time. That is, get the new sources, unpack them, run ./configure; make; make install and that's all. The new Caudium installation will detect your old Caudium and keep all your old installation including your config files. The config files will be compatible with the new version so you will never have to begin the configuration task a second time. The old server directory will be saved as server.old and so the new one will be put in the classical server directory.
If you use a package system, just use the upgrading features of your packaging system.
The CIF. is where the administrator manages the server. When you first login it looks like this.
In the CIF, you'll find four tabs:
As the CIF. is quite easy to cope with, I will try to describe some of the hidden things you may need to know about. One of them is the button. This button is very useful. Furthermore, some Basic options will not be available unless you turn it on. With this option, you will have more control over Global Variables and some modules in Virtual Servers.
One of these controls is thebutton that you will have when you are in a module. This button will allow developers to check the new code of their modules without restarting Caudium. You should also know that very few options in some modules will not be activated unless you reload the module. So always reload a module when you think an option has not been read by Caudium.
In this section, I will give you a step-by-step tutorial on how to create your first site (virtual server) with Caudium. If you want to do something useful with Caudium, you have to create at least one virtual server. Without this first server, Caudium will not do anything. If you use your browser to access your server, you will only get a dialog box prompting for the CIF. login/password.
To create your first server, log into the web based CIF.. Click on the tab, then the button.
Here, you are prompted for the server name:
Type in an easily identifiable name. You also have to select the configuration type. Depending on the configuration you choose, your server will have a different set of modules. In other words, your server will have different capabilities. For your first server, choose Basic server, and click .
In server variables, go intoand choose . Use the default values, choose , and click . Now select the URL of your site, and select . You can now go back to the page displaying all of your modules, that is, where you were before you had gone into Server Variables.
Under your server name, you'll see the status of your server. If it contains the word "Open" in blue everything is okay, and you can continue with configuring the file system.
If it contains the words "Not open" in red, there is a problem. You can go into the Event Log via the CIF. tab to investigate. If you have an error Failed to open socket on 0:80 (already bound ?), you may have another program or Caudium itself already running on this port. To fix the problem, identify the program which is using this port, and restart Caudium . To restart Caudium, go into -> -> -> . Wait a few seconds, and when prompted, select . Now select your server, and you should have the word "Open" in blue.
By selecting a file system, you tell Caudium which files it will send to people browsing your site. For those who know other web servers, please pay close attention to these explanations, because Caudium is quite different from other servers in this respect.
Caudium file systems use the Unix philosophy of mount point, rather than c:, d:, and so forth. The mount point concept allows you to put your files/directory under any URL you want without changing the files on your local file system. For example, assume you have the following local file system:
Example 4-1. Your user filesystem.
And suppose your URL is http://www.iteam.org/.
With a default configuration, you would say that http://www.iteam.org points to /home/ so that you will have customer1 under http://www.iteam.org/customers/customer1, bertrand under http://www.iteam.org/friends/bertrand and bigcustomer3 under http://www.iteam.org/customers/bigcustomer3.
But bigcustomer3 gives you a lot of money and he asks you for an URL such as http://www.iteam.org/bigcustomer3. However, he doesn't want to be moved from /home/customers/bigcustomer3 because of his FTP client's configuration. Moreover, you can't move the other accounts. With the mount point philosophy, you just have to create another mount point saying that /home/customers/bigcustomer3 is mounted on /bigcustomer3 so that when someone uses http://www.iteam.org/bigcustomer3, Caudium will serve them files from /home/customers/bigcustomer3.
Now let's return to our setup. Go into the File System module, and select NONE/ mounted on / -> Path -> Search Path. Here you will decide which of your directories will be available when someone hits the root of your server. Write, for example, /home.
You can now launch your favorite browser to the URL of your site and enjoy.
If you don't want visitors to get a listing of your files for security reasons, you can disable listing by setting Directory Settings -> Enable directory listing per default to No. Next you have to hit the More options button, and then reload the module. Don't forget to click Save. It is possible to put one of two "magic files" in any directory to make it browsable/not browsable despite the setting in the CIF. for that particular file system:
Finally, to allow bigcustomer3 to get to his URL, go to File System -> Copy Module. Next, go to Path -> Search Path and type /home/customers/bigcustomer3, then type /bigcustomer3 in Mount point.
The Figure 4-3 shows the output you should have.
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 Add module button, and click the image named "Virtual Host Matcher".
You are now able to do redirection with the help of regular expressions. If you don't know what regular expressions ("regexp" 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 Regular expression rewrite rules and add the following rule:
Example 4-2. A simple virtual hosting regular expression.
Example 4-3. A better and quicker regular expression.
Save and type this command on your command line in order to get your browser resolving www.virtualhost.com:
You now have to add another virtual server with the button New Virtual Server at the root of the virtual server tab. Put Virtual host as the server name and choose the Generic server configuration type. Go into Server variables -> Server URL and type http://www.virtualhost.com/. You should see:
This server is handled by the port in my first virtual server. Server URL: http://www.virtualhost.com/
Change the file system root and /tmp in File system -> NONE/ mounted on / -> Paths -> Search path.
You can now point your favorite browser to http://localhost/ and http://www.virtualhost.com/ and see the result.
If you have an error telling you www.virtualhost.com is unknown check your host file.
For more information about virtual hosting, see the Virtual-Web Mini-HOWTO available at the LDP or in /usr/share/doc/HOWTO or /usr/doc/HOWTO under Debian GNU/Linux.
Web servers are usually publicly accessible and represent your company, group or entity so there are chances you want to strengthen the security of this service.
As I already mentioned Caudium has a good security for public access behind mostly written in a script language. However Caudium runs as root by default. In the case a non-authorized user gains access to Caudium's process, he might gain root privileges. Consequently,a lot of web servers run as another user with minimal privileges. Doing this may require some work, as you will have to change the owner of all the files Caudium needs access to, so I give step-by-step instructions how to change those permissions:
I will now speak about general security measures you can take if you are very strict about security.
First, benchmarking a web server is not an easy thing. To benchmark a web server the time it will take to give a page is not important: you don't care if a user can have his page in 0.1 ms or in 0.05 ms as nobody can have such delays on the Internet.
What is important is the average time it will take when you have a maximum number of users on your site simultaneously. Another important thing is how much more time it will take when there are 2 times more users: a server that take 2 times more for 2 times more users is better than another that take 4 times more for the same amount of users. If you run more than a web server on your computer, you will also want to look at the load average and CPU time of your system. Here is a typical output of the command uptime:
22:39:49 up 2:22, 5 users, load average: 0.01, 0.01, 0.00
And an extract from the top(1) man page:
" The load averages are the average number of process ready to run during the last 1, 5 and 15 minutes "
So the lower your load average is, the better for the other programs on your machine.
Now comes the next problem: how can you stress your web server with a maximum number of connections when your client (the machine making the request) will usually not be able to cope with the server and with the number of users you have.
To do this, increase the number of sockets you can have on your system. Under some systems it is 1024, which is too low, see Section 5.3 for more information. The next thing to do is to have a good client program written with threads and non-blocking sockets. If you use a multi-fork program on a single client, it will never cope with any web server. It is also good to have several clients stressing the server together.
Last, if you want to compare two web servers, be sure that they are on the same hardware, OS, and network. The same holds for the client(s).
Until a Linux guru has time to make some nice documentation, here is something that came from PureFtpd software :
Finally don't forget to compile Pike with --with-max-fd=60000 (already done in Debian packages).
Here are the optimizations you can try on your servers. They are provided without any warranty.
First, check to see if your filesystems use Soft Updates:
In /boot/loader.conf add the following:
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:
For French users, check these URLs :
Most of the optimization values are in /etc/system 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.
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.
Another good read is the well known document from Adrian Cockroft about tuning Solaris. Sunhelp.org has also a good section about tuning. Finally, you can read a network guide at http://www.sean.de/Solaris/tune.html.
Use the xdumpfont program in the tool directory of Caudium's sources. This program will convert your X fonts to Caudium fonts.
If your Pike supports TrueType Fonts, (type pike --features and check if Image.TTF is available) you can import TTF font by copying them into /usr/local/caudium/server/fonts/ttf.
You can try this code. This is a basic one with only four tags/containers. You should go to http://caudium.info/ and download the Roxen 1.3 documentation.
Example 6-1. Some simple RXML tags.
For a complete tutorial and reference manual on Pike, see http://pike.oav.net/.
The Pike tag allows you to easily insert Pike code into your HTML page à la PHP. This is a good way of learning Pike if you have a PHP background or if you want to do things very easily and don't worry about perfect results.
To do this, you have to load a module in your server. Just select Load module in the CIF. and click the "Pike tag" image. Then hit save and create an .html file where your public web files are. Since everybody tells me that PHP is easy, which is why it's so popular, I took the PHP examples and converted them to Pike. Here is the result:
Example 6-2. The PHP documentation as a Pike tag.
The problem with using this is that you will soon see it is not powerful:
The next step is to write your first Pike script.
A Pike script is quite like a Perl script. It is executed when the user tries to access it. So a Pike script is usually where your public web files are. This is a good choice if you already have a Perl background and want to try Pike.
You have two choices when doing this. You can execute Pike as a CGI script or internally within the server. If you don't know what CGI is, look up the Apache-Overview-HOWTO at http://www.tldp.org/.
Here, we will run Pike scripts internally within Caudium. To achieve this, you have to load another module in your server by selecting Load module in the CIF.. You now have the list of all modules available in Caudium. As you see, there are a lot of modules and reading this page should give you some ideas for future development. To select the Pike script module, just click on the image named "Pike script support" if you use a graphical browser.
You can now create a .pike file containing, for example,
Example 6-3. A basic Pike script.
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:
Example 6-4. A real world script.
But you can also create some powerful scripts:
Example 6-5. A script for the power user.
This example uses non-blocking sockets. my_fd is the file descriptor of the HTTP socket. Here we change the type of the HTTP socket from blocking sockets (default type) to non-blocking sockets. Non-blocking sockets are sockets that won't block the program waiting for data. Instead, a read and write function (the so-called callback functions) will be called automatically when there is some data to read or write to the HTTP socket. Moreover, we return here a special function, http_pipe_in_progress. This is because as the HTTP socket is set to non-blocking, Caudium won't be able to wait for processing the HTTP stuff like headers and so on. So we have to tell it not to wait for us and send a http_pipe_in_progress.
This mechanism is very useful when you have to do some communication with slow sockets on a single process server (multi-threaded one). In the case of a single process, when you wait for a socket it is all the server, which will wait. So all your users will be stalled. With non blocking sockets there is no problem anymore; the server won't wait for each socket. Example of such code includes CAMAS IMAP/NNTP clients. If you don't understand, don't worry, you usually don't have to understand these mechanisms.
However, the Pike script allows you to write some complex code it is not well suited for big projects. If this is the case, read the next paragraph and enjoy.
With a custom module you can do all sorts of things:
There are different types of modules, for example:
There are other module types. For a complete reference see the Roxen 1.3 Programmer's Guide at http://caudium.info/.
For an example on how to write a container, see fnord.pike in /Caudium/sources. Because the location module is a must, here is another example:
Example 6-6. A sample module.
Put this code in ../local/modules/who.pike relative to /usr/local/caudium/server in our example. Log into the CIF., if it is not the case and go into the main Action tab -> Cache -> Flush caches. Check the Module cache check the box and press Next, then OK.
Come back to the main Virtual servers tab and choose one of your servers. Do Add module and select the who module. If you don't have the who module, check your events log.
You don't need to compile to have a working module. You don't even need to restart the web server. When you develop a module and change the code every 30 seconds, you just have to push the Reload button to get the changes. It takes about one second and if there was a compilation error the old copy remains for users.
A backtrace is text that will show you where your program come before the error. This is very useful for developers when they debug. The best is to take an example. Did you try the who module at the end of Section 6.4? If so take it and check it works. Now change the line string command = QUERY(path2who)+" "+QUERY(options2who); to string command = 0;. This will create an error because we put an int into a string. If we want to do that, we have to cast it (for example, use (string) 0). If you have not done it yet, press the More options button in the CIF. and reload the module. Check that the Global Variables -> show_internals option is set to yes, and try your module. You will have an error which should look like this:
This seems awful but it is not. The first line is the error in itself:
where the error occurred. find_file is the name of the function where the error occurred and you have also the arguments given to it. If you use the source, you see mixed find_file(string path, object id). So here path="" and id=object . Next line is the function (low_get_file in configuration.pike) that has called find_file in who.pike. You also have its arguments and so on. This backtrace is very useful when the error doesn't come directly from your code but from another code before.
With Caudium you can output something to the web page or to the debug log file located in ../logs/debug/default.*. This way the end-user will not see any line you can output in your debug log file. Sending output to the debug log file is simple, just write to stdout:
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.
The next paragraph is mainly for users who just want to help us without getting involved too much.
Caudium, and Roxen problems are not technical. Instead, they are advertising and marketing. Caudium needs to become recognized. It could the best product in the world, but if nobody knows, it will not be used. To help Caudium to become recognized for its quality there are some simple things we can do together:
If you do this, you will help promote Caudium's success. Remember, one of Caudium disadvantages is that the community is too small right now.
The next paragraph is for people who want to get involved a little more, but don't have lot of time, and/or are not technically minded.
There are two types of documentation needed for Caudium:
Unlike other projects, it's relatively not much hassle to get access to Caudium cvs tree. Even if you are a beginner you can have cvs access; we just ask you not to change Caudium's core at the beginning.
To get a CVS account, come on IRC or send a mail to kiwi at caudium dot net and explain your plan.
There is a test suite for Caudium written in Expect which uses TCL and DejaGNU. If you want to use it, fetch it from Caudium's CVS repository with the -P testsuite option (the information on this CVS repository is on http://caudium.net/.) Note that this test suite is not maintained, and needs some work.
Here is the list of people that helped me in one way or another to get this HOWTO written:
Version 1.1, March 2000
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.
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.
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.
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".
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.
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.
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.
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.
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".
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.
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.
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.
You may also lend copies, under the same conditions stated above, and you may publicly display copies.
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.
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.
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.
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.
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:
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.
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.
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.
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.
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.
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.
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."
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.
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.
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.
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.
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.
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.
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 http://www.gnu.org/copyleft/.
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.
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:
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.
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.