doc/pod/ovdb_init.pod

   1 =head1 NAME
   2
   3 ovdb_init - Prepare ovdb database for use
   4
   5 =head1 SYNOPSYS
   6
   7 ovdb_init [C<-u>|C<-r>]
   8
   9 =head1 DESCRIPTION
  10
  11 This command must be run before any other process can access the
  12 overview database.  It performs the following steps:
  13
  14 =over 4
  15
  16 =item 1
  17
  18 Creates the database environment, if necessary
  19
  20 =item 2
  21
  22 If the database is idle (and if the C<-u> option is not specified),
  23 it performs a normal recovery.  The recovery will remove stale locks,
  24 recreate the memory pool cache, and repair any damage caused by a system
  25 crash or improper shutdown.
  26
  27 =item 3
  28
  29 If the C<-u> option is specified, it performs any necessary upgrades
  30 to the database.  See the UPGRADING section below.
  31
  32 =item 4
  33
  34 Starts the DB housekeeping processes (ovdb_monitor) if they're not
  35 already running. (Unless the C<-r> option is specified).
  36
  37 =item 5
  38
  39 Starts the ovdb readserver (ovdb_server) processes if C<readserver>
  40 in F<ovdb.conf> is C<true>, and if they're not
  41 already running. (Unless the C<-r> option is specified).
  42
  43 =back
  44
  45 Returns exit status of 0 if all steps were completed successfully.
  46 In the event of an error, messages are written to syslog and/or stderr.
  47
  48 If a recovery was attempted but it failed, the database may be
  49 damaged beyond repair, requiring a rebuild with makehistory(8).
  50
  51 This command is normally invoked automatically by rc.news(8).
  52
  53 It is OK to run this command multiple times.
  54
  55 =head1 OPTIONS
  56
  57 =over 4
  58
  59 =item C<-r>
  60
  61 Perform recovery only.  C<ovdb_monitor> is not started.
  62
  63 =item C<-u>
  64
  65 Perform any needed upgrades.  Recovery is not attempted.
  66 C<ovdb_monitor> is started if the upgrade succeeded.
  67
  68 =back
  69
  70 =head1 UPGRADING
  71
  72 There are two situations in which the database will need to be
  73 upgraded:
  74
  75 =over 4
  76
  77 =item *
  78
  79 You upgrade the BerkeleyDB library to a newer version, for example
  80 from 2.7.7 to 3.1.17.  In this case, the BerkeleyDB db->upgrade()
  81 method is used.
  82
  83 =item *
  84
  85 You upgrade ovdb to a newer major version; i.e., ovdb-1.0 to ovdb-2.0.
  86
  87 =back
  88
  89 In both of these cases, the database is upgraded in-place; and the
  90 upgrade can not be undone.  Do not interrupt the upgrade process once
  91 it has started, because there is a risk of irrepairable corruption.
  92 The upgrade may take several minutes to complete.
  93 If an upgrade does get interrupted, try running the upgrade again.
  94
  95 Here's an example procedure to upgrade a database created with BerkeleyDB
  96 2.7.7 to use BerkeleyDB 3.1.17:
  97
  98 =over 4
  99
 100 =item 1
 101
 102 Build and install the BerkeleyDB 3.1.17
 103
 104 =item 2
 105
 106 Run configure in the INN source tree and make sure it picks up the
 107 right BerkeleyDB directory (e.g., /usr/local/BerkeleyDB.3.1)
 108
 109 =item 3
 110
 111 Do a C<make>
 112
 113 =item 4
 114
 115 Shut down INN (e.g., with C<rc.news stop>).  Be sure to kill all nnrpds as
 116 well.
 117
 118 =item 5
 119
 120 Do a C<make update> to install the new binaries.
 121
 122 =item 6
 123
 124 Run C<ovdb_init -u> as the news user.
 125
 126 =item 7
 127
 128 Start INN with C<rc.news>
 129
 130 =back
 131
 132 It is OK to specify C<-u> even if no upgrades are needed.
 133
 134 =head1 HISTORY
 135
 136 Written by Heath Kehoe E<lt>hakehoe@avalon.netE<gt> for InterNetNews.
 137
 138 =head1 SEE ALSO
 139
 140 ovdb(5), makehistory(8)
 141
 142 =cut