.\" $Header: /nfs/papaya/u2/rsalz/src/newsgate/RCS/gag.1,v 1.6 91/04/01 09:43:50 rsalz Exp Locker: rsalz $
.TH GAG 1 LOCAL
.SH NAME
gag \- Gateway alias generator
.SH SYNOPSIS
.in +.5i
.na
.ti -.5i
.B gag
[
.B \-a
] [
.BI \-b bbn_file
] [
.BI \-c cnews_file
] [
.BI \-i innnews_file
] [
.BI \-n bnews_file
] [
.BI \-d mmdf_dir
] [
.BI \-s sendmail_file
] [
.BI \-t PP_shell
] [
.BI \-u PP_user
] [
.B \-b
] [
.B \-p
] [
.I file
]
.ad
.in -.5i
.SH DESCRIPTION
.I Gag
reads a control file and builds entries for
.IR sendmail (8),
.IR BBN ,
.IR MMDF (8),
and
.IR PP (8)
alias files, as well as
.IR Netnews (1)
sys file entries.
It is an auxiliary program for helping to maintain a mail/news
gateway operation.
A typical
.I gag
file sets up default values for all the parameters, then contains a list
of newsgroup\-mailing list pairs.
Group-specific values can override the defaults.
.PP
.I Gag
input is fairly free-form.
It ignores C-style comments, and whitespace is allowed anywhere.
There are a couple of dozen keywords, and case is significant; most
of the keywords are parameters used to control the gatewaying.
Quoted strings are written as they are in C, except they may not
span lines.
.PP
Using the parameters enumerated below,
.I gag
can write six different sets of alias files:
.RS
.ta \w'InterNetNews  'u
.nf
BBN	if the ``\-b'' flag is used
MMDF	if the ``\-m'' flag is used
B News	if the ``\-n'' flag is used
C News	if the ``\-c'' flag is used
InterNetNews	if the ``\-i'' flag is used
Sendmail	if the ``\-s'' flag is used
PP shell	If the ``\-t'' flag is used
PP user	if the ``\-u'' flag is used
.fi
.RE
Any combination of these flags is allowed.
.I Gag
does not edit any existing files; all output blindly overwrites the
specified output files.
The intent is that you review the output, then manually update the
production versions.
Doing something like ``gag \-n /var/lib/news/sys'' is a sure recipe for
disaster!
Do something like this, instead:
.RS
.nf
    sed '/--START-OF-GATEWAY-OUTPUT-/,/--END-OF-GATEWAY-OUTPUT-/d' \e
	</var/lib/news/sys >/tmp/sys
    gag -n - <gag.data >>/tmp/sys
    mv /tmp/sys /var/lib/news/sys
.fi
.RE
.PP
.I Gag
normally complains about attempts to gateway groups that are not in
the news active file; use the ``\-a'' suppresses this check, assuming
that all named groups are valid.
.PP
BBN-style
aliases can't pipe into a command with parameters.
For example,
.I sendmail
can have an entry like this in
.IR /etc/aliases (5):
.RS
.ta \w'post-bboard:  'u
.nf
post-bboard:	"|/usr/bin/mail2news -n bbn.bboard \e
	-o 'BBN News/Mail Gateway' \e
	-d bbn"
.fi
.RE
With BBN, it is necessary to create an alias that feeds into a custom script:
.RS
.ta \w'bboard-gate:  'u
.nf
bboard-gate:	@mailer.bbn.com { "news|/usr/lib/news/.admin/gate-bboard" }
	bboard-gate@mailer.bbn.com
.fi
.RE
.I Gag
will also create the utility script invoked by the above alias:
.RS
.ta \w'exec 'u
.nf
#! /bin/sh
##  This script is on the "bboard" mailing list.
exec /usr/bin/mail2news -n bbn.bboard \e
	-o "BBN News/Mail Gateway" \e
	-d bbn
.fi
.RE
To create these scripts, use the ``\-d'' flag to name the directory where
they should be created; ``\-d .'' will create them in the current directory.
.PP
.I MMDF
aliases are similar to
.IR sendmail 's,
except that the the scripts are run under a specified user id
(see below).
.PP
.I PP
uses two files, a shell and user file, whose format is not described here.
.PP
Some sites want to create mail aliases that forward into each newsgroup;
that is, mail sent to ``comp-foo-bar'' should get posted to the ``comp.foo.bar''
newsgroup.
If the ``\-p'' flag is used, then each gatewayed group will get such an
alias created.
The
.IR mkmailpost (1L)
command can be used to create
.I gag
``mailpost'' commands for all entries in the news active file.
Note that using
.I mkmailpost
and the ``\-p'' flag will almost certainly result in the creation of duplicate
aliases.
.PP
The parameters that control the gatewaying are:
.IP directory
The directory where the BBN alias scripts are kept.
(In the above example, the directory is
.IR /usr/lib/news/.admin .)
.IP distributions
A space-separated list of distributions to forward from news to mail.
In most cases, this will be the full set of distributions received, but
it can be convenient, for example, to not forward regional articles out
to a world-wide mailing list.
With distributions set to ``world usa na'' then the news sys entry
for ``comp.foo'' will have this in the second field:
.in +.5i
.nf
<site>:\e
  world,!world.all,usa,!usa.all,na,!na.all,comp.foo,!comp.foo.all\e
  <rest of entry>
.in -.5i
.fi
.IP "inews flags"
These are flags to pass on to
.IR inews (8)
when gatewaying a mail message into netnews.
They are put on the
.I news2mail (1)
command line, which will pass them along.
A common use is to set a default distribution or organization.
.IP mail2news
The full pathname of the
.I mail2news
program.
.IP mailcontact
This is the name of the person listed in the ``For more information, contact''
part of the header generated by
.IR news2mail .
.IP mailhost
When remote mailing lists are gatewayed into local newsgroups, it can
often be convenient to provide a local alias that forwards on to the
remote host.
For example, if the list ``info-foo'' is maintained at ``vax.host.edu''
then it is possible to create a local alias that just forwards to
``info-foo@vax.host.edu.''
.IP "mailinglist"
If set to ``true,'' then
.I gag
will write aliases that forward on to the list at the current mailhost; if
set to ``false'' than no such aliases will be written.
.IP moderator
If set, then the value is put on the
.I mail2news
command line with the ``\-a'' flag.
This is useful for making a semi-moderated one-way gateway.
.IP news2mail
The full pathname of the
.I news2mail
program.
.IP organization
If set, then the value is put on the
.I mail2news
command line with the ``\-o'' flag.
.IP owner
If set, then all
.I sendmail
aliases also have an ``owner\-'' version, with this value as the
recipient, to receive trouble reports.
.IP request_address
Most mailing lists have a ``\-request'' address to handle list administration.
When gatewaying the list ``info-foo'' if the maintenance address isn't
``info-foo-request'' set this parameter to the proper address.
.IP site
This is the name of the site to use in the news sys file; ``gateway'' is
a common choice.
.IP user
When running scripts under
.I MMDF
(either normal or with the BBN style)
a userid to setuid to must be given.
.PP
Note that there is some overlap in these parameters.
In particular the ``moderator'' and ``organization'' parameters can really
be subsumed by the ``inews flags'' parameter.
They are explicitly called out, however, for convenience in specifying
the types of gatewaying.
For example, while all gatewayed groups might go out with the same
distribution, only some might need an
.I Approved:
header line.
.SH "THE LANGUAGE"
A
.I gag
file is composed of intermixed parts of three different constructs:
defaults, mail/news posting entries, mail/news gateway entries.
.PP
Individual groups can override the default parameters.
The defaults can be changed at any time, and retain the new value for
the rest of the file or until changed again.
For example, most mail aliases will be ``owned'' by
.IR postmaster ,
but it might be convenient to set the forwarding address on specific
aliases to someone else.
For example:
.RS
.DT
.nf
/* Send gateway complaints to postmaster */
default owner = "postmaster";

/* The "animals" list is privately maintained. */
gateway bbn.animals animal-rights
	owner = "canus-major";
.fi
.RE
The syntax is explained in more detail, below.
.PP
A default parameter assignment looks like one of the following:
.RS
.DT
.nf
\fBdefault\fP <parameter> \fB= true ;\fP
\fBdefault\fP <parameter> \fB= false ;\fP
\fBdefault\fP <parameter> \fB=\fP "string value" \fB;\fP
\fBdefault\fP <parameter> \fB= dotify (\fP "value" \fB) ;\fP
.fi
.RE
The last form is used to translate mixed-case strings into the prefix-period
form used by
.IR mail2news .
.PP
A gateway declaration looks like this:
.RS
.DT
.nf
\fBgateway\fP <newsgroup> <mailinglist>
	[ parameter settings ] \fB;\fP
.fi
.RE
The parameter settings are like the default settings shown above, except
that the word ``default'' is left off, as are all semicolons but the
last one.
.PP
To set up a simple unidirectional newsgroup/mailing list gateway, use a
``mailpost'' declaration:
.RS
.DT
.nf
\fBmailpost\fP <newsgroup> \fB;\fP
.fi
.RE
.SH "BUGS AND CAVEATS"
.I Gag
doesn't free most of the memory that it allocates; in essence, the entire
input must fit into the process space.
.PP
In generating news
.I sys
file entries, remember that the command is a
.IR sprintf (3)
format string, and any percent signs
.RI ( % )
must be doubled or they will be taken as a formatting control.
.SH "SEE ALSO"
mail2news(1L), mkmailpost(1L), news2mail(1L).
.SH AUTHORS
Rich $alz <rsalz@bbn.com>, replacing some
.I m4
scripts that
.br
Erik E. Fair <fair@apple.com> wrote.
.br
Piete Brooks <pb@computer-lab.cambridge.ac.uk> provided the PP support.