<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
- <title>Citadel/UX Documentation</title>
+ <title>Citadel Documentation</title>
<meta http-equiv="content-type"
content="text/html; charset=ISO-8859-1">
</head>
<body>
<div align="center">
-<h1>Citadel/UX</h1>
-<h2>a messaging and collaboration platform for BBS and groupware
-applications</h2>
-Copyright ©1987-2003 by the Citadel development team:<br>
+<h1>C I T A D E L</h1>
+<h2>an open source messaging and collaboration platform</h2>
+Copyright ©1987-2006 by the Citadel development team:<br>
<br>
-<table cellpadding="2" cellspacing="2" border="0" align="center">
+<table align="center" border="0" cellpadding="2" cellspacing="2">
<tbody>
<tr>
<td valign="top">Clint Adams<br>
<tr>
<td valign="top">Art Cancro<br>
</td>
- <td valign="top"><i>overall system design and lead
-developer<br>
+ <td valign="top"><i>overall system design and lead developer<br>
</i></td>
</tr>
<tr>
</i></td>
</tr>
<tr>
- <td valign="top">Michael Hampton<br>
+ <td valign="top">David Given<br>
</td>
- <td valign="top"><i>client software development<br>
+ <td valign="top"><i>IMAP and build patches<br>
</i></td>
</tr>
<tr>
- <td style="vertical-align: top;">Urs Jannsen<br>
+ <td valign="top">Wilfried Goesgens<br>
</td>
- <td style="vertical-align: top;"><span style="font-style: italic;">text
-search algorithm</span><br>
+ <td valign="top"><i>build system patches<br>
+ </i></td>
+ </tr>
+ <tr>
+ <td valign="top">Michael Hampton<br>
</td>
+ <td valign="top"><i>client software development<br>
+ </i></td>
</tr>
<tr>
<td valign="top">Andru Luvisi<br>
<tr>
<td valign="top">Stu Mark<br>
</td>
- <td valign="top"><i>additional client features, IGnet protocol
-design<br>
+ <td valign="top"><i>additional client features, IGnet protocol design<br>
+ </i></td>
+ </tr>
+ <tr>
+ <td valign="top">Edward S. Marshall<br>
+ </td>
+ <td valign="top"><i>RBL checking function design<br>
</i></td>
</tr>
<tr>
<td valign="top"><i>assistance with project management<br>
</i></td>
</tr>
+ <tr>
+ <td valign="top">Trey Van Riper<br>
+ </td>
+ <td valign="top"><i>QA and portability enhancements<br>
+ </i></td>
+ </tr>
<tr>
<td valign="top">John Walker<br>
</td>
- <td valign="top"><i>author of public domain base64
-encoder/decoder<br>
+ <td valign="top"><i>author of public domain base64 encoder/decoder<br>
</i></td>
</tr>
<tr>
</table>
</div>
<br>
-<div align="justify">The entire package is open source; you can
+<div align="justify">The entire package is open source software. You may
redistribute and/or modify it under the terms of the GNU General Public
-License as published by the Free Software Foundation; either version 2
-of the License, or (at your option) any later version.<br>
+License, version 2, which is included in this manual.<br>
<br>
This program is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
-MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
General Public License for more details. </div>
<div align="justify"><br>
For more information, visit either of these locations on
<li>UNCENSORED! BBS, the home of Citadel: <a
href="http://uncensored.citadel.org">http://uncensored.citadel.org</a></li>
</ul>
-<hr width="100%" size="2">
+<hr size="2" width="100%">
<h2 align="center">Table of Contents</h2>
<ol>
<li><a href="#GPL">License</a></li>
<ol>
<li><a href="#Everything_in_its_place...">Everything in its
place...</a></li>
- <li><a href="#The_BBS_Login">Creating a system account for Citadel</a></li>
- <li><a href="#Bypassing_the_login:_prompt">Bypassing the login:
+ <li><a href="#ctdl_login_acct">Creating a system account for Citadel</a></li>
+ <li><a href="#bypassing_login">Bypassing the login:
prompt</a></li>
<li><a href="#Compiling_the_programs">Compiling the programs</a></li>
<li><a href="#Upgrading">Upgrading</a></li>
- <li><a href="#The_citadel.rc_file">The citadel.rc file</a></li>
+ <li><a href="#rc_file">The citadel.rc file</a></li>
<li><a href="#Using_an_external_editor_for_message">Using an
external editor for message composition</a></li>
<li><a href="#Printing_messages">Printing messages</a></li>
<li><a href="#Setup_and_login">Setup and login</a></li>
<li><a href="#Configuring_your_host_system_to_start">Configuring
your host system to start the service</a></li>
- <li><a href="#Logging_in_for_the_first_time">Logging in for
+ <li><a href="#first_time_login">Logging in for
the first time</a></li>
<li><a href="#Welcoming_new_users">Welcoming new users</a></li>
- <li><a href="#Space_for_adding_your_own_client">Space for adding
+ <li><a href="#adding_doors">Space for adding
your own client features (doors)</a></li>
<li><a href="#Troubleshooting_and_getting_help">Troubleshooting and
getting help</a><br>
<li><a href="#Database_maintenance">Database maintenance</a></li>
<ol>
<li><a href="#Introduction_">Introduction</a></li>
+ <li><a href="#Backing_up_your_Citadel_database">Backing up your
+Citadel database</a><br>
+ </li>
<li><a href="#Database_repair">Database repair</a></li>
<li><a href="#ImportingExporting_your_Citadel">Importing/Exporting
your Citadel database</a><br>
</li>
</ol>
+ <li><a href="#crypto">Cryptography support (TLS/SSL)</a></li>
+ <ol>
+ <li><a href="#crypto_intro">Overview</a></li>
+ <li><a href="#real_cert">Generating and installing a Trusted
+Certificate</a></li>
+ </ol>
+ <li><a href="#LDAP_Directory_Support">LDAP directory support</a></li>
+ <ol>
+ <li><a href="#Introduction_ldap">Introduction</a></li>
+ <li><a href="#Preparing_your_LDAP_server_for_Citadel">Preparing
+your LDAP server for Citadel connections</a><br>
+ </li>
+ <li><a href="#Configuring_the_LDAP_Connector_for">Configuring the
+LDAP Connector for Citadel</a><br>
+ </li>
+ </ol>
<li><a href="#utilities">Included utilities</a></li>
<ol>
<li><a href="#overview">Overview</a></li>
<li><a href="#aidepost">aidepost</a></li>
<li><a href="#whobbs">whobbs</a></li>
- <li><a href="#stats">stats</a></li>
<li><a href="#msgform">msgform</a></li>
<li><a href="#userlist">userlist</a></li>
- <li><a href="#readlog">readlog</a></li>
<li><a href="#sendcommand">sendcommand</a></li>
</ol>
</ol>
<br>
-<hr width="100%" size="2"><br>
+<hr size="2" width="100%"><br>
<h2 align="center"><a name="GPL"></a>GNU General Public License<br>
</h2>
</div>
<p align="justify"> </p>
<h3>END OF TERMS AND CONDITIONS</h3>
<br>
-<hr width="100%" size="2"><br>
+<hr size="2" width="100%"><br>
<div align="center">
<h2><a name="Installation"></a>Installation</h2>
</div>
<div align="justify">
<h3>Overview</h3>
-<p>Citadel/UX is an advanced, multiuser, client/server messaging system
+<p>Citadel is an advanced, multiuser, client/server messaging system
suitable for BBS, e-mail, and groupware applications. It is designed to
handle the needs of both small dialup systems and large-scale
Internet-connected systems. It was originally developed on an Altos
public BBS) is an ordinary Linux system. The current distribution
includes: </p>
<ul>
- <li>The Citadel/UX server (this is the back end that does all
+ <li>The Citadel server (this is the back end that does all
processing) </li>
<li>A text-based client program designed with the traditional Citadel
"look and feel" (room prompts, dot commands, and the like) </li>
</ul>
<p>Some knowledge of the Unix system is necessary to install and manage
the system. It is mandatory that the sysop have "root" access to the
-operating system. The following are required to install Citadel/UX: </p>
+operating system. The following are required to install Citadel: </p>
<ul>
- <li>A Unix operating system (Linux, BSD, Solaris, Tru64, HP/UX) </li>
+ <li>A unix-like operating system (Linux, FreeBSD, Solaris, etc.) </li>
<li>C compiler (<a href="http://gcc.gnu.org/">GCC</a> with <a
href="http://www.gnu.org/software/make/make.html">gmake</a> is the
recommended build environment) </li>
</li>
<li>Enough disk space to hold all of the programs and data </li>
</ul>
-<p>If you are running Citadel/UX on a Linux system, it is STRONGLY
-recommended that you run it on a recent distribution (such as <a
- href="http://www.redhat.com">Red Hat</a> 7.3 or newer). A new-ish
+<p>If you are running Citadel on a Linux system, it is STRONGLY
+recommended that you run it on a recent distribution (such as Fedora
+Core 3 or newer). A new-ish
distribution will have most or all of the prerequisite tools and
libraries already integrated for you.</p>
-<h3>Now available:</h3>
+<h3>Other pieces which complete the Citadel system:</h3>
<ul>
<li>"WebCit", a gateway program to allow full access to Citadel via
the World Wide Web. Interactive access through any Web browser. </li>
<li>Access to Citadel via <i>any</i> standards-compliant e-mail
program, thanks to Citadel's built-in SMTP, POP, and IMAP services.
- You can use Netscape/Mozilla, Evolution, Eudora, Pine, or even
-Microsoft
-VirusSpreader (better known as "Outlook") with Citadel. </li>
+You can use Mozilla, Netscape, Evolution, Eudora, Pine, Outlook, etc.
+with Citadel.</li>
+ <li>Access to Citadel's calendar and address book functions using any
+GroupDAV-enabled PIM client (requires WebCit).<br>
+ </li>
</ul>
<h3>Coming soon:</h3>
<ul>
- <li>Newer and better GUI-based clients.</li>
+ <li>More integration with third-party software.<br>
+ </li>
</ul>
<h3><a name="Everything_in_its_place..."></a>Everything in its place...</h3>
<p>Hopefully you've unpacked the distribution archive into its own
might need it.<br>
<br>
</p>
-<h3><a name="The_BBS_Login"></a>Creating a system account for Citadel</h3>
+<h3><a name="ctdl_login_acct"></a>Creating a system account for Citadel</h3>
<p>As with many Unix programs, Citadel wants to run under its own user
ID. Unlike other programs, however, this user ID will do double-duty as
a public login for your system if you are running a BBS. This account
"citadel" in
that directory, or a script that will start up the citadel client.
Example:</p>
-<pre>bbs::100:1:Citadel Login:/usr/local/citadel:/usr/local/citadel/citadel<br></pre>
+<pre>citadel::100:1:Citadel Login:/usr/local/citadel:/usr/local/citadel/citadel<br></pre>
<p>When you run setup later, you will be required to tell it the
username or user ID of the account you created is, so it knows what
-user to run as. If you create an account called <tt>bbs</tt>, <tt>guest</tt>,
-or <tt>citadel</tt>, the setup program will automatically pick up the
+user to run as. If you create an account called <tt>citadel, bbs</tt>,
+or <tt>guest</tt>, the setup program will automatically pick up the
user ID by default.</p>
-<p>For all other users in /etc/passwd, Citadel will automatically set
-up
+<p>For all other users in /etc/passwd (or in some other name service
+such as NIS), Citadel will automatically set up
an account using the full name (or 'gecos' in Unixspeak) of the user.
It'll also ignore any password you supply, because it uses the user's
password
computer, and their password on the host computer.<br>
<br>
</p>
-<h3><a name="Bypassing_the_login:_prompt"></a>Bypassing the <tt>login:</tt>
+<h3><a name="bypassing_login"></a>Bypassing the <tt>login:</tt>
prompt</h3>
<p>If you normally log in to your host system using some method other
than telnet (such as ssh), you might want the telnet service to go
straight into Citadel, instead of displaying the <tt>login:</tt>
prompt first. You
-can do this by having telnetd start citadel directly instead of <tt>/bin/login</tt>.
-This is actually very simple to implement; all you need to do is make a
+can do this by having telnetd start citadel directly instead of
+<tt>/bin/login</tt>. The <tt>setup</tt> program will offer to
+configure
+this automatically for you if it sees a configuration it understands.
+If you would prefer to configure it manually, all you need to do is
+make a
simple change to your <tt>inetd</tt> or <tt>xinetd</tt>
configuration. Here are some configuration examples.</p>
<p>An example for <tt>inetd</tt> (put the following line in <tt>/etc/inetd.conf</tt>,
configuration
accordingly as well. And, of course, if you're working remotely, make
sure you can successfully log in using SSH <b>before</b> you start
-changing
-your telnet configuration, otherwise you could lock yourself out of
-your
-system (ask any networking specialist about the dangers of "working
-inband"
--- then pull up a chair and get a fresh cup of coffee, because you're
-going
-to hear some war stories).<br>
+making
+changes to telnet, because if you accidentally break telnet and don't
+have
+SSH running, you'll have effectively locked yourself out of your system
+until you can get physical access to the console.<br>
<br>
</p>
<h3><a name="Compiling_the_programs"></a>Compiling the programs</h3>
<p>Upgrading to a new version uses the same build procedure as
compiling
the program for a fresh install, except that you want to do <tt>make
-install-exec</tt> instead of <tt>make install</tt>. This will
+upgrade</tt> instead of <tt>make install</tt>. This will
overwrite the programs but not your data. <b>Be sure to shut down
citserver during this process!</b> If Citadel is running while you
upgrade, you may face data corruption issues.<br>
</p>
-<p>After doing <tt>make install-exec</tt>, you should run <tt>setup</tt>
+<p>After doing <tt>make upgrade</tt>, you should run <tt>setup</tt>
again to bring your data files up to date. Please see the setup section
below for more information on this.</p>
-<h3><a name="The_citadel.rc_file"></a>The <tt>citadel.rc</tt> file</h3>
+<h3><a name="rc_file"></a>The <tt>citadel.rc</tt> file</h3>
<p>The text-based client included with Citadel is suitable for BBS
applications. Much of its command set and other behavior is
configurable through a Run Control (RC) file. The standard client looks
<h3><a name="Using_an_external_editor_for_message"></a>Using an
external editor
for message composition</h3>
-<p>Citadel/UX has a built-in message editor. However, you can also use
+<p>Citadel has a built-in message editor. However, you can also use
your favorite text editor to write messages. To do this you simply put
a line in your citadel.rc file like this:</p>
<pre>editor=/usr/bin/vi<br></pre>
<p>The above example would make Citadel call the vi editor when using
-the <tt><b>.E</b>nter <b>E</b>ditor</tt> command. You can also make
+the <tt><b>.E</b>nter <b>E</b>ditor</tt> command, or when a user
+selects the "Always compose messages with the full-screen
+editor" option. You can also make
it the default editor for the <tt><b>E</b>nter</tt> command by editing
the <tt>citadel.rc</tt> file. <b>But be warned:</b> external editors
on public systems can
commands disabled, as well as any other functions which a destructive
user could use to gain unauthorized access to your host system.</p>
<h3><a name="Printing_messages"></a>Printing messages</h3>
-<p>Citadel/UX can send messages to a printer, or just about anywhere
+<p>Citadel can send messages to a printer, or just about anywhere
else in your system. The variable <tt>PRINTCMD</tt> in <tt>citadel.rc</tt>
specifies what command you use to print. Text is sent to the standard
input (stdin) of the print command.</p>
<p>So if you did this:</p>
-<pre>printcmd="nl|pr|lpr -Plocal"<br></pre>
-<p>...that would add line numbers, then paginate, then print on the
+<pre>printcmd="a2ps -o - |lpr -Plocal"<br></pre>
+<p>...that would convert the printed text to PostScript, then print on
+the
printer named "local". There's tons of stuff you can do with this
feature. For example, you could use a command like <tt>cat
<<$HOME/archive</tt> to save copies of important messages in a
<p>Before you can use Citadel, you must define the "citadel" service to
your system. This is accomplished by adding a line to your
/etc/services file that looks something like this:</p>
-<pre>citadel 504/tcp # Citadel/UX Server<br></pre>
+<pre>citadel 504/tcp # Citadel Server<br></pre>
<p>504 is the port number officially designated by the IANA for use by
Citadel. There should not be any need to use a different port number,
unless you are running multiple Citadels on the same computer and
specified, the directory
name which was specified in the <tt>Makefile</tt> will be used.</p>
<p><tt>-xDebugLevel</tt> - Set the verbosity of trace messages printed.
-When -x is used, it will suppress messages sent to syslog (see below). In
-other words, syslog will never see certain messages if -x is used. Normally
-you should configure logging through syslog, but -x may still be useful in
-some circumstances. The available debugging levels are: </p>
+When -x is used, it will suppress messages sent to syslog (see below).
+In
+other words, syslog will never see certain messages if -x is used.
+Normally
+you should configure logging through syslog, but -x may still be useful
+in
+some circumstances. The available debugging levels are: </p>
<ul>
<li>0 - Emergency condition; Citadel will exit immediately </li>
- <li>1 - Severe errors; Citadel may be unable to continue without attention </li>
- <li>2 - Critical errors; Citadel will continue with degraded functionality </li>
+ <li>1 - Severe errors; Citadel may be unable to continue without
+attention </li>
+ <li>2 - Critical errors; Citadel will continue with degraded
+functionality </li>
<li>3 - Error conditions; Citadel will recover and continue normally </li>
<li>4 - Warning messages; Citadel will continue normally </li>
<li>5 - Normal operational messages </li>
</ul>
<p><tt>-tTraceFile</tt> - Tell the server where to send its debug/trace
output. Normally it is sent to stdout.</p>
-<p><tt>-lLogFacility</tt> - Tell the server to send its debug/trace output
-to the <tt>syslog</tt> service on the host system <i>instead of</i> to a
-trace file. <tt>LogFacility</tt> must be one of: <tt><i>kern, user, mail,
+<p><tt>-lLogFacility</tt> - Tell the server to send its debug/trace
+output
+to the <tt>syslog</tt> service on the host system <i>instead of</i>
+to a
+trace file. <tt>LogFacility</tt> must be one of: <tt><i>kern, user,
+mail,
daemon, auth, syslog, lpr, news, uucp, local0, local1, local2, local3,
-local4, local5, local6, local7</i></tt>. Please note that use of the
-<tt>-l</tt> option will cancel any use of the <tt>-t</tt> option; that is,
-if you specify a trace file <i>and</i> a syslog facility, log output will
+local4, local5, local6, local7</i></tt>. Please note that use of the
+<tt>-l</tt> option will cancel any use of the <tt>-t</tt> option; that
+is,
+if you specify a trace file <i>and</i> a syslog facility, log output
+will
only go to the syslog facility.
+</p>
<p><tt>-d</tt> - Run as a daemon; i.e. in the background. This switch
would be necessary if you were starting the Citadel server, for
example, from an rc.local script (which is not recommended, because
the computer.<br>
<br>
</p>
-<h3><a name="Logging_in_for_the_first_time"></a>Logging in for the
+<h3><a name="first_time_login"></a>Logging in for the
first time</h3>
<p>At this point, your system is ready to run. Run the <tt>citadel</tt>
program from the shell and log in as a new user. NOTE: the first user
looking at the same copy of the message on disk.<br>
<br>
</p>
-<h3><a name="Space_for_adding_your_own_client"></a>Space for adding
+<h3><a name="adding_doors"></a>Space for adding
your own
client features (doors)</h3>
<p><b>Please take note!</b> This function really represents the "old"
</ul>
</div>
<div align="center">
-<hr width="100%" size="2">
+<hr size="2" width="100%">
<h2><a name="sysop"></a>System Administration</h2>
</div>
<div align="justify">
<h3><a name="Overview_"></a>Overview</h3>
-<p>Citadel/UX, when installed properly, will do most of its maintenance
+<p>Citadel, when installed properly, will do most of its maintenance
by itself. It is intended to be run unattended for extended periods of
time, and most installations do just that without any software failures.</p>
<p>The system has seven access levels. Most users are at the bottom and
they become a certain number of days old, or until a certain number of
additional messages are posted in the room, at which time the oldest
ones will scroll out.</p>
+<p>When a new Citadel system is first installed, the default
+system-wide
+expire policy is set to 'manual' -- no automatic purging of messages
+takes place anywhere. For public message boards, you will probably want
+to set some sort of automatic expire policy, in order to prevent your
+message base from growing forever.</p>
<p>You will notice that you can also fall back to the default expire
policy for the floor upon which the room resides. This is the default
setting. You can change the floor's default with the <tt><b>;A</b>ide <b>E</b>dit
<p>There are several strings that you can put in help files that will
be automatically
substituted with other strings. They are:</p>
-<pre> <br> ^nodename = The node name of your system on a Citadel/UX network<br> ^humannode = Human-readable node name (also your node name on C86Net)<br> ^fqdn = Your system's fully-qualified domain name<br> ^username = The name of the user reading the help file<br> ^usernum = The user number of the user reading the help file<br> ^sysadm = The name of the system administraor (i.e., you)<br> ^variantname = The name of the software you're running<br> ^bbsdir = The directory on the host system in which you have<br> installed the Citadel system.<br></pre>
+<pre> <br> ^nodename = The node name of your system on a Citadel network<br> ^humannode = Human-readable node name (also your node name on C86Net)<br> ^fqdn = Your system's fully-qualified domain name<br> ^username = The name of the user reading the help file<br> ^usernum = The user number of the user reading the help file<br> ^sysadm = The name of the system administraor (i.e., you)<br> ^variantname = The name of the software you're running<br> ^bbsdir = The directory on the host system in which you have<br> installed the Citadel system.<br></pre>
<p>So, for example, you could create a help file which looked like:</p>
<pre> "Lots of help, of course, is available right here on ^humannode. Of<br>course, if you still have trouble, you could always bug ^sysadm about it!"<br><br></pre>
<h3><a name="Site_configuration"></a>Site configuration</h3>
the system. (This access level may also be granted to a user only for a
specific room, please see 'Room Aide' for more information.) </li>
</ul>
-<pre>Require registration for new users [No]: No<br>Disable self-service user account creation [No]: No<br>Initial access level for new users [4]:<br>Access level required to create rooms [4]: <br>Automatically give room aide privs to a user who creates a private room [No]: No<br><br>Automatically move problem user messages to twit room [Yes]: Yes<br>Name of twit room [Trashcan]: <br>Restrict Internet mail to only those with that privilege [No]: No<br>Allow Aides to Zap (forget) rooms [Yes]: Yes<br>Allow system Aides access to user mailboxes [Yes]: Yes<br>Log all pages [No]: No<br></pre>
+<pre>Require registration for new users [No]: No<br>Disable self-service user account creation [No]: No<br>Initial access level for new users [4]:<br>Access level required to create rooms [4]: <br>Automatically give room aide privs to a user who creates a private room [No]: No<br><br>Automatically move problem user messages to twit room [Yes]: Yes<br>Name of twit room [Trashcan]: <br>Restrict Internet mail to only those with that privilege [No]: No<br>Allow Aides to Zap (forget) rooms [Yes]: Yes<br>Log all pages [No]: No<br></pre>
<p>'Registration' refers to the process of a user entering various
personal contact information (real name, address, telephone number,
etc.) into the system. When enabled, this information is stored as a
privilege.' Obviously this makes no sense for an internal e-mail
system, but for a public BBS it
might be appropriate.</p>
-<p>Normally, Aides have access to every room, public or private, except
-for user mailboxes. They are also forbidden from <tt><b>Z</b>ap</tt>ping
+<p>Normally, Aides have access to every room, public or private.
+They are also forbidden from <tt><b>Z</b>ap</tt>ping
rooms, because the review of content is considered one of their roles.
If you wish to change these policies, the next two options allow you
to. You may 'Allow Aides to Zap (forget) rooms', in which case they may
use the <tt><b>Z</b>ap</tt> command just like any other user.
-Furthermore, if you 'Allow system Aides access to user mailboxes', then
-they may <tt><b>.G</b>oto</tt> any private mailbox belonging to any
+Aides may also <tt><b>.G</b>oto</tt> any private mailbox belonging to
+any
user, using a special room name format.</p>
<p>If your local security and/or privacy policy dictates that you keep
a
copy.</p>
<p>The next set of options deals with the tuning of your system. It is
usually safe to leave these untouched.</p>
-<pre>Server connection idle timeout (in seconds) [900]: <br>Maximum concurrent sessions [20]: <br>Maximum message length [2147483647]: <br>Minimum number of worker threads [5]: <br>Maximum number of worker threads [256]: <br></pre>
+<pre>Server connection idle timeout (in seconds) [900]: <br>Maximum concurrent sessions [20]: <br>Maximum message length [10000000]: <br>Minimum number of worker threads [5]: <br>Maximum number of worker threads [256]: <br>Automatically delete committed database logs [Yes]:<br></pre>
<p>The 'Server connection idle timeout' is for the connection between
client and server software. It is <b>not</b> an idle timer for the
user interface. 900 seconds (15 minutes) is the default and a sane
sessions
with a much smaller thread pool. If you don't know the programming
theory
-behind multithreaded servers, you should leave these parameters alone.</p>
+behind multithreaded servers, you should leave these parameters alone.<br>
+</p>
+<p>'Automatically delete committed database logs' is a <span
+ style="font-style: italic;">crucial</span> setting which affects your
+system's disk utilization and backup recoverability. Please refer
+to the <a href="#Database_maintenance">database maintenance</a>
+section of this document to learn how the presence or absence of
+database logs affect your ability to reliably backup your Citadel
+system.<br>
+</p>
<p>The next set of options affect how Citadel behaves on a network.</p>
-<pre>How often to run network jobs (in seconds) [3600]: <br><br>POP3 server port (-1 to disable) [110]:<br><br>IMAP server port (-1 to disable) [143]:<br><br>SMTP server port (-1 to disable) [25]: <br><br>Correct forged From: lines during authenticated SMTP [Yes]:<br><br></pre>
-<p>"How often to run network jobs" refers to the sharing of content on
-a
-Citadel network. If your system is on a Citadel network, this
-configuration
-item dictates how often the Citadel server will contact other Citadel
-servers to send and receive messages. In reality, this will happen more
-frequently than you specify, because other Citadel servers will be
-contacting yours at regular intervals as well.</p>
+<pre>Server IP address (0.0.0.0 for 'any') [0.0.0.0]:<br>POP3 server port (-1 to disable) [110]:<br>POP3S server port (-1 to disable) [995]:<br>IMAP server port (-1 to disable) [143]:<br>IMAPS server port (-1 to disable) [993]:<br>SMTP MTA server port (-1 to disable) [25]:<br>SMTP MSA server port (-1 to disable) [587]:<br>SMTPS server port (-1 to disable) [465]:<br>Correct forged From: lines during authenticated SMTP [Yes]:<br>Allow unauthenticated SMTP clients to spoof my domains [No]: No<br>Instantly expunge deleted IMAP messages [No]: Yes<br></pre>
+<p>"Server IP address" refers to the IP address on <span
+ style="font-style: italic;">your server</span> to which Citadel's
+protocol services should be bound. Normally you will leave this
+set to 0.0.0.0, which will cause Citadel to listen on all of your
+server's interfaces. However, if you are running multiple
+Citadels on a server with multiple IP addresses, this is where you
+would specify which one to bind this instance of Citadel to.</p>
<p>Then you can specify TCP port numbers for the SMTP, POP3, and IMAP
services. For a system being used primarily for Internet e-mail, these
are essential, so you'll want to specify the standard port numbers: 25,
though, then you might want to choose other, unused port numbers, or
enter -1 for any protocol
to disable it entirely.</p>
+<p>You'll also notice that you can specify two port numbers for SMTP:
+one
+for MTA (Mail Transport Agent) and one for MSA (Mail Submission Agent).
+The
+traditional ports to use for these purposes are 25 and 587. If you are
+running an external MTA, such as Postfix (which submits mail to Citadel
+using
+LMTP) or Sendmail (which submits mail to Citadel using the 'citmail'
+delivery agent), that external MTA will be running on port 25, and you
+should
+specify "-1" for the Citadel MTA port to disable it. The MSA port
+(again,
+usually 587) would be the port used by end-user mail client programs
+such as
+Aethera, Thunderbird, Eudora, or Outlook, to submit mail into the
+system.
+All connections to the MSA port <b>must</b> use Authenticated SMTP.<br>
+</p>
+<p>The protocols ending in "S" (POP3S, IMAPS, and SMTPS) are
+SSL-encrypted. Although all of these protocols support the
+STARTTLS command, older client software sometimes requires connecting
+to "always encrypted" server ports. Usually when you are looking
+at a client program that gives you a choice of "SSL or TLS," the SSL
+option will connect to one of these dedicated ports, while the TLS
+option will connect to the unencrypted port and then issue a STARTTLS
+command to begin encryption. (It is worth noting that this is <span
+ style="font-style: italic;">not</span> the proper use of the acronyms
+SSL and TLS, but that's how they're usually used in many client
+programs.)<br>
+</p>
+<p>All of the default port numbers, including the encrypted ones, are
+the standard ones.<br>
+</p>
<p>The question about correcting forged From: lines affects how Citadel
behaves with authenticated SMTP clients. Citadel does not ever allow
third-party SMTP relaying from unauthenticated clients -- any incoming
this behavior, answer 'No' at the prompt (the default is 'Yes') and the
headers
will never be altered.</p>
+<p>"Instant expunge" affects what happens when IMAP users delete
+messages. As you may already know, messages are not <i>truly</i> deleted
+when an IMAP client sends a delete command; they are only <i>marked for
+deletion</i>. The IMAP client must also send an "expunge" command
+to actually delete the message. The Citadel server automatically expunges
+messages when the client logs out or selects a different folder, but if you
+select the Instant Expunge option, an expunge operation will automatically
+follow any delete operation (and the client will be notified, preventing any
+mailbox state problems). This is a good option to select, for example, if you
+have users who leave their IMAP client software open all the time and are
+wondering why their deleted messages show up again when they log in from a
+different location (such as WebCit).</p>
+<p>"Allow spoofing" refers to the security level applied to
+non-authenticated SMTP clients. Normally, when another host connects to
+Citadel via SMTP to deliver mail, Citadel will reject any attempt to send
+mail whose sender (From) address matches one of your host's own domains. This
+forces your legitimate users to authenticate properly, and prevents foreign
+hosts (such as spammers) from forging mail from your domains. If, however,
+this behavior is creating a problem for you, you can select this option to
+bypass this particular security check.<br>
+<span style="font-family: monospace;"><br>
+Connect this Citadel to an LDAP directory [No]: No</span><br>
+</p>
+<p>The LDAP configuration options are discussed elsewhere in this
+document.<br>
+</p>
<p>The final set of options configures system-wide defaults for the
auto-purger:</p>
-<pre>Default user purge time (days) [120]: <br>
-Default room purge time (days) [30]: <br>
-System default message expire policy (? for list) [2]: <br>
-Keep how many messages online? [150]:<br>
-Mailbox default message expire policy (? for list) [1]: <br>
-</pre>
+<pre>Default user purge time (days) [120]: <br>Default room purge time (days) [30]: <br>System default message expire policy (? for list) [0]: <br>Keep how many messages online? [150]:<br>Mailbox default message expire policy (? for list) [0]:<br>How often to run network jobs (in seconds) [1800]:<br>Enable full text search index (warning: resource intensive) [Yes]: Yes<br>Hour to run purges (0-23) [4]:<br>
+Perform journaling of email messages [No]:<br>Perform journaling of non-email messages [No]:<br>Email destination of journalized messages [example@example.com]:<br></pre>
<p>Any user who does not log in for the period specified in 'Default
user purge time' will be deleted the next time a purge is run. This
setting may be modified on a per-user basis.</p>
<li>Do not purge at all </li>
</ul>
<p>Again, this setting may be overridden on a per-floor basis, and the
-floor setting may be overridden on a per-room basis. You'll also notice
-that you can set a <i>different</i> default for mailbox rooms if you want
-to. This can allow you, for example, to set a policy under which old
-messages scroll out of public rooms, but private mail stays online indefinitely
-until deleted by the mailbox owners.</p>
-<pre>Save this configuration? No<br></pre>
+floor setting may be overridden on a per-room basis. You'll also notice
+that you can set a <i>different</i> default for mailbox rooms if you
+want
+to. This can allow you, for example, to set a policy under which old
+messages scroll out of public rooms, but private mail stays online
+indefinitely
+until deleted by the mailbox owners.<br>
+</p>
+<p>"How often to run network jobs" refers to the sharing of content on
+a
+Citadel network. If your system is on a Citadel network, this
+configuration
+item dictates how often the Citadel server will contact other Citadel
+servers to send and receive messages. In reality, this will happen more
+frequently than you specify, because other Citadel servers will be
+contacting yours at regular intervals as well.<br>
+</p>
+<p>"Hour to run purges" determines when expired and/or deleted objects
+are purged from the database. These purge operations are
+typically run overnight and automatically, sometime during whatever
+hour you specify. If your site is much busier at night than
+during the day, you may choose to have the auto-purger run during the
+day.</p>
+<p>"Enable full text search index," if enabled, instructs the server to
+build and maintain a searchable index of all messages on the
+system. This is a time and resource intensive process -- it could
+take days to build the index if you enable it on a large
+database. It is also fairly memory intensive; we do not recommend
+that you enable the index unless your host system has at least 512 MB
+of memory. Once enabled, however, it will be updated
+incrementally
+and will not have any noticeable impact on the interactive response
+time of your system. The full text index is currently only
+searchable when using IMAP clients; other search facilities will be
+made available in the near future.</p>
+<p>The "Perform journaling..." options allow you to configure
+your Citadel server to send an extra copy of every message, along with
+recipient information if applicable, to the email address of your choice.
+The journaling destination address may be an account on the local Citadel
+server, an account on another Citadel server on your network, or an Internet
+email address. These options, used in conjunction with an archiving service,
+allow you to build an archive of all messages which flow through your Citadel
+system. This is typically used for regulatory compliance in industries which
+require such things. Please refer to the <a href="journaling.html">journaling
+guide</a> for more details on this subject.</p>
+<p><span style="font-family: monospace;">Save this configuration? No</span><br>
+</p>
<p>When you're done, enter 'Yes' to confirm the changes, or 'No' to
discard the changes.</p>
</div>
-<hr width="100%" size="2">
+<hr size="2" width="100%">
<h2 align="center"><a name="Configuring_Citadel_for_Internet_e-mail"></a>Configuring
Citadel for Internet e-mail</h2>
<div align="justify">
<li>Easy-to-configure integration with <a
href="http://www.spamassassin.org/">SpamAssassin</a> can block spam <i>before</i>
it enters the mail system</li>
- <li>Easy-to-configuration integration with most Realtime Blackhole
+ <li>Easy-to-configure integration with most Realtime Blackhole
Lists (RBL) provide further defense against spammers</li>
</ul>
This section of the documentation will demonstrate how to configure
To configure this
functionality, simply enter the domain name or IP address of your relay
as a 'smart-host' entry.</p>
+<p>If your relay server is running on a port other
+than the standard SMTP port 25, you can also specify the port number
+using "host:port" syntax; i.e. <tt>relay99.myisp.com:2525</tt></p>
+<p>Furthermore, if your relay server requires authentication, you can
+specify it using username:password@host or username:password@host:port
+syntax; i.e. <tt>jsmith:pass123@relay99.myisp.com:25</tt></p>
<p><b>directory:</b> a domain for which you are participating in
directory services across any number of Citadel nodes. For example, if
users who have addresses in the domain <tt>citadel.org</tt> are spread
server from a shell and watch it load. It might look something like
this:</p>
<font size="-2"> </font>
-<pre><font size="-2">smw @ pixel % ./citserver<br><br>Multithreaded message server for Citadel/UX<br>Copyright (C) 1987-2003 by the Citadel/UX development team.<br>Citadel/UX is open source, covered by the GNU General Public License, and<br>you are welcome to change it and/or distribute copies of it under certain<br>conditions. There is absolutely no warranty for this software. Please<br>read the 'COPYING.txt' file for details.<br><br>Loading citadel.config<br>Opening databases<br>This is GDBM version 1.8.0, as of May 19, 1999.<br>Checking floor reference counts<br>Creating base rooms (if necessary)<br>Registered a new service (TCP port 504)<br>Registered a new service (TCP port 0)<br>Initializing loadable modules<br>Registered server command CHAT (Begin real-time chat)<br>Registered server command PEXP (Poll for express messages)<br>Registered server command GEXP (Get express messages)<br>Registered server command SEXP (Send an express message)<br>Registered server command DEXP (Disable express messages)<br>Registered a new session function (type 0)<br>Registered a new x-msg function (priority 0)<br>Loaded module: $Id$<br>Registered a new session function (type 1)<br>Registered a new message function (type 201)<br>Registered a new message function (type 202)<br>Registered server command REGI (Enter registration info)<br>Registered server command GREG (Get registration info)<br>Registered a new user function (type 100)<br>Loaded module: $Id$<br>Server-hosted upgrade level is 5.62<br>Loaded module: $Id$<br>Registered server command EXPI (Expire old system objects)<br>Registered server command FSCK (Check message ref counts)<br>Loaded module: $Id$<br><b>citserver: Can't bind: Address already in use<br>ERROR: could not bind to TCP port 25.</b><br>Registered a new service (TCP port 0)<br>Registered a new session function (type 50)<br>Loaded module: $Id$<br><b>citserver: Can't bind: Address already in use<br>ERROR: could not bind to TCP port 110.</b><br>Registered a new session function (type 0)<br>Loaded module: $Id$<br>Registered a new message function (type 202)Loaded module: $Id$<br>Registered server command RWHO (Display who is online)<br>Registered server command HCHG (Masquerade hostname)<br>Registered server command RCHG (Masquerade roomname)<br>Registered server command UCHG (Masquerade username)<br>Registered server command STEL (Enter/exit stealth mode)<br>Loaded module: $Id$<br>Changing uid to 513<br>Starting housekeeper thread<br></font></pre>
+<pre><font size="-2">smw @ pixel % ./citserver<br><br>Multithreaded message server for Citadel<br>Copyright (C) 1987-2003 by the Citadel development team.<br>Citadel is open source, covered by the GNU General Public License, and<br>you are welcome to change it and/or distribute copies of it under certain<br>conditions. There is absolutely no warranty for this software. Please<br>read the 'COPYING.txt' file for details.<br><br>Loading citadel.config<br>Opening databases<br>This is GDBM version 1.8.0, as of May 19, 1999.<br>Checking floor reference counts<br>Creating base rooms (if necessary)<br>Registered a new service (TCP port 504)<br>Registered a new service (TCP port 0)<br>Initializing loadable modules<br>Registered server command CHAT (Begin real-time chat)<br>Registered server command PEXP (Poll for instant messages)<br>Registered server command GEXP (Get instant messages)<br>Registered server command SEXP (Send an instant message)<br>Registered server command DEXP (Disable instant messages)<br>Registered a new session function (type 0)<br>Registered a new x-msg function (priority 0)<br>Loaded module: $Id$<br>Registered a new session function (type 1)<br>Registered a new message function (type 201)<br>Registered a new message function (type 202)<br>Registered server command REGI (Enter registration info)<br>Registered server command GREG (Get registration info)<br>Registered a new user function (type 100)<br>Loaded module: $Id$<br>Server-hosted upgrade level is 5.62<br>Loaded module: $Id$<br>Registered server command EXPI (Expire old system objects)<br>Registered server command FSCK (Check message ref counts)<br>Loaded module: $Id$<br><b>citserver: Can't bind: Address already in use<br>ERROR: could not bind to TCP port 25.</b><br>Registered a new service (TCP port 0)<br>Registered a new session function (type 50)<br>Loaded module: $Id$<br><b>citserver: Can't bind: Address already in use<br>ERROR: could not bind to TCP port 110.</b><br>Registered a new session function (type 0)<br>Loaded module: $Id$<br>Registered a new message function (type 202)Loaded module: $Id$<br>Registered server command RWHO (Display who is online)<br>Registered server command HCHG (Masquerade hostname)<br>Registered server command RCHG (Masquerade roomname)<br>Registered server command UCHG (Masquerade username)<br>Registered server command STEL (Enter/exit stealth mode)<br>Loaded module: $Id$<br>Changing uid to 513<br>Starting housekeeper thread<br></font></pre>
<p>The lines emphasized in boldface in the above log output tell you
that Citadel "can't bind" to various ports. The error 'address already
in use' generally means that something else is already running on the
However, it is beyond the scope of this document to detail the finer
points of the configuration of Postfix or any other mailer, so refer to
the documentation to those programs and keep in mind that Citadel has
-LMTP support.<span style="font-family: monospace;"><br>
-</span></p>
-<p><span style="font-family: monospace;"></span>For outbound mail, you
+LMTP support.<span style="font-family: monospace;"></span></p>
+<p>There are actually <i>two</i> LMTP sockets. One is called
+<tt>lmtp.socket</tt> and the other is called <tt>lmtp-unfiltered.socket</tt>
+(both are found in your Citadel directory). The difference should be
+obvious: messages submitted via <tt>lmtp.socket</tt> are subject to
+any
+spam filtering you may have configured (such as SpamAssassin), while
+messages
+submitted via <tt>lmtp-unfiltered.socket</tt> will bypass the filters.
+You
+would use the filtered socket when receiving mail from an external MTA
+such
+as Postfix, but you might want to use the unfiltered socket with
+utilities
+such as fetchmail.</p>
+<br>
+<p>For outbound mail, you
can either allow Citadel to perform
deliveries directly
(this won't affect your other mail system because outbound mail doesn't
<p>In order to prevent "just anyone" from subscribing to any room on
your system, there is a setting in the <tt><b>.A</b>ide <b>E</b>dit
room</tt> command:</p>
-<pre>CitaNews} . Aide Edit this room<br>Room name [CitaNews]:<br><br><i>(lots of other stuff omitted for brevity...)</i><br><br>Self-service list subscribe/unsubscribe [No]: Yes<br></pre>
+<pre>CitaNews} . Aide Edit this room<br>
+Room name [CitaNews]:<br>
+<br>
+<i>(lots of other stuff omitted for brevity...)</i><br>
+<br>
+Self-service list subscribe/unsubscribe [No]: Yes<br></pre>
<p>When you answer "Yes" to self-service list subscribe/unsubscribe,
you are
enabling that feature. Now, all you have to do is tell the world about
URL's
in your e-mail software) and the confirmation is automatically
completed.</p>
-<hr width="100%" size="2">
+<hr size="2" width="100%">
<center>
<h2><a name="Building_or_joining_a_Citadel_network"></a>Building or
joining a Citadel network</h2>
A few small data files are kept in your main Citadel directory, but the
databases are in the <tt>data/</tt> subdirectory. The files with
names that begin with "cdb" are the databases themselves; the files
-with names that begin with "log" are the journals. Journal files
-will come and go as you use your system; when the database engine has
-determined that a particular log file is no longer needed, the file
-will automatically be deleted. Nevertheless, you should always
-ensure that there is ample disk space for the files to grow.<br>
+with names that begin with "log" are the logs (sometimes referred to as
+"journals"). Log files will continue to appear as you use your
+system; each will grow to approximately 10 megabytes in size before a
+new one is started. There is a system configuration setting
+(found in <span style="font-family: monospace;"><span
+ style="font-weight: bold;">.A</span>ide <span
+ style="font-weight: bold;">S</span>ystem-configuration <span
+ style="font-weight: bold;">G</span>eneral</span> in the text mode
+client, or in <span style="font-family: monospace;">Administration
+--> Edit site-wide configuration --> Tuning</span> in the WebCit
+client) which specifies "Automatically delete committed database
+logs." If you have this option enabled, Citadel will
+automatically delete any log files whose contents have been fully
+committed to the database files.<br>
+<br>
+For more insight into how the database and log files work, you may wish
+to read the <a
+ href="http://www.sleepycat.com/docs/ref/transapp/archival.html">Berkeley
+DB documentation</a> on this subject.<br>
+<br>
+<h3><a name="Backing_up_your_Citadel_database"></a>Backing up your
+Citadel database</h3>
+<span style="font-weight: bold;">Please read this section carefully.</span><br>
+<br>
+There are two backup strategies you can use, depending on your site's
+availability requirements and disk space availability.<br>
+<h5>Strategy #1: Standard backup</h5>
+The standard (or "offline") backup is used when your Citadel server is
+configured to automatically delete committed database logs. The
+backup procedure is as follows:<br>
+<ol>
+ <li>Shut down the Citadel server.</li>
+ <li>Back up all files (database files, log files, etc.) to tape or
+some other backup media.</li>
+ <li>Start the Citadel server.</li>
+</ol>
+<span style="font-style: italic;">Advantage:</span> very little disk
+space is consumed by the logs.<br>
+<span style="font-style: italic;">Disadvantage:</span> Citadel is not
+available during backups.<br>
+<br>
+<h5>Strategy #2: "Hot" backup</h5>
+The "hot backup" procedure is used when your Citadel server is
+configured <span style="font-weight: bold;">not</span> to
+automatically delete committed database logs. The backup
+procedure is as follows:<br>
+<ol>
+ <li>Back up all files. Make sure the database files (<span
+ style="font-family: monospace;">cdb.*</span>) are backed up <span
+ style="font-style: italic;">before</span> the log files (<span
+ style="font-family: monospace;">log.*</span>). This will usually
+be the case, because the database files tend to appear first in both
+alphabetical and on-disk ordering of the <span
+ style="font-family: monospace;">data/</span> directory.</li>
+ <li>After verifying that your backup completed successfully, delete
+the committed log files with a command like this:</li>
+</ol>
+<span style="font-family: monospace;">/usr/local/citadel/sendcommand
+"CULL"</span><br>
+<br>
+<span style="font-style: italic;">Advantage:</span> Citadel continues
+to run normally during backups.<span style="font-style: italic;"><br>
+Disadvantage:</span> Much disk space is consumed by the log files,
+particularly if the full text indexer is turned on.<br>
+<br>
<br>
-There is no need to shut down Citadel during backups. The data
-store may be backed up "hot." The makers of Berkeley DB suggest
-that you should back up the data files <i>first</i> and the log files <i>second</i>.
- This is the only method that will guarantee that a database which
-is being changed while you back it up will still be usable when you
-restore it
-from the tape later.<br>
+It is up to you to decide which backup strategy to use. <span
+ style="font-weight: bold;">Warning: if you configure Citadel to
+automatically delete committed database logs, and do not shut the
+Citadel service down during backups, there is no guarantee that your
+backups will be usable!</span><br>
<br>
<h3><a name="Database_repair"></a>Database repair</h3>
Although Citadel's data store is quite reliable, database corruption
<h3><a name="ImportingExporting_your_Citadel"></a>Importing/Exporting
your Citadel database<br>
</h3>
-<p>Citadel/UX contains an importer/exporter module, affectionately
+<p>Citadel contains an importer/exporter module, affectionately
known as the "Art Vandelay" module (a not-so-obscure Seinfeld
reference). It
allows you to export the entire contents of your Citadel databases to a
</ol>
<hr>
<center>
+<h2><a name="crypto"></a>Cryptography support (TLS/SSL)</h2>
+</center>
+<h3><a name="crypto_intro"></a>Overview</h3>
+<p>Citadel provides built-in support for encryption using Transport
+Layer Security (TLS) for ESMTP, IMAP, POP3, and the Citadel client
+protocol.
+A simple cryptographic configuration is installed automatically when
+you
+bring the system online. The remainder of this section describes how
+this
+configuration is built, and what you can do to make changes to it.</p>
+<p>Encryption files are kept in the <tt>keys/</tt> directory. The
+three
+files used by Citadel are:</p>
+<ul>
+ <li><tt>citadel.key</tt> - Contains your system's RSA private key.
+Citadel
+generates a new key automatically if one is not found. </li>
+ <li><tt>citadel.csr</tt> - Contains a Certificate Signing Request
+(CSR)
+for your system. Citadel generates a new CSR automatically, using your
+private key, if one is not found. </li>
+ <li><tt>citadel.cer</tt> - Contains the public certificate for your
+system. The public key in the certificate <b>must</b> correspond with
+the
+private key in <tt>citadel.key</tt>, otherwise encryption will not
+function properly. Citadel will generate a self-signed certificate,
+again
+using your private key, if a certificate is not found. </li>
+</ul>
+<h3><a name="real_cert"></a>Generating and installing a Trusted
+Certificate</h3>
+<p>If you wish to interact with 3rd party clients
+that have hard coded lists of acceptable Certificate Authorities, and
+you
+do not want annoying dialog boxes popping up for the user on the first
+(or
+all) connections, then you will have to have your key signed by a valid
+Certificate Authority.</p>
+<p>It is beyond the scope of this document to provide a complete
+tutorial
+on SSL certificates. Here are the general rules to follow:</p>
+<ul>
+ <li>Generally, the Certificate Signing Requeste which is
+automatically
+generated by Citadel will not contain enough information for any
+Certificate
+Authority to sign it. Generate a new CSR with the following commands:<br>
+ <br>
+ <tt>cd keys</tt><br>
+ <tt>openssl req -new -key citadel.key -out citadel.csr</tt><br>
+ <br>
+Answer all questions (your geographic location, organization name,
+etc.)
+and then send the new <tt>citadel.csr</tt> to your Certificate
+Authority
+when you order the certificate. </li>
+ <li>When the certificate is received, simply save it as <tt>citadel.cer</tt>
+and restart the Citadel server. </li>
+ <li>If your certificate authority delivers a 'chained' certificate
+(one
+with intermediate certificate authorities), simply append the
+intermediate
+certificate after your server's own certificate in the <tt>citadel.cer</tt>
+file.</li>
+</ul>
+<br>
+<hr style="width: 100%; height: 2px;">
+<div style="text-align: center;">
+<h2><a name="LDAP_Directory_Support"></a>LDAP (Directory) Support</h2>
+<div style="text-align: justify;">
+<h3><a name="Introduction_ldap"></a>Introduction</h3>
+LDAP (Lightweight Directory Access Protocol) has become the open
+standard protocol for directory access. There are many client
+programs which are capable of making use of an LDAP directory
+service. Therefore it may be beneficial for some sites to have a
+directory available which is populated with Citadel user information.<br>
+<br>
+Citadel does not contain its own LDAP service, because that would
+eliminate its ability to coexist with any existing directory you may
+already have in place at your organization. Instead, we provide
+the LDAP Connector for Citadel, which allows the Citadel service to
+populate an external LDAP directory. If you do not already have
+an LDAP directory in place, you can use the OpenLDAP server, which is
+probably already present in your operating system, or at least can be
+loaded from the installation CD's. The supplied configuration
+file <tt>citadel-slapd.conf</tt> can be used as a starting
+point to get your LDAP server running.<br>
+<br>
+<h3><a name="Preparing_your_LDAP_server_for_Citadel"></a>Preparing your
+LDAP server for Citadel connections</h3>
+It is difficult to find a commonly accepted LDAP scheme. It seems, most
+real life LDAP installations go for the domain oriented apporach
+and lay out the structure after an existing domain/subdomain structure.
+<p> The most widely accepted and standardized object for storing
+personal data
+clearly is "inetOrgPerson". Citadel therefore attempts to follow
+this type of schema.<br>
+</p>
+<p>If you are using OpenLDAP as your directory server, you should
+choose options similar to the following:<br>
+</p>
+<pre>database ldbm<br>schemacheck off<br>allow bind_v2<br>suffix "dc=servername,dc=domain,dc=org"<br>rootdn "cn=manager,dc=servername,dc=domain,dc=org"<br>rootpw secret<br></pre>
+<ul>
+ <li>Obviously, you can make your suffix and rootdn whatever you wish,
+but in most cases you'd simply follow a DC path that looks similar to
+your DNS domain.</li>
+ <li>If you don't want LDBM, feel free to choose any backend available
+on your system.</li>
+ <li><span style="font-family: monospace;">bind_v2</span> is <span
+ style="font-style: italic;">required</span> because Citadel will make
+v2 protocol connections.</li>
+ <li><span style="font-family: monospace;">schemacheck off</span> is <span
+ style="font-style: italic;">recommended</span> because Citadel uses
+fields that do not necessarily exist in your system's default
+schema. If you don't like that idea, your other option is to
+reference the included <span style="font-family: monospace;">citadel-openldap.schema</span>
+in your configuration.</li>
+ <li>Your <span style="font-family: monospace;">rootdn</span> and <span
+ style="font-family: monospace;">rootpw</span> can be whatever you
+want. Usually the rootdn is <span style="font-family: monospace;">cn=manager,</span>
+followed by your usual suffix. Please don't use <span
+ style="font-family: monospace;">secret</span> as your password, as in
+this example. Select a new password for your site.</li>
+</ul>
+<br>
+Your LDAP service <span style="font-weight: bold;">must</span> be up
+and running before you attempt to connect Citadel to it.<br>
+<br>
+<h3><a name="Configuring_the_LDAP_Connector_for"></a>Configuring the
+LDAP Connector for Citadel</h3>
+Once you've located or installed your LDAP server, connecting Citadel
+to it is easily completed with the <span style="font-weight: bold;"><span
+ style="font-family: monospace;">.A</span></span><span
+ style="font-family: monospace;">ide <span style="font-weight: bold;">S</span>ystem-configuration
+<span style="font-weight: bold;">G</span>eneral command:<br>
+</span>
+<pre>Lobby> . Aide System configuration General<br><br><span
+ style="font-style: italic;">(lots of other stuff omitted for brevity...)</span><br><br>Connect this Citadel to an LDAP directory [Yes]: <span
+ style="font-weight: bold;">Yes</span><br>Host name of LDAP server []: <span
+ style="font-weight: bold;">127.0.0.1</span><br>Port number of LDAP service [389]: <span
+ style="font-weight: bold;">389</span><br>Base DN []: <span
+ style="font-weight: bold;">dc=servername,dc=domain,dc=org</span><br>Bind DN []: <span
+ style="font-weight: bold;">cn=manager,dc=servername,dc=domain,dc=org</span><br>Password for bind DN []: <span
+ style="font-weight: bold;">secret</span><br style="font-weight: bold;"><br><span
+ style="font-style: italic;">(more questions omitted...)</span><br><br>Save this configuration? <span
+ style="font-weight: bold;">Yes</span><br></pre>
+Once you've done this, restart your Citadel service with the <span
+ style="font-weight: bold;"><span style="font-family: monospace;">.A</span></span><span
+ style="font-family: monospace;">ide <span style="font-weight: bold;">T</span>erminate-server
+<span style="font-weight: bold;">N</span>ow</span> command. When
+Citadel restarts, it will connect to your LDAP directory. Note
+that we gave Citadel the same Base DN, Bind DN, and password that was
+in our LDAP server configuration example. Obviously, everything
+needs to be identical on both sides or the connection will be
+refused. 127.0.0.1 is the loopback address, and 389 is the
+standard port number for LDAP, so this would be the proper host and
+port combination for an LDAP service running on your local
+server. It could just as easily be on another server, for example
+an organization-wide directory server.<br>
+<br>
+You can also configure the LDAP Connector for Citadel from a WebCit
+session. Log on as an Aide and click on Advanced Options -->
+Edit Site-Wide Configuration --> Directory, and you will be
+presented with the same set of questions.<br>
+<br>
+So, what kind of information will be entered into LDAP? As a
+rule, anything that gets saved to your Global Address Book room will
+also be saved to LDAP. Citadel will set up OU's (Organizational
+Units) for each node on your Citadel network, so if you are running
+multiple Citadel servers in an organization, you will automatically
+have a hierarchial view built for you. Below the OU's will be an
+entry for each user who has a vCard registered on the system.
+Citadel automatically translates vCard information to LDAP.<br>
+<br>
+If you already have a Global Address Book full of existing information,
+you can execute an <span style="font-family: monospace;">IGAB</span>
+(Initialize Global Address Book) server command to rebuild it. In
+addition to performing its usual function of rebuilding the internal
+Internet e-mail address mapping table, Citadel will also repopulate
+LDAP with all existing vCards. You should be aware, however, that
+existing LDAP entries will not be cleared from your directory
+server. If your directory contains only Citadel data, you can
+safely delete your database and start over, because it will be
+repopulated. Otherwise, Citadel will merely update any existing
+records with fresh information.<br>
+<br>
+The LDAP Connector for Citadel is a recent development, so expect more
+functionality in this space in the near future.<br>
+</div>
+<br>
+</div>
+<hr>
+<center>
<h2><a name="utilities"></a>Utilities</h2>
</center>
<h3><a name="overview"></a>Overview</h3>
textual output will be sent to stdout.</p>
<p>This utility is intended to be used to enable Citadel server
commands to
-be executed from shell scripts. Review the script called <tt>weekly</tt>
-which ships with the Citadel distribution for an example of how this
-can
-be used.</p>
+be executed from shell scripts.</p>
<p><b>NOTE:</b> be sure that this utility is not world-executable. It
connects to the server in privileged mode, and therefore could present
a security hole
projects / citadel.git / blobdiff