==============================================================================
README for nntp-gw 0.5                                              2000-07-07
==============================================================================

Copyright 1997-2000 by Eberhard Mattes <em-gw@windhager.de>
Portions 1999-2000 by Giles Heron <giles@clear.net.nz>
Donated to the public domain.  No warranty.


Introduction
============

nntp-gw is an add-on for the TIS Firewall Toolkit 2.0; it provides
access to an external NNTP server.  While plug-gw can also be used for
this, nntp-gw provides better logging and can block newsgroups.


Installation
============

1. After installing the TIS Firewall Toolkit, unpack nntp-gw.tar.gz
   or em-gw.tar.gz into the main directory of the TIS Firewall Toolkit:

        cd /sources/fwtk
        gunzip </dist/nntp-gw.tar.gz | tar xf -

2. If your `make' tool requires `.include' instead of `include',
   replace `include' with `.include' in nntp-gw/Makefile and
   libem/Makefile.  (This can also be done by running `fixmake' of the
   TIS Firewall Toolkit.)

3. Compile the libraries and the program:

        cd libem
        make
        cd ../nntp-gw
        make

4. Copy nntp-gw to the target directory:

        cp nntp-gw /usr/local/etc

   (see the definition of DEST in Makefile.config for the target
   directory) and copy nntp-top to a directory in $PATH:

        cp nntp-top /usr/local/bin

5. Configure nntp-gw by editing netperm-table, see below.

6. Start nntp-gw (don't forget to arrange for nntp-gw being started
   automatically when the system comes up), see below.


Compilation problems
====================

If your system does not have vsnprintf(), add

  #define DONT_HAVE_VSNPRINTF

to firewall.h and retry.


Configuration
=============

nntp-gw is -- like the TIS FWTK programs -- configured by rules in
netperm-table.  It reads all rules using the "nntp-gw" and "*"
keywords (however, see <KEY> below).  nntp-gw understands the
following attributes:

  destinations <HOST>... [-port <PORT>]

     Specify access permissions for external news servers.  The
     "destinations" attribute comes in two flavours:
     "permit-destinations" for permitting access to matching servers
     and "deny-destinations" for denying access to matching servers.
     "destinations" is equivalent to "permit-destinations".  If there
     are multiple "destinations" lines, all of them will be read,
     stopping at the first matching line.  If there is no matching
     line, access will be denied.  <PORT> is the port number (which
     applies to all servers listed in that line), the default value is
     119.

     Example:
         nntp-gw: permit-destinations peergroups.shiva.com
         nntp-gw: permit-destinations *.microsoft.com
         nntp-gw: permit-destinations test.example.com -port 911

     Note that if the "server" attribute is given then any
     "destinations" attributes will be ignored - since nntp-gw will
     forward to a single NNTP server.

  groupid <GROUP>

     Run with group ID <GROUP>.  Only the first "groupid" line is read.

     Example:
          nntp-gw: groupid nogroup

  hosts <HOST-PATTERN>...

     Specify access permissions for clients based on IP address.  The
     "hosts" attribute comes in two flavours: "permit-hosts" for
     permitting access for matching hosts and "deny-hosts" for denying
     access for matching hosts.  "hosts" is equivalent to
     "permit-hosts".  If there are multiple "hosts" lines, all of them
     will be read, stopping at the first matching line.

     Example:
          nntp-gw: deny-hosts unknown
          nntp-gw: permit-hosts 199.99.99.*

  log <EVENT>...

     Define what events to log.  Only the first "log" line is read.
     The following keywords are available for <LOG>:

          article-summary

		For each selected newsgroup, log the number of
		articles read and the total number of bytes in those
		articles.  This is required for nntp-top.

          command

		Log each command received from the client.  This is
		useful for debugging.

          list-size

		Log the size of textual responses.  This is useful for
		detecting excessive use of NEWNEWS etc.

          post

		Log the response code and the number of bytes for the
		POST and IHAVE commands.

          response

		Log the status response line.  This is useful for
		debugging.

     Example:
          nntp-gw: log article-summary list-size post

  newsgroups <PATTERN> [-message <MSG>] [-delay <DELAY>] [-quit]

     Specify access permissions for newsgroups.  The "newsgroups"
     attribute comes in two flavours: "permit-newsgroups" for
     permitting access to matching newsgroups and "deny-newsgroups"
     for denying access to matching newsgroups.  "newsgroups" is
     equivalent to "permit-newsgroups".  If there are multiple
     "newsgroups" lines, all of them will be read, stopping at the
     first matching line.  If there is no matching line, access will
     be permitted.  <PATTERN> can contain "*" to match any sequence of
     characters.  Letter case is ignored.  For "deny-newsgroups", the
     following options can be used:

          -message <MSG>

                Define the response to be returned to the client.
                <MSG> must begin with a three-digit response code.
                The default value is "411 access denied".

          -delay <DELAY>

                Sleep for <DELAY> seconds after sending the response.
                This is an attempt to make people actually see the
                response and to encourage removing blocked newsgroups
                from their active list.  By default, there is no
                delay.

          -quit

                If -delay doesn't help, you may try -quit.  With
                -quit, nntp-gw ends the connection after sending the
                response.

     There are no options for "permit-newsgroups".

     Example:

          nntp-gw: permit-newsgroups comp.binaries.important
          nntp-gw: deny-newsgroups *binaries* -message "411 no binaries please"

  server <HOST> [<PORT>]

     Forward to the NNTP server on <HOST>.  <HOST> can be an IP
     address or a hostname.  <PORT> is the port number, the default
     value is 119.  Only the first "server" line is read.  If a
     "server" line is present, no "destinations" lines will be read.

     Example:
          nntp-gw: server news.my-isp.com

  userid <USER>

     Run with user ID <USER>.  Only the first "userid" line is read.

     Example:
          nntp-gw: userid nouser


Running nntp-gw
===============

nntp-gw can be run either from inetd:

        nntp-gw [ <KEY> ]

or as daemon:

        nntp-gw -daemon <PORT> [ <KEY> ]

<PORT> is the port number.  If <KEY> is specified, nntp-gw will read
configuration rules using <KEY> instead of "nntp-gw".  This can be
used for having different configurations of nntp-gw on different
ports.


Using nntp-gw
=============

In the news reader, configure the host running nntp-gw as NNTP server.
If the server requires authentication then configure the username and
password in the news reader as for a local server.

If access to multiple external NNTP servers is required then configure
the news reader to expect the NNTP server to require authentication.
Configure the news reader to give the name of the external news server
to access as the username, with an empty password.  Many news readers
permit the configuration of multiple news reading accounts.  Configure
one account for each external news server.

For example:

    NNTP server = newsproxy.yourdomain.com
    Username    = peergroups.shiva.com
    Password    =

Note that access to multiple external news servers which require
authentication is also possible.  In this case configure the username
as user@server.

For example:

    NNTP server = newsproxy.yourdomain.com
    Username    = 123456@betanews.microsoft.com
    Password    = x1q3sdj1qasd


Statistics
==========

The program nntp-top reports the top <N> newsgroups read via nntp-gw.
nntp-top takes its input from standard input, which is expected to be
in syslog format.  nntp-top is called like this:

        nntp-top [-a] [-b] -n <N>

where <N> is the number of newsgroups to be listed.  With the -b
option, nntp-top lists the top newsgroups by number of bytes, with the
-r option, nntp-top lists the top newsgroups by number of requested
articles.  If neither -a nor -b is given, nntp-top lists the top
newsgroups by number of bytes and by number of articles, i.e.,
omitting both -a and -b is equivalent to giving both -a and -b.

nntp-log requires nntp-gw to be configured with "log article-summary".

Example:

        nntp-top -n 20 </var/adm/messages

The output of nntp-top can be used for finding newsgroups which should
be blocked to save bandwidth on a slow link.


History
=======

Version 0.2, 1998-09-03
-----------------------

- Support the XHDR and XPAT commands

- Check snprintf() and vsnprintf()

Version 0.3, 1999-07-09
-----------------------

- Support the LIST EXTENSIONS, OVER, and PAT commands.

- Optional <KEY> argument on the command line

- Optional <PORT> argument for the "server" attribute

Version 0.4, 2000-04-17
-----------------------

- Support multiple external news servers and news server authentication
  (contributed by Giles Heron)

Version 0.5, 2000-07-17
-----------------------

- Don't crash if a command other than AUTHINFO is issued before the
  server has been selected

- nntp-gw now responds with code 400 if it cannot connect to the server

==============================================================================
                                THE END
==============================================================================
