LMTP2NNTP(8) mail to news gateway LMTP2NNTP(8)NAME
OSSP lmtp2nntp - mail to news gateway
SYNOPSISlmtp2nntp [--childsmax⎪-C childsmax] [--daemonize⎪-D] [--kill⎪-K]
[--pidfile⎪-P filename] [--acl⎪-a addr/mask (LMTP daemon ACL)]
[--bind⎪-b addr[:port]⎪"-"⎪path[:perms] (LMTP daemon bind)]
[--client⎪-c addr[:port] (NNTP client bind)] [--destination⎪-d
addr[:port] (NNTP client destination)] [--groupmode⎪-g groupmode]
[--headerrule⎪-h [pri]:[regex]:header:[val]] [--include⎪-i configfile]
[--l2spec⎪-l l2spec] [--mailfrom⎪-m regex] [--nodename⎪-n name]
[--operationmode⎪-o abc/a.d.e⎪post⎪feed] [--restrictheader⎪-r regex]
[--size⎪-s bytes] [--testfile⎪-t filename] [--timeoutlmtp sec] [--time‐
outlmtpaccept sec] [--timeoutlmtpread sec] [--timeoutlmtpwrite sec]
[--timeoutnntp sec] [--timeoutnntpconnect sec] [--timeoutnntpread sec]
[--timeoutnntpwrite sec] [--user⎪-u uid⎪name] [--version⎪-v] --news‐
group newsgroup⎪wildmat [newsgroup ...]
DESCRIPTION
The OSSP lmtp2nntp program is an LMTP service for use in conjunction
with an MTA (like Sendmail), providing a reliable real-time mail to
news gateway. Input messages get their headers reformatted according to
configurable rewrite rules. The article is then posted or fed into a
remote NNTP service (like INN). Delivery must take place immediately or
the transaction fails. OSSP lmtp2nntp relies on the queuing capabili‐
ties of the MTA in order to provide a fully reliable service. The pro‐
gram returns proper delivery status notification which indicates suc‐
cessful completed action, persistent transient failure or permanent
failure.
Configuration files can be specified to reduce the complexity of com‐
mand lines. Their content has a simple "command WHITESPACE argument"
syntax where commands and their arguments map exactly to the long
options, with dashes omitted. There is no artifical difference between
using command line and using configuration files. The only practical
impact is that the shell expands metacharacters while those have no
special meaning inside the configuration file. However, shell style
line concatenation through BACKSLASH and comments through HASH are sup‐
ported.
Options belong to one of the three classes SINGLE, FLAG or MULTI. Any
option can be specified more than once. Those belonging to SINGLE and
FLAG class can appear multiple times but only the last occurrence in
terms of parsing sequence counts while those belonging to MULTI class
handle their arguments as a array. SINGLE and MULTI require an argu‐
ment, FLAG does not allow an argument.
The following command line options and arguments are available:
--childsmax⎪-C childsmax
Childs the daemon spawns at max. Default is 10. SINGLE.
--daemonize⎪-D
Daemonize and detach from current terminal. FLAG.
--kill⎪-K
Kill a previously run daemon. After processing this option the pro‐
gram is terminated so this option effectivly renders most other
options invalid not including specification of a pidfile and log‐
ging. The pid must be listed in pidfile. FLAG.
--pidfile⎪-P filename
Pidfile holding the process ID. Written when daemonizing. Read when
killing a previously run daemon. Care must be taken when using rel‐
ative path names as daemonizing changes the current working direc‐
tory to '/' before the file is opened. SINGLE.
--acl⎪-a addr/mask (LMTP daemon ACL)
Access control list specifying TCP INET addresses and masks where
incoming LMTP connections are accepted from. Omitting a mask
defaults to a host comparison. The mask is a CIDR style bitmask
where /0 means no comparison and enforces a match. Omitting the
wholly option defaults to 0.0.0.0/0 and [::] which allows access
from any IPv4 or IPv6 host. It is possible to specify both inclu‐
sive and exclusive addresses, the latter have to be prefixed with
an exclamation mark. In order to pass the ACL a client must match
any inclusion and not match any exclusion. If you specify exclu‐
sions only, a fake inclusion of 0.0.0.0/0 and [::] is appended
internally. Any addr can be a name which will be resolved on pro‐
gram launch time. MULTI.
--bind⎪-b addr[:port]⎪"-"⎪path[:perms] (LMTP daemon bind)
Bind address accepting incoming LMTP connections. Supported are
""-"" for stdio, path[:perms] for Unix Domain socket with optional
chmod-like permissions and addr[:port] for TCP INET socket. Omit‐
ting this option defaults to stdio. The path for a UNIX domain
socket must start with a slash. The addr can be a name which will
be resolved on program launch time. SINGLE.
--client⎪-c addr[:port] (NNTP client bind)
Client connections for outgoing NNTP communication bind to this
address. If an address is specified but port is omitted the kernel
chooses an ephemeral port. If you want to specify a port but no
address then replace address with all zeros. If completely omit‐
ted, no assumptions are made which causes the kernel to choose an
address based on routing information and an ephemeral port. The
addr can be a name which will be resolved on program launch time.
SINGLE.
--destination⎪-d addr[:port] (NNTP client destination)
Destination hostname or address and optional TCP port of a NNTP
service. Unless a port is specified, getserbyname(nntp) is queried
with fallback to 119/tcp. If "-d" option is ommited, "news" is used
and if this doesn't resolve, "localhost" is assumed. Any addr can
be a name which will be resolved on program launch time. It is
assumed that multiple servers are used to increase the reliability
of the news system and to speed up distribution by posting the same
article to more than one server. In regard to this program they
must provide the same groups and talk to each other. MULTI.
--groupmode⎪-g groupmode
Groupmode configures news group(s). Possible values are "arg"
(default), "envelope" and "header". In "arg" mode, the "newsgroup"s
specified as command line arguments are ultimate destinations for
the received messages. Addresses from envelope and headers are
ignored. In "envelope" mode the newsgroup(s) are taken from the
LMTP envelope, in "header" mode the newsgroup(s) are taken from the
header. In all modes "Newsgroups:" header is rewritten. In "enve‐
lope" and "header" mode groups must still be specified as newsgroup
options. However, in these modes the newsgroup options are filters
representing allowed groups. Filters can be specified as wildmat's.
MULTI.
--headerrule⎪-h [pri]:[regex]:header:[val]
Header rewriting rule. A message received by the LMTP server is
split into header and body. The header is further split into a list
where the headernames are unique keys to access single- or multi‐
values. The values are kept in sequence as they appeared in the
original message. The gateway processes each rule in priority
order. Small pri numbers are processed first. The default prioriy
is 500. Each rule can modify a header and thus change the input of
the remaining rules. If a regex is given, the rule processes all
currently existing headers that match the regular expression. A new
header header with val will be created. With no regex given, a new
header with name header and data val is created. In both cases,
the new header will replace an existing header with the same name.
Also, if the name or value ever becomes empty, the header is
removed. Omitting regex and nothing found to replace, the new
header will be appended. Processed headers will always be sin‐
gle-valued. Omitting the val means the (matching) header(s) will
be deleted. The headderrules support PCRE (Perl compatible reguar
expression) and if a regex was used, the matching elements are
available to header and value as "DOLLAR NUMBER". The value is
also processed through a variable expansion library which has
access to all command line options, many internal variables and all
currently existing headers. The expansion allows powerful con‐
structs like joining multivalues into a single value. MULTI.
Functional diagram:
foreach rule
if rule has regex
foreach header
if regex matches
create new header
expand regex references into headername
if headername is empty
delete header
if headervalue is empty
delete header
expand regex references into headervalue
expand variables into headervalue
if headervalue is empty
delete header
replace existing header
else (= rule has no regex)
create new header
if headervalue is empty
delete header
expand variables into headervalue
replace existing or append new header
Further reading:
- regular expressions see 'pcre' manual page - variable expansion
see 'lib_var/var.pod' and 'lib_var/var_play'
Variables:
The variables use a hierarchical name space scheme. All options are
available through '${option.optionname}'. For options of class
MULTI this yields the first element. Other elements can be accessed
through '${option.optionname[index]}'. All headers can be accessed
through '${msg.header.headername}' and again, indexes are supported
for multivalued headers.
Inside variables, functions can be accessed through '%function‐
name'. Currently, only %createmessageid is available which creates
a value properly suitable for a Message-ID: header.
--include⎪-i configfile
Include a configuration file. There is no artifical limitation on
the number and levels of configuration files supported. However, no
attempt is made to prevent recursion. Order of inclusion matters
for SINGLE and FLAG option classes. MULTI.
--l2spec⎪-l l2spec
L2 channel tree specification. The full functionality of lib_l2 is
exposed to the user, see 'lib_l2/l2.pod' when it becomes available
and have a look at the example configuration file in the meantime.
SINGLE.
--mailfrom⎪-m regex
"Mail From:" envelope restriction to limit sender addresses. If
omitted, anyone can send mail. The value to be compared includes
the angle brackets. Use a PCRE (Perl compatible reguar expression)
for mailfrom. SINGLE.
--nodename⎪-n name
Own FQDN used in LMTP and NNTP protocols. This overrides the node‐
name returned by uname(3). SINGLE.
--operationmode⎪-o abc/a.d.e⎪post⎪feed
Set fake status or operationmode. Possible values for operation‐
mode are "post", "feed" or a string in "LLL/D.D.D" format used to
fake a LMTP return code. In "post" mode articles are sent to the
NNTP server(s) using POST command. Before posting, a duplicate
check using STAT command is issued. In "feed" mode articles are
sent to the NNTP server(s) using IHAVE command. Specifying a
return code and DSN replaces the post/ feed logic by a noop and
assumes the given string must be returned to the LMTP side. The
slash is replaced by a space internally. The default is "553/5.7.1"
meaning "Requested action not taken: mailbox name not allowed/
Delivery not authorized, message refused". This is useful for
debugging LMTP setups without engaging NNTP. Fake mode makes it
possible to run without any -d option. However, if -d option is
given the NNTP client tries to connect but it's return codes are
ignored. SINGLE.
--restrictheader⎪-r regex
Restrict messages by header. Messages with a matching restrict‐
header are rejected. If omitted no restrictions apply. Matching is
done before headers are rewritten. Use a PCRE (Perl compatible
reguar expression) for regex. SINGLE.
--size⎪-s bytes
Size limitation on message in bytes. Default is 8388608 (8M).
--testfile⎪-t filename
Testfile for headerrule. Allows debugging without LMTP or NNTP
activity. The file must be in RFC822 E-Mail format. Use this
option for debugging only, it disables both the mail server and
news client.
--timeoutlmtp sec
LMTP server default timeout. Sets timeout for accept, read and
write at once. Setting sec to zero means to wait infinite. Note
that all LMTP timeouts only apply to socket operations, stdio
always waits infinite. SINGLE.
--timeoutlmtpaccept sec
LMTP server accept timeout. Default is 0.SINGLE.
--timeoutlmtpread sec
LMTP server read timeout. Default is 10. SINGLE.
--timeoutlmtpwrite sec
LMTP server write timeout. Default is 10. SINGLE.
--timeoutnntp sec
NNTP client default timeout. Sets timeout for connect, read and
write at once. Setting sec to zero means to wait infinite. SIN‐
GLE.
--timeoutnntpconnect sec
NNTP client connect timeout. Default is 360. SINGLE.
--timeoutnntpread sec
NNTP client read timeout. Default is 60. SINGLE.
--timeoutnntpwrite sec
NNTP client write timeout. Default is 60. SINGLE.
--user⎪-u uid⎪name
User identity to be set for program execution. SINGLE.
--version⎪-v
Version information is printed, then program exits. FLAG.
--newsgroup newsgroup⎪wildmat [newsgroup ...] =item newsgroup⎪wildmat
[newsgroup ...]
Newsgroup name or match. Depending on groupmode, this is a news‐
group to post or feed the message to or it is a wildmat filter.
Crosspostings succeed if delivery to any group succeeds. MULTI.
SIGNALS
Sending a USR1 signal to the program will flush the logging stream.
DIAGNOSTICS
If invoked it returns 0 on successful execution (not neccessarily mean‐
ing successful delivery!) or 1 on failed execution. Returning proper
delivery status notification is part of the LMTP protocol.
STANDARDS
RFC0821
Simple Mail Transfer Protocol. J. Postel. Aug-01-1982. (Format:
TXT=124482 bytes) (Obsoletes RFC0788 ) (Obsoleted by RFC2821) (Also
STD0010) (Status: STANDARD )
RFC0822
Standard for the format of ARPA Internet text messages. D.
Crocker. Aug-13-1982. (Format: TXT=109200 bytes) (Obsoletes
RFC0733) (Obsoleted by RFC2822) (Updated by RFC1123, RFC1138,
RFC1148, RFC1327, RFC2156) (Also STD0011) (Status: STANDARD)
RFC0977
Network News Transfer Protocol. B. Kantor, P. Lapsley.
Feb-01-1986. (Format: TXT=55062 bytes) (Status: PROPOSED STANDARD)
RFC1035
Domain names - implementation and specification. P.V. Mockapetris.
Nov-01-1987. (Format: TXT=125626 bytes) (Obsoletes RFC0973,
RFC0882, RFC0883) (Updated by RFC1101, RFC1183, RFC1348, RFC1876,
RFC1982, RFC1995, RFC1996, RFC2065, RFC2136, RFC2181, RFC2137,
RFC2308, RFC2535, RFC2845) (Also STD0013) (Status: STANDARD)
RFC1652
SMTP Service Extension for 8bit-MIMEtransport. J. Klensin, N.
Freed, M. Rose, E. Stefferud, D. Crocker. July 1994. (Format:
TXT=11842 bytes) (Obsoletes RFC1426) (Status: DRAFT STANDARD)
RFC1854
SMTP Service Extension for Command Pipelining. N. Freed. October
1995. (Format: TXT=14097 bytes) (Obsoleted by RFC2197) (Status:
PROPOSED STANDARD)
RFC1893
Enhanced Mail System Status Codes. G. Vaudreuil. January 1996.
(Format: TXT=28218 bytes) (Status: PROPOSED STANDARD)
RFC1894
An Extensible Message Format for Delivery Status Notifications. K.
Moore, G. Vaudreuil. January 1996. (Format: TXT=77462 bytes)
(Updated by RFC2852) (Status: PROPOSED STANDARD)
RFC2034
SMTP Service Extension for Returning Enhanced Error Codes. N.
Freed. October 1996. (Format: TXT=10460 bytes) (Status: PROPOSED
STANDARD)
RFC2606
Reserved Top Level DNS Names. D. Eastlake, A. Panitz. June 1999.
(Format: TXT=8008 bytes) (Also BCP0032) (Status: BEST CURRENT PRAC‐
TICE)
RFC2821
Simple Mail Transfer Protocol. J. Klensin, Editor. April 2001.
(Format: TXT=192504 bytes) (Obsoletes RFC0821, RFC0974, RFC1869)
(Status: PROPOSED STANDARD)
RFC2980
Common NNTP Extensions. S. Barber. October 2000. (Format:
TXT=57165 bytes) (Status: INFORMATIONAL)
1.4.1 1.4.1 (09-Oct-2005) LMTP2NNTP(8)
