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).