1TDX-UTIL(8)               InterNetNews Documentation               TDX-UTIL(8)
2
3
4

NAME

6       tdx-util - Tradindexed overview manipulation utility
7

SYNOPSIS

9       tdx-util [-AFcgiOo] [-a article] [-f status] [-n newsgroup] [-p path]
10       [-R path]
11

DESCRIPTION

13       tdx-util is an administrative interface to the tradindexed overview
14       method for INN.  It only works on tradindexed overview databases, not
15       on any other type of INN overview.  It allows the administrator to dump
16       various information about the internal state of the overview, audit it
17       for errors, and rebuild portions of the overview database.
18
19       The tradindexed overview method should lock properly and therefore it
20       should be safe to run this utility and perform any operation it
21       performs, including full repairs or per-group overview rebuilds, while
22       the server is running.  However, note that some of the operations
23       performed by this utility can take an extended period of time and will
24       hold locks in the overview database during that period, which depending
25       on what the server is doing may cause the server to stall until tdx-
26       util completes its operation.
27
28       The dump operations are -i, which dumps the master index for the
29       overview database, -g, which dumps the index for an individual group,
30       and -o and -O, which dump the overview information for a particular
31       group (including the additional metadata stored in the index) in two
32       different formats.  For -g, -o, and -O, the -n option must also be
33       given to specify a newsgroup to operate on.
34
35       To add a new newsgroup to the overview database, use -c.  A group must
36       be specified with -n.  If the group status is something other than "y",
37       it should be specified with -f, and the low and high article numbers
38       may be specified with -a.  If only one number is given rather than a
39       range, it will be taken to be the high water mark and the low mark will
40       be set to 1.
41
42       To audit the entire overview database for problems, use -A.  Any
43       problems found will be reported to standard error.  Use -F to correct
44       the errors found.
45
46       To rebuild the database for a particular newsgroup, use -R.  The -R
47       option takes a path to a directory which contains all of the articles
48       for that newsgroup, one per file.  The names of the files must be the
49       numbers of the articles in that group.  (In other words, this directory
50       must be a traditional spool directory for that group.)  The -n option
51       must also be given to specify the newsgroup for which the overview is
52       being rebuilt.
53
54       For all operations performed by tdx-util, a different overview database
55       than the one specified in inn.conf may be specified using the -p
56       option.
57

OPTIONS

59       -A  Audit the entire overview database for problems.  This runs the
60           internal consistency checks built into the tradindexed overview
61           implementation, checking such things as the validity and
62           reachability of all group index entries, the format of the
63           individual overview entries, the correspondence of index entries to
64           overview data, and similar such things.  No changes will be made to
65           the database, but problems will be reported to standard error.
66
67       -a article
68           The article number or numbers to act on.  article is a valid NNTP
69           range, meaning that it can be either a single article number or a
70           range of article numbers (like "1-5").  Either the start or the end
71           (or both) of the range may be omitted, in which case they will be
72           set to the first or last article number in the group.  Passing "-"
73           for article is therefore equivalent to not using the -a option at
74           all.
75
76           Only useful in combination with the -o option to dump overview
77           information or with -c to specify the low and high article numbers
78           when creating a group.
79
80       -c  Create a new group in the overview database.  The group must be
81           specified with -n.  The newsgroup status defaults to "y" but may be
82           set with -f.  The low and high article numbers default to 1 and 0
83           respectively, but may be set with -a.  If only one number is given
84           to -a, it is taken as the high article number.
85
86       -F  Audit the entire overview database for problems, fixing them as
87           they're detected where possible.  This runs the internal
88           consistency checks built into the tradindexed overview
89           implementation, checking such things as the validity and
90           reachability of all group index entries, the format of the
91           individual overview entries, the correspondence of index entries to
92           overview data, and similar such things.  The strategy used when
93           fixing problems is to throw away data that's unrecoverable, so be
94           warned that using this option may result in inaccessible articles
95           if their overview data has been corrupted.
96
97           To see what would be changed by -F, run tdx-util with -A first.
98
99       -f status
100           When creating a newsgroup with -c, set the status of the newly
101           created group to status instead of "y".  Only useful with -c.
102
103       -g  Dump the index of a particular group.  The fields are, in order,
104           the article number, the offset of the data for that article in the
105           overview data file for that group, the length of the overview data,
106           the time (in seconds since epoch) when the article arrived on the
107           server, the time (in seconds since epoch) when the article should
108           expire based on its Expires header field (or 0 if there is no
109           Expires header field), and the storage API token of the article.
110
111           If this option is given, the -n option must also be given to
112           specify the newsgroup on which to act.
113
114       -i  Dump the master index of the overview database.  This contains
115           similar information to the server active file, such as high and low
116           water marks and moderation status, and is the information that
117           nnrpd hands out to clients.
118
119           The fields are, in order, the newsgroup name, the high water mark,
120           the low water mark, the base article number (the point at which the
121           group index begins), the count of articles in the group, the group
122           status, the time (in seconds since epoch) when that newsgroup was
123           deleted or 0 if it hasn't been, and the inode of the index file for
124           that group.
125
126           A particular newsgroup can be specified with the -n option.  If -n
127           is not given, the entire master index will be dumped.
128
129       -n newsgroup
130           Specify the newsgroup on which to act, required for the -i, -o, and
131           -R options.
132
133       -O  Dump the overview information for a newsgroup in the format used by
134           overchan as input.  Each line will start with the storage API
135           token, the arrival timestamp in seconds since epoch, the expires
136           timestamp in the same format (or 0 if there is no Expires header
137           field), and then the overview data.
138
139           If this option is given, the -n option must also be given to
140           specify the newsgroup on which to act.  By default, all of the
141           overview information for that newsgroup is dumped, but the -a
142           option may be given to restrict the dump to the information for a
143           single article.
144
145       -o  Dump the overview information for a newsgroup, in the same format
146           as it would be returned to clients but with one modification.
147           Appended to the end of each entry will be four additional pieces of
148           data: the article number according to the index file for that group
149           labelled with "Article:", the storage API token for that article
150           labelled with "Token:", the arrival date for that article on the
151           server in RFC 5322 date format labelled with "Arrived:", and the
152           expiration date for that article (from the Expires header field) in
153           RFC 5322 date format if there is any, labelled with "Expires:".
154
155           If this option is given, the -n option must also be given to
156           specify the newsgroup on which to act.  By default, all of the
157           overview information for that newsgroup is dumped, but the -a
158           option may be given to restrict the dump to the information for a
159           single article.
160
161       -p path
162           Act on the overview database rooted in path, overriding the
163           overview path specified in inn.conf.
164
165       -R path
166           Rebuild the overview for a given group from the articles stored in
167           path.  The articles must be in the form of a traditional spool
168           directory; in other words, each article must be in a separate file
169           and the name of the file must match the article number of the
170           article.
171
172           If this option is given, the -n option must also be given to
173           specify the newsgroup on which to act.
174

EXAMPLES

176       Dump the master index for the overview database in /news/overview,
177       regardless of the overview path specified in inn.conf:
178
179           tdx-util -i -p /news/overview
180
181       Dump the group index for example.test:
182
183           tdx-util -g -n example.test
184
185       Dump the complete overview information for example.test:
186
187           tdx-util -o -n example.test
188
189       Dump the overview information for articles 45 and higher in
190       example.test:
191
192           tdx-util -o -n example.test -a 45-
193
194       Create an entry for example.test with mode m and low and high article
195       numbers of 4 and 23, respectively.
196
197           tdx-util -c -n example.test -f m -a 4-23
198
199       Audit the entire overview database for any problems:
200
201           tdx-util -A
202
203       Rebuild the overview information for example.test from a traditional
204       spool directory:
205
206           tdx-util -R <patharticles in inn.conf>/example/test -n example.test
207
208       The last command may be useful for recovering from a bad crash or
209       corrupted overview information for a particular group, if you are also
210       using the tradspool article storage method.
211

HISTORY

213       Written by Russ Allbery <eagle@eyrie.org> for InterNetNews.
214

SEE ALSO

216       makehistory(8), nnrpd(8).
217
218
219
220INN 2.7.0                         2022-07-10                       TDX-UTIL(8)
Impressum