<!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>
+<h1>Citadel</h1>
<h2>a messaging and collaboration platform for BBS and groupware
applications</h2>
-Copyright ©1987-2003 by the Citadel development team:<br>
+Copyright ©1987-2004 by the Citadel development team:<br>
<br>
<table cellpadding="2" cellspacing="2" border="0" align="center">
<tbody>
<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>
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>
<p align="justify"> <strong>3.</strong> You may copy and distribute
the Program (or a work based on it, under Section 2) in object code or
executable form under the terms of Sections 1 and 2 above provided that
-you also do one of the following:<!-- we use this doubled UL to get the sub-sections indented, --><!-- while making the bullets as unobvious as possible. --> </p>
+you also do one of the following:<!-- we use this doubled UL to get the sub-sections indented, --><!-- while making the bullets as unobvious as possible. -->
+</p>
<div align="justify">
<ul>
<li><strong>a)</strong> Accompany it with the complete corresponding
</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>C compiler (<a href="http://gcc.gnu.org/">GCC</a> with <a
</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
+<p>If you are running Citadel 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
distribution will have most or all of the prerequisite tools and
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>
</ul>
<h3>Coming soon:</h3>
<ul>
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
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 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>If you've got Berkeley DB installed in a non-standard location, you
can help the configure script find it by doing something like this:</p>
<pre>./configure --with-db=/usr/local/BerkeleyDB-4.1<br></pre>
-<p>Keep in mind that if you're using Berkeley DB from a non-standard location,
+<p>Keep in mind that if you're using Berkeley DB from a non-standard
+location,
you'll have to make sure that location is available at runtime.</p>
<p>File permissions are always a bother to work with. You don't want
Citadel to crash because someone couldn't access a file, but you also
<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
for this file in the following locations: </p>
<ul>
<li><tt>$HOME/.citadelrc</tt></li>
- <li><tt>/usr/local/lib/citadel.rc</tt></li>
<li><i>your-Citadel-directory</i><tt>/citadel.rc</tt></li>
+ <li><tt>/etc/citadel.rc</tt></li>
+ <li><i>current-directory</i><tt>/citadel.rc</tt></li>
</ul>
The next couple of sections deal with client-side configuration.
<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>
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>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
<p>The next step is to arrange for the server to start. The <tt>citserver</tt>
program is the main Citadel server. Before we cover the recommended
method of starting the server, let's examine its usage options:</p>
-<pre>citserver [-hHomeDir] [-xDebugLevel] [-tTraceFile] [-d] [-f]<br></pre>
+<pre>citserver [-hHomeDir] [-xDebugLevel] [-tTraceFile] [-lLogFacility] [-d] [-f]<br></pre>
<p>The options are as follows:</p>
<p><tt>-hHomeDir</tt> - the directory your Citadel data files live in.
This should, of course, be a directory that you've run the <tt>setup</tt>
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.
-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>1 - Internal errors (failed thread creation, malloc problems,
-etc.) </li>
- <li>2 - Network errors (broken sockets, failed socket creation) </li>
- <li>3 - Begin and end of sessions, startup/shutdown of server </li>
- <li>5 - Server commands being sent from clients </li>
- <li>7 - Entry and exit of various functions </li>
- <li>9 - Various debugging checkpoints (insanely verbose) </li>
+ <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>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>
+ <li>6 - Informational messages, progress reports, etc. </li>
+ <li>7 - Debugging messages; extremely verbose </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,
+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
+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
server up when your system is up, and terminate it gracefully when your
system is shutting down. The exact syntax for your system may vary, but
here's an entry that could be used on a Linux system:</p>
-<pre>cit:2345:respawn:/usr/local/citadel/citserver -h/usr/local/citadel -t/dev/tty9 -x3<br></pre>
-<p>In this example, we've chosen debugging level 3, and have the trace
+<pre>cit:2345:respawn:/usr/local/citadel/citserver -h/usr/local/citadel -t/dev/tty9 -x6<br></pre>
+<p>In this example, we've chosen debugging level 6, and have the trace
stuff output to one of the virtual consoles. It's important to remember
to turn off any getty that is set up on that virtual console, if you do
this. After making this change, the command <tt>init q</tt> works on
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>
<p>To report a problem, you can log on to <a
href="http://uncensored.citadel.org">UNCENSORED!</a> or any other BBS
-on the Citadel network which carries the <tt>Citadel/UX></tt> room.
+on the Citadel network which carries the <tt>Citadel></tt> room.
Please DO NOT e-mail the developers directly. Post a request for help
on the BBS, with all of the following information: </p>
<ul>
</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
<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
will never be altered.</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></pre>
+<pre>Default user purge time (days) [120]: <br><br>Default room purge time (days) [30]: <br><br>System default message expire policy (? for list) [2]: <br><br>Keep how many messages online? [150]:<br><br>Mailbox default message expire policy (? for list) [1]: <br><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.</p>
+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>
<p>When you're done, enter 'Yes' to confirm the changes, or 'No' to
discard the changes.</p>
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
host system. For example, you might have multiple groups of users, some
of
which are using Citadel and some of which are using a legacy Unix mail
-spool. This type of configuration is discouraged, but a tool is
+spool. This type of configuration is discouraged, but two tools are
provided
to allow it.</p>
<p>The tool is called <tt>citmail</tt> and it is, quite simply, a
discussion of the finer points of complex Sendmail configurations is
beyond the scope of this document; however, you might want to visit <a
href="http://pixel.citadel.org/citadel/docs/">Pixel BBS</a> where some
-useful HOWTO documents are provided.</p>
-<p>For outbound mail, you can either allow Citadel to perform
+useful HOWTO documents are provided.<br>
+</p>
+<p>The other tool is an <a href="http://www.faqs.org/rfcs/rfc2033.html">RFC2033</a>
+compliant LMTP service running on a local socket. If you're
+running a mailer that speaks LMTP (such as <a
+ href="http://www.postfix.org/">Postfix</a>), you can simply point your
+mailer at the socket called <span style="font-family: monospace;">citadel.socket</span>
+in your Citadel directory. For example, in Postfix you might put
+the following line into <span style="font-family: monospace;">main.cf</span>
+in order to tell it to use Citadel to deliver mail to local recipients:<br>
+</p>
+<pre>local_transport = lmtp:unix:/usr/local/citadel/lmtp.socket<br></pre>
+<p>Postfix also has something called a "fallback transport" which can
+be used to implement Citadel as a "secondary" mail system on your
+server, while keeping the existing Unix mailboxes intact.
+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>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
tie
<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
<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>
+</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>
projects / citadel.git / blobdiff