chiark / gitweb /
option for no inotify; manpage fix
[innduct.git] / doc / man / pullnews.1
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 "PULLNEWS 1"
132 .TH PULLNEWS 1 "2008-06-05" "INN 2.4.5" "InterNetNews Documentation"
133 .SH "NAME"
134 pullnews \- Pull news from multiple news servers and feed it to another
135 .SH "SYNOPSIS"
136 .IX Header "SYNOPSIS"
137 \&\fBpullnews\fR [\fB\-hnqRx\fR] [\fB\-b\fR \fIfraction\fR] [\fB\-c\fR \fIconfig\fR] [\fB\-C\fR \fIwidth\fR]
138 [\fB\-d\fR \fIlevel\fR] [\fB\-f\fR \fIfraction\fR] [\fB\-F\fR \fIfakehop\fR] [\fB\-g\fR \fIgroups\fR]
139 [\fB\-G\fR \fInewsgroups\fR] [\fB\-H\fR \fIheaders\fR] [\fB\-k\fR \fIcheckpt\fR] [\fB\-l\fR \fIlogfile\fR]
140 [\fB\-m\fR \fIheader_pats\fR] [\fB\-M\fR \fInum\fR] [\fB\-N\fR \fItimeout\fR] [\fB\-p\fR \fIport\fR]
141 [\fB\-P\fR \fIhop_limit\fR] [\fB\-Q\fR \fIlevel\fR] [\fB\-r\fR \fIfile\fR] [\fB\-s\fR \fIto-server\fR[:\fIport\fR]]
142 [\fB\-S\fR \fImax-run\fR] [\fB\-t\fR \fIretries\fR] [\fB\-T\fR \fIconnect-pause\fR] [\fB\-w\fR \fInum\fR]
143 [\fB\-z\fR \fIarticle-pause\fR] [\fB\-Z\fR \fIgroup-pause\fR] [\fIfrom-server\fR ...]
144 .SH "REQUIREMENTS"
145 .IX Header "REQUIREMENTS"
146 The \f(CW\*(C`Net::NNTP\*(C'\fR module must be installed.  This module is available as part
147 of the libnet distribution and comes with recent versions of Perl.  For
148 older versions of Perl, you can download it from <http://www.cpan.org/>.
149 .SH "DESCRIPTION"
150 .IX Header "DESCRIPTION"
151 \&\fBpullnews\fR reads a config file in the running user's home directory
152 (normally called \fI~/.pullnews\fR) and connects to the upstream servers
153 given there as a reader client.  By default, it connects to all servers
154 listed in the configuration file, but you can limit \fBpullnews\fR to
155 specific servers by listing them on the command line:  a whitespace-separated
156 list of server names can be specified, like \fIfrom-server\fR for one of them.
157 For each server it connects to, it pulls over articles and feeds them to the
158 destination server via the \s-1IHAVE\s0 or \s-1POST\s0 commands.  This means that the system
159 \&\fBpullnews\fR is run on must have feeding access to the destination news server.
160 .PP
161 \&\fBpullnews\fR is designed for very small sites that do not want to bother
162 setting up traditional peering and is not meant for handling large feeds.
163 .SH "OPTIONS"
164 .IX Header "OPTIONS"
165 .IP "\fB\-b\fR \fIfraction\fR" 4
166 .IX Item "-b fraction"
167 Backtrack on server numbering reset.  Specify the proportion (\f(CW0.0\fR to \f(CW1.0\fR)
168 of a group's articles to pull when the server's article number is less than
169 our high for that group.  When \fIfraction\fR is \f(CW1.0\fR, pull all the articles on
170 a renumbered server.  The default is to do nothing.
171 .IP "\fB\-c\fR \fIconfig\fR" 4
172 .IX Item "-c config"
173 Normally, the config file is stored in \fI~/.pullnews\fR for the user running
174 \&\fBpullnews\fR.  If \fB\-c\fR is given, \fIconfig\fR will be used as the config file
175 instead.  This is useful if you're running \fBpullnews\fR as a system user on
176 an automated basis out of cron rather than as an individual user.
177 .Sp
178 See \*(L"\s-1CONFIG\s0 \s-1FILE\s0\*(R" below for the format of this file.
179 .IP "\fB\-C\fR \fIwidth\fR" 4
180 .IX Item "-C width"
181 Use \fIwidth\fR characters per line for the progress table.  The default value
182 is \f(CW50\fR.
183 .IP "\fB\-d\fR \fIlevel\fR" 4
184 .IX Item "-d level"
185 Set the debugging level to the integer \fIlevel\fR; more debugging output
186 will be logged as this increases.  The default value is \f(CW0\fR.
187 .IP "\fB\-f\fR \fIfraction\fR" 4
188 .IX Item "-f fraction"
189 This changes the proportion of articles to get from each group to
190 \&\fIfraction\fR and should be in the range \f(CW0.0\fR to \f(CW1.0\fR (\f(CW1.0\fR being
191 the default).
192 .IP "\fB\-F\fR \fIfakehop\fR" 4
193 .IX Item "-F fakehop"
194 Prepend \fIfakehop\fR as a host to the Path: header of articles fed.
195 .IP "\fB\-g\fR \fIgroups\fR" 4
196 .IX Item "-g groups"
197 Specify a collection of groups to get.  \fIgroups\fR is a list of
198 newsgroups separated by commas (only commas, no spaces).  Each group must
199 be defined in the config file, and only the remote hosts that carry those
200 groups will be contacted.  Note that this is a simple list of groups, not
201 a wildmat expression, and wildcards are not supported.
202 .IP "\fB\-G\fR \fInewsgroups\fR" 4
203 .IX Item "-G newsgroups"
204 Add the comma-separated list of groups \fInewsgroups\fR to each server in the
205 configuration file (see also \fB\-g\fR and \fB\-w\fR).
206 .IP "\fB\-h\fR" 4
207 .IX Item "-h"
208 Print a usage message and exit.
209 .IP "\fB\-H\fR \fIheaders\fR" 4
210 .IX Item "-H headers"
211 Remove these named headers (colon\-separated list) from fed articles.
212 .IP "\fB\-k\fR \fIcheckpt\fR" 4
213 .IX Item "-k checkpt"
214 Checkpoint (save) the config file every \fIcheckpt\fR articles
215 (default is \f(CW0\fR, that is to say at the end of the session).
216 .IP "\fB\-l\fR \fIlogfile\fR" 4
217 .IX Item "-l logfile"
218 Log progress/stats to \fIlogfile\fR (default is \f(CW\*(C`stdout\*(C'\fR).
219 .IP "\fB\-m\fR \fIheader_pats\fR" 4
220 .IX Item "-m header_pats"
221 Feed an article based on header matching.  The argument is a number of
222 whitespace-separated tuples (each tuple being a colon-separated header and
223 regular expression).  For instance:
224 .Sp
225 .Vb 1
226 \&    Hdr1:regexp1 !Hdr2:regexp2
227 .Ve
228 .Sp
229 specifies that the article will be passed only if the \f(CW\*(C`Hdr1:\*(C'\fR header
230 matches \f(CW\*(C`regexp1\*(C'\fR and the \f(CW\*(C`Hdr2:\*(C'\fR header does not match \f(CW\*(C`regexp2\*(C'\fR.
231 .IP "\fB\-M\fR \fInum\fR" 4
232 .IX Item "-M num"
233 Specify the maximum number of articles (per group) to process.
234 The default is to process all new articles.  See also \fB\-f\fR.
235 .IP "\fB\-n\fR" 4
236 .IX Item "-n"
237 Do nothing but read articles \-\-\ does not feed articles downstream,
238 writes no \fBrnews\fR file, does not update the config file.
239 .IP "\fB\-N\fR \fItimeout\fR" 4
240 .IX Item "-N timeout"
241 Specify the timeout length, as \fItimeout\fR seconds,
242 when establishing an \s-1NNTP\s0 connection.
243 .IP "\fB\-p\fR \fIport\fR" 4
244 .IX Item "-p port"
245 Connect to the destination news server on a port other than the default of
246 \&\f(CW119\fR.  This option does not change the port used to connect to the source
247 news servers.
248 .IP "\fB\-P\fR \fIhop_limit\fR" 4
249 .IX Item "-P hop_limit"
250 Restrict feeding an article based on the number of hops it has already made.
251 Count the hops in the Path: header (\fIhop_count\fR), feeding the article only
252 when \fIhop_limit\fR is \f(CW\*(C`+num\*(C'\fR and \fIhop_count\fR is more than \fInum\fR;
253 or \fIhop_limit\fR is \f(CW\*(C`\-num\*(C'\fR and \fIhop_count\fR is less than \fInum\fR.
254 .IP "\fB\-q\fR" 4
255 .IX Item "-q"
256 Print out less status information while running.
257 .IP "\fB\-Q\fR \fIlevel\fR" 4
258 .IX Item "-Q level"
259 Set the quietness level (\f(CW\*(C`\-Q 2\*(C'\fR is equivalent to \f(CW\*(C`\-q\*(C'\fR).  The higher this
260 value, the less gets logged.  The default is \f(CW0\fR.
261 .IP "\fB\-r\fR \fIfile\fR" 4
262 .IX Item "-r file"
263 Rather than feeding the downloaded articles to a destination server, instead
264 create a batch file that can later be fed to a server using \fBrnews\fR.  See
265 \&\fIrnews\fR\|(1) for more information about the batch file format.
266 .IP "\fB\-R\fR" 4
267 .IX Item "-R"
268 Be a reader (use \s-1MODE\s0 \s-1READER\s0 and \s-1POST\s0 commands) to the downstream
269 server.  The default is to use the \s-1IHAVE\s0 command.
270 .IP "\fB\-s\fR \fIto-server\fR[:\fIport\fR]" 4
271 .IX Item "-s to-server[:port]"
272 Normally, \fBpullnews\fR will feed the articles it retrieves to the news
273 server running on localhost.  To connect to a different host, specify a
274 server with the \fB\-s\fR flag.  You can also specify the port with this same
275 flag or use \fB\-p\fR.
276 .IP "\fB\-S\fR \fImax-run\fR" 4
277 .IX Item "-S max-run"
278 Specify the maximum time \fImax-run\fR in seconds for \fBpullnews\fR to run.
279 .IP "\fB\-t\fR \fIretries\fR" 4
280 .IX Item "-t retries"
281 The maximum number (\fIretries\fR) of attempts to connect to a server
282 (see also \fB\-T\fR).  The default is \f(CW0\fR.
283 .IP "\fB\-T\fR \fIconnect-pause\fR" 4
284 .IX Item "-T connect-pause"
285 Pause \fIconnect-pause\fR seconds between connection retries (see also \fB\-t\fR).
286 The default is \f(CW1\fR.
287 .IP "\fB\-w\fR \fInum\fR" 4
288 .IX Item "-w num"
289 Set each group's high watermark (last received article number) to \fInum\fR.
290 If \fInum\fR is negative, calculate \fICurrent\fR+\fInum\fR instead (i.e. get the last
291 \&\fInum\fR articles).  Therefore, a \fInum\fR of \f(CW0\fR will re-get all articles on the
292 server; whereas a \fInum\fR of \f(CW\*(C`\-0\*(C'\fR will get no old articles, setting the
293 watermark to \fICurrent\fR (the most recent article on the server).
294 .IP "\fB\-x\fR" 4
295 .IX Item "-x"
296 If the \fB\-x\fR flag is used, an Xref: header is added to any article
297 that lacks one.  It can be useful for instance if articles are fed
298 to a news server which has \fIxrefslave\fR set in \fIinn.conf\fR.
299 .IP "\fB\-z\fR \fIarticle-pause\fR" 4
300 .IX Item "-z article-pause"
301 Sleep \fIarticle-pause\fR seconds between articles.  The default is \f(CW0\fR.
302 .IP "\fB\-Z\fR \fIgroup-pause\fR" 4
303 .IX Item "-Z group-pause"
304 Sleep \fIgroup-pause\fR seconds between groups.  The default is \f(CW0\fR.
305 .SH "CONFIG FILE"
306 .IX Header "CONFIG FILE"
307 The config file for \fBpullnews\fR is divided into blocks, one block for each
308 remote server to connect to.  A block begins with the host line, which
309 must have no leading whitespace and contains just the hostname of the
310 remote server, optionally followed by authentication details (username
311 and password for that server).
312 .PP
313 Following the host line should be one or more newsgroup lines which start
314 with whitespace followed by the name of a newsgroup to retrieve.  Only one
315 newsgroup should be listed on each line.
316 .PP
317 \&\fBpullnews\fR will update the config file to include the time the group was
318 last checked and the highest numbered article successfully retrieved and
319 transferred to the destination server.  It uses this data to avoid doing
320 duplicate work the next time it runs.
321 .PP
322 The full syntax is:
323 .PP
324 .Vb 3
325 \&    <host> [<username> <password>]
326 \&            <group> [<time> <high>]
327 \&            <group> [<time> <high>]
328 .Ve
329 .PP
330 where the <host> line must not have leading whitespace and the <group>
331 lines must.
332 .PP
333 A typical configuration file would be:
334 .PP
335 .Vb 7
336 \&    # Format group date high
337 \&    data.pa.vix.com
338 \&            rec.bicycles.racing 908086612 783
339 \&            rec.humor.funny 908086613 18
340 \&            comp.programming.threads
341 \&    nnrp.vix.com pull sekret
342 \&            comp.std.lisp
343 .Ve
344 .PP
345 Note that an earlier run of \fBpullnews\fR has filled in details about the
346 last article downloads from the two rec.* groups.  The two comp.* groups
347 were just added by the user and have not yet been checked.
348 .PP
349 The nnrp.vix.com server requires authentication, and \fBpullnews\fR will use
350 the username \f(CW\*(C`pull\*(C'\fR and the password \f(CW\*(C`sekret\*(C'\fR.
351 .SH "FILES"
352 .IX Header "FILES"
353 .IP "\fIpathbin\fR/pullnews" 4
354 .IX Item "pathbin/pullnews"
355 The Perl script itself used to pull news from upstream servers and feed
356 it to another news server.
357 .IP "\fI$HOME\fR/.pullnews" 4
358 .IX Item "$HOME/.pullnews"
359 The default config file.  It is in the running user's home directory
360 (normally called \fI~/.pullnews\fR).
361 .SH "HISTORY"
362 .IX Header "HISTORY"
363 \&\fBpullnews\fR was written by James Brister for \s-1INN\s0.  The documentation was
364 rewritten in \s-1POD\s0 by Russ Allbery <rra@stanford.edu>.
365 .PP
366 Geraint A. Edwards greatly improved \fBpullnews\fR, adding no more than 16\ new
367 recognized flags, fixing some bugs and integrating the \fBbackupfeed\fR
368 contrib script by Kai Henningsen, adding again 6\ other flags.
369 .PP
370 $Id: pullnews.pod 7853 2008\-05\-27 19:07:45Z iulius $
371 .SH "SEE ALSO"
372 .IX Header "SEE ALSO"
373 \&\fIincoming.conf\fR\|(5), \fIrnews\fR\|(1).