--- /dev/null
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+<html>
+<head>
+ <title>Citadel/UX Documentation</title>
+
+ <meta http-equiv="content-type"
+ content="text/html; charset=ISO-8859-1">
+</head>
+<body>
+
+<div align="center">
+<h1>Citadel/UX</h1>
+
+<h2>a messaging and collaboration platform for BBS and groupware applications</h2>
+ Copyright ©1987-2003 by the Citadel development team:<br>
+ <br>
+
+<table cellpadding="2" cellspacing="2" border="0" align="center">
+ <tbody>
+ <tr>
+ <td valign="top">Steven M. Bellovin<br>
+ </td>
+ <td valign="top"><i>author of public domain 'parsedate' function<br>
+ </i></td>
+ </tr>
+ <tr>
+ <td valign="top">Nathan Bryant<br>
+ </td>
+ <td valign="top"><i>build system, security, database access,
+and others<br>
+ </i></td>
+ </tr>
+ <tr>
+ <td valign="top">Art Cancro<br>
+ </td>
+ <td valign="top"><i>overall system design and lead developer<br>
+ </i></td>
+ </tr>
+ <tr>
+ <td valign="top">Brian Costello<br>
+ </td>
+ <td valign="top"><i>cosmetics, additional commands<br>
+ </i></td>
+ </tr>
+ <tr>
+ <td valign="top">Michael Hampton<br>
+ </td>
+ <td valign="top"><i>client software development<br>
+ </i></td>
+ </tr>
+ <tr>
+ <td valign="top">Andru Luvisi<br>
+ </td>
+ <td valign="top"><i>troubleshooting and development assistance<br>
+ </i></td>
+ </tr>
+ <tr>
+ <td valign="top">Daniel Malament<br>
+ </td>
+ <td valign="top"><i>string compare function for IMAP server<br>
+ </i></td>
+ </tr>
+ <tr>
+ <td valign="top">Stu Mark<br>
+ </td>
+ <td valign="top"><i>additional client features, IGnet protocol
+ design<br>
+ </i></td>
+ </tr>
+ <tr>
+ <td valign="top">Ben Mehlman<br>
+ </td>
+ <td valign="top"><i>additional client features<br>
+ </i></td>
+ </tr>
+ <tr>
+ <td valign="top">Ari Samson<br>
+ </td>
+ <td valign="top"><i>assistance with project management<br>
+ </i></td>
+ </tr>
+ <tr>
+ <td valign="top">John Walker<br>
+ </td>
+ <td valign="top"><i>author of public domain base64 encoder/decoder<br>
+ </i></td>
+ </tr>
+ <tr>
+ <td valign="top">Steve Williams<br>
+ </td>
+ <td valign="top"><i>documentation<br>
+ </i></td>
+ </tr>
+ <tr>
+ <td valign="top">Ethan Young<br>
+ </td>
+ <td valign="top"><i>IGnet protocol design<br>
+ </i></td>
+ </tr>
+
+ </tbody>
+</table>
+ <br>
+
+<div align="justify">The entire package is open source; you can redistribute
+ and/or modify it under the terms of the GNU General Public License as
+published by the Free Software Foundation; either version 2 of the License,
+or (at your option) any later version.<br>
+ <br>
+ This program is distributed in the hope that it will be useful, but
+WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
+or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
+for more details.<br>
+ </div>
+ <br>
+
+<div align="justify">You should have received a copy of the GNU General Public
+ License along with this program; if not, write to the Free Software Foundation,
+ Inc., 675 Mass Ave, Cambridge, MA 02139, USA.<br>
+ <br>
+ For more information, visit either of these locations on the web:<br>
+
+<ul>
+ <li>The Citadel home page: <a href="http://www.citadel.org">http://www.citadel.org</a></li>
+ <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">
+<h2 align="center">Table of Contents</h2>
+
+<ol>
+ <li><a href="#GPL">Warranty</a></li>
+ <li><a href="#Installation_Guide">Installation Guide</a></li>
+ <li> Baz</li>
+ <li> Eek</li>
+
+</ol>
+ <br>
+
+<hr width="100%" size="2"><br>
+
+<h2 align="center"><a name="GPL"></a>GNU General Public License<br>
+ </h2>
+ </div>
+
+<p> Version 2, June 1991 </p>
+
+<pre>Copyright (C) 1989, 1991 Free Software Foundation, Inc. <br>59 Temple Place - Suite 330, Boston, MA 02111-1307, USA<br><br>Everyone is permitted to copy and distribute verbatim copies<br>of this license document, but changing it is not allowed.<br></pre>
+
+<h3 align="justify">Preamble</h3>
+
+<div align="justify"> </div>
+
+<p align="justify"> The licenses for most software are designed to take
+ away your freedom to share and change it. By contrast, the GNU General
+Public License is intended to guarantee your freedom to share and change
+free software--to make sure the software is free for all its users. This
+General Public License applies to most of the Free Software Foundation's
+software and to any other program whose authors commit to using it. (Some
+other Free Software Foundation software is covered by the GNU Library General
+Public License instead.) You can apply it to your programs, too. </p>
+
+<div align="justify"> </div>
+
+<p align="justify"> When we speak of free software, we are referring to
+ freedom, not price. Our General Public Licenses are designed to make sure
+ that you have the freedom to distribute copies of free software (and charge
+ for this service if you wish), that you receive source code or can get it
+ if you want it, that you can change the software or use pieces of it in
+new free programs; and that you know you can do these things. </p>
+
+<div align="justify"> </div>
+
+<p align="justify"> To protect your rights, we need to make restrictions
+ that forbid anyone to deny you these rights or to ask you to surrender the
+ rights. These restrictions translate to certain responsibilities for you
+ if you distribute copies of the software, or if you modify it. </p>
+
+<div align="justify"> </div>
+
+<p align="justify"> For example, if you distribute copies of such a program,
+ whether gratis or for a fee, you must give the recipients all the rights
+ that you have. You must make sure that they, too, receive or can get the
+ source code. And you must show them these terms so they know their rights.
+ </p>
+
+<div align="justify"> </div>
+
+<p align="justify"> We protect your rights with two steps: (1) copyright
+ the software, and (2) offer you this license which gives you legal permission
+ to copy, distribute and/or modify the software. </p>
+
+<div align="justify"> </div>
+
+<p align="justify"> Also, for each author's protection and ours, we want
+ to make certain that everyone understands that there is no warranty for
+this free software. If the software is modified by someone else and passed
+on, we want its recipients to know that what they have is not the original,
+so that any problems introduced by others will not reflect on the original
+ authors' reputations. </p>
+
+<div align="justify"> </div>
+
+<p align="justify"> Finally, any free program is threatened constantly by
+software patents. We wish to avoid the danger that redistributors of a free
+program will individually obtain patent licenses, in effect making the program
+proprietary. To prevent this, we have made it clear that any patent must
+be licensed for everyone's free use or not licensed at all. </p>
+
+<div align="justify"> </div>
+
+<p align="justify"> The precise terms and conditions for copying, distribution
+ and modification follow. </p>
+
+<div align="justify"> </div>
+
+<h3>TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION</h3>
+
+<div align="justify"> </div>
+
+<p align="justify"> <strong>0.</strong> This License applies to any program
+ or other work which contains a notice placed by the copyright holder saying
+ it may be distributed under the terms of this General Public License. The
+ "Program", below, refers to any such program or work, and a "work based
+on the Program" means either the Program or any derivative work under copyright
+ law: that is to say, a work containing the Program or a portion of it, either
+ verbatim or with modifications and/or translated into another language.
+ (Hereinafter, translation is included without limitation in the term "modification".)
+ Each licensee is addressed as "you". </p>
+
+<p align="justify"> Activities other than copying, distribution and modification
+ are not covered by this License; they are outside its scope. The act of
+ running the Program is not restricted, and the output from the Program
+is covered only if its contents constitute a work based on the Program
+(independent of having been made by running the Program). Whether that
+is true depends on what the Program does. </p>
+
+<p align="justify"> <strong>1.</strong> You may copy and distribute verbatim
+ copies of the Program's source code as you receive it, in any medium, provided
+ that you conspicuously and appropriately publish on each copy an appropriate
+ copyright notice and disclaimer of warranty; keep intact all the notices
+ that refer to this License and to the absence of any warranty; and give
+any other recipients of the Program a copy of this License along with the
+Program. </p>
+
+<p align="justify"> You may charge a fee for the physical act of transferring
+ a copy, and you may at your option offer warranty protection in exchange
+ for a fee. </p>
+
+<p align="justify"> <strong>2.</strong> You may modify your copy or copies
+ of the Program or any portion of it, thus forming a work based on the Program,
+ and copy and distribute such modifications or work under the terms of Section
+ 1 above, provided that you also meet all of these conditions: </p>
+
+<p align="justify"> </p>
+
+<div align="justify">
+<ul>
+ <li><strong>a)</strong> You must cause the modified files to
+carry prominent notices stating that you changed the files and the
+date of any change.
+ <p> </p>
+ </li>
+ <li><strong>b)</strong> You must cause any work that you distribute
+ or publish, that in whole or in part contains or is derived from the
+ Program or any part thereof, to be licensed as a whole at no charge
+ to all third parties under the terms of this License.
+
+ <p> </p>
+ </li>
+ <li><strong>c)</strong> If the modified program normally reads
+ commands interactively when run, you must cause it, when started running
+ for such interactive use in the most ordinary way, to print or display
+ an announcement including an appropriate copyright notice and a
+ notice that there is no warranty (or else, saying that you provide
+ a warranty) and that users may redistribute the program under these
+ conditions, and telling the user how to view a copy of this License.
+ (Exception: if the Program itself is interactive but does not normally
+ print such an announcement, your work based on the Program is not required
+ to print an announcement.) </li>
+
+</ul>
+ These requirements apply to the modified work as a whole. If identifiable
+ sections of that work are not derived from the Program, and can be reasonably
+ considered independent and separate works in themselves, then this License,
+ and its terms, do not apply to those sections when you distribute them as
+ separate works. But when you distribute the same sections as part of a
+whole which is a work based on the Program, the distribution of the whole
+must be on the terms of this License, whose permissions for other licensees
+extend to the entire whole, and thus to each and every part regardless of
+who wrote it. </div>
+
+<p align="justify"> Thus, it is not the intent of this section to claim rights
+or contest your rights to work written entirely by you; rather, the intent
+is to exercise the right to control the distribution of derivative or collective
+works based on the Program. </p>
+
+<p align="justify"> In addition, mere aggregation of another work not based
+ on the Program with the Program (or with a work based on the Program) on
+ a volume of a storage or distribution medium does not bring the other work
+ under the scope of this License. </p>
+
+<p align="justify"> <strong>3.</strong> You may copy and distribute the
+ Program (or a work based on it, under Section 2) in object code or executable
+ form under the terms of Sections 1 and 2 above provided that you also do
+ one of the following: <!-- we use this doubled UL to get the sub-sections indented, -->
+ <!-- while making the bullets as unobvious as possible. --> </p>
+
+<div align="justify">
+<ul>
+ <li><strong>a)</strong> Accompany it with the complete corresponding
+ machine-readable source code, which must be distributed under the terms
+ of Sections 1 and 2 above on a medium customarily used for software
+ interchange; or,
+ <p> </p>
+ </li>
+ <li><strong>b)</strong> Accompany it with a written offer, valid
+ for at least three years, to give any third party, for a charge no
+more than your cost of physically performing source distribution, a
+complete machine-readable copy of the corresponding source code, to
+be distributed under the terms of Sections 1 and 2 above on a medium
+ customarily used for software interchange; or,
+
+ <p> </p>
+ </li>
+ <li><strong>c)</strong> Accompany it with the information you
+ received as to the offer to distribute corresponding source code.
+ (This alternative is allowed only for noncommercial distribution and
+only if you received the program in object code or executable form with
+such an offer, in accord with Subsection b above.) </li>
+
+</ul>
+ The source code for a work means the preferred form of the work for
+ making modifications to it. For an executable work, complete source code
+ means all the source code for all modules it contains, plus any associated
+ interface definition files, plus the scripts used to control compilation
+ and installation of the executable. However, as a special exception, the
+ source code distributed need not include anything that is normally distributed
+ (in either source or binary form) with the major components (compiler, kernel,
+ and so on) of the operating system on which the executable runs, unless
+that component itself accompanies the executable. </div>
+
+<p align="justify"> If distribution of executable or object code is made
+ by offering access to copy from a designated place, then offering equivalent
+ access to copy the source code from the same place counts as distribution
+ of the source code, even though third parties are not compelled to copy
+the source along with the object code. </p>
+
+<p align="justify"> <strong>4.</strong> You may not copy, modify, sublicense,
+ or distribute the Program except as expressly provided under this License.
+ Any attempt otherwise to copy, modify, sublicense or distribute the Program
+ is void, and will automatically terminate your rights under this License.
+ However, parties who have received copies, or rights, from you under this
+ License will not have their licenses terminated so long as such parties
+remain in full compliance. </p>
+
+<p align="justify"> <strong>5.</strong> You are not required to accept
+ this License, since you have not signed it. However, nothing else grants
+ you permission to modify or distribute the Program or its derivative works.
+ These actions are prohibited by law if you do not accept this License.
+ Therefore, by modifying or distributing the Program (or any work based on
+ the Program), you indicate your acceptance of this License to do so, and
+all its terms and conditions for copying, distributing or modifying the Program
+ or works based on it. </p>
+
+<p align="justify"> <strong>6.</strong> Each time you redistribute the Program
+(or any work based on the Program), the recipient automatically receives a
+license from the original licensor to copy, distribute or modify the Program
+ subject to these terms and conditions. You may not impose any further restrictions
+ on the recipients' exercise of the rights granted herein. You are not responsible
+ for enforcing compliance by third parties to this License. </p>
+
+<p align="justify"> <strong>7.</strong> If, as a consequence of a court
+ judgment or allegation of patent infringement or for any other reason (not
+ limited to patent issues), conditions are imposed on you (whether by court
+ order, agreement or otherwise) that contradict the conditions of this License,
+ they do not excuse you from the conditions of this License. If you cannot
+ distribute so as to satisfy simultaneously your obligations under this
+License and any other pertinent obligations, then as a consequence you may
+not distribute the Program at all. For example, if a patent license would
+not permit royalty-free redistribution of the Program by all those who receive
+copies directly or indirectly through you, then the only way you could satisfy
+both it and this License would be to refrain entirely from distribution
+of the Program. </p>
+
+<p align="justify"> If any portion of this section is held invalid or unenforceable
+ under any particular circumstance, the balance of the section is intended
+ to apply and the section as a whole is intended to apply in other circumstances.
+ </p>
+
+<p align="justify"> It is not the purpose of this section to induce you to
+infringe any patents or other property right claims or to contest validity
+ of any such claims; this section has the sole purpose of protecting the
+integrity of the free software distribution system, which is implemented
+by public license practices. Many people have made generous contributions
+to the wide range of software distributed through that system in reliance
+on consistent application of that system; it is up to the author/donor to
+decide if he or she is willing to distribute software through any other system
+and a licensee cannot impose that choice. </p>
+
+<p align="justify"> This section is intended to make thoroughly clear what
+ is believed to be a consequence of the rest of this License. </p>
+
+<p align="justify"> <strong>8.</strong> If the distribution and/or use of
+the Program is restricted in certain countries either by patents or by copyrighted
+interfaces, the original copyright holder who places the Program under this
+License may add an explicit geographical distribution limitation excluding
+those countries, so that distribution is permitted only in or among countries
+not thus excluded. In such case, this License incorporates the limitation
+as if written in the body of this License. </p>
+
+<p align="justify"> <strong>9.</strong> The Free Software Foundation may
+ publish revised and/or new versions of the General Public License from time
+ to time. Such new versions will be similar in spirit to the present version,
+ but may differ in detail to address new problems or concerns. </p>
+
+<p align="justify"> Each version is given a distinguishing version number.
+ If the Program specifies a version number of this License which applies
+ to it and "any later version", you have the option of following the terms
+ and conditions either of that version or of any later version published by
+ the Free Software Foundation. If the Program does not specify a version
+number of this License, you may choose any version ever published by the Free
+Software Foundation. </p>
+
+<p align="justify"> <strong>10.</strong> If you wish to incorporate parts
+ of the Program into other free programs whose distribution conditions are
+ different, write to the author to ask for permission. For software which
+ is copyrighted by the Free Software Foundation, write to the Free Software
+ Foundation; we sometimes make exceptions for this. Our decision will be
+ guided by the two goals of preserving the free status of all derivatives
+of our free software and of promoting the sharing and reuse of software generally.
+ </p>
+
+<p align="justify"><strong>NO WARRANTY</strong></p>
+
+<div align="justify"> </div>
+
+<p align="justify"> <strong>11.</strong> BECAUSE THE PROGRAM IS LICENSED
+ FREE OF CHARGE, THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED
+ BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
+ HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY
+ OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO,
+ THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
+ THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH
+ YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY
+ SERVICING, REPAIR OR CORRECTION. </p>
+
+<p align="justify"> <strong>12.</strong> IN NO EVENT UNLESS REQUIRED BY
+ APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY
+ OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE,
+ BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL
+OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM
+ (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE
+ OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM
+TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS
+BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. </p>
+
+<p align="justify"> </p>
+
+<h3>END OF TERMS AND CONDITIONS</h3>
+ <br>
+
+<hr width="100%" size="2"><br>
+
+<h2><a name="Installation_Guide"></a>Installation Guide</h2>
+
+<div align="justify">
+<h3>Overview</h3>
+
+<p>Citadel/UX is an advanced, multiuser, client/server, room-based BBS program.
+ It is designed to handle the needs of both small dialup systems and large-scale
+ Internet-connected systems. It was originally developed on an Altos system
+ running Xenix, and has been installed and tested on various Unix and Unix-like
+ platforms. The author's current development environment (and BBS) is an
+ordinary Linux system. The current distribution includes: </p>
+
+<ul>
+ <li>The Citadel/UX server (this is the back end that does all processing)
+ </li>
+ <li>A text-based client program designed with the traditional Citadel
+ "look and feel" (room prompts, dot commands, and the like) </li>
+ <li>Setup programs </li>
+ <li>A set of utilities for system administration and maintenance </li>
+ <li>Documentation </li>
+
+</ul>
+
+<p>Some knowledge of the Unix system is necessary to install and manage the
+ system. It is mandatory that the sysop have "root" access to the operating
+ system. The following are required to install Citadel/UX: </p>
+
+<ul>
+ <li>A Unix operating system (Linux, BSD, Solaris, Tru64, HP/UX) </li>
+ <li>C compiler (such as gcc or egcs) and "make" </li>
+ <li>POSIX threads (the "pthreads" library) </li>
+ <li>TCP/IP </li>
+ <li><a href="http://www.sleepycat.com">Berkeley DB</a> v4.1 or newer
+(GDBM also works, but its use is officially depracated. If you are building
+a new system, do <i>not</i> use GDBM. If you have an existing system which
+uses GDBM, you should migrate it to Berkeley DB as soon as possible.) </li>
+ <li>Enough disk space to hold all of the programs and data </li>
+
+</ul>
+
+<p>If you are running Citadel/UX on a Linux system, it is STRONGLY recommended
+ that you run it on a recent distribution (such as <a
+ href="http://www.redhat.com">Red Hat</a> 7.3 or newer). A new-ish distribution
+ will have most or all of the prerequisite tools and libraries already integrated
+ for you.</p>
+
+<h3>Now available:</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 *any* standards-compliant e-mail program,
+thanks to Citadel's built-in SMTP, POP, and IMAP services. </li>
+
+</ul>
+
+<h3>Coming soon:</h3>
+
+<ul>
+ <li>Newer and better GUI-based clients. </li>
+
+</ul>
+
+<h3>Everything in its place...</h3>
+
+<p>Hopefully you've unpacked the distribution archive into its own directory.
+ This is the directory in which all Citadel files are located and in which
+ all activity will take place. Several subdirectories have already been
+created during the unpacking process, and others may be created by the software
+if needed. Make sure you have Berkeley DB installed on your system, and
+that you have all the development libraries and headers in place so that
+you can compile against them. If you don't, you can get the latest Berkeley
+DB at <a href="http://www.sleepycat.com">http://www.sleepycat.com</a>.
+If your operating system uses a separate library to support POSIX threads
+(pthreads), make sure that library is installed as well. This is almost
+never the case with Linux, but some commercial Unix flavors might need it.</p>
+
+<h3>The BBS Login</h3>
+
+<p>As with many Unix programs, Citadel wants to run under its own user ID.
+Unlike other programs, however, this user ID will do double-duty as a public
+login for your system if you are running a BBS. This account is typically
+called "bbs" or "citadel" or something to that effect. You will tell Citadel
+what the user-id of that account is, and when someone logs in under that
+account, Citadel will prompt for a user name.</p>
+
+<p>The Citadel user should have a unique uid. The home directory should be
+the one your Citadel installation resides in (in this example we will use
+/usr/local/citadel) and the shell should be either "citadel" in that directory,
+or a script that will start up citadel (you may wish to set up an external
+text editor; see below). Example:</p>
+
+<pre>bbs::100:1:BBS Login:/usr/local/citadel:/usr/local/citadel/citadel<br></pre>
+
+<p>When you run setup later, you will be required to tell it what the Citadel
+user's numeric user ID 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 ID by default.</p>
+
+<p>For all other users in /etc/passwd, Citadel will automatically set up
+an account using the full name (or 'gecos' in Unixspeak) of the user. It'll
+also ignore any password you supply, because it uses the user's password
+on the host system. This allows a 'single sign on' type of environment. Note
+that this does have to be enabled at compile time -- it's the configure option
+called <tt>--enable-autologin</tt>. Keep in mind that these users can use
+*either* their Citadel login name or their login name on the host computer,
+and their password on the host computer.</p>
+
+<h3>Bypassing the <tt>login:</tt> prompt</h3>
+
+<p>If you normally log in to your host system using some method other than
+telnet (such as ssh), you might want the telnet service to go straight to
+the Citadel BBS, instead of displaying the <tt>login:</tt> prompt first.
+ You can do this by having telnetd start citadel directly instead of <tt>/bin/login</tt>.
+This is actually very simple to implement; all you need to do is make a simple
+change to your <tt>inetd</tt> or <tt>xinetd</tt> configuration. Here are
+some configuration examples.</p>
+
+<p>An example for <tt>inetd</tt> (put the following line in <tt>/etc/inetd.conf<tt>,
+replacing any existing telnet configuration line already there):</p>
+
+<pre>
+telnet stream tcp nowait root /usr/sbin/tcpd in.telnetd -L /usr/local/citadel/citadel
+</pre>
+
+<p>An example for <tt>xinetd</tt> (if you have a file called <tt>/etc/xinetd.d/telnet</tt>
+then simply replace that file with this one):</p>
+
+<pre>service telnet
+{
+ flags = REUSE
+ socket_type = stream
+ wait = no
+ user = root
+ server = /usr/sbin/in.telnetd
+ server_args = -L /usr/local/citadel/citadel
+ log_on_failure += USERID
+ disable = no
+}
+</pre>
+
+<p>Please make sure you know what you're doing before you install
+this! If you are going to put Citadel somewhere other than <tt>/usr/local/citadel</tt>
+then change the directory name accordingly. If you know of any other local
+peculiarities which need to be observed, edit the above configuration accordingly
+as well. And, of course, if you're working remotely, make sure you can successfully
+log in using SSH before you start changing your telnet configuration, otherwise
+you could lock yourself out of your system (ask any networking specialist
+about the dangers of "working inline" -- then pull up a chair and get a fresh
+cup of coffee, because you're going to hear some war stories).</p>
+
+<h3>Compiling the programs</h3>
+
+<p>You can easily compile the Citadel system with the following commands:</p>
+
+<pre>
+./configure<br>make
+make install
+</pre>
+
+<p>The 'configure' script will generate a Makefile from the Makefile.in,
+and it will also write the file "sysdep.h" to your Citadel directory. Please
+do not edit sysdep.h or Makefile.in yourself. The configure script will
+figure out your system dependencies and set everything correctly.</p>
+
+<p>Mac OS X 10.1 and later are now supported. (Sorry, 10.0 cannot
+be supported, now or in the future.) You need to install the Developer Tools
+CD, which you can purchase or download for free from
+<a href="http://developer.apple.com">http://developer.apple.com</a>. Then run
+configure like this:</p>
+
+<pre>
+env CC=/usr/bin/cc ./configure (options - see below)
+</pre>
+
+<p>By default, the Citadel system will install in <tt>/usr/local/citadel</tt>.
+If you wish to place it in a different directory, you can instead do:</p>
+
+<pre>
+./configure --prefix=/export/home/citadel (or whatever)
+</pre>
+
+<p>If you've got Berkeley DB installed in a non-standard location,
+you can help the configure script find it by doing something like this:</p>
+
+<pre>
+./configure --with-db=/usr/local/BerkeleyDB-4.1
+</pre>
+
+<p>The configure script prefers Berkeley DB if it is available, but
+will fall back to GDBM if it has to.</p>
+
+<p>File permissions are always a bother to work with. You don't want
+Citadel to crash because someone couldn't access a file, but you also don't
+want shell users peeking into the binaries to do things like reading others'
+mail, finding private rooms, etc. The Citadel server needs to be started
+as root in order to bind to privileged ports, but as soon as its initialization
+is finished, it changes its user ID to your BBS user ID in order to avoid
+security holes.</p>
+
+<h3>Upgrading</h3>
+
+<p>Upgrading to a new version uses the same build procedure as compiling
+the program for a fresh install, except that you want to do <tt>make install-exec</tt>
+instead of <tt>make install</tt>. This will overwrite the programs but not
+your data. <b>Be sure to shut down citserver during this process!</b> If
+Citadel is running while you upgrade, you may face data corruption issues.</p>
+
+<h3>The <tt>citadel.rc</tt> file</h3>
+
+<p>The text-based client included with Citadel is suitable for BBS
+applications. Much of its command set and other behavior is configurable
+through a Run Control (RC) file. The standard client looks for this file
+in the following locations:
+<ul>
+<li><tt>$HOME/.citadelrc</tt></li>
+<li><tt>/usr/local/lib/citadel.rc</tt></li>
+<li><i>your-Citadel-directory</i><tt>/citadel.rc</tt></li>
+</ul>
+The next couple of sections deal with client-side configuration.</p>
+
+<h3>Using an external editor for message composition</h3>
+
+<p>Citadel/UX has a built-in message editor. However, you can also
+use your favorite text editor to write messages. To do this you simply put
+a line in your citadel.rc file like this:</p>
+
+<pre>
+editor=/usr/bin/vi
+</pre>
+
+<p>The above example would make Citadel call the vi editor when using
+the <tt><b>.E</b>nter <b>E</b>ditor</tt> command. You can also make it the
+default editor for the <tt><b>E</b>nter</tt> command by editing the <tt>citadel.rc</tt>
+file. <b>But be warned:</b> external editors on public systems can be a
+security hole, because they usually provide users with the ability to drop
+into a shell on the host system, or save files using names other than the
+name of the temporary file they are editing. If you intend to use an external
+editor on a public BBS, make sure you use one that has been hardened for
+such a purpose -- one which has had the 'shell' and 'save as' commands disabled,
+as well as any other functions which a destructive user could use to gain
+unauthorized access to your host system.</p>
+
+<h3>Printing messages</h3>
+
+<p>Citadel/UX can send messages to a printer, or just about anywhere
+else in your system. The variable <tt>PRINTCMD</tt> in <tt>citadel.rc</tt>
+specifies what command you use to print. Text is sent to the standard input
+(stdin) of the print command.</p>
+
+<p>So if you did this:</p>
+
+<pre>
+printcmd="nl|pr|lpr -Plocal"
+</pre>
+
+<p>...that would add line numbers, then paginate, 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 textfile. Again, this is probably
+something you don't want to configure for a public BBS host -- most system
+administrators don't want remote users sending arbitrary things to local
+printers.</p>
+
+<h3>URL viewing</h3>
+
+<p>This is one more feature which is appropriate for local users.
+ While reading a message that has Internet URL's in it, you can select the
+<tt><b>U</b>RL-view</tt> command, and it will perform some pre-defined action
+(usually, this is to open up the URL in a web browser). For example:</p>
+
+<pre>
+urlcmd=netscape -remote "openURL(%s)"
+</pre>
+
+<p>In the above example, it would open up the URL in an open
+<a href="http://www.netscape.com/download">Netscape</a> window.</p>
+
+<h3>Setup and login</h3>
+
+<p>Before logging in for the first time, you must run the setup program.
+To begin this procedure, enter the following commands:</p>
+
+<pre>
+cd /usr/local/citadel
+./setup
+</pre>
+
+<p>The setup program will guide you through a simple configuration
+procedure. It will ask you what directory to place your data files in --
+the default is the current directory, which is usually the sensible thing
+to select. If you want to run more than one instance of Citadel on the same
+host, however, you can specify a different directory here -- just remember
+to specify the directory name again when you start up the server later on.</p>
+
+<p><tt>setup</tt> will then shut down the Citadel service if it is
+found to be running.</p>
+
+<p>You will then be prompted for the name of the system administrator.
+This is not merely a cosmetic option -- when you log in to your system a
+little while from now, you'll log in with this name, and it will automatically
+assign your account the highest access level.</p>
+
+<p>Next, you will be prompted for the User ID of the Citadel account
+on your host system. If you have an account called <tt>bbs</tt>, <tt>guest</tt>,
+or <tt>citadel</tt>, that account's UID will be the default. If you are
+upgrading or reconfiguring an existing system, the existing value will be
+preserved.</p>
+
+<p>Then you will be prompted for a server port number. This is the
+TCP port which Citadel clients use to connect to your Citadel server. In
+almost all cases, you want to use the default -- port 504, which is the official
+port number assigned by the IANA for Citadel implementations.</p>
+
+<p>The Citadel service will then be started, and you will see the
+following message:</p>
+
+<pre>
+Setup is finished. You may now log in.
+</pre>
+
+<p>Setup is now complete, on most systems, anyway. Please see below
+to find out if you need to do anything else:</p>
+
+<h3>Configuring your host system to start the service</h3>
+
+<p><b>Please note:</b> this topic involves modifications made to
+<tt>/etc/services</tt> and <tt>/etc/inittab</tt> in order to configure your
+host system to automatically start the Citadel service. <tt>setup</tt> will
+automatically perform these steps if it can, and if you allow it to -- just
+answer 'Yes' when prompted, and everything will be taken care of for you.
+ If you answer 'No' -- or if your system is a little bit odd (for example,
+BSD systems don't have <tt>/etc/inittab</tt>) -- read this section and do
+what you need to in order to get things configured.</p>
+
+<p>Before you can use Citadel, you must define the "citadel" service
+to your system. This is accomplished by adding a line to your /etc/services
+file that looks something like this:</p>
+
+<pre>citadel 504/tcp # Citadel/UX Server<br></pre>
+
+<p>504 is the port number officially designated by the IANA for use
+by Citadel. There should not be any need to use a different port number,
+unless you are running multiple Citadels on the same computer and therefore
+need a different port for each one.</p>
+
+<p>The next step is to arrange for the server to start. The <tt>citserver</tt>
+program is the main Citadel server. Before we cover the recommended method
+of starting the server, let's examine its usage options:</p>
+
+<pre>citserver [-hHomeDir] [-xDebugLevel] [-tTraceFile] [-d] [-f]<br></pre>
+
+<p>The options are as follows:</p>
+
+<p><tt>-hHomeDir</tt> - the directory your BBS data files live in.
+ This should, of course, be a directory that you've run the <tt>setup</tt>
+program against to set up some data files. If a directory is not specified,
+the directory name which was specified in the <tt>Makefile</tt> will be used.</p>
+
+<p><tt>-xDebugLevel</tt> - Set the verbosity of trace messages printed.
+ The available debugging levels are: </p>
+<ul>
+ <li>1 - Internal errors (failed thread creation, malloc problems,
+etc.) </li>
+ <li>2 - Network errors (broken sockets, failed socket creation)
+ </li>
+ <li>3 - Begin and end of sessions, startup/shutdown of server </li>
+ <li>5 - Server commands being sent from clients </li>
+ <li>7 - Entry and exit of various functions </li>
+ <li>8 - Entry and exit of critical sections </li>
+ <li>9 - Various debugging checkpoints (insanely verbose) </li>
+</ul>
+
+<p><tt>-tTraceFile</tt> - Tell the server where to send its debug/trace
+output. Normally it is sent to stdout.</p>
+
+<p><tt>-d</tt> - Run as a daemon; i.e. in the background. This switch
+would be necessary if you were starting the Citadel server, for example,
+from an rc.local script (which is not recommended, because this won't allow
+the server to automatically restart when it is shut down).</p>
+
+<p><tt>-f</tt> - Defragment all the databases upon startup. This
+isn't normally necessary due to the nature of the data stored in Citadel,
+but the option is provided in case you need it. (Note that this only applies
+to GDBM installations; if you are using Berkeley DB it has no effect.)</p>
+
+<p>The preferred method of starting the Citadel server is to place
+an entry in your /etc/inittab file. This will conveniently bring the server
+up when your system is up, and terminate it gracefully when your system
+is shutting down. The exact syntax for your system may vary, but here's
+an entry that could be used on a Linux system:</p>
+
+<pre>
+cit:2345:respawn:/usr/local/citadel/citserver -h/usr/local/citadel -t/dev/tty9 -x3
+</pre>
+
+<p>In this example, we've chosen debugging level 3, and have the
+trace stuff output to one of the virtual consoles. It's important to remember
+to turn off any getty that is set up on that virtual console, if you do this.
+ After making this change, the command <tt>init q</tt> works on most systems
+to tell init to re-read the file. If in doubt, just reboot the computer.</p>
+
+<h3>Logging in for the first time</h3>
+
+<p>At this point, your system is ready to run. Run the <tt>citadel</tt>
+program from the shell and log in as a new user. NOTE: the first user account
+to be created will automatically be set to access level 6 (Aide). This overcomes
+some obvious logistical problems - normally, Aide access is given by another
+Aide, but since there aren't any on your system yet, this isn't possible.</p>
+
+<h3>Welcoming new users</h3>
+
+<p>Sometimes you might decide that you want a welcome message (or
+several different messages) automatically mailed to new users upon their
+first login. Now there is a way to do this. If you create a room called <tt>New
+User Greetings</tt>, and it is a <i>private</i> room (invitation-only probably
+makes the most sense), any messages you enter into that room will automatically
+be delivered to all new users upon registration.</p>
+
+<p>You can put anything you want there: a welcome message, system
+policies, special information, etc. You can also put as many messages there
+as you want to (although it really doesn't make sense to clutter new users'
+mailboxes with lots of junk).</p>
+
+<p>Don't worry about wasting disk space, either. Citadel has a single-instance
+message store, so all the new users are actually looking at the same copy
+of the message on disk.</p>
+
+<h3>Space for adding your own client features (doors)</h3>
+
+<p><b>Please take note!</b> This function really represents the
+"old" way of doing things, and it doesn't fit in well with the client/server
+paradigm. Please consider it "deprecated" because it may be removed someday.</p>
+
+<p>The "doorway" feature is just a generic way to add features to
+the system. I called it "Doorway" to make it resemble the doors on non-Unix
+boards, but as we all know, us Unix types don't have to write special code
+to access the modem. :-) Anyway, when a user hits the <tt><b>*</b></tt>
+(doorway) command, Citadel does...</p>
+
+<pre>
+USERNAME=(username); export USERNAME
+./subsystem (user-number) (screen-width) (access level)
+</pre>
+
+<p>...so you can put whatever you want in there. I suggest putting
+in a menu program to allow the users to pick one of a number of programs,
+etc. Do be aware that door programs will only be available when the client
+and server programs are running on the <i>same</i> computer, and when the
+user is running the text-mode client. Because of these restrictions, Door
+programs are being utilized less and less every day.</p>
+
+<h3>Troubleshooting and getting help</h3>
+
+<p>That's just about all the information you need to install the
+system. But if you get stuck, you can visit UNCENSORED! BBS and report a
+problem or ask for help. But if you intend to report a problem getting the
+Citadel server to run, <i>please</i> double-check the following things first:
+</p>
+<ul>
+ <li>Did you do <tt>./configure && make && make install</tt>
+ ?? </li>
+ <li>Did you run setup? </li>
+ <li>Did you start the server? </li>
+</ul>
+
+<p>To report a problem, you can log on to UNCENSORED! or any other
+BBS 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>
+ <li>The exact nature of your difficulty </li>
+ <li>A transcript of the error message(s) if possible </li>
+ <li>The version of Citadel you are running </li>
+ <li>The version of Berkeley DB present on your system </li>
+ <li>Which operating system you are running, and what version </li>
+ <li>If you are running a Linux system, we need to know which distribution,
+and the version of the kernel, libc, and pthreads you are using (it would
+help to post the output of a <tt>ldd ./citserver</tt> command). </li>
+</ul>
+ </div>
+ </div>
+</body>
+</html>
projects / citadel.git / commitdiff