Debian Codegraph @

upstream/debian-unstable/man1/rpost.1

raw
1 .\" $Revision: 3.10.2 $
2 .TH RPOST 1
3 .SH NAME
4 rpost - post an article to an NNTP news server
5 .SH SYNOPSIS
6 .I rpost
7 [
8 .BI
9 hostname
10 ]
11 [
12 .BI @filename
13 ]
14 [
15 .BI -s\ |\ -S
16 filename
17 ]
18 [
19 .BI -e\ |\ -E
20 filename
21 ]
22 [
23 .BI -b
24 batchfile
25 ]
26 [
27 .BI -r
28 rnews_file rnews_path
29 ]
30 [
31 .BI -p
32 prefix
33 ]
34 [
35 .BI -Q
36 ]
37 [
38 .BI -d
39 ]
40 [
41 .BI \-U
42 userid
43 ]
44 [
45 .BI \-P
46 password
47 ]
48 [
49 .BI \-M
50 ]
51 [
52 .BI \-N
53 port_number
54 ]
55 [
56 .BI \-l
57 phrase_file
58 ]
59 [
60 .BI \-D
61 ]
62 [
63 .BI \-T
64 timeout
65 ]
66 [
67 .BI \-u
68 ]
69 [
70 .BI \-n
71 ]
72
73 [
74 .BI -F
75 perl_file
76 ]
77 [
78 .BI -i
79 ]
80 [
81 .BI -z
82 ]
83 [
84 .BI -f
85 filter $$o=<outfile> filter_arg1 ...
86 ]
87 .SH DESCRIPTION
88 .I Rpost
89 will post one or more articles, specified by
90 .I hostname.
91 If hostname is not specified, rpost will use the environment
92 variable
93 .BI NNTPSERVER.
94 The hostname may optionally include the port number, in the form
95 .BI Host:Port
96 If this form is used, any port number specified via the -N option
97 will be ignored.
98 .SH Generic Options
99
100 .BI \@filename
101
102 This option tells rpost to read other options from a file in addition to the
103 command line.
104
105 .BI \-D
106 This option tells rpost to log various debugging messages to "debug.suck",
107 primarily for use by the developer.
108
109 .BI \-e | \-E
110 filename
111
112 These options will send all error messages (normally displayed on stderr), to
113 an alternate file. The lower case version, -e, will send the error messages
114 to the compiled-in default defined in suck_config.h. The default is suck.errlog.
115 The upper case version, -E, requires the filename parameter. All error messages
116 will then be sent to this file.
117
118 .BI \-i
119
120 This option tells rpost to ignore the 201 (no posting allowed) from the welcoming
121 message and to try and post anyway. Some news servers (inn-2.3.1) send 201
122 no posting allowed when they are using the AUTHINFO commands to verify permission
123 to post.
124
125 .BI \-l
126 phrase_file
127
128 This option tells rpost to load in an alternate phrase file, instead of using
129 the built-in messages. This allows you to have rpost print phrases in another
130 language, or to allow you to customize the messages without re-building.
131 See the "FOREIGN LANGUAGE PHRASES" in suck.1 for more details.
132
133 .BI \-M
134
135 This option tells rpost to send the "mode reader" command to the remote
136 server. If you get an invalid command message from rpost immediately
137 after the welcome announcement, then try this option.
138
139 .BI \-n
140
141 This option tells rpost to show the name of the file as it is being
142 uploaded.
143
144 .BI \-N
145 port_number
146
147 This option tells rpost to use an alternate NNRP port number when connecting
148 to the host, instead of the default port number, 119.
149
150 .BI \-s | \-S
151 filename
152
153 These options will send all status messages (normally displayed on stdout), to
154 an alternate file. The lower case version, -s, will send the status messages
155 to the compiled-in default defined in suck_config.h. The default is /dev/null,
156 so no status messages will be displayed. The upper case version, -S, requires
157 the filename parameter. All status messages will then be sent to this file.
158
159 .BI \-T
160 This option overrides the compiled-in TIMEOUT value. This is how long rpost waits for data
161 from the remote host before timing out and aborting.
162
163 .BI \-u
164 This option tells rpost to send the AUTHINFO USER command immediately upon connect to the
165 remote server, rather than wait for a request for authorization. You must supply the
166 \-U and \-P options when you use this option.
167
168 .BI \-U
169 userid
170 .BI \-P
171 password
172
173 These two options let you specify a userid and password, if your NNTP server
174 requires them.
175
176 .BI \-Q
177
178 This option allows you to specify the userid and password via the environment variables
179 "NNTP_USER" and "NNTP_PASS" instead of on the command line. This prevents a potential
180 security issue where someone doing a ps command can see your login and password.
181
182 .BI \-z
183 This option tells rpost to use SSL to communicate with the remote hosts, if SSL was
184 compiled into rpost.
185
186 .SH STDIN MODE
187 rpost
188
189 rpost hostname
190
191 rpost reads one article from stdin and sends it to the
192 NNTP server. The article must have a header of at least two lines, namely
193 Newsgroups: and Subject: and a body (the article). Header and body
194 have to be separated by a newline. Rpost does not change the article
195 in any way.
196
197 Rpost uses the POST command to post your article, just like any standard
198 newsreader. This is handy when using SLIP and PPP, since most providers
199 do not allow any other method to post articles (such as nntpsend or innxmit).
200 .SH BATCH MODE
201
202 .I rpost
203 .BI
204 hostname
205 .BI -b
206 batchfile
207 .BI -p
208 prefix
209 .BI -d
210
211 This batch mode allows you to give rpost a list of articles, and have
212 them all posted.
213
214 -b batchfile
215
216 A listing of the articles to be posted. This parameter is REQUIRED.
217 This file contains one article per line, with
218 the line being the path to the file containing the article. For
219 example:
220
221 .RS
222 -b /usr/spool/news/out.going/pixi
223 .RE
224
225 IF there are any problems uploading a specific article, a "failed" file
226 will be created. It will be called "batchfile".fail, and contain the
227 line from this batchfile for the article(s) that did not successfully upload.
228 This file can be used to re-run the failed messages through rpost. NOTE:
229 duplicate articles are NOT considered an error for the fail file.
230
231 -d
232
233 If the upload of articles is successful, this option will cause rpost to
234 delete the batchfile named in the -b option.
235
236 -p prefix
237
238 If the batchfile does not contain a full path, but rather
239 a partial path, this parameter must be specified. This is useful
240 when the batch file is generated by another program.
241 For example, Inn lists the path in the out.going file relative
242 to its base directory /usr/spool/news. In that case just use:
243
244 .RS
245 -p /usr/spool/news
246 .RE
247
248 .SH RNEWS MODE
249 .I rpost
250 .BI
251 hostname
252 .BI -r
253 rnews_file
254 rnews_path
255
256 This option allows you to use rnews generated file(s) to post. It requires
257 two parameters.
258
259 rnews_file - this is the base name for the rnews files. If you have your
260 rnews file(s) called batch1, batch2, etc., then this argument would be
261 "batch".
262
263 rnews_path - this is the path to the location of the rnews files.
264 .RS
265 -r batch /usr/tmp/rnews
266 .RE
267
268 -d
269
270 If the upload of all the articles from any of the rnews files is
271 successful, then this option will cause rpost to delete that
272 particular rnews file.
273
274 .SH FILTER MODES
275 -f filter $$o=<outfile> filter_arg1 filter_arg2 ...
276
277 In many cases, each article must be massaged before the
278 remote NNTP will accept it. This option, and the embedded
279 perl filter option below, lets you do that. These filters do not
280 work in STDIN mode, but in the batch and rnews modes from above.
281 Note that the -f .... option must be the LAST option, as
282 everything that follows it is passed to the filter, except
283 as noted below.
284 There are three required parameters with this:
285
286 $$o=<outfile> - <outfile> is the name of the file produced by
287 your filter that will get uploaded to the remote NNTP server.
288 THIS IS NOT passed to your filter program. This can be specified
289 anywhere on the command line AFTER the -f filter argument, either before
290 the filter name, or after it.
291
292 filter - name of the program to call. Whatever follows filter, EXCEPT
293 for the $$o, are arguments passed to the filter.
294
295 arg1 - The first argument to your filter program/script. It most
296 likely will be $$i, which rpost fills in with the name of the article
297 that needs to be cleaned up.
298
299 arg2 ... - any additional args needed can be specified.
300
301 .PP
302 Let's clarify this a bit with an example. Some NNTP servers don't
303 like to receive articles with the NNTP-Posting-Host filled in.
304 Create a short shell script to delete this from a file:
305
306 \-myscr--------------------------------------------
307
308 #!/bin/sh
309
310 sed -e "/^NNTP-Posting-Host/d" $1 > $2
311
312 \-end myscr----------------------------------------
313 .PP
314 Then call rpost like this:
315 .RS
316 rpost localhost -b /usr/spool/news/out.going/pixi -f myscr \\$\\$o=/tmp/FILTERED_MSG \\$\\$i /tmp/FILTERED_MSG
317 .RE
318
319 Then, before each article is uploaded, myscr is called like such:
320 .RS
321 myscr infilename /tmp/FILTERED_MSG
322 .RE
323
324 After myscr has finished, rpost uploads the cleaned up article,
325 stored in /tmp/FILTERED_MSG, to the remote NNTP server.
326 .SH NOTE:
327 The $$o and $$i have to be escaped, using either the backslashes
328 as above, or with single quotes, to prevent the shell from
329 trying to interpret these as variables. Failure to escape them will result
330 in rpost not working!
331
332 .BI -F
333 perlfilter
334 .PP
335 This option allows you to use an embedded perl filter to filter your articles.
336 In order to use this, you must edit the Makefile, and define the various
337 PERL_ options.
338 It has a couple of advantages over the -f option above. Because it is
339 embedded perl, there are no forks and execls() done, so it should be faster.
340 Also, you don't need to worry about the arguments to the program and
341 escaping $$, etc as above.
342 .PP
343 Rpost will, when it starts up, load in the perlfilter file designated and parse
344 it for syntax errors. Then, for each article to be uploaded, rpost will call the
345 subroutine "perl_rpost", contained in the perlfilter file. See sample/put.news.pl
346 for a complete working example. There are
347 three key points you need to be aware of when creating your filter.
348
349 .RS
350 1. The perlfilter file must contain the line "package Embed::Persistant;", so
351 that variables in the perlfilter file don't clash with rpost variables, and
352 the subroutine must be called "perl_rpost". This can be changed by editting
353 the PERL_RPOST_SUB define in suck_config.h.
354 .RE
355
356 .RS
357 2. The perl_rpost subroutine receives the input file name as its sole argument,
358 and must return the full path to the location of the
359 filtered article as a single scalar string (return $outfile).
360 .RE
361
362 .RS
363 3. The subroutine must explicitly close the output file (containing the filtered
364 argument) before it returns. This is because perl will only do an automatic
365 close upon program completion (in our case when rpost exits), or when the
366 file handle is reused (the next time the subroutine is called). If the
367 close is not done, then more than likely, a 0 byte file will exist when
368 rpost tries to post the article, and errors will result.
369
370 .SH WARNING:
371
372 Be very careful with what the filter program deletes from the article. Deleting
373 the wrong line can have bad effects later on. For example, do not delete the
374 MSG-ID line, as this could cause a single message to be posted many times, depending
375 on the configuration of both the local and remote newserver.
376
377 .SH RPOST ARGUMENT FILE
378 .PP
379 If you specify @filename on the command line, rpost will read from filename and
380 parse it for any arguments that you wish to pass to rpost. You specify the
381 same arguments in this file as you do on the command line. The arguments
382 can be on one line, or spread out among more than one line. You may also
383 use comments. Comments begin with '#' and go to the end of a line. All
384 command line arguments override arguments in the file. One advantage to
385 using the file instead of the command line, is that you don't have to
386 escape any special characters, such as $.
387
388 .RS
389 # Sample Argument file
390 .RE
391 .RS
392 -b batch # batch file option
393 .RE
394 .RS
395 -M # use mode reader option
396 .RE
397
398 .SH EXIT VALUES
399 Rpost returns the following exit values:
400
401 .RS
402 0 = success
403 .RE
404 .RS
405 1 = error posting an article
406 .RE
407 .RS
408 2 = unable to do NNTP authorization with the remote server.
409 .RE
410 .RS
411 3 = unexpected answer to command when doing NNTP authorization.
412 .RE
413 .RS
414 -1 = other fatal error.
415 .RE
416
417 .de R$
418 This is revision \\$3, \\$4.
419 ..
420 .SH "SEE ALSO"
421 suck(1), testhost(1), lpost(1).