$Log$
+ Revision 573.143 2001/07/03 03:06:50 ajc
+ * Last minute doco update for 5.80
+
Revision 573.142 2001/07/01 15:44:32 nbryant
configure.in: check for Berkeley DB first.
Fri Jul 10 1998 Art Cancro <ajc@uncensored.citadel.org>
* Initial CVS import
-
+++ /dev/null
-Title: Citadel/UX
-Version: 5.80
-Description: An advanced messaging system which can be used for BBS,
- groupware, and
- online community applications. It is multithreaded,
- client/server, database drive, and accessible via a
- growing selection of front ends.
-Author: Art Cancro <ajc@uncensored.citadel.org>
-Maintained-by: Art Cancro <ajc@uncensored.citadel.org>
-Maintained-at: uncensored.citadel.org, ftp.tux.org
-Platforms: Any reasonably compliant POSIX (Unix, Linux, etc.) type
- system with a TCP/IP stack and POSIX Threads (pthreads).
-Copying-Policy: Freely Redistributable
-Keywords: Citadel Citadel/UX UNIX room-based BBS IGnet IGnet/Open
+++ /dev/null
-Begin3
-Title: Citadel/UX
-Version: 5.80
-Entered-date: Sat Apr 28 00:41:52 EDT 2001
-Description: An advanced messaging system which can be used for BBS,
- groupware, and online community applications. It is
- multithreaded, client/server, database driven, and
- accessible via a growing selection of front ends.
-Keywords: Citadel Citadel/UX UNIX POSIX room-based BBS IGnet IGnet/Open
-Author: Art Cancro <ajc@uncensored.citadel.org>
-Maintained-by: Art Cancro <ajc@uncensored.citadel.org>
-Primary-site: uncensored.citadel.org
-Alternate-site: ftp.tux.org
-Original-site: uncensored.citadel.org
-Platform: Any reasonably compliant POSIX (Unix, Linux, etc.) type
- system with a TCP/IP stack and POSIX Threads (pthreads).
-Copying-Policy: GPL
-End
--- /dev/null
+
+ Using Citadel/UX with Sleepycat (Berkeley) DB
+
+Abstract
+
+ [1]Citadel/UX can now use the robust and scalable [2]Berkeley DB from
+ Sleepycat Software as its data store, for increased scalability,
+ reliability, and recoverability.
+
+History and introduction
+
+ From its inception in 1987 until versions 5.1x in 1988,
+ Citadel/UX utilized a built-in data store loosely modelled after Jeff
+ Prothero's original Citadel-CP/M design. But as Citadel systems
+ scaled upwards, supporting Internet-connected systems with heavy
+ concurrent use, and aspirations of becoming a world-class
+ messaging/groupware platform someday, the developers made the decision
+ to switch to an embedded database. The Free Software Foundation's
+ [3]GDBM product was chosen for its simple API and its free license
+ (the LGPL).
+
+ Somewhat less than trouble-free operation from 1988 through 2000,
+ however, proved that GDBM was not the best choice. Heavily utilized
+ systems experienced occasional database corruption, often resulting in
+ repeated crashes of the Citadel server. As a result, we made the
+ decision to switch to [4]Berkeley DB.
+
+ Berkeley DB offers [5]numerous features which help Citadel/UX to meet
+ its goals as a high-end messaging platform:
+ * Database sizes can scale to hundreds of terabytes
+ * A transaction-based logging system
+ * Recovery utilities
+
+ It is clear that Berkeley DB is a better choice than GDBM for a
+ high-utilization database that requires crash recovery. Beginning on
+ December 7, 2000, Citadel/UX supports the use of either GDBM or DB as
+ the data store. At some point in the future, DB will become the
+ default. If you are setting up a potentially busy system, we
+ recommend that you use DB.
+
+
+Building Citadel/UX with DB support
+
+ Here are the steps required to get Citadel/UX running with Berkeley
+ DB as its back end data store.
+
+ 1. First, you must download and build Berkeley DB itself. Citadel
+ has been developed and tested with DB 3.1.17, which can be
+ downloaded from [6]www.sleepycat.com. Follow the "[7]Building for
+ UNIX" instructions. Make sure that you run the test suite, and
+ perhaps test with some of the sample applications, before moving
+ on.
+ 2. Start with a clean source tree. Either unpack a fresh copy of the
+ source or do a "make distclean" before continuing.
+ 3. Run the configure script: ./configure
+ --with-db=/usr/local/BerkeleyDB.3.1 (Specify whatever directory
+ you've actually installed DB into, of course. Also specify any
+ other configure options you need at this time.)
+ 4. Run "make" and "make install-exec." Continue installing Citadel
+ as per the instructions supplied with the system.
+
+Migrating an existing GDBM-based Citadel to a DB-based Citadel
+
+ If you have an existing system, you must export your databases,
+ rebuild Citadel with DB support, and then re-import your databases
+ into the new system. Please refer to the document "[8]How to use the
+ importer/exporter" for detailed instructions on this.
+
+ After you export your database, but before you re-import it, you must
+ perform the following steps:
+ 1. Re-build Citadel with DB support, as described above
+ 2. Remove all of the *.gdbm files from your data directory.
+
+Care and feeding of your DB-powered Citadel
+
+ Citadel uses the transaction-based logging facility of Berkeley DB.
+ Therefore you will notice log files accumulating in your data
+ directory. These are required for automatic recovery in the event of
+ a catastrophic system failure. Log files have filenames that look
+ like "log.0000000001" whereas the normal database files have names
+ like "cdb.05".
+
+ So do you have to keep these log files around forever? No, but there
+ are some rules you should follow:
+ * Don't remove a log file if it's the only log file there.
+ * Don't remove any log file that has a recent timestamp. Generally
+ speaking, if it's more than a week old, and you've been running
+ tape backups every day (you are doing daily backups, right?), you
+ can safely remove the log file.
+
+ You may think that it's going to keep writing to that one log file
+ forever, but don't panic; when the log file gets sufficiently large it
+ will switch over to another one. As a general rule of thumb, your
+ archival procedure should be to back up to tape every day, and only
+ delete log files that are older than your oldest backup. Berkeley DB
+ supports "hot" backups; in other words, you are permitted to back up
+ your Citadel data without having to first shut down the Citadel
+ server.
+
+References
+
+ 1. http://uncensored.citadel.org/citadel
+ 2. http://www.sleepycat.com/
+ 3. http://www.gnu.org/software/gdbm/gdbm.html
+ 4. http://www.sleepycat.com/
+ 5. http://www.sleepycat.com/xactfeatures.html
+ 6. http://www.sleepycat.com/
+ 7. http://www.sleepycat.com/docs/ref/build_unix/intro.html
+ 8. http://pixel.citadel.org/citadel/docs/export.html
+++ /dev/null
-<!doctype html public "-//w3c//dtd html 4.0 transitional//en">
-<html>
-<head>
- <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
- <meta name="GENERATOR" content="Mozilla/4.72 [en] (X11; U; Linux 2.2.14-5.0 i586) [Netscape]">
-</head>
-<body>
-
-<center>
-<h1>
-Using Citadel/UX with Sleepycat (Berkeley) DB</h1></center>
-
-<h2>
-Abstract</h2>
-<a href="http://uncensored.citadel.org/citadel">Citadel/UX</a> can
-now use the robust and scalable <a href="http://www.sleepycat.com">Berkeley
-DB from Sleepycat Software</a> as its data store, for increased scalability,
-reliability, and recoverability.
-<h2>
-History and introduction</h2>
-From its inception in 1987 until versions 5.1x in 1988, Citadel/UX utilized
-a built-in data store loosely modelled after Jeff Prothero's original Citadel-CP/M design.
-But as Citadel systems scaled upwards, supporting Internet-connected systems
-with heavy concurrent use, and aspirations of becoming a world-class messaging/groupware
-platform someday, the developers made the decision to switch to an embedded
-database. The Free Software Foundation's <a href="http://www.gnu.org/software/gdbm/gdbm.html">GDBM</a> product
-was chosen for its simple API and its free license (the LGPL).
-<p>Somewhat less than trouble-free operation from 1988 through 2000, however,
-proved that GDBM was not the best choice. Heavily utilized systems
-experienced occasional database corruption, often resulting in repeated
-crashes of the Citadel server. As a result, we made the decision
-to switch to <a href="http://www.sleepycat.com">Berkeley DB</a>.
-<p>Berkeley DB offers <a href="http://www.sleepycat.com/xactfeatures.html">numerous
-features</a> which help Citadel/UX to meet its goals as a high-end
-messaging platform:
-<ul>
-<li>
-Database sizes can scale to hundreds of terabytes</li>
-
-<li>
-A transaction-based logging system</li>
-
-<li>
-Recovery utilities</li>
-</ul>
-It is clear that Berkeley DB is a better choice than GDBM for
-a high-utilization database that requires crash recovery. Beginning
-on December 7, 2000, Citadel/UX supports the use of <i>either</i> GDBM
-or DB as the data store. At some point in the future, DB will
-become the default. <b>If you are setting up a potentially busy system,
-we recommend that you use DB.</b>
-<br>
-<h2>
-Building Citadel/UX with DB support</h2>
-Here are the steps required to get Citadel/UX running with Berkeley DB as
-its back end data store.
-<br>
-<ol>
-<li>
-First, you must download and build Berkeley DB itself. Citadel
-has been developed and tested with DB 3.1.17, which can be downloaded
-from <a href="http://www.sleepycat.com">www.sleepycat.com</a>. Follow
-the "<a href="http://www.sleepycat.com/docs/ref/build_unix/intro.html">Building
-for UNIX</a>" instructions. <b>Make sure that you run the test suite,
-and perhaps test with some of the sample applications, before moving on.</b></li>
-
-<li>
-Start with a clean source tree. Either unpack a fresh copy of the
-source or do a "<tt>make distclean</tt>" before continuing.</li>
-
-<li>
-Run the configure script: <tt>./configure --with-db=/usr/local/BerkeleyDB.3.1</tt>
-(Specify whatever directory you've actually installed DB into, of
-course. Also specify any other configure options you need at this
-time.)</li>
-
-<li>
-Run "make" and "make install-exec." Continue installing Citadel as
-per the instructions supplied with the system.</li>
-</ol>
-
-<h2>
-Migrating an existing GDBM-based Citadel to a DB-based Citadel</h2>
-If you have an existing system, you must export your databases, rebuild
-Citadel with DB support, and then re-import your databases into the
-new system. Please refer to the document "<a href="http://pixel.citadel.org/citadel/docs/export.html">How
-to use the importer/exporter</a>" for detailed instructions on this.
-<p>After you export your database, but before you re-import it, you must
-perform the following steps:
-<ol>
-<li>
-Re-build Citadel with DB support, as described above</li>
-
-<li>
-Remove all of the *.gdbm files from your data directory.</li>
-</ol>
-
-<h2>
-Care and feeding of your DB-powered Citadel</h2>
-Citadel uses the transaction-based logging facility of Berkeley DB.
-Therefore you will notice log files accumulating in your data directory.
-These are required for automatic recovery in the event of a catastrophic
-system failure. Log files have filenames that look like "log.0000000001"
-whereas the normal database files have names like "cdb.05".
-<p>So do you have to keep these log files around forever? No, but
-there are some rules you should follow:
-<ul>
-<li>
-Don't remove a log file if it's the only log file there.</li>
-
-<li>
-Don't remove any log file that has a recent timestamp. Generally
-speaking, if it's more than a week old, and you've been running tape backups
-every day (you <i>are</i> doing daily backups, right?), you can safely
-remove the log file.</li>
-</ul>
-You may think that it's going to keep writing to that one log file forever,
-but don't panic; when the log file gets sufficiently large it will switch
-over to another one. As a general rule of thumb, your archival procedure
-should be to back up to tape every day, and only delete log files that
-are older than your oldest backup. Berkeley DB supports "hot" backups;
-in other words, you are permitted to back up your Citadel data without
-having to first shut down the Citadel server.
-<br>
-</body>
-</html>
-
-
-
Citadel/UX Internet E-mail setup instructions (native Citadel/UX version)
This document explains how to set up your citadel as an Internet e-mail
This means that Citadel couldn't start up pop services. Generally this
only happens if there's something on this port. In this case it's Pixel's pop
-server (incidentally, PixelBBS uses Citadel/UX for pop).
+server (incidentally, PixelBBS uses Citadel/UX for pop). You'll find the same
+is true for IMAP, which runs on port 143.
citserver: Can't bind: Address already in use
ERROR: could not bind to TCP port 25.
- C compiler (such as gcc or egcs) and "make"
- POSIX threads (the "pthreads" library)
- TCP/IP
- - The "gdbm" library
+ - Berkeley DB v3.1 or newer, or GDBM 1.8 or newer
- Enough disk space to hold all of the programs and data
If you are running Citadel/UX on a Linux system, it is STRONGLY recommended
-that you use a version based on glibc v2 (also called libc6). libc5 contains
-a number of thread safety problems. Furthermore, most modern Linux
-distributions have libc6, pthreads, gdbm, and the compiler already installed
-and integrated for you.
+that you run it on a recent distribution (such as Red Hat 7.0 or newer). A
+new-ish distribution will have most or all of the prerequisite tools and
+libraries already integrated for you.
NOW AVAILABLE:
during the unpacking process, and others may be created by the software if
needed.
- Make sure you have the "gdbm" record manager installed on your system, and
-that you have installed the libraries and headers required to compile gdbm
-programs. Likewise, if your operating system uses a separate library to
-support POSIX threads, make sure that library is installed as well.
+ Make sure you have either Berkeley DB, or GDBM 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 http://www.sleepycat.com *or* you can get GDBM from http://www.gnu.org or
+one of its mirrors. We strongly recommend Berkeley DB for all but the lightest
+of installations, as it is far more robust and reliable.
+
+ If your operating system uses a separate library to support POSIX threads
+(pthreads), make sure that library is installed as well.
+
-
THE BBS LOGIN
There will be one account in /etc/passwd which all BBS users will use to
wish to place it in a different directory, you can instead do:
./configure --prefix=/usr/local/citadel (or whatever)
+
+ 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:
+
+ ./configure --with-db=/usr/local/BerkeleyDB-3.1
+
+ The configure script prefers Berkeley DB if it is available, but will fall
+back to GDBM if it has to.
-
File permissions are always a bother to work with. You don't want the
board 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'
-f - 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.
+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.)
The preferred method of starting the Citadel server is to place an entry in
- THE PEANUT GALLERY
+ TROUBLESHOOTING AND GETTING HELP
That's just about all the information you need to install the system.
For more information, visit the Citadel/UX web site at UNCENSORED! BBS,
3. Did you start the server?
To report a problem, you can log on to UNCENSORED! or any other BBS on the
-Citadel network which carries the Citadel/UX> room. Please remember to mention
-all of the following information:
+Citadel network which carries the Citadel/UX> room. Please DO NOT e-mail the
+developers directly. Post a request for help on the BBS, with all of the
+following information:
1. The exact nature of your difficulty
2. A transcript of the error message(s) if possible
3. The version of Citadel you are running
- 4. The version of GDBM present on your system
+ 4. The version of Berkeley DB or GDBM present on your system
5. Which operating system you are running, and what version
6. 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 "ldd ./citserver" command).
-
-
projects / citadel.git / commitdiff