</head>
<body>
<div align="center">
-<h1>Citadel</h1>
-<h2>a messaging and collaboration platform for BBS and groupware
-applications</h2>
-Copyright ©1987-2004 by the Citadel development team:<br>
+<h1>C I T A D E L</h1>
+<h2>a messaging and collaboration platform
+for groupware and BBS applications</h2>
+Copyright ©1987-2005 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>
<td valign="top"><i>additional client features<br>
</i></td>
</tr>
+ <tr>
+ <td valign="top">David Given<br>
+ </td>
+ <td valign="top"><i>IMAP and build patches<br>
+ </i></td>
+ </tr>
+ <tr>
+ <td valign="top">Wilfried Goesgens<br>
+ </td>
+ <td valign="top"><i>build system patches<br>
+ </i></td>
+ </tr>
<tr>
<td valign="top">Michael Hampton<br>
</td>
<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>portability enhancements<br>
+ </i></td>
+ </tr>
<tr>
<td valign="top">John Walker<br>
</td>
<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>
<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>
</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>
the system. It is mandatory that the sysop have "root" access to the
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>Enough disk space to hold all of the programs and data </li>
</ul>
<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
+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 Mozilla, Netscape, Evolution, Eudora, Pine, Outlook, etc.
-with Citadel. </li>
+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
"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 (or in some other name service
such as NIS), Citadel will automatically set up
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
</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></tt> room.
+on the Citadel network which carries the <tt>Citadel/UX></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>
</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">
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
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.
-Aides may also <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></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
suppress
this behavior, answer 'No' at the prompt (the default is 'Yes') and the
headers
-will never be altered.</p>
+will never be altered.<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><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>
+<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></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>
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>
+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.<br>
+<span style="font-family: monospace;"></span></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
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>
+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
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>
-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>
+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>
+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
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;">
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