diff options
Diffstat (limited to 'upstream/debian-unstable/man1/rpost.1')
| -rw-r--r-- | upstream/debian-unstable/man1/rpost.1 | 421 |
1 files changed, 421 insertions, 0 deletions
diff --git a/upstream/debian-unstable/man1/rpost.1 b/upstream/debian-unstable/man1/rpost.1 new file mode 100644 index 00000000..3262b778 --- /dev/null +++ b/upstream/debian-unstable/man1/rpost.1 @@ -0,0 +1,421 @@ +.\" $Revision: 3.10.2 $ +.TH RPOST 1 +.SH NAME +rpost - post an article to an NNTP news server +.SH SYNOPSIS +.I rpost +[ +.BI +hostname +] +[ +.BI @filename +] +[ +.BI -s\ |\ -S +filename +] +[ +.BI -e\ |\ -E +filename +] +[ +.BI -b +batchfile +] +[ +.BI -r +rnews_file rnews_path +] +[ +.BI -p +prefix +] +[ +.BI -Q +] +[ +.BI -d +] +[ +.BI \-U +userid +] +[ +.BI \-P +password +] +[ +.BI \-M +] +[ +.BI \-N +port_number +] +[ +.BI \-l +phrase_file +] +[ +.BI \-D +] +[ +.BI \-T +timeout +] +[ +.BI \-u +] +[ +.BI \-n +] + +[ +.BI -F +perl_file +] +[ +.BI -i +] +[ +.BI -z +] +[ +.BI -f +filter $$o=<outfile> filter_arg1 ... +] +.SH DESCRIPTION +.I Rpost +will post one or more articles, specified by +.I hostname. +If hostname is not specified, rpost will use the environment +variable +.BI NNTPSERVER. +The hostname may optionally include the port number, in the form +.BI Host:Port +If this form is used, any port number specified via the -N option +will be ignored. +.SH Generic Options + +.BI \@filename + +This option tells rpost to read other options from a file in addition to the +command line. + +.BI \-D +This option tells rpost to log various debugging messages to "debug.suck", +primarily for use by the developer. + +.BI \-e | \-E +filename + +These options will send all error messages (normally displayed on stderr), to +an alternate file. The lower case version, -e, will send the error messages +to the compiled-in default defined in suck_config.h. The default is suck.errlog. +The upper case version, -E, requires the filename parameter. All error messages +will then be sent to this file. + +.BI \-i + +This option tells rpost to ignore the 201 (no posting allowed) from the welcoming +message and to try and post anyway. Some news servers (inn-2.3.1) send 201 +no posting allowed when they are using the AUTHINFO commands to verify permission +to post. + +.BI \-l +phrase_file + +This option tells rpost to load in an alternate phrase file, instead of using +the built-in messages. This allows you to have rpost print phrases in another +language, or to allow you to customize the messages without re-building. +See the "FOREIGN LANGUAGE PHRASES" in suck.1 for more details. + +.BI \-M + +This option tells rpost to send the "mode reader" command to the remote +server. If you get an invalid command message from rpost immediately +after the welcome announcement, then try this option. + +.BI \-n + +This option tells rpost to show the name of the file as it is being +uploaded. + +.BI \-N +port_number + +This option tells rpost to use an alternate NNRP port number when connecting +to the host, instead of the default port number, 119. + +.BI \-s | \-S +filename + +These options will send all status messages (normally displayed on stdout), to +an alternate file. The lower case version, -s, will send the status messages +to the compiled-in default defined in suck_config.h. The default is /dev/null, +so no status messages will be displayed. The upper case version, -S, requires +the filename parameter. All status messages will then be sent to this file. + +.BI \-T +This option overrides the compiled-in TIMEOUT value. This is how long rpost waits for data +from the remote host before timing out and aborting. + +.BI \-u +This option tells rpost to send the AUTHINFO USER command immediately upon connect to the +remote server, rather than wait for a request for authorization. You must supply the +\-U and \-P options when you use this option. + +.BI \-U +userid +.BI \-P +password + +These two options let you specify a userid and password, if your NNTP server +requires them. + +.BI \-Q + +This option allows you to specify the userid and password via the environment variables +"NNTP_USER" and "NNTP_PASS" instead of on the command line. This prevents a potential +security issue where someone doing a ps command can see your login and password. + +.BI \-z +This option tells rpost to use SSL to communicate with the remote hosts, if SSL was +compiled into rpost. + +.SH STDIN MODE +rpost + +rpost hostname + +rpost reads one article from stdin and sends it to the +NNTP server. The article must have a header of at least two lines, namely +Newsgroups: and Subject: and a body (the article). Header and body +have to be separated by a newline. Rpost does not change the article +in any way. + +Rpost uses the POST command to post your article, just like any standard +newsreader. This is handy when using SLIP and PPP, since most providers +do not allow any other method to post articles (such as nntpsend or innxmit). +.SH BATCH MODE + +.I rpost +.BI +hostname +.BI -b +batchfile +.BI -p +prefix +.BI -d + +This batch mode allows you to give rpost a list of articles, and have +them all posted. + +-b batchfile + +A listing of the articles to be posted. This parameter is REQUIRED. +This file contains one article per line, with +the line being the path to the file containing the article. For +example: + +.RS +-b /usr/spool/news/out.going/pixi +.RE + +IF there are any problems uploading a specific article, a "failed" file +will be created. It will be called "batchfile".fail, and contain the +line from this batchfile for the article(s) that did not successfully upload. +This file can be used to re-run the failed messages through rpost. NOTE: +duplicate articles are NOT considered an error for the fail file. + +-d + +If the upload of articles is successful, this option will cause rpost to + delete the batchfile named in the -b option. + +-p prefix + +If the batchfile does not contain a full path, but rather +a partial path, this parameter must be specified. This is useful +when the batch file is generated by another program. +For example, Inn lists the path in the out.going file relative +to its base directory /usr/spool/news. In that case just use: + +.RS + -p /usr/spool/news +.RE + +.SH RNEWS MODE +.I rpost +.BI +hostname +.BI -r +rnews_file +rnews_path + +This option allows you to use rnews generated file(s) to post. It requires +two parameters. + +rnews_file - this is the base name for the rnews files. If you have your +rnews file(s) called batch1, batch2, etc., then this argument would be +"batch". + +rnews_path - this is the path to the location of the rnews files. +.RS +-r batch /usr/tmp/rnews +.RE + +-d + +If the upload of all the articles from any of the rnews files is +successful, then this option will cause rpost to delete that +particular rnews file. + +.SH FILTER MODES +-f filter $$o=<outfile> filter_arg1 filter_arg2 ... + +In many cases, each article must be massaged before the +remote NNTP will accept it. This option, and the embedded +perl filter option below, lets you do that. These filters do not +work in STDIN mode, but in the batch and rnews modes from above. +Note that the -f .... option must be the LAST option, as +everything that follows it is passed to the filter, except +as noted below. +There are three required parameters with this: + +$$o=<outfile> - <outfile> is the name of the file produced by +your filter that will get uploaded to the remote NNTP server. +THIS IS NOT passed to your filter program. This can be specified +anywhere on the command line AFTER the -f filter argument, either before +the filter name, or after it. + +filter - name of the program to call. Whatever follows filter, EXCEPT +for the $$o, are arguments passed to the filter. + +arg1 - The first argument to your filter program/script. It most +likely will be $$i, which rpost fills in with the name of the article +that needs to be cleaned up. + +arg2 ... - any additional args needed can be specified. + +.PP +Let's clarify this a bit with an example. Some NNTP servers don't +like to receive articles with the NNTP-Posting-Host filled in. +Create a short shell script to delete this from a file: + +\-myscr-------------------------------------------- + +#!/bin/sh + +sed -e "/^NNTP-Posting-Host/d" $1 > $2 + +\-end myscr---------------------------------------- +.PP +Then call rpost like this: +.RS +rpost localhost -b /usr/spool/news/out.going/pixi -f myscr \\$\\$o=/tmp/FILTERED_MSG \\$\\$i /tmp/FILTERED_MSG +.RE + +Then, before each article is uploaded, myscr is called like such: +.RS +myscr infilename /tmp/FILTERED_MSG +.RE + +After myscr has finished, rpost uploads the cleaned up article, +stored in /tmp/FILTERED_MSG, to the remote NNTP server. +.SH NOTE: +The $$o and $$i have to be escaped, using either the backslashes +as above, or with single quotes, to prevent the shell from +trying to interpret these as variables. Failure to escape them will result +in rpost not working! + +.BI -F +perlfilter +.PP +This option allows you to use an embedded perl filter to filter your articles. +In order to use this, you must edit the Makefile, and define the various +PERL_ options. +It has a couple of advantages over the -f option above. Because it is +embedded perl, there are no forks and execls() done, so it should be faster. +Also, you don't need to worry about the arguments to the program and +escaping $$, etc as above. +.PP +Rpost will, when it starts up, load in the perlfilter file designated and parse +it for syntax errors. Then, for each article to be uploaded, rpost will call the +subroutine "perl_rpost", contained in the perlfilter file. See sample/put.news.pl +for a complete working example. There are +three key points you need to be aware of when creating your filter. + +.RS +1. The perlfilter file must contain the line "package Embed::Persistant;", so +that variables in the perlfilter file don't clash with rpost variables, and +the subroutine must be called "perl_rpost". This can be changed by editting +the PERL_RPOST_SUB define in suck_config.h. +.RE + +.RS +2. The perl_rpost subroutine receives the input file name as its sole argument, +and must return the full path to the location of the +filtered article as a single scalar string (return $outfile). +.RE + +.RS +3. The subroutine must explicitly close the output file (containing the filtered +argument) before it returns. This is because perl will only do an automatic +close upon program completion (in our case when rpost exits), or when the +file handle is reused (the next time the subroutine is called). If the +close is not done, then more than likely, a 0 byte file will exist when +rpost tries to post the article, and errors will result. + +.SH WARNING: + +Be very careful with what the filter program deletes from the article. Deleting +the wrong line can have bad effects later on. For example, do not delete the +MSG-ID line, as this could cause a single message to be posted many times, depending +on the configuration of both the local and remote newserver. + +.SH RPOST ARGUMENT FILE +.PP +If you specify @filename on the command line, rpost will read from filename and +parse it for any arguments that you wish to pass to rpost. You specify the +same arguments in this file as you do on the command line. The arguments +can be on one line, or spread out among more than one line. You may also +use comments. Comments begin with '#' and go to the end of a line. All +command line arguments override arguments in the file. One advantage to +using the file instead of the command line, is that you don't have to +escape any special characters, such as $. + +.RS +# Sample Argument file +.RE +.RS +-b batch # batch file option +.RE +.RS +-M # use mode reader option +.RE + +.SH EXIT VALUES +Rpost returns the following exit values: + +.RS +0 = success +.RE +.RS +1 = error posting an article +.RE +.RS +2 = unable to do NNTP authorization with the remote server. +.RE +.RS +3 = unexpected answer to command when doing NNTP authorization. +.RE +.RS +-1 = other fatal error. +.RE + +.de R$ +This is revision \\$3, \\$4. +.. +.SH "SEE ALSO" +suck(1), testhost(1), lpost(1). |