.\" $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).