chiark / gitweb /
debugging for thing that crashed
[innduct.git] / doc / pod / pullnews.pod
1 =head1 NAME
2
3 pullnews - Pull news from multiple news servers and feed it to another
4
5 =head1 SYNOPSIS
6
7 B<pullnews> [B<-hnqRx>] [B<-b> I<fraction>] [B<-c> I<config>] [B<-C> I<width>]
8 [B<-d> I<level>] [B<-f> I<fraction>] [B<-F> I<fakehop>] [B<-g> I<groups>]
9 [B<-G> I<newsgroups>] [B<-H> I<headers>] [B<-k> I<checkpt>] [B<-l> I<logfile>]
10 [B<-m> I<header_pats>] [B<-M> I<num>] [B<-N> I<timeout>] [B<-p> I<port>]
11 [B<-P> I<hop_limit>] [B<-Q> I<level>] [B<-r> I<file>] [B<-s> I<to-server>[:I<port>]]
12 [B<-S> I<max-run>] [B<-t> I<retries>] [B<-T> I<connect-pause>] [B<-w> I<num>]
13 [B<-z> I<article-pause>] [B<-Z> I<group-pause>] [I<from-server> ...]
14
15 =head1 REQUIREMENTS
16
17 The C<Net::NNTP> module must be installed.  This module is available as part
18 of the libnet distribution and comes with recent versions of Perl.  For
19 older versions of Perl, you can download it from L<http://www.cpan.org/>.
20
21 =head1 DESCRIPTION
22
23 B<pullnews> reads a config file in the running user's home directory
24 (normally called F<~/.pullnews>) and connects to the upstream servers
25 given there as a reader client.  By default, it connects to all servers
26 listed in the configuration file, but you can limit B<pullnews> to
27 specific servers by listing them on the command line:  a whitespace-separated
28 list of server names can be specified, like I<from-server> for one of them.
29 For each server it connects to, it pulls over articles and feeds them to the
30 destination server via the IHAVE or POST commands.  This means that the system
31 B<pullnews> is run on must have feeding access to the destination news server.
32
33 B<pullnews> is designed for very small sites that do not want to bother
34 setting up traditional peering and is not meant for handling large feeds.
35
36 =head1 OPTIONS
37
38 =over 4
39
40 =item B<-b> I<fraction>
41
42 Backtrack on server numbering reset.  Specify the proportion (C<0.0> to C<1.0>)
43 of a group's articles to pull when the server's article number is less than
44 our high for that group.  When I<fraction> is C<1.0>, pull all the articles on
45 a renumbered server.  The default is to do nothing.
46
47 =item B<-c> I<config>
48
49 Normally, the config file is stored in F<~/.pullnews> for the user running
50 B<pullnews>.  If B<-c> is given, I<config> will be used as the config file
51 instead.  This is useful if you're running B<pullnews> as a system user on
52 an automated basis out of cron rather than as an individual user.
53
54 See L<CONFIG FILE> below for the format of this file.
55
56 =item B<-C> I<width>
57
58 Use I<width> characters per line for the progress table.  The default value
59 is C<50>.
60
61 =item B<-d> I<level>
62
63 Set the debugging level to the integer I<level>; more debugging output
64 will be logged as this increases.  The default value is C<0>.
65
66 =item B<-f> I<fraction>
67
68 This changes the proportion of articles to get from each group to
69 I<fraction> and should be in the range C<0.0> to C<1.0> (C<1.0> being
70 the default).
71
72 =item B<-F> I<fakehop>
73
74 Prepend I<fakehop> as a host to the Path: header of articles fed.
75
76 =item B<-g> I<groups>
77
78 Specify a collection of groups to get.  I<groups> is a list of
79 newsgroups separated by commas (only commas, no spaces).  Each group must
80 be defined in the config file, and only the remote hosts that carry those
81 groups will be contacted.  Note that this is a simple list of groups, not
82 a wildmat expression, and wildcards are not supported.
83
84 =item B<-G> I<newsgroups>
85
86 Add the comma-separated list of groups I<newsgroups> to each server in the
87 configuration file (see also B<-g> and B<-w>).
88
89 =item B<-h>
90
91 Print a usage message and exit.
92
93 =item B<-H> I<headers>
94
95 Remove these named headers (colon-separated list) from fed articles.
96
97 =item B<-k> I<checkpt>
98
99 Checkpoint (save) the config file every I<checkpt> articles
100 (default is C<0>, that is to say at the end of the session).
101
102 =item B<-l> I<logfile>
103
104 Log progress/stats to I<logfile> (default is C<stdout>).
105
106 =item B<-m> I<header_pats>
107
108 Feed an article based on header matching.  The argument is a number of
109 whitespace-separated tuples (each tuple being a colon-separated header and
110 regular expression).  For instance:
111
112     Hdr1:regexp1 !Hdr2:regexp2
113
114 specifies that the article will be passed only if the C<Hdr1:> header
115 matches C<regexp1> and the C<Hdr2:> header does not match C<regexp2>.
116
117 =item B<-M> I<num>
118
119 Specify the maximum number of articles (per group) to process.
120 The default is to process all new articles.  See also B<-f>.
121
122 =item B<-n>
123
124 Do nothing but read articles S<-- does> not feed articles downstream,
125 writes no B<rnews> file, does not update the config file.
126
127 =item B<-N> I<timeout>
128
129 Specify the timeout length, as I<timeout> seconds,
130 when establishing an NNTP connection.
131
132 =item B<-p> I<port>
133
134 Connect to the destination news server on a port other than the default of
135 C<119>.  This option does not change the port used to connect to the source
136 news servers.
137
138 =item B<-P> I<hop_limit>
139
140 Restrict feeding an article based on the number of hops it has already made.
141 Count the hops in the Path: header (I<hop_count>), feeding the article only
142 when I<hop_limit> is C<+num> and I<hop_count> is more than I<num>;
143 or I<hop_limit> is C<-num> and I<hop_count> is less than I<num>.
144
145 =item B<-q>
146
147 Print out less status information while running.
148
149 =item B<-Q> I<level>
150
151 Set the quietness level (C<-Q 2> is equivalent to C<-q>).  The higher this
152 value, the less gets logged.  The default is C<0>.
153
154 =item B<-r> I<file>
155
156 Rather than feeding the downloaded articles to a destination server, instead
157 create a batch file that can later be fed to a server using B<rnews>.  See
158 rnews(1) for more information about the batch file format.
159
160 =item B<-R>
161
162 Be a reader (use MODE READER and POST commands) to the downstream
163 server.  The default is to use the IHAVE command.
164
165 =item B<-s> I<to-server>[:I<port>]
166
167 Normally, B<pullnews> will feed the articles it retrieves to the news
168 server running on localhost.  To connect to a different host, specify a
169 server with the B<-s> flag.  You can also specify the port with this same
170 flag or use B<-p>.
171
172 =item B<-S> I<max-run>
173
174 Specify the maximum time I<max-run> in seconds for B<pullnews> to run.
175
176 =item B<-t> I<retries>
177
178 The maximum number (I<retries>) of attempts to connect to a server
179 (see also B<-T>).  The default is C<0>.
180
181 =item B<-T> I<connect-pause>
182
183 Pause I<connect-pause> seconds between connection retries (see also B<-t>).
184 The default is C<1>.
185
186 =item B<-w> I<num>
187
188 Set each group's high watermark (last received article number) to I<num>.
189 If I<num> is negative, calculate S<I<Current>+I<num>> instead (i.e. get the last
190 I<num> articles).  Therefore, a I<num> of C<0> will re-get all articles on the
191 server; whereas a I<num> of C<-0> will get no old articles, setting the
192 watermark to I<Current> (the most recent article on the server).
193
194 =item B<-x>
195
196 If the B<-x> flag is used, an Xref: header is added to any article
197 that lacks one.  It can be useful for instance if articles are fed
198 to a news server which has I<xrefslave> set in F<inn.conf>.
199
200 =item B<-z> I<article-pause>
201
202 Sleep I<article-pause> seconds between articles.  The default is C<0>.
203
204 =item B<-Z> I<group-pause>
205
206 Sleep I<group-pause> seconds between groups.  The default is C<0>.
207
208 =back
209
210 =head1 CONFIG FILE
211
212 The config file for B<pullnews> is divided into blocks, one block for each
213 remote server to connect to.  A block begins with the host line, which
214 must have no leading whitespace and contains just the hostname of the
215 remote server, optionally followed by authentication details (username
216 and password for that server).
217
218 Following the host line should be one or more newsgroup lines which start
219 with whitespace followed by the name of a newsgroup to retrieve.  Only one
220 newsgroup should be listed on each line.
221
222 B<pullnews> will update the config file to include the time the group was
223 last checked and the highest numbered article successfully retrieved and
224 transferred to the destination server.  It uses this data to avoid doing
225 duplicate work the next time it runs.
226
227 The full syntax is:
228
229     <host> [<username> <password>]
230             <group> [<time> <high>]
231             <group> [<time> <high>]
232
233 where the <host> line must not have leading whitespace and the <group>
234 lines must.
235
236 A typical configuration file would be:
237
238     # Format group date high
239     data.pa.vix.com
240             rec.bicycles.racing 908086612 783
241             rec.humor.funny 908086613 18
242             comp.programming.threads
243     nnrp.vix.com pull sekret
244             comp.std.lisp
245
246 Note that an earlier run of B<pullnews> has filled in details about the
247 last article downloads from the two rec.* groups.  The two comp.* groups
248 were just added by the user and have not yet been checked.
249
250 The nnrp.vix.com server requires authentication, and B<pullnews> will use
251 the username C<pull> and the password C<sekret>.
252
253 =head1 FILES
254
255 =over 4
256
257 =item I<pathbin>/pullnews
258
259 The Perl script itself used to pull news from upstream servers and feed
260 it to another news server.
261
262 =item I<$HOME>/.pullnews
263
264 The default config file.  It is in the running user's home directory
265 (normally called F<~/.pullnews>).
266
267 =back
268
269 =head1 HISTORY
270
271 B<pullnews> was written by James Brister for INN.  The documentation was
272 rewritten in POD by Russ Allbery <rra@stanford.edu>.
273
274 Geraint A. Edwards greatly improved B<pullnews>, adding no more than S<16 new>
275 recognized flags, fixing some bugs and integrating the B<backupfeed>
276 contrib script by Kai Henningsen, adding again S<6 other> flags.
277
278 $Id: pullnews.pod 7853 2008-05-27 19:07:45Z iulius $
279
280 =head1 SEE ALSO
281
282 incoming.conf(5), rnews(1).
283
284 =cut