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