+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 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">
+<h3><a name="Introduction"></a>Introduction</h3>
+As you know by now, Citadel is a completely self-contained,
+full-featured Internet e-mail system. When you run Citadel you do
+not need any other mail software on your host system. This
+eliminates the need for tedious mucking about with sendmail, qmail,
+postfix, Cyrus, the UW IMAP
+server, or any of countless other needlessly complex programs that lead
+some people to the false assumption that Unix systems are difficult to
+administer.<br>
+<br>
+Some of the many features supported by Citadel are:<br>
+<ul>
+ <li>Built-in SMTP and ESMTP service, for delivering and receiving
+e-mail on the Internet</li>
+ <li>Built-in POP3 service, for remote fetching of messages</li>
+ <li>Built-in IMAP service, for access to mail using any standard mail
+client program</li>
+ <li>Web mail (implemented using the "WebCit" middleware, which is
+installed separately)</li>
+ <li>Support for mailing lists, in both "individual message" and
+"digest" formats</li>
+ <li>Multiple/virtual domain support</li>
+ <li>Any user may have multiple Internet e-mail addresses, in multiple
+domains</li>
+ <li>Global address book (Users with addresses in a domain may be
+spread out across many servers on a Citadel network)</li>
+ <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-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
+these features.<br>
+<br>
+<h3><a name="Basic_site_configuration"></a>Basic site configuration</h3>
+<p>Basic configuration of your Citadel system for Internet e-mail
+begins with
+the <tt><b>.A</b>ide <b>S</b>ystem configuration <b>I</b>nternet</tt>
+command:</p>
+<pre>Lobby> <b>.A</b>ide <b>S</b>ystem configuration <b>I</b>nternet<br><br>### Host or domain Record type<br>--- -------------------------------------------------- --------------------<br> 1<br><A>dd <D>elete <S>ave <Q>uit -><br></pre>
+<p>This is a "clean" setup. For a simple, standalone e-mail system you
+simply have to enter the <tt><b>A</b>dd</tt> command:</p>
+<pre><A>dd <D>elete <S>ave <Q>uit -> <b>A</b>dd<br><br>Enter host name: schmeep.splorph.com<br> (1) localhost (Alias for this computer)<br> (2) gateway domain (Domain for all Citadel systems)<br> (3) smart-host (Forward all outbound mail to this host)<br> (4) directory (Consult the Global Address Book)<br> (5) SpamAssassin (Address of SpamAssassin server)<br> (6) RBL (domain suffix of spam hunting RBL)<br><br>Which one [1]:<br></pre>
+<p><b>localhost:</b> Basically what you're doing here is telling
+Citadel
+what any aliases for your machine are. If your machine were <tt>schmeep.splorph.com</tt>
+and you also had a DNS entry set up for <tt>blah.com</tt>, you might
+want to enter '1' and enter <tt>blah.com</tt> as your alias, so that
+e-mail
+sent to that address won't bounce.</p>
+<p><i>Important tip:</i> if your system is known by one name and <i>only</i>
+one domain, you might not even need to do this at all. You will recall
+that you entered your system's fully qualified domain name earlier when
+you went through the <tt><b>.A</b>ide <b>S</b>ystem configuration <b>G</b>eneral</tt>
+command. The domain name you entered there is automatically considered
+by Citadel to be a 'localhost' entry in your Internet mail
+configuration. It does not hurt to enter it in both locations, though.</p>
+<p><b>gateway domain:</b> this is a simple way of mapping various
+Citadel hosts in an Internet domain. For example, if you enter <tt>bar.com</tt>
+as a gateway domain, then mail to users at <tt>foo.bar.com</tt> will
+be forwarded to the host called <tt>foo</tt> on a Citadel network,
+mail to users
+at <tt>kunst.bar.com</tt> will be delivered to the Citadel server
+called
+<tt>kunst</tt>, etc. This feature has limited usefulness; if you are
+operating
+a network of Citadel servers, it is more likely that you will use the
+'directory'
+feature, explained below.</p>
+<p><b>smart-host:</b> Normally, Citadel sends outbound Internet e-mail
+directly to its destination. This may not be appropriate for some
+sites; you may require (due to local convention, security policy, or
+whatever) that all outbound mail be sent to an SMTP relay or forwarder.
+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
+out across multiple Citadel servers on your network, then enter <tt>citadel.org</tt>
+as a 'directory' entry. <i>For this to work, all Citadel servers
+participating in directory service <b>must</b> carry and share the <tt>Global
+Address Book></tt> room.</i></p>
+<p><b>spamassassin:</b> if you are running a <a
+ href="http://www.spamassassin.org">SpamAssassin</a> service anywhere
+on your
+<b>local</b> network, enter its name or IP address as a 'spamassassin'
+entry. This may be (and, in fact, will usually be) <tt>127.0.0.1</tt>
+to specify
+that the service is running on the same host computer as the Citadel
+server.</p>
+<p>Please install SpamAssassin as per its own documentation. You will
+want to run SpamAssassin in client/server mode, where a <tt>spamd</tt>
+daemon is always running on your computer. Citadel does not utilize the
+<tt>spamc</tt> client; instead, it implements SpamAssassin's protocol
+on its own.</p>
+<p>Connecting to a SpamAssassin service across a wide area network is
+strongly discouraged. In order to determine whether an incoming e-mail
+is spam, Citadel must feed the <i>entire message</i> to the
+SpamAssassin service. Doing this over a wide area network would consume
+time and bandwidth,
+which would affect performance.</p>
+<p>Citadel invokes the SpamAssassin service when incoming messages are
+arriving via SMTP. Before a message is accepted, it is submitted to
+SpamAssassin. If SpamAssassin determines that the message is spam, the
+Citadel SMTP
+service <i>rejects the message,</i> causing a delivery failure on the
+sending
+host. This is superior to software which files away spam in a separate
+folder, because delivery failures will cause some spammers to assume
+the
+address is invalid and remove it from their mailing lists.</p>
+<p><b>RBL:</b> Realtime Blackhole Lists (RBL's) provide defense against
+spammers based on their source IP address. There are many such lists
+available on the Internet, some of which may be utilized free of
+charge. Since they are DNS based, the lists do not require storage on
+your server -- they are queried during the SMTP conversation.</p>
+<p>Citadel can utilize any RBL that uses the <tt>z.y.x.w.nameoflist.org</tt>
+syntax, where <tt>w.x.y.z</tt> is the source IP address which is
+attempting to deliver mail to your server. For example, <a
+ href="http://www.spamcop.net">SpamCop</a> would use the query <tt>2.0.0.127.bl.spamcop.net</tt>
+to determine whether the host at <tt>127.0.0.2</tt> is a known spammer
+or open relay. In this case, you simply select option '6' to add an RBL
+entry, and provide it with the domain suffix of <tt>bl.spamcop.net</tt>
+(the IP address
+and extra dot will be automatically prepended for each query).</p>
+<p>Now select <tt><b>S</b>ave</tt> and you are just about ready for
+Internet e-mail.</p>
+<h3><a name="Enabling_the_Internet_mail_protocols"></a>Enabling the
+Internet mail protocols</h3>
+<p>As previously mentioned, Citadel contains its own SMTP, POP3, and
+IMAP services. Enabling them is simple.</p>
+<p>Check for the existance of a current MTA (sendmail, qmail, etc.) by
+connecting to port 25 on your host. If you see something similar to the
+following
+you're running an MTA already and you'll need to shut it down:</p>
+<pre>smw @ pixel % telnet localhost 25<br>Trying 127.0.0.1...<br>Connected to localhost.<br>Escape character is '^]'.<br>220 pixel.citadel.org ESMTP Sendmail 8.9.3/8.9.3; Wed, 15 Mar 2000 19:00:53 -0500<br></pre>
+<p>In the above example, we see that the host already has Sendmail
+listening on port 25. Before Citadel can use port 25, Sendmail must be
+shut off. Please consult the documentation for your operating system
+for instructions on how to do this. (On a Red Hat Linux system, for
+example, you can run the <tt>ntsysv</tt> utility, un-checking <tt>sendmail</tt>
+to disable it at
+the next reboot; then, run <tt>service sendmail stop</tt> to shut off
+the
+currently running service.)</p>
+<p>If you get a 'connection refused' message when you telnet to port 25
+there's nothing running and you should be able to continue. You might
+also want to turn off POP (try the above test substituting 110 for 25)
+and IMAP (port 143) and use Citadel's POP and IMAP services.</p>
+<p>Citadel will look for an existing pop/smtp server on startup. If
+they
+don't exist (and you've configured them properly) then Citadel should
+enable
+them at startup. You can check your logs to be sure, or you can start
+the
+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<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
+requested port. Make SURE you've followed the above steps to remove
+sendmail/pop and start your Citadel server again.</p>
+<h3><a name="citmail"></a>Using Citadel in conjunction with another MTA</h3>
+<p>Occationally it is not practical to remove a non-Citadel MTA on your
+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 two tools are
+provided
+to allow it.</p>
+<p>The tool is called <tt>citmail</tt> and it is, quite simply, a
+local MDA (Mail Delivery Agent) which you can configure into your MTA
+for final delivery of incoming messages to Citadel users. A full
+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.<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;"></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
+tie
+up port 25) or enter <tt>127.0.0.1</tt> as your smart-host, which will
+tell
+Citadel to forward all of its outbound mail to your other mail system.</p>
+<h3><a name="Hosting_an_Internet_mailing_list"></a>Hosting an Internet
+mailing list</h3>
+<p>Citadel has built in mailing list service (known in the 'net
+vernacular as "listserv") functionality. You can turn any room
+into a mailing list. Users can then choose how they participate
+-- by logging on to your Citadel server directly, or by having the
+room's contents mailed to
+them somewhere else. Configuring this is easy.</p>
+<p>Citadel supports two modes of mailing list delivery: </p>
+<ul>
+ <li>"List mode" -- each individual message is delivered as a single
+e-mail to each list mode recipient. The "From:" header will
+display the address of the message's original author.</li>
+ <li>"Digest mode" -- groups of one or more messages are delivered
+to digest mode recipients. The number of messages in the group
+depends on how many new messages arrived since the last batch was
+delivered. The "From:" header will display the address of the
+room itself, which allows replies to be posted back to the room.</li>
+</ul>
+A room may have any combination of list mode and digest mode
+recipients.
+<p>As alluded to above, every room on your Citadel system has an
+Internet e-mail address of its own. Messages sent to that address
+will be
+posted in the room (and sent back out to mailing list recipients, as
+well
+as to any other Citadels you share the room with). The address
+format
+is <tt>room_</tt> plus the name of the room, with any spaces replaced
+by
+underscores, followed by <tt>@</tt> and your hostname. For example, if
+your
+system is known as <tt>phlargmalb.orc.org</tt> on the Internet, and
+you have
+a room called <tt>Bubblegum Collectors</tt>, you can post to that room
+from
+anywhere on the Internet simply by sending an e-mail to <tt>room_bubblegum_collectors@phlargmalb.orc.org</tt>.
+When the message arrives, it's automatically posted in that room.</p>
+<p>To manually edit the list of "list mode" recipients, simply enter
+the <tt><b>.A</b>ide
+mailing <b>L</b>ist management</tt> command. Your text editor will
+open
+up and you will be able to create or edit a list of recipients, one per
+line. Lines beginning with a hash (<tt>#</tt>) are comments.</p>
+<p>To manually edit the list of "digest mode" recipients, enter the <tt><b>.A</b>ide
+mailing list <b>D</b>igest recipients</tt> command. As with the
+previous command, the text editor will open up and you can edit the
+list of digest mode recipients, one per line.</p>
+<p>Citadel also has a facility which allows users to subscribe or
+unsubscribe to mailing lists using a web browser. In order to do this,
+WebCit must also be running on your server in addition to Citadel.
+WebCit is obtained and installed separately from the rest of the
+Citadel system.</p>
+<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>
+<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
+the
+web page they need to visit. It looks like this:</p>
+<center><tt>http://foobar.baz.org:2000/listsub</tt></center>
+<p>In this example, the server is called <tt>foobar.baz.org</tt> and
+WebCit is running on port 2000. Edit appropriately.</p>
+<p>Citadel offers a subscribe/unsubscribe facility that is more
+intuitive than other listservs. With most systems, sending commands to
+the listserv requires that you e-mail it commands in a special format.
+It's easy to get it wrong. Citadel simply uses your web browser. You
+select the list you want to subscribe or unsubscribe (hint: it's the
+list of rooms you've enabled self-service for), select whether you want
+list mode or digest mode, and enter your e-mail address. For security
+purposes, a confirmation message is sent to the address you enter. But
+you don't have to reply to the message in a weird format, either: the
+confirmation contains another URL which
+you simply click on (or paste into your browser if you can't click on
+URL's
+in your e-mail software) and the confirmation is automatically
+completed.</p>
+<hr size="2" width="100%">
+<center>
+<h2><a name="Building_or_joining_a_Citadel_network"></a>Building or
+joining a Citadel network</h2>
+</center>
+<h3><a name="Overview__"></a>Overview</h3>
+<p>If you are running Citadel as a BBS or other forum type of
+application, one way to 'keep the conversation going' is to share rooms
+with other Citadel systems. In a shared room, a message posted to the
+room is automatically
+propagated to every system on the network. It's kind of like a UseNet
+newsgroup,
+but without the spam.</p>
+<p>If you are using Citadel as the e-mail and groupware platform for a
+large organization, you can use its networking features to build a
+large network of Citadel servers which share content (think of rooms as
+public folders), redistribute e-mail throughout the organization, and
+integrate the global address book. It might make sense, for
+example, in a large corporation to give each department or location its
+own Citadel server. Thanks
+to Citadel's global address book features, you could still have all of
+the
+users share a single e-mail domain.</p>
+<p>Obviously, the first thing you have to do is find another Citadel to
+share rooms with, and make arrangements with them. The following
+Citadels are a good place to start:</p>
+<ul>
+ <li>UNCENSORED! - <a href="http://uncensored.citadel.org">uncensored.citadel.org</a>
+ </li>
+ <li>The Dog Pound II - <a href="http://dogpound2.citadel.org">dogpound2.citadel.org</a>
+ </li>
+ <li>PixelBBS - <a href="http://pixel.citadel.org">pixel.citadel.org</a>
+ </li>
+</ul>
+<p>You don't have to be a part of the citadel.org domain to participate
+in the public Citadel network, but the DNS service is provided free of
+charge by the Citadel community if you wish to do this.</p>
+<h3><a name="Conventions_and_etiquette_when"></a>Conventions and
+etiquette when connecting to the public Citadel network</h3>
+<p>Before we get into the technical nitty gritty, there are two points
+of etiquette to keep in mind. The first thing to keep in mind is that
+the operator of any particular Citadel may not be willing to share some
+of his/her rooms. Some sites are proud to offer exclusive content in
+certain areas. Chances are, if a room is already being shared on the
+network, it's available for anyone to share; if not, it can't hurt to
+ask -- but take care not to demand it of them. Ask if you may share the
+room instead of telling them that you wish to share the room. When
+looking at a <tt><b>K</b></tt>nown rooms list, network rooms are the
+ones ending in parentheses instead of angle brackets. For example, <tt>Gateway)</tt>
+would be a network room, <tt>Lobby></tt> would not.</p>
+<p>The other point of etiquette to remember is that you should be
+making
+the arrangements in advance, and then set it up. It is extremely rude
+to
+simply begin networking with another Citadel, or unilaterally start
+sharing
+a new room, without first obtaining permission from its operator.
+Always
+ask first. Most Citadel operators are more than happy to network with
+you. Also, if later on you decide to take your system down, please take
+the time
+to notify the operators of any other Citadels you network with, so they
+can
+unconfigure their end.</p>
+<h3><a name="Getting_ready_to_join_the_network"></a>Getting ready to
+join the network</h3>
+<p>Ok, first things first. On a Citadel room sharing network, the first
+thing you need to know is your own system's node name. Presumably you
+set
+this up during installation, but if you want to change it you can do so
+using
+the <tt><b>.A</b>ide <b>S</b>ysconfig <b>G</b>eneral</tt> command:</p>
+<pre>Lobby> . Aide System configuration General<br>Node name [uncnsrd]:<br>Fully qualified domain name [uncensored.citadel.org]:<br>Human readable node name [Uncensored]:<br></pre>
+<p>The "node name" is important, it's how the network identifies
+messages coming from your system. The "human readable node name" is
+simply a label; it shows up in messages coming from your system. "Fully
+qualified domain name" is your DNS name; it's used for routing messages
+on the Internet. In the above example, the node name is "uncnsrd".</p>
+<h3><a name="Defining_neighbor_nodes"></a>Defining neighbor nodes</h3>
+<p>The next thing you need to do is configure your neighbor node(s).
+You need to do this for each node you network with. Let's say you
+wanted
+to talk to a Citadel system called "frobozz". Use the <tt><b>.A</b>ide
+<b>S</b>ysconfig <b>N</b>etwork</tt> command:</p>
+<pre>Lobby> . Aide System configuration Network<br>### Node Secret Host or IP Port#<br>--- ---------------- ---------------- -------------------------------- -----<br><A>dd <D>elete <S>ave <Q>uit -> Add<br><br>Enter node name : frobozz<br>Enter shared secret: frotz<br>Enter host or IP : frobozz.magick.org<br>Enter port number : [504]: 504<br><br>### Node Secret Host or IP Port#<br>--- ---------------- ---------------- -------------------------------- -----<br> 1 frobozz frotz frobozz.magick.org 504<br><A>dd <D>elete <S>ave <Q>uit -> Save<br><br>Lobby><br></pre>
+<p>As you can see in the above example, you have to enter the Citadel
+node name, the DNS name or IP address of the server, and the port
+number the Citadel service is running on. The "shared secret" is a
+password to allow the two Citadel nodes to connect to each other to
+exchange network data. The password must be <i>identical</i> on both
+ends of the connection -- when the operator of the other Citadel node
+sets up the connection with
+your system, he/she must use the same password.</p>
+<h3><a name="Sharing_rooms"></a>Sharing rooms</h3>
+<p>Now you're ready to share rooms. You have to do this for each room
+you want to share, and you have to do it from BOTH ENDS -- again, when
+you
+share a room with another Citadel, they must share it with you as well.
+Let's say you have a room called "Quiche Recipes>" and you want to
+share
+it with the node you set up above. First, edit the room and flag it as
+a
+network room:</p>
+<pre>Quiche Recipes> . Aide Edit this room<br>Room name [Quiche Recipes]:<br>Private room [No]: No<br>Preferred users only [No]: No<br>Read-only room [No]: No<br>Directory room [No]: No<br>Permanent room [No]: No<br>Network shared room [No]: Yes<br>Automatically make all messages anonymous [No]: No<br>Ask users whether to make messages anonymous [No]: No<br>Listing order [64]:<br>Room aide (or 'none') [none]:<br>Message expire policy (? for list) [0]:<br>Save changes (y/n)? Yes<br>Ok<br><br>Quiche Recipes)<br></pre>
+<p>Notice how the prompt changed? It was > before, but it's ) now.
+That means it's a network room. Now you can tell Citadel that you want
+to
+share the room with frobozz. Enter this command:</p>
+<pre>Quiche Recipes) . Aide Network room sharing<br></pre>
+<p>Your text editor will pop up (you <i>did</i> configure Citadel to
+use
+your favorite text editor, right?) with a screen that looks like this:</p>
+<pre># Configuration for room: Quiche Recipes<br># Nodes with which we share this room<br># Specify one per line.<br></pre>
+<p>All you have to do is enter the name of the other Citadel node (i.e.
+"frobozz" in our example) on a line by itself. As usual, lines starting
+with a
+"#" are comments. Just go to the end of the file, type "frobozz"
+(without
+the quotes), save the file... and you're done!</p>
+<p>At this point, you just sit back and enjoy. Your Citadel and the
+other one will begin polling each other at regular intervals (once per
+hour
+by default) and sharing messages.</p>
+<h3><a name="Sending_mail"></a>Sending mail</h3>
+<p>You can send mail to any user on any node of your Citadel network.
+It may take a little while for your system to learn the entire node
+list, though, as this is done by watching incoming messages on the
+network and learning which nodes are out there.</p>
+<p>To send a private message, just enter <tt>user @ host</tt> as the
+recipient:</p>
+<pre>Mail> Enter message <br>Enter recipient: Some other user @ frobozz<br> Feb 11 2003 11:36pm from I. M. Me to Some other user @ frobozz<br>type message here...<br><br>Entry command (? for options) -><br><br></pre>
+<h3><a name="Changing_the_polling_interval"></a>Changing the polling
+interval</h3>
+<p>As previously mentioned, Citadel will poll other Citadel nodes for
+messages once per hour. If this is not an acceptable interval, you can
+change it using the <tt><b>.A</b>ide <b>S</b>ystem configuration <b>G</b>eneral</tt>
+command. Enter this command and look for the option:</p>
+<pre>How often to run network jobs (in seconds) [3600]:<br></pre>
+<p>Change it to whatever you like. For example, 15 minutes is 900
+seconds. So if you changed the default value to 900, network polling
+would occur every 15 minutes.</p>
+<hr>
+<h2 align="center"><a name="Database_maintenance"></a>Database
+maintenance</h2>
+<h3><a name="Introduction_"></a>Introduction</h3>
+The data store used by Citadel is reliable and self-maintaining.
+ It requires very little maintenance. This is primarily due
+to its use of the <a href="http://www.sleepycat.com">Berkeley DB</a>
+record manager. It is robust, high-performance, and transactional.<br>
+<br>
+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 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>
+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
+can occur in rare instances. External factors such as an
+operating
+system crash or an unexpected loss of power might leave the database in
+an unknown state. A utility is provided which may be able to
+repair
+your database if this occurs. If you find that your Citadel
+server
+is not running, and reading the logs shows that it is crashing because
+of
+an inability to validate a database, follow these steps:<br>
+<ol>
+ <li>Edit <tt>/etc/inittab</tt> and switch the Citadel service from
+"respawn" to "off." Type <tt>init q</tt> to make this setting
+permanent.</li>
+ <li><b>Make a backup of your data.</b> Either write it out to
+tape or copy it to another directory, or a tarball.<br>
+ </li>
+ <li><tt>cd</tt> to your Citadel directory and type <tt>./database_cleanup.sh</tt></li>
+ <li>Let the cleanup script run. <b>Do not interrupt this
+process for any reason.</b><br>
+ </li>
+ <li>Edit <tt>/etc/inittab</tt> and switch the Citadel service from
+"off" to "respawn". Type <tt>init q</tt> to activate your
+changes.</li>
+</ol>
+If this procedure does not work, you must restore from your most recent
+backup.<br>
+<br>
+<h3><a name="ImportingExporting_your_Citadel"></a>Importing/Exporting
+your Citadel database<br>
+</h3>
+<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
+flat file, which may then be imported on another system. (This
+procedure
+is also known as "dump and load" to database gurus.)</p>
+<p>Why would you want to do this? Here are some scenarios: </p>
+<ul>
+ <li>You are moving a Citadel installation to another computer, which
+uses a different CPU. Since Citadel stores data in an
+architecture-dependent format, the data files wouldn't work on the new
+computer as-is. </li>
+ <li>Your computer crashed, lost power, etc. and you suspect that your
+databases have become corrupted. </li>
+ <li>You want to switch to a different back-end data store. (For
+example, from GDBM to Berkeley DB) </li>
+</ul>
+<p>So ... how do we work this magic? Follow these steps <i>exactly</i>
+as documented and you should be able to do it all with very little
+trouble.</p>
+<ol>
+ <li>This should be obvious, but it's still worth mentioning: <b>Make
+sure you have a backup of everything before you start this! </b>
+You're performing a major operation here. Don't risk it. </li>
+ <li>First, get all the users logged off from your system. Disconnect
+it from the network if possible. You don't want anyone logging in while
+you're doing this. </li>
+ <li>Log on as root, or some other user that has read/write access to
+all relevant files. </li>
+ <li>Go to the directory that Citadel is installed in. For example,
+issue a command like <tt>cd /usr/local/citadel</tt> </li>
+ <li>Export the databases with the following command:<br>
+ <br>
+ <tt>./sendcommand "ARTV export" >exported.dat</tt><br>
+ <br>
+This command may run for a while. On a very large system it could take
+an hour or more. Please be patient! </li>
+ <li>When the export completes, check to make sure that <tt>exported.dat</tt>
+exists and has some data in it. (Type "ls -l exported.dat") </li>
+ <li>Shut down the Citadel server. If you have a line in <tt>/etc/inittab</tt>
+that reads like this:<br>
+ <br>
+ <tt>c1:2345:respawn:/usr/local/citadel/citserver
+-h/usr/local/citadel</tt> <br>
+...then you should change the <tt>respawn</tt> to <tt>off</tt> and
+then type <tt>/sbin/init q</tt> to make the changes take effect. </li>
+ <li>Now it's time to delete your current binary databases. Type:<br>
+ <br>
+ <tt>rm -f citadel.config citadel.control data/*</tt> </li>
+ <li>If you're moving Citadel to another computer, you should move the
+ <i>entire</i> directory over at this time. <tt>exported.dat</tt>
+only contains the information that was in the binary databases.
+Information which was stored in portable formats doesn't need to be
+exported/imported, so
+you must bring it all over in its current form. </li>
+ <li>Now get Citadel running on the new computer (or whatever). Run <tt>setup</tt>
+and turn the service back on (from <tt>/etc/inittab</tt>) but DO NOT
+log in. </li>
+ <li>As root, run the import command:<br>
+ <br>
+ <tt>./sendcommand "ARTV import" <exported.dat</tt><br>
+ <br>
+This will import your databases. Again, it may run for a long time. </li>
+ <li>Restart the Citadel server. You can do this any way you like.
+From the command line, you can do it with a command like:<br>
+ <br>
+ <tt>./sendcommand "DOWN"</tt> <br>
+ </li>
+ <li>Now you're finished. Log in and test everything. You may delete
+exported.dat at this time, or you might want to save it somewhere as a
+sort of pseudo-backup. </li>
+</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>
+<p>The following utilities will be discussed: </p>
+<ul>
+ <li><b>aidepost</b> - Post standard input to the Aide> room </li>
+ <li><b>whobbs</b> - Who is on the system </li>
+ <li><b>msgform</b> - Format a binary message to the screen (stdin or
+in a file) </li>
+ <li><b>userlist</b> - Print the userlist </li>
+ <li><b>sendcommand</b> - Send a server command </li>
+</ul>
+<p>It is up to you to decide which utilities should be made accessible
+only to system administrators. It is important that you set the file
+permissions correctly. All utilities should have access to the Citadel
+data files. We
+will attempt to address each program individually.</p>
+<h3><a name="aidepost"></a>aidepost</h3>
+<p>The nature of this program is rather simple. Standard input (stdin)
+is converted into a message, filed in the main message store, and
+posted in the Aide> room. This is useful for keeping transcripts of
+system activity that has to do with Citadel operations. You might even
+elect to send all of
+your system logs there, too.</p>
+<p><tt>aidepost</tt> also accepts the usage <tt>aidepost -rTargetRoom</tt>,
+where TargetRoom is the name of a room to which you'd like the message
+to be sent.</p>
+<h3><a name="whobbs"></a>whobbs</h3>
+<p>This program is similar to the <tt>who</tt> command. It lists all
+of the users who are currently connected to your Citadel server, either
+locally or
+across a network. Unless you're running a standalone system, <tt>who</tt>
+and <tt>whobbs</tt> will probably not have a one-to-one
+correspondence. Remember
+that you will see sessions for SMTP, POP, and IMAP users, as well as
+users
+running a Citadel client.</p>
+<p>One thing to keep in mind is that the <tt>whobbs</tt> utility
+actually opens a connection to the server. If the server is maxed out, <tt>whobbs</tt>
+will still be able to provide a listing, because it doesn't need to log
+in to execute the <tt>RWHO</tt> command. Note that whobbs does not
+list its own session.</p>
+<p>The <tt>whobbs</tt> utility is smart enough to know when it is
+being invoked by a web server as a CGI program. In this situation, it
+will output its listing
+as a nicely formatted web page instead of plain text. This makes it
+easy
+to just put a link to the whobbs binary in your cgi-bin directory,
+allowing
+a quick and easy way for web surfers to see who is online.</p>
+<p>Running the <tt><b>W</b>ho is online</tt> command from the Citadel
+client does <b>not</b> call this utility. It has this functionality
+built in.<br>
+<br>
+</p>
+<h3><a name="msgform"></a>msgform</h3>
+<p>The <tt>msgform</tt> utility reads its standard input (stdin)
+looking for
+Citadel messages stored in the internal format used on disk and over
+the
+network, and sends them in a human-readable format to standard output
+(stdout). There is no longer much use for this program, but it is
+included for hack
+value.</p>
+<h3><a name="userlist"></a>userlist</h3>
+<p>This is a program to print the userlist. There are two flags that
+may be
+set when running this program. When called without any arguments, <tt>userlist</tt>
+will display all users (except those who have chosen to be unlisted),
+their user numbers, times called, messages posted, screen width, and
+date of their most recent call.</p>
+<p><tt>userlist</tt> is simply the same user listing code that is in
+the
+client, made into a standalone utility for convenience.<br>
+</p>
+<h3><a name="sendcommand"></a>sendcommand</h3>
+<p><tt>sendcommand</tt> will interpret its arguments (except for <tt>-hDIRNAME</tt>)
+as a server command, which is sent to the server. Commands which
+require textual input will read it from stdin. Commands which generate
+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.</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
+if not properly restricted.</p>
+</div>
+<br>