+<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>