updated citadel-with-berkeley-db.txt.

 - updated build instructions
 - improved backup procedures to be safer and more space-efficient.

diff --git a/citadel/ChangeLog b/citadel/ChangeLog
index 2548b209ad3b40a07383a0e7ee6e10bfdfb03522..4543ca7265dc1c6144bf1583bd0e648b85e666ad 100644 (file)
--- a/citadel/ChangeLog
+++ b/citadel/ChangeLog
@@ -1,4 +1,9 @@
  $Log$
+ Revision 580.23  2001/08/11 22:35:40  nbryant
+ updated citadel-with-berkeley-db.txt.
+  - updated build instructions
+  - improved backup procedures to be safer and more space-efficient.
+
  Revision 580.22  2001/08/11 19:18:41  ajc
  * Realized that I am stupid and started implementing server commands to load
    and save network configurations, when I had already lovingly implemented the
@@ -2672,3 +2677,4 @@ Sat Jul 11 00:20:48 EDT 1998 Nathan Bryant <bryant@cs.usm.maine.edu>
 
 Fri Jul 10 1998 Art Cancro <ajc@uncensored.citadel.org>
        * Initial CVS import 
+

diff --git a/citadel/docs/citadel-with-berkeley-db.txt b/citadel/docs/citadel-with-berkeley-db.txt
index bd817db97a4cfa9799f5b0d01a2e1267de627048..6ce13fe90bbdec7e37bcf7ee91d1cc90049dab6d 100644 (file)
--- a/citadel/docs/citadel-with-berkeley-db.txt
+++ b/citadel/docs/citadel-with-berkeley-db.txt
@@ -9,7 +9,7 @@ Abstract
    
 History and introduction
 
-   From its inception in 1987 until versions 5.1x in 1988,
+   From its inception in 1987 until versions 5.1x in 1998,
    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
@@ -19,7 +19,7 @@ History and introduction
    [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,
+   Somewhat less than trouble-free operation from 1998 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
@@ -34,9 +34,9 @@ History and introduction
    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.
+   the data store.  As of July 1, 2001, DB has become the default.  We
+   recommend DB in preference to GDBM wherever possible because there is
+   no effective way to recover from corrupted GDBM files.
    
    
 Building Citadel/UX with DB support
@@ -50,12 +50,20 @@ Building Citadel/UX with DB support
        UNIX" instructions.  Make sure that you run the test suite, and
        perhaps test with some of the sample applications, before moving
        on.
+
+       Note that as of DB 3.1.17, DB's configure script can't check for
+       OpenBSD systems. You will need to configure DB as follows:
+
+         env CC='gcc -pthread -Di386' ../dist/configure [flags]
+
+       DB 3.3.x's configure script should not need the -Di386 flag.
+
     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.)
+       (Optionally specify --with-db=DIR for whatever prefix
+       you've actually installed DB into, if you overrode DB's defaults.
+       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.
        
@@ -83,19 +91,25 @@ Care and feeding of your DB-powered Citadel
    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.
-       
+     * If it's not listed in the output of the db_archive[9] command, it's
+       not safe to remove.
+     * After a successful backup (see below) log files listed by the
+       db_archive[9] command may be removed to conserve disk space, if 
+       those log files were backed up.
+
    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.
+   archival procedure should be to back up to tape every day, removing log
+   files after backups as described above.  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, AS LONG AS YOU 
+   COPY THE DATA FILES BEFORE THE LOG FILES.  One way to ensure this is to 
+   first copy the data files to a temporary directory, then copy the log 
+   files to the same temporary directory, and finally back up and remove 
+   the temporary directory. This temporary-directory procedure also makes 
+   it easy to determine which log files made it onto the backup when 
+   determining what is safe to remove. (See above.)
 
 References
 
@@ -107,3 +121,4 @@ References
    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
+   9. http://www.sleepycat.com/docs/utility/db_archive.html