=head1 NAME

ovdb_init - Prepare ovdb database for use

=head1 SYNOPSIS

B<ovdb_init> [B<-r>|B<-u>]

=head1 DESCRIPTION

This command must be run before any other process can access the
overview database.  B<ovdb_init> is normally invoked automatically by
B<rc.news> when starting the news system.

B<ovdb_init> performs the following steps:

=over 4

=item 1.

Creates the database environment, if necessary.

=item 2.

If the database is idle (and if the B<-u> option is not specified),
it performs a normal recovery.  The recovery will remove stale locks,
recreate the memory pool cache, and repair any damage caused by a system
crash or improper shutdown.

=item 3.

If the B<-u> option is specified, it performs any necessary upgrades
to the database.  See the L<"UPGRADING"> section below.

=item 4.

Starts the database housekeeping processes (B<ovdb_monitor>) if they are
not already running.  (Unless the B<-r> option is specified.)

=item 5.

Starts the ovdb readserver processes (B<ovdb_server>) if I<readserver>
in F<ovdb.conf> is true, and if they are not already running.  (Unless
the B<-r> option is specified.)

=back

Returns exit status of C<0> if all steps were completed successfully.
In the event of an error, messages are written to syslog and/or stderr.

If a recovery was attempted but failed, the database may be
damaged beyond repair, requiring a rebuild with B<makehistory>.

This command can be run multiple times.

=head1 OPTIONS

=over 4

=item B<-r>

Perform recovery only.  B<ovdb_monitor> is not started.

=item B<-u>

Perform any needed upgrades.  Recovery is not attempted.
B<ovdb_monitor> is started if the upgrade succeeded.

This option can be used even if no upgrades are needed.

=back

=head1 UPGRADING

There are two situations in which the database will need to be
upgraded:

=over 4

=item *

You upgrade the S<Berkeley DB> library to a newer version, for example
from 2.7.7 to 3.1.17.  In this case, the S<Berkeley DB> C<< db->upgrade() >>
method is used.

=item *

You upgrade ovdb to a newer major version; i.e., ovdb-1.0 (shipped with
S<INN 2.3.0> up to S<INN 2.3.5>) to ovdb-2.0 (since S<INN 2.4.0>).

=back

In both of these cases, the database is upgraded in-place; and the
upgrade cannot be undone.  Do not interrupt the upgrade process once
it has started, because there is a risk of irreparable corruption.
The upgrade may take several minutes to complete.
If an upgrade does get interrupted, try running the upgrade again.

Here's an example procedure to upgrade a database created with
S<Berkeley DB 2.7.7> to use S<Berkeley DB 3.1.17>:

=over 4

=item 1.

Build and install the S<Berkeley DB 3.1.17> version;

=item 2.

Run B<configure> in the INN source tree and make sure it picks up the
right S<Berkeley DB> directory (e.g., F</usr/local/BerkeleyDB.3.1>);

=item 3.

Do a C<make>;

=item 4.

Shut down INN (e.g., with C<rc.news stop>) and be sure to kill all
instances of B<nnrpd> as well;

=item 5.

Do a C<make update> to install the new binaries;

=item 6.

Run C<ovdb_init -u> as the news user;

=item 7.

Start INN with the C<rc.news> command.

=back

=head1 HISTORY

Written by Heath Kehoe <hakehoe@avalon.net> for InterNetNews.

=head1 SEE ALSO

ovdb(5), makehistory(8), rc.news(8).

=cut
