doc/man/makehistory.8

   1 .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sh \" Subsection heading
   6 .br
   7 .if t .Sp
   8 .ne 5
   9 .PP
  10 \fB\\$1\fR
  11 .PP
  12 ..
  13 .de Sp \" Vertical space (when we can't use .PP)
  14 .if t .sp .5v
  15 .if n .sp
  16 ..
  17 .de Vb \" Begin verbatim text
  18 .ft CW
  19 .nf
  20 .ne \\$1
  21 ..
  22 .de Ve \" End verbatim text
  23 .ft R
  24 .fi
  25 ..
  26 .\" Set up some character translations and predefined strings.  \*(-- will
  27 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  28 .\" double quote, and \*(R" will give a right double quote.  \*(C+ will
  29 .\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
  30 .\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
  31 .\" nothing in troff, for use with C<>.
  32 .tr \(*W-
  33 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  34 .ie n \{\
  35 .    ds -- \(*W-
  36 .    ds PI pi
  37 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  38 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  39 .    ds L" ""
  40 .    ds R" ""
  41 .    ds C` ""
  42 .    ds C' ""
  43 'br\}
  44 .el\{\
  45 .    ds -- \|\(em\|
  46 .    ds PI \(*p
  47 .    ds L" ``
  48 .    ds R" ''
  49 'br\}
  50 .\"
  51 .\" If the F register is turned on, we'll generate index entries on stderr for
  52 .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
  53 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  54 .\" output yourself in some meaningful fashion.
  55 .if \nF \{\
  56 .    de IX
  57 .    tm Index:\\$1\t\\n%\t"\\$2"
  58 ..
  59 .    nr % 0
  60 .    rr F
  61 .\}
  62 .\"
  63 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
  64 .\" way too many mistakes in technical documents.
  65 .hy 0
  66 .if n .na
  67 .\"
  68 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  69 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  70 .    \" fudge factors for nroff and troff
  71 .if n \{\
  72 .    ds #H 0
  73 .    ds #V .8m
  74 .    ds #F .3m
  75 .    ds #[ \f1
  76 .    ds #] \fP
  77 .\}
  78 .if t \{\
  79 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  80 .    ds #V .6m
  81 .    ds #F 0
  82 .    ds #[ \&
  83 .    ds #] \&
  84 .\}
  85 .    \" simple accents for nroff and troff
  86 .if n \{\
  87 .    ds ' \&
  88 .    ds ` \&
  89 .    ds ^ \&
  90 .    ds , \&
  91 .    ds ~ ~
  92 .    ds /
  93 .\}
  94 .if t \{\
  95 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  96 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  97 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  98 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  99 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 100 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 101 .\}
 102 .    \" troff and (daisy-wheel) nroff accents
 103 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 104 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 105 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 106 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 107 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 108 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 109 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 110 .ds ae a\h'-(\w'a'u*4/10)'e
 111 .ds Ae A\h'-(\w'A'u*4/10)'E
 112 .    \" corrections for vroff
 113 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 114 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 115 .    \" for low resolution devices (crt and lpr)
 116 .if \n(.H>23 .if \n(.V>19 \
 117 \{\
 118 .    ds : e
 119 .    ds 8 ss
 120 .    ds o a
 121 .    ds d- d\h'-1'\(ga
 122 .    ds D- D\h'-1'\(hy
 123 .    ds th \o'bp'
 124 .    ds Th \o'LP'
 125 .    ds ae ae
 126 .    ds Ae AE
 127 .\}
 128 .rm #[ #] #H #V #F C
 129 .\" ========================================================================
 130 .\"
 131 .IX Title "MAKEHISTORY 8"
 132 .TH MAKEHISTORY 8 "2008-04-06" "INN 2.4.5" "InterNetNews Documentation"
 133 .SH "NAME"
 134 makehistory \- Initialize or rebuild INN history database
 135 .SH "SYNOPSIS"
 136 .IX Header "SYNOPSIS"
 137 \&\fBmakehistory\fR [\fB\-abeFIOx\fR] [\fB\-f\fR \fIfilename\fR] [\fB\-l\fR \fIcount\fR]
 138 [\fB\-T\fR \fItmpdir\fR] [\fB\-s\fR \fIsize\fR]
 139 .SH "DESCRIPTION"
 140 .IX Header "DESCRIPTION"
 141 \&\fBmakehistory\fR rebuilds the \fIhistory\fR\|(5) text file, which contains a list of
 142 Message-IDs of articles already seen by the server.  It can also be used
 143 to rebuild the overview database.  Note that the \fIdbz\fR\|(3) indexes for the
 144 history file are rebuilt by \fImakedbz\fR\|(8), not by \fBmakehistory\fR as in
 145 earlier versions of \s-1INN\s0.
 146 .PP
 147 The default location of the history text file is \fIpathdb\fR/history; to
 148 specify an alternate location, use the \fB\-f\fR flag.
 149 .PP
 150 By default, \fBmakehistory\fR will scan the entire spool, using the storage
 151 manager, and write a history line for every article.  To also generate
 152 overview information, use the \fB\-O\fR flag.
 153 .PP
 154 \&\s-1WARNING:\s0 If you're trying to rebuild the overview database, be sure to
 155 stop \fIinnd\fR\|(8) and delete or zero out the existing database before you start
 156 for the best results.  An overview rebuild should not be done while the
 157 server is running.  Unless the existing overview is deleted, you may end
 158 up with problems like out-of-order overview entries, excessively large
 159 overview buffers, and the like.
 160 .PP
 161 If \fIovmethod\fR in \fIinn.conf\fR is \f(CW\*(C`ovdb\*(C'\fR, you must have the ovdb processes
 162 running while rebuilding overview.  ovdb needs them available while
 163 writing overview entries.  You can start them by hand separate from the
 164 rest of the server by running \fBovdb_init\fR; see \fIovdb_init\fR\|(8) for more
 165 details.
 166 .SH "OPTIONS"
 167 .IX Header "OPTIONS"
 168 .IP "\fB\-a\fR" 4
 169 .IX Item "-a"
 170 Append to the history file rather than generating a new one.  If you
 171 append to the main history file, make sure \fIinnd\fR\|(8) is throttled or not
 172 running, or you can corrupt the history.
 173 .IP "\fB\-b\fR" 4
 174 .IX Item "-b"
 175 Delete any messages found in the spool that do not have valid Message-ID
 176 headers in them.
 177 .IP "\fB\-e\fR" 4
 178 .IX Item "-e"
 179 Compute Bytes headers which is used for overview data.  This option is valid
 180 only if \fB\-O\fR flag is specified and \fIoverview.fmt\fR includes \f(CW\*(C`Bytes:\*(C'\fR.
 181 .IP "\fB\-f\fR \fIfilename\fR" 4
 182 .IX Item "-f filename"
 183 Rather than writing directly to \fIpathdb\fR/history, instead write to
 184 \&\fIfilename\fR.
 185 .IP "\fB\-F\fR" 4
 186 .IX Item "-F"
 187 Fork a separate process to flush overview data to disk rather than doing
 188 it directly.  The advantage of this is that it allows \fBmakehistory\fR to
 189 continue to collect more data from the spool while the first batch of data
 190 is being written to the overview database.  The disadvantage is that up to
 191 twice as much temporary disk space will be used for the generated overview
 192 data.  This option only makes sense in combination with \fB\-O\fR.  With
 193 \&\f(CW\*(C`buffindexed\*(C'\fR, the \f(CW\*(C`overchan\*(C'\fR program is invoked to write overview.
 194 .IP "\fB\-I\fR" 4
 195 .IX Item "-I"
 196 Don't store overview data for articles numbered lower than the lowest
 197 article number in \fIactive\fR.  This is useful if there are for whatever
 198 reason old articles on disk that shouldn't be available to readers or put
 199 into the overview database.
 200 .IP "\fB\-l\fR \fIcount\fR" 4
 201 .IX Item "-l count"
 202 This option specifies how many articles to process before writing the
 203 accumulated overview information out to the overview database.  The
 204 default is \f(CW10000\fR.  Since overview write performance is faster with
 205 sorted data, each \*(L"batch\*(R" gets sorted.  Increasing the batch size
 206 with this option may further improve write performance, at the cost
 207 of longer sort times.  Also, temporary space will be needed to store
 208 the overview batches.  At a rough estimate, about 300 * \fIcount\fR bytes
 209 of temporary space will be required (not counting temp files created
 210 by \fIsort\fR\|(1)).  See the description of the \fB\-T\fR option for how to
 211 specify the temporary storage location.  This option has no effect
 212 with \f(CW\*(C`buffindexed\*(C'\fR, because \f(CW\*(C`buffindexed\*(C'\fR does not need sorted
 213 overview and no batching is done.
 214 .IP "\fB\-s\fR \fIsize\fR" 4
 215 .IX Item "-s size"
 216 Size the history database for approximately \fIsize\fR pairs.  Accurately
 217 specifying the size is an optimization that will create a more
 218 efficient database.  (The size should be the estimated eventual size
 219 of the \fIhistory\fR file, typically the size of the old file, in lines.)
 220 .IP "\fB\-O\fR" 4
 221 .IX Item "-O"
 222 Create the overview database as well as the history file.  Overview
 223 information is only required if the server supports readers; it is not
 224 needed for a transit-only server (see \fIenableoverview\fR in \fIinn.conf\fR\|(5)).
 225 If you are using the \f(CW\*(C`buffindexed\*(C'\fR overview storage method, erase all of
 226 your overview buffers before running \fBmakehistory\fR with \fB\-O\fR.
 227 .IP "\fB\-T\fR \fItmpdir\fR" 4
 228 .IX Item "-T tmpdir"
 229 If \fB\-O\fR is given, \fBmakehistory\fR needs a location to write temporary
 230 overview data.  By default, it uses \fIpathtmp\fR, set in \fIinn.conf\fR, but if
 231 this option is given, the provided \fItmpdir\fR is used instead.  This is
 232 also used for temporary files created by \fIsort\fR\|(1) (which is invoked in the
 233 process of writing overview information since sorted overview information
 234 writes faster).  By default, sort usually uses your system temporary
 235 directory; see the \fIsort\fR\|(1) man page on your system to be sure.
 236 .IP "\fB\-x\fR" 4
 237 .IX Item "-x"
 238 If this option is given, \fBmakehistory\fR won't write out history file
 239 entries.  This is useful mostly for building overview without generating
 240 a new history file.
 241 .SH "EXAMPLES"
 242 .IX Header "EXAMPLES"
 243 Here's a typical example of rebuilding the entire history and overview
 244 database, removing broken articles in the news spool.  This uses the
 245 default temporary file locations and should be done while innd isn't
 246 running (or is throttled).
 247 .PP
 248 .Vb 1
 249 \&    makehistory \-b \-f history.n \-O \-l 30000 \-I
 250 .Ve
 251 .PP
 252 This will rebuild the overview (if using \f(CW\*(C`buffindexed\*(C'\fR, erase the
 253 existing overview buffers before running this command) and leave a new
 254 history file as \f(CW\*(C`history.n\*(C'\fR in \fIpathdb\fR.  To preserve all of the history
 255 entries from the old history file that correspond to rejected articles or
 256 expired articles, follow the above command with:
 257 .PP
 258 .Vb 2
 259 \&    cd /usr/local/news/db
 260 \&    awk 'NF == 2 { print }' < history >> history.n
 261 .Ve
 262 .PP
 263 (replacing the path with your \fIpathdb\fR, if it isn't the default).  Then
 264 look over the new history file for problems and run:
 265 .PP
 266 .Vb 1
 267 \&    makedbz \-s `wc \-l < history` \-f history.n
 268 .Ve
 269 .PP
 270 Then rename all of the files matching \f(CW\*(C`history.n.*\*(C'\fR to \f(CW\*(C`history.*\*(C'\fR,
 271 replacing the current history database and indexes.  After that, it's safe
 272 to unthrottle innd.
 273 .PP
 274 For a simpler example:
 275 .PP
 276 .Vb 1
 277 \&    makehistory \-b \-f history.n \-I \-O
 278 .Ve
 279 .PP
 280 will scan the spool, removing broken articles and generating history and
 281 overview entries for articles missing from history.
 282 .PP
 283 To just rebuild overview:
 284 .PP
 285 .Vb 1
 286 \&    makehistory \-O \-x \-F
 287 .Ve
 288 .SH "FILES"
 289 .IX Header "FILES"
 290 .IP "inn.conf" 4
 291 .IX Item "inn.conf"
 292 Read for \fIpathdb\fR, \fIpathtmp\fR, and other settings.
 293 .IP "\fIpathdb\fR/history" 4
 294 .IX Item "pathdb/history"
 295 This is the default output file for \fBmakehistory\fR.
 296 .IP "\fIpathtmp\fR" 4
 297 .IX Item "pathtmp"
 298 Where temporary files are written unless \fB\-T\fR is given.
 299 .SH "HISTORY"
 300 .IX Header "HISTORY"
 301 Originally written by Rich \f(CW$alz\fR <rsalz@uunet.uu.net> for InterNetNews and
 302 updated by various other people since.
 303 .PP
 304 $Id: makehistory.8 7880 2008-06-16 20:37:13Z iulius $
 305 .SH "SEE ALSO"
 306 .IX Header "SEE ALSO"
 307 \&\fIdbz\fR\|(3), \fIactive\fR\|(5), \fIhistory\fR\|(5), \fIinn.conf\fR\|(5), \fIctlinnd\fR\|(8), \fIinnd\fR\|(8),
 308 \&\fImakedbz\fR\|(8), \fIovdb_init\fR\|(8), \fIoverview.fmt\fR\|(5).