chiark / gitweb /
debugging for thing that crashed
[innduct.git] / doc / pod / makehistory.pod
1 =head1 NAME
2
3 makehistory - Initialize or rebuild INN history database
4
5 =head1 SYNOPSIS
6
7 B<makehistory> [B<-abeFIOx>] [B<-f> I<filename>] [B<-l> I<count>]
8 [B<-T> I<tmpdir>] [B<-s> I<size>]
9
10 =head1 DESCRIPTION
11
12 B<makehistory> rebuilds the history(5) text file, which contains a list of
13 Message-IDs of articles already seen by the server.  It can also be used
14 to rebuild the overview database.  Note that the dbz(3) indexes for the
15 history file are rebuilt by makedbz(8), not by B<makehistory> as in
16 earlier versions of INN.
17
18 The default location of the history text file is I<pathdb>/history; to
19 specify an alternate location, use the B<-f> flag.
20
21 By default, B<makehistory> will scan the entire spool, using the storage
22 manager, and write a history line for every article.  To also generate
23 overview information, use the B<-O> flag.
24
25 WARNING: If you're trying to rebuild the overview database, be sure to
26 stop innd(8) and delete or zero out the existing database before you start
27 for the best results.  An overview rebuild should not be done while the
28 server is running.  Unless the existing overview is deleted, you may end
29 up with problems like out-of-order overview entries, excessively large
30 overview buffers, and the like.
31
32 If I<ovmethod> in F<inn.conf> is C<ovdb>, you must have the ovdb processes
33 running while rebuilding overview.  ovdb needs them available while
34 writing overview entries.  You can start them by hand separate from the
35 rest of the server by running B<ovdb_init>; see ovdb_init(8) for more
36 details.
37
38 =head1 OPTIONS
39
40 =over 4
41
42 =item B<-a>
43
44 Append to the history file rather than generating a new one.  If you
45 append to the main history file, make sure innd(8) is throttled or not
46 running, or you can corrupt the history.
47
48 =item B<-b>
49
50 Delete any messages found in the spool that do not have valid Message-ID
51 headers in them.
52
53 =item B<-e>
54
55 Compute Bytes headers which is used for overview data.  This option is valid
56 only if B<-O> flag is specified and F<overview.fmt> includes C<Bytes:>.
57
58 =item B<-f> I<filename>
59
60 Rather than writing directly to I<pathdb>/history, instead write to
61 I<filename>.
62
63 =item B<-F>
64
65 Fork a separate process to flush overview data to disk rather than doing
66 it directly.  The advantage of this is that it allows B<makehistory> to
67 continue to collect more data from the spool while the first batch of data
68 is being written to the overview database.  The disadvantage is that up to
69 twice as much temporary disk space will be used for the generated overview
70 data.  This option only makes sense in combination with B<-O>.  With
71 C<buffindexed>, the C<overchan> program is invoked to write overview.
72
73 =item B<-I>
74
75 Don't store overview data for articles numbered lower than the lowest
76 article number in F<active>.  This is useful if there are for whatever
77 reason old articles on disk that shouldn't be available to readers or put
78 into the overview database.
79
80 =item B<-l> I<count>
81
82 This option specifies how many articles to process before writing the
83 accumulated overview information out to the overview database.  The
84 default is C<10000>.  Since overview write performance is faster with
85 sorted data, each "batch" gets sorted.  Increasing the batch size
86 with this option may further improve write performance, at the cost
87 of longer sort times.  Also, temporary space will be needed to store
88 the overview batches.  At a rough estimate, about 300 * I<count> bytes
89 of temporary space will be required (not counting temp files created
90 by sort(1)).  See the description of the B<-T> option for how to
91 specify the temporary storage location.  This option has no effect
92 with C<buffindexed>, because C<buffindexed> does not need sorted
93 overview and no batching is done.
94
95 =item B<-s> I<size>
96
97 Size the history database for approximately I<size> pairs.  Accurately
98 specifying the size is an optimization that will create a more
99 efficient database.  (The size should be the estimated eventual size
100 of the F<history> file, typically the size of the old file, in lines.)
101
102 =item B<-O>
103
104 Create the overview database as well as the history file.  Overview
105 information is only required if the server supports readers; it is not
106 needed for a transit-only server (see I<enableoverview> in inn.conf(5)).
107 If you are using the C<buffindexed> overview storage method, erase all of
108 your overview buffers before running B<makehistory> with B<-O>.
109
110 =item B<-T> I<tmpdir>
111
112 If B<-O> is given, B<makehistory> needs a location to write temporary
113 overview data.  By default, it uses I<pathtmp>, set in F<inn.conf>, but if
114 this option is given, the provided I<tmpdir> is used instead.  This is
115 also used for temporary files created by sort(1) (which is invoked in the
116 process of writing overview information since sorted overview information
117 writes faster).  By default, sort usually uses your system temporary
118 directory; see the sort(1) man page on your system to be sure.
119
120 =item B<-x>
121
122 If this option is given, B<makehistory> won't write out history file
123 entries.  This is useful mostly for building overview without generating
124 a new history file.
125
126 =back
127
128 =head1 EXAMPLES
129
130 Here's a typical example of rebuilding the entire history and overview
131 database, removing broken articles in the news spool.  This uses the
132 default temporary file locations and should be done while innd isn't
133 running (or is throttled).
134
135     makehistory -b -f history.n -O -l 30000 -I
136
137 This will rebuild the overview (if using C<buffindexed>, erase the
138 existing overview buffers before running this command) and leave a new
139 history file as C<history.n> in I<pathdb>.  To preserve all of the history
140 entries from the old history file that correspond to rejected articles or
141 expired articles, follow the above command with:
142
143     cd /usr/local/news/db
144     awk 'NF == 2 { print }' < history >> history.n
145
146 (replacing the path with your I<pathdb>, if it isn't the default).  Then
147 look over the new history file for problems and run:
148
149     makedbz -s `wc -l < history` -f history.n
150
151 Then rename all of the files matching C<history.n.*> to C<history.*>,
152 replacing the current history database and indexes.  After that, it's safe
153 to unthrottle innd.
154
155 For a simpler example:
156
157     makehistory -b -f history.n -I -O
158
159 will scan the spool, removing broken articles and generating history and
160 overview entries for articles missing from history.
161
162 To just rebuild overview:
163
164     makehistory -O -x -F
165
166 =head1 FILES
167
168 =over 4
169
170 =item inn.conf
171
172 Read for I<pathdb>, I<pathtmp>, and other settings.
173
174 =item I<pathdb>/history
175
176 This is the default output file for B<makehistory>.
177
178 =item I<pathtmp>
179
180 Where temporary files are written unless B<-T> is given.
181
182 =back
183
184 =head1 HISTORY
185
186 Originally written by Rich $alz <rsalz@uunet.uu.net> for InterNetNews and
187 updated by various other people since.
188
189 $Id: makehistory.pod 6400 2003-07-12 19:26:58Z rra $
190
191 =head1 SEE ALSO
192
193 dbz(3), active(5), history(5), inn.conf(5), ctlinnd(8), innd(8),
194 makedbz(8), ovdb_init(8), overview.fmt(5).
195
196 =cut