Caucus Installation Guide
Once you have downloaded
and built a Caucus kit,
you must actually install the kit on your server.
(Some people actually install Caucus multiple times on the same
server, setting up independent virtual hosts that are completely
separate Caucus sites.)
Caucus must be installed by a system administrator with 'root'
privileges. Caucus does not, however, run as root,
but under and as an ordinary userid via the unix 'setuid' feature.
The installation consists of six steps:
If you are upgrading an existing Caucus installation,
you will only need to perform step II, and possibly V and VI.
- Install MySQL 5.0 or higher
- Create a pair of ordinary userids for Caucus.
- Install the Caucus software
in one of them (the other is used
for automatic Caucus email features)
- Configure the Apache or other web server to run Caucus
- Make Caucus start automatically on server reboot.
- Test Caucus.
I. Install MySQL (required)
Many unix/linux systems today come with MySQL pre-installed.
If you do not have MySQL,
see the separate Installing MySQL
page for detailed instructions.
II. Create userids
For example, if the numeric userids 500 and 501 are available, you
could create these userids as root with the following commands:
- Create a new userid, typically called "caucus", with its own home
directory, such as /home/caucus.
(You may use a different name or home directory if you prefer.
The installation procedure will adapt to whichever name you choose.)
Caucus must also have a dedicated unix group that is not used for
any other purpose.
The home directory for Caucus must have enough free disk space
to contain all of the Caucus programs and data files, and all
of the anticipated conference data.
A minimum of 100MB is recommended.
(The software itself is less than 30MB.)
Only the system administrator, or a designated Caucus manager, should
know the password to the Caucus userid.
- Create a second userid, typically called "caucus_mail".
It must use the same group as the "caucus" userid from step II.1.
This userid is used for the Caucus "E-mail participation" feature.
adduser -u 500 -d /home/caucus caucus
adduser -u 501 -d /home/caucus_mail -g caucus caucus_mail
III. Install (or upgrade) the Caucus kit
The installation procedure is the same whether you are
installing Caucus for the first time, or
upgrading your existing Caucus software.
The installation procedure automatically determines if this is
a new installation of Caucus or an upgrade to an existing Caucus
If you are upgrading Caucus, your existing conferences will
not be affected by the upgrade.
- Login to the Caucus userid.
Unless otherwise stated, all commands in this installation guide
must be typed while logged in to your unix system, in a
terminal (shell) window, as the "caucus" userid.
- Unpackage the software
The Caucus kit is packaged in a file called caucus5.tar.
In the Caucus home directory, type the following commands to
unpackage this file.
tar xvf caucus5.tar
- Run the installation script
The software includes an installation script that will
automatically create the proper script files, set the proper file
permissions, and so on.
The script will ask for your
hostname (and port number, if
needed) of your web server, and some
To run the script, type:
and follow the directions.
- Check for swebd.conf.new
If you are installing Caucus as an upgrade, look for the files
SWEB/swebd.conf and SWEB/swebd.conf.new.
Compare the two files with 'diff' or merge2.
Swebd.conf.new is the new version created by the installer; if you've
made any significant changes to swebd.conf, you should now make the
same changes to swebd.conf.new.
Then, in either case, rename swebd.conf.new to swebd.conf.
- Public HTML directory
Caucus requires that certain files be placed in the Caucus
userid's public HTML directory. The standard name for this
directory is public_html. The Caucus distribution includes
a public_html directory with the necessary files already in it.
If your httpd server uses a different name by default, persuade
it map the URL "~caucus" (for example) to /home/caucus/public_html.
your web server to run Caucus
- Allow Access to Caucus directories
Most web servers require that you "open up"
access to any specific directories that live outside the
"root" directory of the web tree.
In particular, assuming /home/caucus is the Caucus
home directory, you may need to allow access to the directories
To do this for Apache, modify your httpd.conf or other configuration
file to include:
allow from all
allow from all
- Define CGI directories
Caucus uses several different CGI programs in the directories
SWEB and REG to communicate with the web server.
The best way to identify these programs to the web server is to
declare SWEB and REG as CGI directories.
Specifically, declare the following mappings of URLs to CGI
http://yourhost.com/sweb/ to /home/caucus/SWEB/
http://yourhost.com/reg/ to /home/caucus/REG/
If for some reason you cannot declare a CGI directory, enable
your server in some other way to treat the files below as
To do this for Apache, include the directives:
ScriptAlias /sweb/ /home/caucus/SWEB/
ScriptAlias /reg/ /home/caucus/REG/
- Define special "/caucus" URL
Existing Caucus users may go
directly to specific conferences, items, or responses through the
special URLs shown below:
||http://yourhost.com/caucus ||("Caucus Center"
|http://yourhost.com/caucus/conference_name/item ||(go to
||(go to that response)
In order to make these special URLs work, the web server must
be configured to map URLs that begin
to the CGI file /home/caucus/REG/start.cgi.
If this is not possible for your web server, your users may still
access Caucus through the regular login page.)
To do this for Apache, add the directives:
ScriptAlias /caucus/ /home/caucus/REG/start.cgi/
ScriptAlias /caucus /home/caucus/REG/start.cgi
- Allow access to ~caucus
Ensure that the URL http://yourhost.com/~caucus maps to
To do this for Apache, you have three choices:
- If it is acceptable to map all "~user" URLs to the equivalent
public_html directories, just include the directive:
- If you have a separate section for a Caucus virtual host
(recommended), include the same directive in that section.
- Otherwise, you can add a specific directive to do the mapping:
Alias /~caucus /home/caucus/public_html
- Restrict "Directory Indexing"
This turns off the automatic indexing (directory listing)
of the directories (folders) under Caucus.
Otherwise outside users could, in principle, navigate
through all the files uploaded to Caucus.
To do this for Apache, include the directive:
- Allow file upload
If (and only if) you encounter problems uploading files into Caucus,
you may need to specifically allow file uploads.
To do this for Apache, add the directive:
AddHandler cgi-script .cgi
- Restart your web server
The usual method for Apache is
service httpd restart
Caucus automatically on server reboot
Caucus runs as a single master "daemon" program called swebd,
which accepts requests for new Caucus sessions.
It spawns off
a "sub-server child" called swebs, one for each
(See the Caucus architecture description
for more information.)
Swebd is normally started from root, so that it
may start as many children as needed.
Each swebs child runs as effective userid "caucus", and real
(If you are just testing Caucus, or if your
system policies discourage running outside software as root,
you may instead start Caucus logged in as the "caucus" userid.
On most Unix systems, however, this will limit the number of
simultaneous Caucus sessions.)
Note: if you do not have a "nobody" userid, or if the
user number of "nobody" is negative, you should create a
user with no rights (say, "noone") and a postive user number.
Then edit /home/caucus/SWEB/swebd.conf, and change the
"Real_ID" line to use the "noone" userid.
To start the Caucus daemon, login as root, and type the
rm -f /home/caucus/SOCKET/sweb
rm -f /home/caucus/SOCKET/sweb0*
where /home/caucus is the home directory of the "caucus" userid.
You must also add these same commands to your system start-up
so that the Caucus daemon will automatically start
when your system reboots:
Point your browser at http://yourhost.com/~caucus/caucus.html.
Click on the "New User Registration" link, and follow the
If you encounter problems, check the trouble-shooting guide below:
- The server encountered an internal error...
- The swebd program was probably not started.
- The requested URL was not found on this server
- The 'sweb' or 'reg' parameter in the web server configuration
may have been misspelled.
Hint: If file is correct, volume may not be mounted suid.
- The files swebs or swebsock in /home/caucus/SWEB are not
setuid, or the volume (disk) that contains them is specifically
mounted as to not allow setuid programs to run.