chiark / gitweb /
debugging for thing that crashed
[innduct.git] / 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