citadel/docs/citadel-with-berkeley-db.txt

   1
   2                Using Citadel/UX with Sleepycat (Berkeley) DB
   3
   4 Abstract
   5
   6    Citadel/UX can now use the robust and scalable Berkeley DB from
   7    Sleepycat Software as its data store, for increased scalability,
   8    reliability, and recoverability.
   9
  10 History and introduction
  11
  12    From its inception in 1987 until versions 5.1x in 1998,
  13    Citadel/UX utilized a built-in data store loosely modeled after Jeff
  14    Prothero's original Citadel-CP/M design.  But as Citadel systems
  15    scaled upwards, supporting Internet-connected systems with heavy
  16    concurrent use, and aspirations of becoming a world-class
  17    messaging/groupware platform someday, the developers made the decision
  18    to switch to an embedded database.  The Free Software Foundation's
  19    GDBM product was chosen for its simple API and its free license
  20    (the LGPL).
  21
  22    Somewhat less than trouble-free operation from 1998 through 2000,
  23    however, proved that GDBM was not the best choice.  Heavily utilized
  24    systems experienced occasional database corruption, often resulting in
  25    repeated crashes of the Citadel server.  As a result, we made the
  26    decision to switch to Berkeley DB.
  27
  28    Berkeley DB offers numerous features which help Citadel/UX to meet
  29    its goals as a high-end messaging platform:
  30      * Database sizes can scale to hundreds of terabytes
  31      * A transaction-based logging system
  32      * Recovery utilities
  33
  34    It is clear that Berkeley DB is a better choice than GDBM for a
  35    high-utilization database that requires crash recovery.  Citadel/UX can
  36    currently be built with either DB or GDBM as the data store; however,
  37    THE USE OF GDBM IS DEPRECATED AND STRONGLY DISCOURAGED.  If you are
  38    bringing up a new site you should use Berkeley DB, period.  If you are
  39    maintaining an existing site using GDBM you should migrate it to Berkeley
  40    DB as soon as possible, because support for it will be dropped in a future
  41    release.
  42
  43
  44 Building Citadel/UX with DB support
  45
  46    If you are running Citadel/UX on a Red Hat Linux system, you don't have
  47    to build Berekeley DB from source.  Simply install the RPM's for "db3"
  48    and "db3-devel" (the latter may be on the second CD) and you're ready to
  49    run Citadel.
  50
  51    Otherwise, here are the steps required to get Citadel running with
  52    Berkeley DB as its back end data store.
  53
  54     1. First, you must download and build Berkeley DB itself.  Citadel
  55        has been developed and tested with DB 3.1.17, which can be
  56        downloaded from www.sleepycat.com.  Follow the "Building for
  57        UNIX" instructions.  Make sure that you run the test suite, and
  58        perhaps test with some of the sample applications, before moving
  59        on.
  60
  61        Note that as of DB 3.1.17, DB's configure script can't check for
  62        OpenBSD systems. You will need to configure DB as follows:
  63
  64          env CC='gcc -pthread -Di386' ../dist/configure [flags]
  65
  66        DB 3.3.x's configure script should not need the -Di386 flag.
  67
  68     2. Start with a clean source tree.  Either unpack a fresh copy of the
  69        source or do a "make distclean" before continuing.
  70     3. Run the configure script:  ./configure
  71        (Optionally specify --with-db=DIR for whatever prefix
  72        you've actually installed DB into, if you overrode DB's defaults.
  73        Also specify any other configure options you need at this time.)
  74     4. Run "make" and "make install-exec."  Continue installing Citadel
  75        as per the instructions supplied with the system.
  76
  77 Migrating an existing GDBM-based Citadel to a DB-based Citadel
  78
  79    If you have an existing system, you must export your databases,
  80    rebuild Citadel with DB support, and then re-import your databases
  81    into the new system.  Please refer to the document "How to use the
  82    importer/exporter" for detailed instructions on this.
  83
  84    After you export your database, but before you re-import it, you must
  85    perform the following steps:
  86     1. Re-build Citadel with DB support, as described above
  87     2. Remove all of the *.gdbm files from your data directory.
  88
  89 Care and feeding of your DB-powered Citadel
  90
  91    Citadel uses the transaction-based logging facility of Berkeley DB.
  92    Therefore you will notice log files accumulating in your data
  93    directory.  These are required for automatic recovery in the event of
  94    a catastrophic system failure.  Log files have filenames that look
  95    like "log.0000000001" whereas the normal database files have names
  96    like "cdb.05".
  97
  98    So do you have to keep these log files around forever?  No, but there
  99    are some rules you should follow:
 100      * Don't remove a log file if it's the only log file there.
 101      * If it's not listed in the output of the db_archive command, it's
 102        not safe to remove.
 103      * After a successful backup (see below) log files listed by the
 104        db_archive command may be removed to conserve disk space, if
 105        those log files were backed up.
 106
 107    You may think that it's going to keep writing to that one log file
 108    forever, but don't panic; when the log file gets sufficiently large it
 109    will switch over to another one.  As a general rule of thumb, your
 110    archival procedure should be to back up to tape every day.  Berkeley DB
 111    supports "hot" backups; in other words, you are permitted to back up your
 112    Citadel data without having to first shut down the Citadel server, as long
 113    as you copy the data files before the log files.
 114
 115    And don't worry about your system filling up with log files; the Citadel
 116    server will automatically remove them when they're no longer needed.
 117
 118