doc/man/tdx-util.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 "TDX-UTIL 8"
 132 .TH TDX-UTIL 8 "2008-04-06" "INN 2.4.5" "InterNetNews Documentation"
 133 .SH "NAME"
 134 tdx\-util \- Tradindexed overview manipulation utility
 135 .SH "SYNOPSIS"
 136 .IX Header "SYNOPSIS"
 137 \&\fBtdx-util\fR [\fB\-AFgio\fR] [\fB\-a\fR \fIarticle\fR] [\fB\-n\fR \fInewsgroup\fR]
 138 [\fB\-p\fR \fIpath\fR] [\fB\-R\fR \fIpath\fR]
 139 .SH "DESCRIPTION"
 140 .IX Header "DESCRIPTION"
 141 \&\fBtdx-util\fR is an administrative interface to the tradindexed overview
 142 method for \s-1INN\s0.  It only works on tradindexed overview databases, not on
 143 any other type of \s-1INN\s0 overview.  It allows the administrator to dump
 144 various information about the internal state of the overview, audit it for
 145 errors, and rebuild portions of the overview database.
 146 .PP
 147 The tradindexed overview method should lock properly and therefore it
 148 should be safe to run this utility and perform any operation it performs,
 149 including full repairs or per-group overview rebuilds, while the server is
 150 running.  However, note that some of the operations performed by this
 151 utility can take an extended period of time and will hold locks in the
 152 overview database during that period, which depending on what the server
 153 is doing may cause the server to stall until \fBtdx-util\fR completes its
 154 operation.
 155 .PP
 156 The dump operations are \fB\-i\fR, which dumps the master index for the
 157 overview database, \fB\-g\fR, which dumps the index for an individual group,
 158 and \fB\-o\fR, which dumps the overview information for a particular group
 159 (including the additional metadata stored in the index).  For \fB\-g\fR and
 160 \&\fB\-o\fR, the \fB\-n\fR option must also be given to specify a newsgroup to
 161 operate on.
 162 .PP
 163 To audit the entire overview database for problems, use \fB\-A\fR.  Any
 164 problems found will be reported to standard error.  There is not (yet) a
 165 corresponding option to correct the errors found.
 166 .PP
 167 To rebuild the database for a particular newsgroup, use \fB\-R\fR.  The \fB\-R\fR
 168 option takes a path to a directory which contains all of the articles for
 169 that newsgroup, one per file.  The names of the files must be the numbers
 170 of the articles in that group.  (In other words, this directory must be a
 171 traditional spool directory for that group.)  The \fB\-n\fR option must also
 172 be given to specify the newsgroup for which the overview is being rebuilt.
 173 .PP
 174 For all operations performed by \fBtdx-util\fR, a different overview database
 175 than the one specified in \fIinn.conf\fR may be specified using the \fB\-p\fR
 176 option.
 177 .SH "OPTIONS"
 178 .IX Header "OPTIONS"
 179 .IP "\fB\-A\fR" 4
 180 .IX Item "-A"
 181 Audit the entire overview database for problems.  This runs the internal
 182 consistency checks built into the tradindexed overview implementation,
 183 checking such things as the validity and reachability of all group index
 184 entries, the format of the individual overview entries, the correspondance
 185 of index entries to overview data, and similar such things.  No changes
 186 will be made to the database, but problems will be reported to standard
 187 error.
 188 .IP "\fB\-a\fR \fIarticle\fR" 4
 189 .IX Item "-a article"
 190 The article number to act on.  Only useful in combination with the \fB\-o\fR
 191 option to dump overview information.
 192 .IP "\fB\-F\fR" 4
 193 .IX Item "-F"
 194 Audit the entire overview database for problems, fixing them as they're
 195 detected where possible. This runs the internal consistency checks built
 196 into the tradindexed overview implementation, checking such things as the
 197 validity and reachability of all group index entries, the format of the
 198 individual overview entries, the correspondance of index entries to
 199 overview data, and similar such things.  The strategy used when fixing
 200 problems is to throw away data that's unrecoverable, so be warned that
 201 using this option may result in inaccessible articles if their overview
 202 data has been corrupted.
 203 .Sp
 204 To see what would be changed by \fB\-F\fR, run \fBtdx-util\fR with \fB\-A\fR first.
 205 .IP "\fB\-g\fR" 4
 206 .IX Item "-g"
 207 Dump the master index of the overview database.  This contains similar
 208 information to the server active file, such as high and low water marks
 209 and moderation status, and is the information that nnrpd hands out to
 210 clients.
 211 .Sp
 212 The fields are, in order, the newsgroup name, the high water mark, the low
 213 water mark, the base article number (the point at which the group index
 214 begins), the count of articles in the group, the group status flag, the
 215 time (in seconds since epoch) when that newsgroup was deleted or 0 if it
 216 hasn't been, and the inode of the index file for that group.
 217 .IP "\fB\-i\fR" 4
 218 .IX Item "-i"
 219 Dump the index of a particular group.  The fields are, in order, the
 220 article number, the offset of the data for that article in the overview
 221 data file for that group, the length of the overview data, the time (in
 222 seconds since epoch) when the article arrived on the server, the time (in
 223 seconds since epoch) when the article should expire based on its Expires
 224 header (or 0 if there is no Expires header), and the storage \s-1API\s0 token of
 225 the article.
 226 .Sp
 227 If this option is given, the \fB\-n\fR option must also be given to specify
 228 the newsgroup on which to act.
 229 .IP "\fB\-n\fR \fInewsgroup\fR" 4
 230 .IX Item "-n newsgroup"
 231 Specify the newsgroup on which to act, required for the \fB\-i\fR, \fB\-o\fR, and
 232 \&\fB\-R\fR options.
 233 .IP "\fB\-o\fR" 4
 234 .IX Item "-o"
 235 Dump the overview information for a newsgroup, in the same format as it
 236 would be returned to clients but with one modification.  Appended to the
 237 end of each entry will be four additional pieces of data:  the article
 238 number according to the index file for that group, the storage \s-1API\s0 token
 239 for that article, the arrival date for that article on the server in \s-1RFC\s0
 240 822 date format, and the expiration date for that article (from the
 241 Expires header) in \s-1RFC\s0 822 date format if there is any.
 242 .Sp
 243 If this option is given, the \fB\-n\fR option must also be given to specify
 244 the newsgroup on which to act.  By default, all of the overview
 245 information for that newsgroup is dumped, but the \fB\-a\fR option may be
 246 given to restrict the dump to the information for a single article.
 247 .IP "\fB\-p\fR \fIpath\fR" 4
 248 .IX Item "-p path"
 249 Act on the overview database rooted in \fIpath\fR, overriding the overview
 250 path specified in \fIinn.conf\fR.
 251 .IP "\fB\-R\fR \fIpath\fR" 4
 252 .IX Item "-R path"
 253 Rebuild the overview for a given group from the articles stored in
 254 \&\fIpath\fR.  The articles must be in the form of a traditional spool
 255 directory; in other words, each article must be in a separate file and the
 256 name of the file must match the article number of the article.
 257 .Sp
 258 If this option is given, the \fB\-n\fR option must also be given to specify
 259 the newsgroup on which to act.
 260 .SH "EXAMPLES"
 261 .IX Header "EXAMPLES"
 262 Dump the master index for the overview database in \fI/news/overview\fR,
 263 regardless of the overview path specified in \fIinn.conf\fR:
 264 .PP
 265 .Vb 1
 266 \&    tdx\-util \-i \-p /news/overview
 267 .Ve
 268 .PP
 269 Dump the group index for example.test:
 270 .PP
 271 .Vb 1
 272 \&    tdx\-util \-g \-n example.test
 273 .Ve
 274 .PP
 275 Dump the complete overview information for example.test:
 276 .PP
 277 .Vb 1
 278 \&    tdx\-util \-o \-n example.test
 279 .Ve
 280 .PP
 281 Audit the entire overview database for any problems:
 282 .PP
 283 .Vb 1
 284 \&    tdx\-util \-A
 285 .Ve
 286 .PP
 287 Rebuild the overview information for example.test from a traditional spool
 288 directory:
 289 .PP
 290 .Vb 1
 291 \&    tdx\-util \-R /news/spool/articles/example/test \-n example.test
 292 .Ve
 293 .PP
 294 The last command may be useful for recovering from a bad crash or
 295 corrupted overview information for a particular group, if you are also
 296 using the tradspool article storage method.
 297 .SH "HISTORY"
 298 .IX Header "HISTORY"
 299 Written by Russ Allbery <rra@stanford.edu> for InterNetNews.
 300 .PP
 301 $Id: tdx-util.8 7880 2008-06-16 20:37:13Z iulius $
 302 .SH "SEE ALSO"
 303 .IX Header "SEE ALSO"
 304 \&\fImakehistory\fR\|(8)