<head>
<title>Citadel/UX Documentation</title>
-
+
<meta http-equiv="content-type"
content="text/html; charset=ISO-8859-1">
</head>
<body>
-
-<div align="center">
+
+<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>
-
+ 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>
+ <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>
- </div>
- <br>
+ </div>
+ <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. </div>
-<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. </div>
-
<div align="justify"><br>
- For more information, visit either of these locations on the web:<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
+ <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">
+
+<hr width="100%" size="2">
<h2 align="center">Table of Contents</h2>
-
+
<ol>
- <li><a href="#GPL">License</a></li>
- <li><a href="#Installation">Installation</a></li>
-
+ <li><a href="#GPL">License</a></li>
+ <li><a href="#Installation">Installation</a></li>
+
<ol>
- <li><a href="#Everything_in_its_place...">Everything in its place...</a></li>
- <li><a href="#The_BBS_Login">The BBS Login</a></li>
- <li><a href="#Bypassing_the_login:_prompt">Bypassing the login: prompt</a></li>
- <li><a href="#Compiling_the_programs">Compiling the programs</a></li>
- <li><a href="#Upgrading">Upgrading</a></li>
- <li><a href="#The_citadel.rc_file">The citadel.rc file</a></li>
- <li><a href="#Using_an_external_editor_for_message">Using an external
- editor for message composition</a></li>
- <li><a href="#Printing_messages">Printing messages</a></li>
- <li><a href="#URL_viewing">URL viewing</a></li>
- <li><a href="#Setup_and_login">Setup and login</a></li>
- <li><a href="#Configuring_your_host_system_to_start">Configuring
-your host system to start the service</a></li>
- <li><a href="#Logging_in_for_the_first_time">Logging in for the first
- time</a></li>
- <li><a href="#Welcoming_new_users">Welcoming new users</a></li>
- <li><a href="#Space_for_adding_your_own_client">Space for adding
-your own client features (doors)</a></li>
- <li><a href="#Troubleshooting_and_getting_help">Troubleshooting and
- getting help</a><br>
- </li>
-
+ <li><a href="#Everything_in_its_place...">Everything in its place...</a></li>
+ <li><a href="#The_BBS_Login">The BBS Login</a></li>
+ <li><a href="#Bypassing_the_login:_prompt">Bypassing the login:
+ prompt</a></li>
+ <li><a href="#Compiling_the_programs">Compiling the programs</a></li>
+ <li><a href="#Upgrading">Upgrading</a></li>
+ <li><a href="#The_citadel.rc_file">The citadel.rc file</a></li>
+ <li><a href="#Using_an_external_editor_for_message">Using an external
+ editor for message composition</a></li>
+ <li><a href="#Printing_messages">Printing messages</a></li>
+ <li><a href="#URL_viewing">URL viewing</a></li>
+ <li><a href="#Setup_and_login">Setup and login</a></li>
+ <li><a href="#Configuring_your_host_system_to_start">Configuring
+ your host system to start the service</a></li>
+ <li><a href="#Logging_in_for_the_first_time">Logging in for the
+ first time</a></li>
+ <li><a href="#Welcoming_new_users">Welcoming new users</a></li>
+ <li><a href="#Space_for_adding_your_own_client">Space for adding
+ your own client features (doors)</a></li>
+ <li><a href="#Troubleshooting_and_getting_help">Troubleshooting
+ and getting help</a><br>
+ </li>
+
+ </ol>
+ <li><a href="#sysop">System Administration</a></li>
+
+ <ol>
+ <li><a href="#Overview_">Overview</a></li>
+ <li><a href="#Aide_commands">Aide commands</a></li>
+ <li><a href="#Editing_rooms">Editing rooms</a></li>
+ <li><a href="#File_directories">File directories</a></li>
+ <li><a href="#Creating_and_editing_user_accounts">Creating and
+editing user accounts</a></li>
+ <li><a href="#Deleting_and_moving_messages">Deleting and moving
+ messages</a></li>
+ <li><a href="#Customizing_the_help_files">Customizing the help
+files</a></li>
+ <li><a href="#Site_configuration">Site configuration</a><br>
+ </li>
+
+ </ol>
+ <li> <a href="#Configuring_Citadel_for_Internet_e-mail">Configuring
+ Citadel for Internet e-mail</a></li>
+
+ <ol>
+ <li><a href="#Introduction">Introduction</a></li>
+ <li><a href="#Basic_site_configuration">Basic site configuration</a></li>
+ <li><a href="#Enabling_the_Internet_mail_protocols">Enabling the
+Internet mail protocols</a></li>
+ <li><a href="#Hosting_an_Internet_mailing_list">Hosting an Internet
+ mailing list</a><br>
+ </li>
+ <li><a href="#citmail">Using Citadel in conjunction with another
+MTA</a></li>
+
</ol>
- <li><a href="#sysop">System Administration</a></li>
+ <li><a href="#Building_or_joining_a_Citadel_network">Building or joining
+ a Citadel network</a></li>
<ol>
- <li><a href="#Overview_">Overview</a></li>
- <li><a href="#Aide_commands">Aide commands</a></li>
- <li><a href="#Editing_rooms">Editing rooms</a></li>
- <li><a href="#File_directories">File directories</a></li>
- <li><a href="#Creating_and_editing_user_accounts">Creating and editing
- user accounts</a></li>
- <li><a href="#Deleting_and_moving_messages">Deleting and moving messages</a></li>
- <li><a href="#Customizing_the_help_files">Customizing the help files</a></li>
- <li><a href="#Site_configuration">Site configuration</a><br>
- </li>
+ <li><a href="#Overview__">Overview</a></li>
+ <li><a href="#Conventions_and_etiquette_when">Conventions and etiquette
+ when connecting to the public Citadel network</a></li>
+ <li><a href="#Getting_ready_to_join_the_network">Getting ready to
+join the network</a></li>
+ <li><a href="#Defining_neighbor_nodes">Defining neighbor nodes</a></li>
+ <li><a href="#Sharing_rooms">Sharing rooms</a></li>
+ <li><a href="#Sending_mail">Sending mail</a></li>
+ <li><a href="#Changing_the_polling_interval">Changing the polling
+interval</a></li>
</ol>
- <li> <a href="#Configuring_Citadel_for_Internet_e-mail">Configuring
- Citadel for Internet e-mail</a></li>
+ <li><a href="#Database_maintenance">Database maintenance</a></li>
<ol>
- <li><a href="#Introduction">Introduction</a></li>
- <li><a href="#Basic_site_configuration">Basic site configuration</a></li>
- <li><a href="#Enabling_the_Internet_mail_protocols">Enabling the Internet
- mail protocols</a></li>
- <li><a href="#Hosting_an_Internet_mailing_list">Hosting an Internet
-mailing list</a><br>
+ <li><a href="#Introduction_">Introduction</a></li>
+ <li><a href="#Database_repair">Database repair</a></li>
+ <li><a href="#ImportingExporting_your_Citadel">Importing/Exporting
+your Citadel database</a><br>
</li>
- <li><a href="#citmail">Using Citadel in conjunction with another MTA</a></li>
-
- </ol>
- <li><a href="#Building_or_joining_a_Citadel_network">Building or joining
-a Citadel network</a></li>
-
- <ol>
- <li><a href="#Overview__">Overview</a></li>
- <li><a href="#Conventions_and_etiquette_when">Conventions and etiquette
-when connecting to the public Citadel network</a></li>
- <li><a href="#Getting_ready_to_join_the_network">Getting ready to join
-the network</a></li>
- <li><a href="#Defining_neighbor_nodes">Defining neighbor nodes</a></li>
- <li><a href="#Sharing_rooms">Sharing rooms</a></li>
- <li><a href="#Sending_mail">Sending mail</a></li>
- <li><a href="#Changing_the_polling_interval">Changing the polling interval</a></li>
-
+
</ol>
-
+
</ol>
- <br>
-
+ <br>
+
<hr width="100%" size="2"><br>
-
+
<h2 align="center"><a name="GPL"></a>GNU General Public License<br>
- </h2>
- </div>
-
+ </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.
+
+<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>
-
+ 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>
-
+
+<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 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>
-
+
+<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>
-
+
+<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>
-
+
+<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>
-
+
+<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>
-
+
+<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"> <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">
+
+<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.
-
+ <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.
-
+ </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>
-
+ </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">
+ 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,
-
+ <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,
-
+ </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>
-
+ </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
+ 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>
-
+ 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"> <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>
-
+ <br>
+
<hr width="100%" size="2"><br>
-
-<div align="center">
+
+<div align="center">
<h2><a name="Installation"></a>Installation</h2>
- </div>
-
-<div align="justify">
+ </div>
+
+<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>
-
+
+<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>
-
+ <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>
-
+
+<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>
-
+ <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>
-
+
+<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 <i>any</i> standards-compliant e-mail
-program, thanks to Citadel's built-in SMTP, POP, and IMAP services. You
-can use Netscape/Mozilla, Evolution, Eudora, Pine, or even Microsoft VirusSpreader
- (better known as "Outlook") with Citadel. </li>
-
+ <li>"WebCit", a gateway program to allow full access to Citadel
+ via the World Wide Web. Interactive access through any Web browser.
+ </li>
+ <li>Access to Citadel via <i>any</i> standards-compliant e-mail
+ program, thanks to Citadel's built-in SMTP, POP, and IMAP services.
+ You can use Netscape/Mozilla, Evolution, Eudora, Pine, or even Microsoft
+VirusSpreader (better known as "Outlook") with Citadel. </li>
+
</ul>
-
+
<h3>Coming soon:</h3>
-
+
<ul>
- <li>Newer and better GUI-based clients. </li>
-
+ <li>Newer and better GUI-based clients. </li>
+
</ul>
-
+
<h3><a name="Everything_in_its_place..."></a>Everything in its place...</h3>
-
-<p>Hopefully you've unpacked the distribution archive into its own 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>
-
+
+<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><a name="The_BBS_Login"></a></h3>
-
+
<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
+
+<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>
-
+
+<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>
-
+
+<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><a name="Bypassing_the_login:_prompt"></a></h3>
-
+
<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>
-
+
+<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<br></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>
-
+
+<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<br>{<br> flags = REUSE<br> socket_type = stream<br> wait = no<br> user = root<br> server = /usr/sbin/in.telnetd<br> server_args = -L /usr/local/citadel/citadel<br> log_on_failure += USERID<br> disable = no<br>}<br></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>
-
+
+<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><a name="Compiling_the_programs"></a>Compiling the programs</h3>
-
+
<p>You can easily compile the Citadel system with the following commands:</p>
-
+
<pre>./configure<br>make<br>make install<br></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>
-
+
+<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)<br></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>
-
+
+<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)<br></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>
-
+
+<p>If you've got Berkeley DB installed in a non-standard location, you can
+ help the configure script find it by doing something like this:</p>
+
<pre>./configure --with-db=/usr/local/BerkeleyDB-4.1<br></pre>
-
-<p>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>
-
+
+<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><a name="Upgrading"></a></h3>
-
+
<h3>Upgrading</h3>
-
-<p>Any existing Citadel installation which is at version 5.50 or newer may
- be upgraded in place without the need to discard your existing data files.</p>
-
-<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.<br>
- </p>
-
-<p>After doing <tt>make install-exec</tt>, you should run <tt>setup</tt> again
-to bring your data files up to date. Please see the setup section below
-for more information on this.</p>
-
+
+<p>Any existing Citadel installation which is at version 5.50 or newer may
+ be upgraded in place without the need to discard your existing data files.</p>
+
+<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.<br>
+ </p>
+
+<p>After doing <tt>make install-exec</tt>, you should run <tt>setup</tt>
+again to bring your data files up to date. Please see the setup section
+below for more information on this.</p>
+
<h3><a name="The_citadel.rc_file"></a>The <tt>citadel.rc</tt> file</h3>
-
-<p>The text-based client included with Citadel is suitable for BBS applications.
- Much of its command set and other behavior is configurable through a Run
- Control (RC) file. The standard client looks for this file in the following
- locations: </p>
-
+
+<p>The text-based client included with Citadel is suitable for BBS applications.
+ Much of its command set and other behavior is configurable through a Run
+ Control (RC) file. The standard client looks for this file in the following
+ locations: </p>
+
<ul>
- <li><tt>$HOME/.citadelrc</tt></li>
- <li><tt>/usr/local/lib/citadel.rc</tt></li>
- <li><i>your-Citadel-directory</i><tt>/citadel.rc</tt></li>
-
+ <li><tt>$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.
-
-<h3><a name="Using_an_external_editor_for_message"></a>Using an external
-editor for message composition</h3>
-
-<p>Citadel/UX has a built-in message editor. However, you can also use your
- favorite text editor to write messages. To do this you simply put a line
- in your citadel.rc file like this:</p>
-
+ The next couple of sections deal with client-side configuration.
+
+<h3><a name="Using_an_external_editor_for_message"></a>Using an external editor
+for message composition</h3>
+
+<p>Citadel/UX has a built-in message editor. However, you can also use your
+ favorite text editor to write messages. To do this you simply put a line
+ in your citadel.rc file like this:</p>
+
<pre>editor=/usr/bin/vi<br></pre>
-
-<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>
-
+
+<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><a name="Printing_messages"></a>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>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"<br></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>
-
+
+<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><a name="URL_viewing"></a>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
+
+<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)"<br></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><a name="Setup_and_login"></a></h3>
-
+
<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>
-
+
+<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<br>./setup<br></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
+
+<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>
-
+
+<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.<br></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><a name="Configuring_your_host_system_to_start"></a>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
+
+<p>Setup is now complete, on most systems, anyway. Please see below to find
+ out if you need to do anything else:</p>
+
+<h3><a name="Configuring_your_host_system_to_start"></a>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>
-
+
+<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>
-
+
+<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>
-
+
+<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>
-
+ <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
+
+<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
+
+<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>
-
+
+<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<br></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
+
+<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><a name="Logging_in_for_the_first_time"></a>Logging in for the first
-time</h3>
-
-<p>At this point, your system is ready to run. Run the <tt>citadel</tt> program
- from the shell and log in as a new user. NOTE: the first user 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
+
+<h3><a name="Logging_in_for_the_first_time"></a>Logging in for the first time</h3>
+
+<p>At this point, your system is ready to run. Run the <tt>citadel</tt> program
+ from the shell and log in as a new user. NOTE: the first user 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><a name="Welcoming_new_users"></a>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><a name="Space_for_adding_your_own_client"></a>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>
-
+
+<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><a name="Space_for_adding_your_own_client"></a>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<br>./subsystem (user-number) (screen-width) (access level)<br></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><a name="Troubleshooting_and_getting_help"></a>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>
-
+
+<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><a name="Troubleshooting_and_getting_help"></a>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>
-
+ <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
+
+<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>
-
+ <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 align="center">
-<hr width="100%" size="2">
+ </div>
+
+<div align="center">
+<hr width="100%" size="2">
<h2><a name="sysop"></a>System Administration</h2>
- </div>
-
-<div align="justify">
+ </div>
+
+<div align="justify">
<h3><a name="Overview_"></a>Overview</h3>
-
-<p>Citadel/UX, when installed properly, will do most of its maintenance by
- itself. It is intended to be run unattended for extended periods of time,
- and most installations do just that without any software failures.</p>
-
-<p>The system has seven access levels. Most users are at the bottom and
-have no special privileges. Aides are selected people who have special access
-within the Citadel program. Room Aides only have this access in a certain
-room. Preferred users can be selected by Aides for access to preferred only
-rooms. A sysop is anyone who has access to the various sysop utilities -
-these are in their own executable files, which should have their permissions
-set to allow only sysops to run them. You should either create a sysops
-group in /etc/group, or use some other existing group for this purpose.</p>
-
-<p>Aides have access to EVERY room on the system, public and private (all
- types). They also have access to commands starting with <tt>.<b>A</b>ide</tt>
- in addition to being able to delete and move messages. The system room,
- <tt>Aide></tt>, is accessible only by those users designated as Aides.</p>
-
+
+<p>Citadel/UX, when installed properly, will do most of its maintenance by
+ itself. It is intended to be run unattended for extended periods of
+time, and most installations do just that without any software failures.</p>
+
+<p>The system has seven access levels. Most users are at the bottom and have
+no special privileges. Aides are selected people who have special access within
+the Citadel program. Room Aides only have this access in a certain room.
+ Preferred users can be selected by Aides for access to preferred only rooms.
+ A sysop is anyone who has access to the various sysop utilities - these
+are in their own executable files, which should have their permissions set
+to allow only sysops to run them. You should either create a sysops group
+in /etc/group, or use some other existing group for this purpose.</p>
+
+<p>Aides have access to EVERY room on the system, public and private (all
+ types). They also have access to commands starting with <tt>.<b>A</b>ide</tt>
+ in addition to being able to delete and move messages. The system room,
+ <tt>Aide></tt>, is accessible only by those users designated as Aides.</p>
+
<h3><a name="Aide_commands"></a>Aide commands</h3>
-
-<p>Aides have the following commands available to them that are not available
- to normal users. They are:</p>
-
+
+<p>Aides have the following commands available to them that are not available
+ to normal users. They are:</p>
+
<table>
- <tbody>
- <tr>
- <td width="30%"><tt> .<b>A</b>ide <b>K</b>ill this room </tt></td>
- <td> Deletes the current room from the system. </td>
- </tr>
- <tr>
- <td width="30%"><tt> .<b>A</b>ide <b>E</b>dit this room </tt></td>
- <td> Allows editing of the properties of the current room. This
- is explained in greater detail below. </td>
- </tr>
- <tr>
- <td width="30%"><tt> .<b>A</b>ide <b>W</b>ho knows room </tt></td>
- <td> For private rooms with access controls, or mailbox rooms,
-this command displays a list of users who have access to the current room.
- </td>
- </tr>
- <tr>
- <td width="30%"><tt> .<b>A</b>ide edit <b>U</b>ser </tt></td>
- <td> Allows editing of the properties of any user account on the
- system. </td>
- </tr>
- <tr>
- <td width="30%"><tt> .<b>A</b>ide <b>V</b>alidate new users </tt></td>
- <td> For public access systems, this command reviews all new user
- registrations and allows you to set each new user's access level (or simply
- delete the accounts). </td>
- </tr>
- <tr>
- <td width="30%"><tt> .<b>A</b>ide enter <b>I</b>nfo file </tt></td>
- <td> Each room may contain a short textual description of its purpose,
- which is displayed to users upon entering the room for the first time (or
- in the room banner, for users of the Web client). This command allows
-you to enter or edit that description. </td>
- </tr>
- <tr>
- <td width="30%"><tt> .<b>A</b>ide <b>R</b>oom <b>I</b>nvite user
- </tt></td>
- <td> Access control command to grant any specific user access to
- a private room. </td>
- </tr>
- <tr>
- <td width="30%"><tt> .<b>A</b>ide <b>R</b>oom <b>K</b>ick out user
- </tt></td>
- <td> Access control command to revoke any specifc user's access
-to the current room. This works regardless of whether the room is public
-or private. </td>
- </tr>
- <tr>
- <td width="30%"><tt> .<b>A</b>ide <b>F</b>ile <b>D</b>elete </tt></td>
- <td> If the current room has an associated file directory, this
-command may be used to delete files from it. </td>
- </tr>
- <tr>
- <td width="30%"><tt> .<b>A</b>ide <b>F</b>ile <b>S</b>end over
-net </tt></td>
- <td> If the current room has an associated file directory, this
-command may be used to transmit a copy of any file in that directory to another
-node on a Citadel network. </td>
- </tr>
- <tr>
- <td width="30%"><tt> .<b>A</b>ide <b>F</b>ile <b>M</b>ove </tt></td>
- <td> If the current room has an associated file directory, this
-command may be used to move any file in that directory to another room.
-The target room must also have an associated file directory. </td>
- </tr>
- <tr>
- <td width="30%"><tt> .<b>A</b>ide <b>M</b>essage edit </tt></td>
- <td> This command allows editing of any of the various system banners
- and messages which are displayed to users. Type the name of the banner
-or message you wish to edit. </td>
- </tr>
- <tr>
- <td width="30%"><tt> .<b>A</b>ide <b>P</b>ost </tt></td>
- <td> This is the functional equivalent of the <tt><b>E</b>nter
-message</tt> command available to all users, except that it allows you
+ <tbody>
+ <tr>
+ <td width="30%"><tt> .<b>A</b>ide <b>K</b>ill this room </tt></td>
+ <td> Deletes the current room from the system. </td>
+ </tr>
+ <tr>
+ <td width="30%"><tt> .<b>A</b>ide <b>E</b>dit this room </tt></td>
+ <td> Allows editing of the properties of the current room.
+This is explained in greater detail below. </td>
+ </tr>
+ <tr>
+ <td width="30%"><tt> .<b>A</b>ide <b>W</b>ho knows room </tt></td>
+ <td> For private rooms with access controls, or mailbox rooms,
+ this command displays a list of users who have access to the current room.
+ </td>
+ </tr>
+ <tr>
+ <td width="30%"><tt> .<b>A</b>ide edit <b>U</b>ser </tt></td>
+ <td> Allows editing of the properties of any user account on
+the system. </td>
+ </tr>
+ <tr>
+ <td width="30%"><tt> .<b>A</b>ide <b>V</b>alidate new users
+ </tt></td>
+ <td> For public access systems, this command reviews all new
+user registrations and allows you to set each new user's access level (or
+simply delete the accounts). </td>
+ </tr>
+ <tr>
+ <td width="30%"><tt> .<b>A</b>ide enter <b>I</b>nfo file </tt></td>
+ <td> Each room may contain a short textual description of its
+ purpose, which is displayed to users upon entering the room for the first
+ time (or in the room banner, for users of the Web client). This command
+ allows you to enter or edit that description. </td>
+ </tr>
+ <tr>
+ <td width="30%"><tt> .<b>A</b>ide <b>R</b>oom <b>I</b>nvite
+user </tt></td>
+ <td> Access control command to grant any specific user access
+ to a private room. </td>
+ </tr>
+ <tr>
+ <td width="30%"><tt> .<b>A</b>ide <b>R</b>oom <b>K</b>ick out
+ user </tt></td>
+ <td> Access control command to revoke any specifc user's access
+ to the current room. This works regardless of whether the room is public
+ or private. </td>
+ </tr>
+ <tr>
+ <td width="30%"><tt> .<b>A</b>ide <b>F</b>ile <b>D</b>elete
+ </tt></td>
+ <td> If the current room has an associated file directory, this
+ command may be used to delete files from it. </td>
+ </tr>
+ <tr>
+ <td width="30%"><tt> .<b>A</b>ide <b>F</b>ile <b>S</b>end over
+ net </tt></td>
+ <td> If the current room has an associated file directory, this
+ command may be used to transmit a copy of any file in that directory to
+ another node on a Citadel network. </td>
+ </tr>
+ <tr>
+ <td width="30%"><tt> .<b>A</b>ide <b>F</b>ile <b>M</b>ove </tt></td>
+ <td> If the current room has an associated file directory, this
+ command may be used to move any file in that directory to another room.
+ The target room must also have an associated file directory. </td>
+ </tr>
+ <tr>
+ <td width="30%"><tt> .<b>A</b>ide <b>M</b>essage edit </tt></td>
+ <td> This command allows editing of any of the various system
+ banners and messages which are displayed to users. Type the name of the
+ banner or message you wish to edit. </td>
+ </tr>
+ <tr>
+ <td width="30%"><tt> .<b>A</b>ide <b>P</b>ost </tt></td>
+ <td> This is the functional equivalent of the <tt><b>E</b>nter
+ message</tt> command available to all users, except that it allows you
to post using any user name. </td>
- </tr>
- <tr>
- <td width="30%"><tt> .<b>A</b>ide <b>S</b>ystem configuration <b>G</b>eneral
- </tt></td>
- <td> This command allows configuration of a large number of global
- settings for your Citadel system. These settings will be explained in
-greater detail below. </td>
- </tr>
- <tr>
- <td width="30%"><tt> .<b>A</b>ide <b>S</b>ystem configuration <b>I</b>nternet
+ </tr>
+ <tr>
+ <td width="30%"><tt> .<b>A</b>ide <b>S</b>ystem configuration
+ <b>G</b>eneral </tt></td>
+ <td> This command allows configuration of a large number of
+global settings for your Citadel system. These settings will be explained
+in greater detail below. </td>
+ </tr>
+ <tr>
+ <td width="30%"><tt> .<b>A</b>ide <b>S</b>ystem configuration
+ <b>I</b>nternet </tt></td>
+ <td> This command allows configuration of settings which affect
+ how your Citadel system sends and receives messages on the Internet. </td>
+ </tr>
+ <tr>
+ <td width="30%"><tt> .<b>A</b>ide <b>S</b>ystem configuration
+ check <b>M</b>essage base </tt></td>
+ <td> Perform a consistency check on your message store. This
+ is a very time-consuming operation which should not be performed unless
+ you have reason to believe there is trouble with your database. </td>
+ </tr>
+ <tr>
+ <td width="30%"><tt> .<b>A</b>ide <b>S</b>ystem configuration
+ <b>N</b>etwork </tt></td>
+ <td> Configure networking (e-mail, room sharing, etc.) with
+other Citadel nodes. </td>
+ </tr>
+ <tr>
+ <td width="30%"><tt> .<b>A</b>ide <b>S</b>ystem configuration
+ network <b>F</b>ilter list </tt></td>
+ <td> If you are on a large public or semi-public network of
+Citadel nodes and you find content from certain systems or individuals
+objectionable, you can use this command to define a rule set to automatically
+reject those messages when they arrive on your system. </td>
+ </tr>
+ <tr>
+ <td width="30%"><tt> .<b>A</b>ide <b>T</b>erminate server <b>N</b>ow
+ </tt></td>
+ <td> Immediately shut down the Citadel service, disconnecting
+ any users who are logged in. Please keep in mind that it will start right
+ back up again if you are running the service from <tt>/etc/inittab</tt>,
+ so in practice this command will probably not get much use. </td>
+ </tr>
+ <tr>
+ <td width="30%"><tt> .<b>A</b>ide <b>T</b>erminate server <b>S</b>cheduled
+ </tt></td>
+ <td> Shut down the Citadel service the next time there are zero
+ users connected. This allows you to automatically wait until all users
+are logged out. </td>
+ </tr>
+ <tr>
+ <td width="30%"><tt> .<b>A</b>ide mailing <b>L</b>ist recipients
</tt></td>
- <td> This command allows configuration of settings which affect
-how your Citadel system sends and receives messages on the Internet. </td>
- </tr>
- <tr>
- <td width="30%"><tt> .<b>A</b>ide <b>S</b>ystem configuration check
- <b>M</b>essage base </tt></td>
- <td> Perform a consistency check on your message store. This is
- a very time-consuming operation which should not be performed unless you
- have reason to believe there is trouble with your database. </td>
- </tr>
- <tr>
- <td width="30%"><tt> .<b>A</b>ide <b>S</b>ystem configuration <b>N</b>etwork
- </tt></td>
- <td> Configure networking (e-mail, room sharing, etc.) with other
- Citadel nodes. </td>
- </tr>
- <tr>
- <td width="30%"><tt> .<b>A</b>ide <b>S</b>ystem configuration network
- <b>F</b>ilter list </tt></td>
- <td> If you are on a large public or semi-public network of Citadel
- nodes and you find content from certain systems or individuals objectionable,
- you can use this command to define a rule set to automatically reject those
- messages when they arrive on your system. </td>
- </tr>
- <tr>
- <td width="30%"><tt> .<b>A</b>ide <b>T</b>erminate server <b>N</b>ow
- </tt></td>
- <td> Immediately shut down the Citadel service, disconnecting any
- users who are logged in. Please keep in mind that it will start right back
- up again if you are running the service from <tt>/etc/inittab</tt>, so in
- practice this command will probably not get much use. </td>
- </tr>
- <tr>
- <td width="30%"><tt> .<b>A</b>ide <b>T</b>erminate server <b>S</b>cheduled
- </tt></td>
- <td> Shut down the Citadel service the next time there are zero
-users connected. This allows you to automatically wait until all users are
-logged out. </td>
- </tr>
- <tr>
- <td width="30%"><tt> .<b>A</b>ide mailing <b>L</b>ist recipients
- </tt></td>
- <td> Any room may be made into a mailing list. Enter this command
- to open an editor window containing the list of Internet e-mail addresses
- to which every message posted in the room will be sent. </td>
- </tr>
- <tr>
- <td width="30%"><tt> .<b>A</b>ide mailing list <b>D</b>igest recipients
- </tt></td>
- <td> Similar to the regular mailing list command, except the messages
- will be sent out in 'digest' form -- recipients will see messages from
-the address of the room itself rather than the address of the author of
-each message, and a digest may contain more than one message. Each room
+ <td> Any room may be made into a mailing list. Enter this command
+ to open an editor window containing the list of Internet e-mail addresses
+ to which every message posted in the room will be sent. </td>
+ </tr>
+ <tr>
+ <td width="30%"><tt> .<b>A</b>ide mailing list <b>D</b>igest
+recipients </tt></td>
+ <td> Similar to the regular mailing list command, except the
+messages will be sent out in 'digest' form -- recipients will see messages
+from the address of the room itself rather than the address of the author
+of each message, and a digest may contain more than one message. Each room
may have any combination of List and Digest recipients. </td>
- </tr>
- <tr>
- <td width="30%"><tt> .<b>A</b>ide <b>N</b>etwork room sharing </tt></td>
- <td> Configures the sharing of the current room's contents with
-other Citadel nodes. Messages posted in this room on any Citadel system
-will automatically be replicated to other Citadel systems carrying the room.
- </td>
- </tr>
-
- </tbody>
+ </tr>
+ <tr>
+ <td width="30%"><tt> .<b>A</b>ide <b>N</b>etwork room sharing
+ </tt></td>
+ <td> Configures the sharing of the current room's contents with
+ other Citadel nodes. Messages posted in this room on any Citadel system
+ will automatically be replicated to other Citadel systems carrying the
+room. </td>
+ </tr>
+
+ </tbody>
</table>
-
+
<h3><a name="Editing_rooms"></a>Editing rooms</h3>
-
-<p>This command allows any aide to change the parameters of a room. Go to
- the room you wish to edit and enter the <tt><b>.A</b>ide <b>E</b>dit room</tt>
- command. A series of prompts will be displayed. The existing parameters
- will be displayed in brackets; simply press return if you want to leave
-any or all of them unchanged.</p>
-
+
+<p>This command allows any aide to change the parameters of a room. Go to
+ the room you wish to edit and enter the <tt><b>.A</b>ide <b>E</b>dit
+room</tt> command. A series of prompts will be displayed. The existing
+parameters will be displayed in brackets; simply press return if you want
+to leave any or all of them unchanged.</p>
+
<pre> <br>Room name [IG's Fun Room]:<br></pre>
-
+
<p>...the name of the room.</p>
-
+
<pre>Private room [Yes]? <br></pre>
-
-<p>...enter Yes if you wish to restrict access to the room, or no if the
-room is to be accessible by all users. Note that Citadel doesn't bother
-users about access to rooms every time they need to access the room. Once
-a user gains access to a private room, it then behaves like a public room
-to them. The following four questions will only be asked if you selected
-Private...</p>
-
+
+<p>...enter Yes if you wish to restrict access to the room, or no if the room
+is to be accessible by all users. Note that Citadel doesn't bother users
+about access to rooms every time they need to access the room. Once a user
+gains access to a private room, it then behaves like a public room to them.
+The following four questions will only be asked if you selected Private...</p>
+
<pre>Accessible by guessing room name [No]?<br></pre>
-
-<p>...if you enter Yes, the room will not show up in users' <tt><b>K</b>nown
- rooms</tt> listing, but if they <tt><b>.G</b>oto</tt> the room (typing
+
+<p>...if you enter Yes, the room will not show up in users' <tt><b>K</b>nown
+ rooms</tt> listing, but if they <tt><b>.G</b>oto</tt> the room (typing
the room's full name), they will gain access to the room.</p>
-
+
<pre>Accessible by entering a password [No]?<br>Room password [mypasswd]: <br></pre>
-
-<p>...this adds an additional layer of security to the room, prompting users
- for a password before they can gain access to the room.</p>
-
-<p>If you did not select guessname or passworded, then the only way users
- can access the room is if an Aide explicitly invites them to the room using
- the <tt><b>.A</b>ide <b>R</b>oom <b>I</b>nvite user</tt> command.</p>
-
+
+<p>...this adds an additional layer of security to the room, prompting users
+ for a password before they can gain access to the room.</p>
+
+<p>If you did not select guessname or passworded, then the only way users
+ can access the room is if an Aide explicitly invites them to the room using
+ the <tt><b>.A</b>ide <b>R</b>oom <b>I</b>nvite user</tt> command.</p>
+
<pre>Cause current users to forget room [No] ? No<br></pre>
-
-<p>Enter Yes if you wish to kick out anyone who currently has access to the
- room.</p>
-
+
+<p>Enter Yes if you wish to kick out anyone who currently has access to the
+ room.</p>
+
<pre>Preferred users only [No]? No<br></pre>
-
-<p>Enter Yes if you wish to restrict the room to only users who have level
- 5 (Preferred User) status (and Aides too, of course). You should make
-the room public if you intend to do this, otherwise the two restrictions
+
+<p>Enter Yes if you wish to restrict the room to only users who have level
+ 5 (Preferred User) status (and Aides too, of course). You should make
+the room public if you intend to do this, otherwise the two restrictions
will be COMBINED.</p>
-
+
<pre>Read-only room [No]? No<br></pre>
-
-<p>If you set a room to Read-Only, then normal users will not be allowed
-to post messages in it. Messages may only be posted by Aides, and by utility
- programs such as the networker and the "aidepost" utility. This is useful
- in situations where a room is used exclusively for important announcements,
- or if you've set up a room to receive an Internet mailing list and posting
- wouldn't make sense. Other uses will, of course, become apparent as the
- need arises.</p>
-
+
+<p>If you set a room to Read-Only, then normal users will not be allowed to
+post messages in it. Messages may only be posted by Aides, and by utility
+ programs such as the networker and the "aidepost" utility. This is useful
+ in situations where a room is used exclusively for important announcements,
+ or if you've set up a room to receive an Internet mailing list and posting
+ wouldn't make sense. Other uses will, of course, become apparent as
+the need arises.</p>
+
<p>Now for a few other attributes...</p>
-
+
<pre>Directory room [Yes]? Yes<br></pre>
-
-<p>...enter Yes if you wish to associate a directory with this room. This
- can be used as a small file repository for files relevant to the topic
-of the room. If you enter Yes, you will also be prompted with the following
- four questions:</p>
-
+
+<p>...enter Yes if you wish to associate a directory with this room. This
+ can be used as a small file repository for files relevant to the topic
+of the room. If you enter Yes, you will also be prompted with the following
+ four questions:</p>
+
<pre>Directory name [mydirname]: <br></pre>
-
-<p>...the name of the subdirectory to put this room's files in. The name
- of the directory created will be <tt><i><your BBS directory></i>/files/<i><room
- dir name></i></tt>.</p>
-
+
+<p>...the name of the subdirectory to put this room's files in. The name
+ of the directory created will be <tt><i><your BBS directory></i>/files/<i><room
+ dir name></i></tt>.</p>
+
<pre>Uploading allowed [Yes]? Yes<br></pre>
-
+
<p>...enter Yes if users are allowed to upload to this room.</p>
-
+
<pre>Downloading allowed [Yes]? Yes<br></pre>
-
+
<p>...enter Yes if users are allowed to download from this room.</p>
-
+
<pre>Visible directory [Yes]? Yes<br></pre>
-
+
<p>...enter Yes if users can read the directory of this room.</p>
-
+
<pre>Network shared room [No]? No<br></pre>
-
-<p>...you can share a room over a network without setting this flag, and vice
-versa, but what this flag does is twofold: </p>
-
+
+<p>...you can share a room over a network without setting this flag, and
+vice versa, but what this flag does is twofold: </p>
+
<ul>
- <li>It prevents people with no network access from entering messages
-here </li>
- <li>Messages are displayed with the name of their originating system
- in the header. </li>
-
+ <li>It prevents people with no network access from entering messages
+ here </li>
+ <li>Messages are displayed with the name of their originating system
+ in the header. </li>
+
</ul>
-
+
<pre>Permanent room [No]? No<br></pre>
-
-<p>Citadel contains an 'auto purger' which is capable of removing rooms which
- have not been posted in for a pre-defined period of time (by default this
- is set to two weeks). If you wish to keep this from happening to a particular
- room, you can set this option. (Keep in mind that <tt>Lobby></tt>, <tt>Aide></tt>,
- any private mailbox rooms, any network shared rooms, and any rooms with
-a file directory are automatically permanent.)</p>
-
+
+<p>Citadel contains an 'auto purger' which is capable of removing rooms which
+ have not been posted in for a pre-defined period of time (by default
+this is set to two weeks). If you wish to keep this from happening to
+a particular room, you can set this option. (Keep in mind that <tt>Lobby></tt>,
+ <tt>Aide></tt>, any private mailbox rooms, any network shared rooms,
+ and any rooms with a file directory are automatically permanent.)</p>
+
<pre>Anonymous messages [No]? No<br>Ask users whether to make messages anonymous [No]? No<br></pre>
-
-<p>...you can have rooms in which all messages are automatically anonymous,
- and you can have rooms in which users are prompted whether to make a message
- anonymous when they enter it. The real identity of the author of each message
- is still revealed to the Room Aide for this room, as well as any system-wide
- Aides.</p>
-
+
+<p>...you can have rooms in which all messages are automatically anonymous,
+ and you can have rooms in which users are prompted whether to make a
+message anonymous when they enter it. The real identity of the author
+of each message is still revealed to the Room Aide for this room, as well
+as any system-wide Aides.</p>
+
<pre>Room aide [Joe Responsible]: <br></pre>
-
-<p>...on larger systems, it helps to designate a person to be responsible
- for a room. Room Aides have access to a restricted set of Aide commands,
- ONLY when they are in the room in which they have this privilege. They
-can edit the room, delete the room, delete and move messages, and invite
-or kick out users (if it is a private room), but they cannot perform aide
-commands that are not room-related (such as changing users access levels).</p>
-
+
+<p>...on larger systems, it helps to designate a person to be responsible
+ for a room. Room Aides have access to a restricted set of Aide commands,
+ ONLY when they are in the room in which they have this privilege. They
+ can edit the room, delete the room, delete and move messages, and invite
+ or kick out users (if it is a private room), but they cannot perform aide
+ commands that are not room-related (such as changing users access levels).</p>
+
<pre>Listing order [64]: <br></pre>
-
-<p>This is just a simple way to try to control the order rooms are listed
- in when users call up a <tt><b>K</b>nown Rooms</tt> listing. Rooms with
- a lower listing order are displayed prior to rooms with a higher listing
-order. It has no other effect. For users who list rooms in floor order,
-the display will sort first by floor, then by listing order.</p>
-
+
+<p>This is just a simple way to try to control the order rooms are listed
+ in when users call up a <tt><b>K</b>nown Rooms</tt> listing. Rooms with
+ a lower listing order are displayed prior to rooms with a higher listing
+ order. It has no other effect. For users who list rooms in floor order,
+ the display will sort first by floor, then by listing order.</p>
+
<pre>Message expire policy (? for list) [0]:<br></pre>
-
-<p>This provides you with the opportunity to select how long each message
- will remain in a room before automatically being deleted. Press <tt><b>?</b></tt>
- for a list of options. You can choose to keep messages around forever (or
- until they are manually deleted), until they become a certain number of
-days old, or until a certain number of additional messages are posted in
-the room, at which time the oldest ones will scroll out.</p>
-
-<p>You will notice that you can also fall back to the default expire policy
- for the floor upon which the room resides. This is the default setting.
- You can change the floor's default with the <tt><b>;A</b>ide <b>E</b>dit
- floor</tt> command. The default setting for the floor default, in turn,
-is the system default setting, which can be changed using the <tt><b>.A</b>ide
- <b>S</b>ystem configuration <b>G</b>eneral</tt> command.</p>
-
+
+<p>This provides you with the opportunity to select how long each message
+ will remain in a room before automatically being deleted. Press <tt><b>?</b></tt>
+ for a list of options. You can choose to keep messages around forever
+ (or until they are manually deleted), until they become a certain number
+ of days old, or until a certain number of additional messages are posted
+ in the room, at which time the oldest ones will scroll out.</p>
+
+<p>You will notice that you can also fall back to the default expire policy
+ for the floor upon which the room resides. This is the default setting.
+ You can change the floor's default with the <tt><b>;A</b>ide <b>E</b>dit
+ floor</tt> command. The default setting for the floor default, in turn,
+ is the system default setting, which can be changed using the <tt><b>.A</b>ide
+ <b>S</b>ystem configuration <b>G</b>eneral</tt> command.</p>
+
<pre>Save changes (y/n)? Yes<br></pre>
-
-<p>...this gives you an opportunity to back out, if you feel you really messed
- things up while editing.</p>
-
+
+<p>...this gives you an opportunity to back out, if you feel you really messed
+ things up while editing.</p>
+
<h3><a name="File_directories"></a>File directories</h3>
-
-<p>If you have created any directory rooms, you can attach file descriptions
- to the filenames through a special file called <tt>filedir</tt>. Each line
- contains the name of a file in the directory, followed by a space and then
- a description of the file, such as:</p>
-
+
+<p>If you have created any directory rooms, you can attach file descriptions
+ to the filenames through a special file called <tt>filedir</tt>. Each line
+ contains the name of a file in the directory, followed by a space and
+then a description of the file, such as:</p>
+
<pre>myfile.txt This is a description of my file.<br>phluff A phile phull of phluff!<br></pre>
-
-<p>...this would create file descriptions for the files <tt>myfile.txt</tt>
- and <tt>phluff</tt> which would be displayed along with the directory.
-It should also be noted that when users upload files to your system, they
-will be prompted for file descriptions, which will be added to the <tt>filedir</tt>
- file. If one does not exist, it will be created.</p>
-
-<h3><a name="Creating_and_editing_user_accounts"></a>Creating and editing
- user accounts</h3>
-
-<p>Anyone with Aide level access may use the <tt><b>.A</b>ide edit <b>U</b>ser</tt>
- command to create and/or edit user accounts. There are several parameters
- which can be set here.</p>
-
+
+<p>...this would create file descriptions for the files <tt>myfile.txt</tt>
+ and <tt>phluff</tt> which would be displayed along with the directory.
+ It should also be noted that when users upload files to your system, they
+ will be prompted for file descriptions, which will be added to the <tt>filedir</tt>
+ file. If one does not exist, it will be created.</p>
+
+<h3><a name="Creating_and_editing_user_accounts"></a>Creating and editing
+ user accounts</h3>
+
+<p>Anyone with Aide level access may use the <tt><b>.A</b>ide edit <b>U</b>ser</tt>
+ command to create and/or edit user accounts. There are several parameters
+ which can be set here.</p>
+
<p>To create a user:</p>
-
+
<pre>Lobby> . Aide edit User <br>User name: New User Name<br>No such user.<br>Do you want to create this user? Yes<br></pre>
-
-<p>At this point, the new user account has been created, and the command
-will continue as if you were editing an existing account. Therefore the
-remainder of this procedure is the same for creating and editing:</p>
-
+
+<p>At this point, the new user account has been created, and the command will
+continue as if you were editing an existing account. Therefore the remainder
+of this procedure is the same for creating and editing:</p>
+
<pre>Lobby> . Aide edit User <br>User name: person of significance<br>User #70 - Person of Significance PW: <br> <br><br>, <br> <br> <br><br>Current access level: 4 (Network User)<br></pre>
-
-<p>The blank lines are the user's 'registration' information -- personal information
-such as full name, address, telephone number, etc. This information will
-comprise the user's vCard in both their user profile and in the Global Address
-Book.</p>
-
+
+<p>The blank lines are the user's 'registration' information -- personal
+information such as full name, address, telephone number, etc. This information
+will comprise the user's vCard in both their user profile and in the Global
+Address Book.</p>
+
<pre>Change password [No]: No<br></pre>
-
+
<p>...answer Yes to set or change the password for this account.</p>
-
+
<pre>Access level [4]: <br></pre>
-
-<p>...this allows you to set or change the access level for this account.
- The access levels available are as follows: </p>
-
+
+<p>...this allows you to set or change the access level for this account.
+ The access levels available are as follows: </p>
+
<ul>
- <li>0 - Deleted. (This immediately deletes the account.) </li>
- <li>1 - New, unvalidated user </li>
- <li>2 - Problem user (severely restricts account - use for probationary
- access) </li>
- <li>3 - User with no network privileges. Same access as a normal user
- except cannot post messages in rooms shared on a network. </li>
- <li>4 - Normal user </li>
- <li>5 - Preferred user (access is granted to privileged rooms) </li>
- <li>6 - Aide (administrative access to the whole system) </li>
-
-</ul>
+ <li>0 - Deleted. (This immediately deletes the account.) </li>
+ <li>1 - New, unvalidated user </li>
+ <li>2 - Problem user (severely restricts account - use for probationary
+ access) </li>
+ <li>3 - User with no network privileges. Same access as a normal
+ user except cannot post messages in rooms shared on a network. </li>
+ <li>4 - Normal user </li>
+ <li>5 - Preferred user (access is granted to privileged rooms) </li>
+ <li>6 - Aide (administrative access to the whole system) </li>
+</ul>
+
<pre>Permission to send/receive Internet mail [ No]? No<br></pre>
-
-<p>If your system is configured to only allow Internet mail privileges to
- certain users, this is where you can grant or revoke that privilege.</p>
-
+
+<p>If your system is configured to only allow Internet mail privileges to
+ certain users, this is where you can grant or revoke that privilege.</p>
+
<pre>Ask user to register again [Yes]: Yes<br></pre>
-
-<p>If you answer Yes to this question, the user will be presented with a 'registration'
-screen or set of prompts, the next time they log in using a Citadel client.
- This will prompt them for their full name, address, telephone number, etc.</p>
-
+
+<p>If you answer Yes to this question, the user will be presented with a
+'registration' screen or set of prompts, the next time they log in using
+a Citadel client. This will prompt them for their full name, address, telephone
+number, etc.</p>
+
<pre>Times called [0]: <br>Messages posted [0]: <br></pre>
-
-<p>These statistics are available for informational purposes only, so there
- is normally no need to change them.</p>
-
+
+<p>These statistics are available for informational purposes only, so there
+ is normally no need to change them.</p>
+
<pre>Set last call to now [No]: No<br>Purge time (in days, 0 for system default [0]: <br></pre>
-
-<p>Citadel contains an auto-purger which is capable of automatically deleting
- accounts which have not been accessed in a predefined period of time. If
- you choose to perform this operation, you can 'touch' the account of a
-wayward user by setting their 'last call' time to 'now'. You can also adjust,
-on a per-user basis, the amount of time which must pass before their account
- is purged by the system. This time is set in days. You can also specify
- 0 days to indicate that you wish to use the system default setting.</p>
-
+
+<p>Citadel contains an auto-purger which is capable of automatically deleting
+ accounts which have not been accessed in a predefined period of time.
+ If you choose to perform this operation, you can 'touch' the account of
+ a wayward user by setting their 'last call' time to 'now'. You can also
+ adjust, on a per-user basis, the amount of time which must pass before
+their account is purged by the system. This time is set in days. You
+can also specify 0 days to indicate that you wish to use the system default
+setting.</p>
+
<h3><a name="Deleting_and_moving_messages"></a>Deleting and moving messages</h3>
-
-<p>Aides and Room Aides have the ability to delete and move messages. After
- each message, the normal prompt appears:</p>
-
+
+<p>Aides and Room Aides have the ability to delete and move messages. After
+ each message, the normal prompt appears:</p>
+
<pre>(8) <B>ack <A>gain <Q>uote <R>eply <N>ext <S>top m<Y> next <?>help -><br></pre>
-
-<p>Entering <tt><b>D</b>elete</tt> will delete the message. A <tt>(y/n)</tt>
- prompt will appear to confirm that you really want to delete the message.
- Entering <tt><b>M</b>ove</tt> will prompt for a room to which the message
- should be moved.</p>
-
+
+<p>Entering <tt><b>D</b>elete</tt> will delete the message. A <tt>(y/n)</tt>
+ prompt will appear to confirm that you really want to delete the message.
+ Entering <tt><b>M</b>ove</tt> will prompt for a room to which the message
+ should be moved.</p>
+
<h3><a name="Customizing_the_help_files"></a>Customizing the help files</h3>
-
-<p>The subdirectory called <tt>help</tt> contains your system's help files.
- There's nothing hard-coded into the system that dictates what files should
- be there. Whenever a user types the command <tt><b>.H</b>elp</tt> followed
- by the name of a help file, it displays the contents of that help file.</p>
-
-<p>The help files that come with the system, of course, are enough to guide
- a user through its operation. But you can add, change, or remove help files
- to suit whatever is appropriate for your system.</p>
-
-<p>There are several strings that you can put in help files that will be
-automatically substituted with other strings. They are:</p>
-
+
+<p>The subdirectory called <tt>help</tt> contains your system's help files.
+ There's nothing hard-coded into the system that dictates what files should
+ be there. Whenever a user types the command <tt><b>.H</b>elp</tt> followed
+ by the name of a help file, it displays the contents of that help file.</p>
+
+<p>The help files that come with the system, of course, are enough to guide
+ a user through its operation. But you can add, change, or remove help
+ files to suit whatever is appropriate for your system.</p>
+
+<p>There are several strings that you can put in help files that will be automatically
+substituted with other strings. They are:</p>
+
<pre> <br> ^nodename = The node name of your system on a Citadel/UX network<br> ^humannode = Human-readable node name (also your node name on C86Net)<br> ^fqdn = Your system's fully-qualified domain name<br> ^username = The name of the user reading the help file<br> ^usernum = The user number of the user reading the help file<br> ^sysadm = The name of the system administraor (i.e., you)<br> ^variantname = The name of the BBS software you're running<br> ^bbsdir = The directory on the host system in which you have<br> installed the Citadel system.<br></pre>
-
+
<p>So, for example, you could create a help file which looked like:</p>
-
+
<pre> "Lots of help, of course, is available right here on ^humannode. Of<br>course, if you still have trouble, you could always bug ^sysadm about it!"<br></pre>
-
+
<h3><a name="Site_configuration"></a>Site configuration</h3>
-
-<p>Once your Citadel server is up and running, the first thing you'll want
- to do is customize and tune it. This can be done from the text-based client
- with the <tt><b>.A</b>ide <b>S</b>ystem configuration <b>G</b>eneral</tt>
- command, or from WebCit (if you have it installed) by clicking 'Advanced
- Options' followed by 'Edit site-wide configuration.' Either method will
- offer the same configuration options. This document shows the text mode
- client being used.</p>
-
+
+<p>Once your Citadel server is up and running, the first thing you'll want
+ to do is customize and tune it. This can be done from the text-based client
+ with the <tt><b>.A</b>ide <b>S</b>ystem configuration <b>G</b>eneral</tt>
+ command, or from WebCit (if you have it installed) by clicking 'Advanced
+ Options' followed by 'Edit site-wide configuration.' Either method will
+ offer the same configuration options. This document shows the text mode
+ client being used.</p>
+
<p>The first set of options deal with the identification of your system.</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>Modem dialup number [US 914 999 9999]: <br>Geographic location of this system [Mount Kisco, NY]: <br>Name of system administrator [IGnatius T Foobar]: <br>Paginator prompt [<jinkies
!="" more="" text="" on="" the="" next="" screen="">]: <br></jinkies></pre>
-
-<p>'Node name' refers to the short, unqualified node name by which your system
- is known on a Citadel network. Generally it will be the same as the unqualified
- host name of your computer; this is, in fact, the default setting.</p>
-
-<p>Then enter the fully-qualified domain name (FQDN) of your system. If
-you are not on the Internet, you can simply set it to the same as your unqualified
- host name. Otherwise you should set this value to the host name by which
- your system is most commonly known.</p>
-
-<p>The field called 'Human-readable node name' (also known as the 'node title'
- or 'organization name' in other software) is used solely for display purposes.
- Set it to the actual name of your system as you want it to appear in banners,
- messages, etc.</p>
-
-<p>If you have a modem or bank of modems answering data calls for your system,
- enter it in the field marked 'Modem dialup number.' Otherwise you may
+
+<p>'Node name' refers to the short, unqualified node name by which your system
+ is known on a Citadel network. Generally it will be the same as the unqualified
+ host name of your computer; this is, in fact, the default setting.</p>
+
+<p>Then enter the fully-qualified domain name (FQDN) of your system. If you
+are not on the Internet, you can simply set it to the same as your unqualified
+ host name. Otherwise you should set this value to the host name by which
+ your system is most commonly known.</p>
+
+<p>The field called 'Human-readable node name' (also known as the 'node title'
+ or 'organization name' in other software) is used solely for display purposes.
+ Set it to the actual name of your system as you want it to appear in banners,
+ messages, etc.</p>
+
+<p>If you have a modem or bank of modems answering data calls for your system,
+ enter it in the field marked 'Modem dialup number.' Otherwise you may
leave it blank.</p>
-
-<p>'Geographic location of this system' is another display field. Enter
-a city and state, or city and country. </p>
-
-<p>'Name of system administrator' is important! Any user who logs on with
- the name you enter here will automatically be granted Aide privileges.
-This is one of two ways for the system administrator to grant himself/herself
- Aide access to the system when initially setting it up. (The other is simply
- to have the first account created on a new installation.)</p>
-
-<p>The next set of options are your system's security settings. Before delving
- into the actual options, we should review the various access levels available
- on the system. Citadel has seven access levels:</p>
-
+
+<p>'Geographic location of this system' is another display field. Enter a
+ city and state, or city and country. </p>
+
+<p>'Name of system administrator' is important! Any user who logs on with
+ the name you enter here will automatically be granted Aide privileges.
+ This is one of two ways for the system administrator to grant himself/herself
+ Aide access to the system when initially setting it up. (The other is simply
+ to have the first account created on a new installation.)</p>
+
+<p>The next set of options are your system's security settings. Before delving
+ into the actual options, we should review the various access levels available
+ on the system. Citadel has seven access levels:</p>
+
<ul>
- <li>0 (Deleted). A user whose access level is set to 0 will automatically
- be deleted by the system. </li>
- <li>1 (New User). Users at this level may only read messages. Entering
- messages is prohibited, except in the <tt>Mail></tt> room, where a message
- to 'sysop' may be entered. </li>
- <li>2 (Problem User). Also known as 'Twit.' </li>
- <li>3 (Local User). May enter messages, except in rooms shared on
-a Citadel network. </li>
- <li>4 (Network User). May enter messages in every accessible room.
- </li>
- <li>5 (Preferred User). Use of this level is up to the whim of the
-system administrator. </li>
- <li>6 (Aide). Access is granted to the administrative functions of
-the system. (This access level may also be granted to a user only for a
-specific room, please see 'Room Aide' for more information.) </li>
-
+ <li>0 (Deleted). A user whose access level is set to 0 will automatically
+ be deleted by the system. </li>
+ <li>1 (New User). Users at this level may only read messages.
+ Entering messages is prohibited, except in the <tt>Mail></tt> room,
+where a message to 'sysop' may be entered. </li>
+ <li>2 (Problem User). Also known as 'Twit.' </li>
+ <li>3 (Local User). May enter messages, except in rooms shared
+on a Citadel network. </li>
+ <li>4 (Network User). May enter messages in every accessible room.
+ </li>
+ <li>5 (Preferred User). Use of this level is up to the whim of
+the system administrator. </li>
+ <li>6 (Aide). Access is granted to the administrative functions
+of the system. (This access level may also be granted to a user only for
+a specific room, please see 'Room Aide' for more information.) </li>
+
</ul>
-
+
<pre>Require registration for new users [No]: No<br>Disable self-service user account creation [No]: No<br>Initial access level for new users [4]:<br>Access level required to create rooms [4]: <br>Automatically give room aide privs to a user who creates a private room [No]: No<br><br>Automatically move problem user messages to twit room [Yes]: Yes<br>Name of twit room [Trashcan]: <br>Restrict Internet mail to only those with that privilege [No]: No<br>Allow Aides to Zap (forget) rooms [Yes]: Yes<br>Allow system Aides access to user mailboxes [Yes]: Yes<br>Log all pages [No]: No<br></pre>
-
-<p>'Registration' refers to the process of a user entering various personal
- contact information (real name, address, telephone number, etc.) into the
- system. When enabled, this information is stored as a vCard object on the
- system in two places: the user's <tt>My Citadel Config></tt> room, and
- in the <tt>Global Address Book></tt> room. (Note: the latter should
- be made private on publicly-accessible systems, for obvious reasons.)</p>
-
-<p>If you answer Yes to 'Require registration for new users' then each new
- user, upon creating a new account, will immediately be entered into the
-registration process. On the other hand, if you answer Yes to 'Disable self-service
-user account creation' then new users will not be able to log in at all --
-all accounts must be created by an Aide.</p>
-
-<p>'Initial access level for new users' should be set to 1 (New User) if
-you would like to review each new user's registration info before granting
- them higher access. This would be done periodically with the <tt><b>.A</b>ide
- <b>V</b>alidate new users</tt> command. If you do not require registration,
- you should set the initial access level to 4 (Network User).</p>
-
-<p>Given the above options, it then becomes clear that there are generally
- two ways you can set up your Citadel system, depending on its purpose:</p>
-
+
+<p>'Registration' refers to the process of a user entering various personal
+ contact information (real name, address, telephone number, etc.) into
+the system. When enabled, this information is stored as a vCard object
+on the system in two places: the user's <tt>My Citadel Config></tt> room,
+ and in the <tt>Global Address Book></tt> room. (Note: the latter should
+ be made private on publicly-accessible systems, for obvious reasons.)</p>
+
+<p>If you answer Yes to 'Require registration for new users' then each new
+ user, upon creating a new account, will immediately be entered into the
+ registration process. On the other hand, if you answer Yes to 'Disable
+self-service user account creation' then new users will not be able to log
+in at all -- all accounts must be created by an Aide.</p>
+
+<p>'Initial access level for new users' should be set to 1 (New User) if you
+ would like to review each new user's registration info before granting
+ them higher access. This would be done periodically with the <tt><b>.A</b>ide
+ <b>V</b>alidate new users</tt> command. If you do not require registration,
+ you should set the initial access level to 4 (Network User).</p>
+
+<p>Given the above options, it then becomes clear that there are generally
+ two ways you can set up your Citadel system, depending on its purpose:</p>
+
<ul>
- <li><b>A public access BBS or message board</b> - since you do not know
- who might want to log in, self-service account creation needs to stay enabled.
- If you want to be strict about users identifying themselves, then you should
- also require users to register (just remember to post a privacy policy if
- you're going to collect personal information) -- then set the initial access
- level to 1 (New User), so new users cannot post messages until after you've
- validated them. For a more lax environment, you can remove the registration
- requirement and grant new accounts level 4 (Normal User) access on the
-first visit. </li>
- <li><b>A private email/groupware system for your organization</b> -
-in this case, disable self-service account creation; you don't want strangers
- welcoming themselves to your system. You'll probably also want to disable
- registration, because you or some other site administrator will be entering
- users' contact info when you create their accounts. Since this is also
-how you assign their Internet e-mail addresses, it's probably a good idea
-to do it yourself instead of expecting them to do it. </li>
-
+ <li><b>A public access BBS or message board</b> - since you do not
+ know who might want to log in, self-service account creation needs to
+stay enabled. If you want to be strict about users identifying themselves,
+then you should also require users to register (just remember to post
+a privacy policy if you're going to collect personal information) -- then
+set the initial access level to 1 (New User), so new users cannot post messages
+until after you've validated them. For a more lax environment, you can
+remove the registration requirement and grant new accounts level 4 (Normal
+User) access on the first visit. </li>
+ <li><b>A private email/groupware system for your organization</b>
+ - in this case, disable self-service account creation; you don't want
+strangers welcoming themselves to your system. You'll probably also want
+to disable registration, because you or some other site administrator
+will be entering users' contact info when you create their accounts.
+Since this is also how you assign their Internet e-mail addresses, it's
+probably a good idea to do it yourself instead of expecting them to do it.
+ </li>
+
</ul>
-
-<p>'Access level required to create rooms' is up to you. You might wish
-to restrict the creation of new rooms only to Aides, or you might wish to
- allow anyone to create a room. The latter is one of the Citadel culture's
-most long-standing traditions; the former may be appropriate if users are
-abusing this privilege.</p>
-
-<p>You have the ability to 'Automatically give room aide privs to a user
-who creates a private room.' If you answer Yes, then any user who creates
-a guess-name, passworded, or invitation-only room will automatically become
- the room aide, and will have access to a subset of the <tt><b>.A</b>ide</tt>
- command set while in that room. If you would rather grant this permission
- manually, answer No.</p>
-
-<p>Another tradition in the Citadel culture is to refrain from deleting problem
-users, but instead to 'twit' them (reduce their access level to 2 [Problem
-User]). You can then 'Automatically move problem user messages to twit
-room' (answer Yes, then specify 'Name of twit room' and remember to create
-that room). If you employ this logic, any user with level 2 (Problem User)
-access will continue to have access to the same set of rooms, but all messages
-posted will automatically be routed to the Trashcan (or whatever you call
-your twit room).</p>
-
-<p>If you have Internet mail configured, you have the option of restricting
- its use on a user-by-user basis. If you wish to do this, answer Yes to
-'Restrict Internet mail to only those with that privilege.' Obviously this
-makes no sense for an internal e-mail system, but for a public BBS it might
-be appropriate.</p>
-
-<p>Normally, Aides have access to every room, public or private, except for
- user mailboxes. They are also forbidden from <tt><b>Z</b>ap</tt>ping rooms,
- because the review of content is considered one of their roles. If you
-wish to change these policies, the next two options allow you to. You may
-'Allow Aides to Zap (forget) rooms', in which case they may use the <tt><b>Z</b>ap</tt>
- command just like any other user. Furthermore, if you 'Allow system Aides
- access to user mailboxes', then they may <tt><b>.G</b>oto</tt> any private
- mailbox belonging to any user, using a special room name format.</p>
-
-<p>If your local security and/or privacy policy dictates that you keep a log
-of all pages (instant messages) that go through the system, then answer Yes
-to 'Log all pages'. If you answer Yes, you will be prompted for the name
-of a room to which all pages will be logged. If you answer No, then only
-the sender and recipient of each individual message will receive a copy.</p>
-
-<p>The next set of options deals with the tuning of your system. It is usually
- safe to leave these untouched.</p>
-
+
+<p>'Access level required to create rooms' is up to you. You might wish to
+restrict the creation of new rooms only to Aides, or you might wish to allow
+anyone to create a room. The latter is one of the Citadel culture's most
+long-standing traditions; the former may be appropriate if users are abusing
+this privilege.</p>
+
+<p>You have the ability to 'Automatically give room aide privs to a user who
+ creates a private room.' If you answer Yes, then any user who creates a
+guess-name, passworded, or invitation-only room will automatically become
+ the room aide, and will have access to a subset of the <tt><b>.A</b>ide</tt>
+ command set while in that room. If you would rather grant this permission
+ manually, answer No.</p>
+
+<p>Another tradition in the Citadel culture is to refrain from deleting
+problem users, but instead to 'twit' them (reduce their access level to 2
+[Problem User]). You can then 'Automatically move problem user messages
+to twit room' (answer Yes, then specify 'Name of twit room' and remember
+to create that room). If you employ this logic, any user with level 2 (Problem
+User) access will continue to have access to the same set of rooms, but all
+messages posted will automatically be routed to the Trashcan (or whatever
+you call your twit room).</p>
+
+<p>If you have Internet mail configured, you have the option of restricting
+ its use on a user-by-user basis. If you wish to do this, answer Yes to
+ 'Restrict Internet mail to only those with that privilege.' Obviously this
+ makes no sense for an internal e-mail system, but for a public BBS it might
+ be appropriate.</p>
+
+<p>Normally, Aides have access to every room, public or private, except for
+ user mailboxes. They are also forbidden from <tt><b>Z</b>ap</tt>ping rooms,
+ because the review of content is considered one of their roles. If you
+ wish to change these policies, the next two options allow you to. You
+may 'Allow Aides to Zap (forget) rooms', in which case they may use the
+<tt><b>Z</b>ap</tt> command just like any other user. Furthermore, if
+you 'Allow system Aides access to user mailboxes', then they may <tt><b>.G</b>oto</tt>
+any private mailbox belonging to any user, using a special room name format.</p>
+
+<p>If your local security and/or privacy policy dictates that you keep a
+log of all pages (instant messages) that go through the system, then answer
+Yes to 'Log all pages'. If you answer Yes, you will be prompted for the
+name of a room to which all pages will be logged. If you answer No, then
+only the sender and recipient of each individual message will receive a copy.</p>
+
+<p>The next set of options deals with the tuning of your system. It is usually
+ safe to leave these untouched.</p>
+
<pre>Server connection idle timeout (in seconds) [900]: <br>Maximum concurrent sessions [20]: <br>Maximum message length [2147483647]: <br>Minimum number of worker threads [5]: <br>Maximum number of worker threads [256]: <br></pre>
-
-<p>The 'Server connection idle timeout' is for the connection between client
- and server software. It is <b>not</b> an idle timer for the user interface.
- 900 seconds (15 minutes) is the default and a sane setting.</p>
-
-<p>'Maximum concurrent sessions' is the highest number of user sessions you
- wish to allow on your system at any given time. Citadel can scale to hundreds
- of concurrent users, but if you have limited hardware or (more likely)
-limited bandwidth, you might wish to set a maximum. You can also set it
-to zero for no limit.</p>
-
-<p>'Maximum message length' is just that. This could be a good way to prevent
- enormous multimedia files from finding their way into your message base.
- This maximum is enforced in all protocols and is also advertised by the
-ESMTP service.</p>
-
-<p>The minimum and maximum number of worker threads can be tuned to your liking.
- Citadel will attempt to keep one worker thread running per session, within
-these constraints. You should be aware that due to the use of the worker
-thread model, Citadel can handle a large number of concurrent sessions with
-a much smaller thread pool. If you don't know the programming theory behind
-multithreaded servers, you should leave these parameters alone.</p>
-
+
+<p>The 'Server connection idle timeout' is for the connection between client
+ and server software. It is <b>not</b> an idle timer for the user interface.
+ 900 seconds (15 minutes) is the default and a sane setting.</p>
+
+<p>'Maximum concurrent sessions' is the highest number of user sessions you
+ wish to allow on your system at any given time. Citadel can scale to
+hundreds of concurrent users, but if you have limited hardware or (more
+likely) limited bandwidth, you might wish to set a maximum. You can also
+set it to zero for no limit.</p>
+
+<p>'Maximum message length' is just that. This could be a good way to prevent
+ enormous multimedia files from finding their way into your message base.
+ This maximum is enforced in all protocols and is also advertised by the
+ ESMTP service.</p>
+
+<p>The minimum and maximum number of worker threads can be tuned to your
+liking. Citadel will attempt to keep one worker thread running per session,
+within these constraints. You should be aware that due to the use of the
+worker thread model, Citadel can handle a large number of concurrent sessions
+with a much smaller thread pool. If you don't know the programming theory
+behind multithreaded servers, you should leave these parameters alone.</p>
+
<p>The next set of options affect how Citadel behaves on a network.</p>
-
+
<pre>How often to run network jobs (in seconds) [3600]: <br>SMTP server port (-1 to disable) [25]: <br>POP3 server port (-1 to disable) [110]:<br>IMAP server port (-1 to disable) [143]:<br></pre>
-
-<p>'How often to run network jobs' refers to the sharing of content on a Citadel
-network. If your system is on a Citadel network, this configuration item
-dictates how often the Citadel server will contact other Citadel servers
- to send and receive messages. In reality, this will happen more frequently
- than you specify, because other Citadel servers will be contacting yours
- at regular intervals as well.</p>
-
-<p>Then you can specify TCP port numbers for the SMTP, POP3, and IMAP services.
- For a system being used primarily for Internet e-mail, these are essential,
- so you'll want to specify the standard port numbers: 25, 110, and 143.
- If Citadel is running alongside some other mail system, though, then you
-might want to choose other, unused port numbers, or enter -1 for any protocol
-to disable it entirely.</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.</p>
+
+<p>Then you can specify TCP port numbers for the SMTP, POP3, and IMAP services.
+ For a system being used primarily for Internet e-mail, these are essential,
+ so you'll want to specify the standard port numbers: 25, 110, and 143.
+ If Citadel is running alongside some other mail system, though, then you
+ might want to choose other, unused port numbers, or enter -1 for any protocol
+ to disable it entirely.</p>
+
<p>The final set of options configures system-wide defaults for the auto-purger:</p>
-
+
<pre>Default user purge time (days) [120]: <br>Default room purge time (days) [30]: <br>System default message expire policy (? for list) [2]: <br>Keep how many messages online? [150]:<br></pre>
-
-<p>Any user who does not log in for the period specified in 'Default user
- purge time' will be deleted the next time a purge is run. This setting
-may be modified on a per-user basis.</p>
-
-<p>'Default room purge time' behaves the same way, and may also be modified
- on a per-room basis.</p>
-
-<p>'System default message expire policy' defines the way in which old messages
- are expired (purged) off the system. You can specify any of:</p>
-
+
+<p>Any user who does not log in for the period specified in 'Default user
+ purge time' will be deleted the next time a purge is run. This setting
+ may be modified on a per-user basis.</p>
+
+<p>'Default room purge time' behaves the same way, and may also be modified
+ on a per-room basis.</p>
+
+<p>'System default message expire policy' defines the way in which old messages
+ are expired (purged) off the system. You can specify any of:</p>
+
<ul>
- <li>Purge by age (specify in days) </li>
- <li>Purge by message count in the room (specify number of messages)
- </li>
- <li>Do not purge at all </li>
-
+ <li>Purge by age (specify in days) </li>
+ <li>Purge by message count in the room (specify number of messages)
+ </li>
+ <li>Do not purge at all </li>
+
</ul>
-
-<p>Again, this setting may be overridden on a per-floor basis, and the floor
- setting may be overridden on a per-room basis.</p>
-
+
+<p>Again, this setting may be overridden on a per-floor basis, and the floor
+ setting may be overridden on a per-room basis.</p>
+
<pre>Save this configuration? No<br></pre>
-
-<p>When you're done, enter 'Yes' to confirm the changes, or 'No' to discard
- the changes.</p>
- </div>
-
-<hr width="100%" size="2">
-<h2 align="center"><a name="Configuring_Citadel_for_Internet_e-mail"></a>Configuring
- Citadel for Internet e-mail</h2>
-
-<div align="justify">
+
+<p>When you're done, enter 'Yes' to confirm the changes, or 'No' to discard
+ the changes.</p>
+ </div>
+
+<hr width="100%" size="2">
+<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,
+ 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>
-
+ 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>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>
+
</ul>
- This section of the documentation will demonstrate how to configure these
- features.<br>
- <br>
-
+ 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>
-
+
+<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>
-
+
+<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><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.
+
+<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><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>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><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>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>
-
+ 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>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/UX<br>Copyright (C) 1987-2000 by the Citadel/UX development team.<br>Citadel/UX is open source, covered by the GNU General Public License, and<br>you are welcome to change it and/or distribute copies of it under certain<br>conditions. There is absolutely no warranty for this software. Please<br>read the 'COPYING.txt' file for details.<br><br>Loading citadel.config<br>Opening databases<br>This is GDBM version 1.8.0, as of May 19, 1999.<br>Checking floor reference counts<br>Creating base rooms (if necessary)<br>Registered a new service (TCP port 504)<br>Registered a new service (TCP port 0)<br>Initializing loadable modules<br>Registered server command CHAT (Begin real-time chat)<br>Registered server command PEXP (Poll for express messages)<br>Registered server command GEXP (Get express messages)<br>Registered server command SEXP (Send an express message)<br>Registered server command DEXP (Disable express messages)<br>Registered a new session function (type 0)<br>Registered a new x-msg function (priority 0)<br>Loaded module: $Id$<br>Registered a new session function (type 1)<br>Registered a new message function (type 201)<br>Registered a new message function (type 202)<br>Registered server command REGI (Enter registration info)<br>Registered server command GREG (Get registration info)<br>Registered a new user function (type 100)<br>Loaded module: $Id$<br>Server-hosted upgrade level is 5.62<br>Loaded module: $Id$<br>Registered server command EXPI (Expire old system objects)<br>Registered server command FSCK (Check message ref counts)<br>Loaded module: $Id$<br><b>citserver: Can't bind: Address already in use<br>ERROR: could not bind to TCP port 25.</b>
-Registered a new service (TCP port 0)
-Registered a new session function (type 50)
-Loaded module: $Id$
-<b>citserver: Can't bind: Address already in use<br>ERROR: could not bind to TCP port 110.</b>
-Registered a new session function (type 0)
-Loaded module: $Id$
-Registered a new message function (type 202)Loaded module: $Id:
-serv_inetcfg.c,v 1.2 2000/02/03 03:57:35 ajc Exp $
-Registered server command RWHO (Display who is online)
-Registered server command HCHG (Masquerade hostname)
-Registered server command RCHG (Masquerade roomname)
-Registered server command UCHG (Masquerade username)
-Registered server command STEL (Enter/exit stealth mode)
-Loaded module: $Id$
-Changing uid to 513
-Starting housekeeper thread
-</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
+
+<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/UX<br>Copyright (C) 1987-2000 by the Citadel/UX development team.<br>Citadel/UX is open source, covered by the GNU General Public License, and<br>you are welcome to change it and/or distribute copies of it under certain<br>conditions. There is absolutely no warranty for this software. Please<br>read the 'COPYING.txt' file for details.<br><br>Loading citadel.config<br>Opening databases<br>This is GDBM version 1.8.0, as of May 19, 1999.<br>Checking floor reference counts<br>Creating base rooms (if necessary)<br>Registered a new service (TCP port 504)<br>Registered a new service (TCP port 0)<br>Initializing loadable modules<br>Registered server command CHAT (Begin real-time chat)<br>Registered server command PEXP (Poll for express messages)<br>Registered server command GEXP (Get express messages)<br>Registered server command SEXP (Send an express message)<br>Registered server command DEXP (Disable express messages)<br>Registered a new session function (type 0)<br>Registered a new x-msg function (priority 0)<br>Loaded module: $Id$<br>Registered a new session function (type 1)<br>Registered a new message function (type 201)<br>Registered a new message function (type 202)<br>Registered server command REGI (Enter registration info)<br>Registered server command GREG (Get registration info)<br>Registered a new user function (type 100)<br>Loaded module: $Id$<br>Server-hosted upgrade level is 5.62<br>Loaded module: $Id$<br>Registered server command EXPI (Expire old system objects)<br>Registered server command FSCK (Check message ref counts)<br>Loaded module: $Id$<br><b>citserver: Can't bind: Address already in use<br>ERROR: could not bind to TCP port 25.</b><br>Registered a new service (TCP port 0)<br>Registered a new session function (type 50)<br>Loaded module: $Id$<br><b>citserver: Can't bind: Address already in use<br>ERROR: could not bind to TCP port 110.</b><br>Registered a new session function (type 0)<br>Loaded module: $Id$<br>Registered a new message function (type 202)Loaded module: $Id$<br>Registered server command RWHO (Display who is online)<br>Registered server command HCHG (Masquerade hostname)<br>Registered server command RCHG (Masquerade roomname)<br>Registered server command UCHG (Masquerade username)<br>Registered server command STEL (Enter/exit stealth mode)<br>Loaded module: $Id$<br>Changing uid to 513<br>Starting housekeeper thread<br></font></pre>
+
+<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 a tool is 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.</p>
-
-<p>For outbound mail, you can either allow Citadel to perform deliveries
-directly (this won't affect your other mail system because outbound mail
-doesn't tie 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
+
+<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 a tool is 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.</p>
+
+<p>For outbound mail, you can either allow Citadel to perform deliveries directly
+(this won't affect your other mail system because outbound mail doesn't tie
+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>
- 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.<br>
-<br>
-Citadel supports two modes of mailing list delivery:<br>
+
+<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>
+ <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.<br>
-<br>
-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.<br>
-<br>
-<FONT SIZE=+3>FIXME ... finish this</FONT>
-
-<hr width="100%" size="2">
-<center>
-<h2><a name="Building_or_joining_a_Citadel_network"></a>Building or joining
-a Citadel network</h2>
- </center>
-
+ 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 width="100%" size="2">
+<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>
-
+
+<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>
-
+ <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>
-
+
+<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.
+
+<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>
-
+
+<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>
-
+
+<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>
-
+
+<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>
-
+
+<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>
-
+
+<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>
-
+
+<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>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></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>
-
+
+<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> </div>
+
+<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 journals. Journal files will come and go as
+you use your system; when the database engine has determined that a particular
+log file is no longer needed, the file will automatically be deleted. Nevertheless,
+you should always ensure that there is ample disk space for the files to
+grow.<br>
<br>
+ There is no need to shut down Citadel during backups. The data store
+may be backed up "hot." The makers of Berkeley DB suggest that you should
+back up the data files <i>first</i> and the log files <i>second</i>. This
+is the only method that will guarantee that a database which is being changed
+while you back it up will still be usable when you restore it from the tape
+later.<br>
+ <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>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/UX now contains an importer/exporter module, affectionaly 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 some 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: MAKE SURE
+ YOU TAKE A BACKUP OF EVERYTHING BEFORE YOU START THIS!! 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>
+ </div>
+ <br>
+
</body>
</html>