% @(#) body.text 1.46@(#) 95/05/22 %
\chapter{Introduction}\label{C-intro}
\WHATID{1.46 body.text 95/05/22%
}

ExFilter has one main r\^ole: protecting your network from another
(untrusted) network, often the Internet.

You can use ExFilter to protect parts of your network from one another,
for example to protect your personnel department's computers and files
from other parts of your organisation to help keep sensitive data
secure while still allowing the personnel department to benefit from
your corporate IT investment.

ExFilter can be used in conjunction with other commercial and PD
software to produce a very secure but highly usable connection to
another untrusted network.

As well as protection, ExFilter can improve the perceived performance
of your links.

To do this ExFilter helps you limit how much of each type of traffic
(eg mail, FTP, news, telnet) you want on your link to fairly share the
link between its users.  ExFilter tries to prevent the packet traffic
jams that can build up on slower links that destroy interactive
performance.

ExNet itself uses ExFilter to regulate and filter its connections to
the Internet.

ExFilter V1.1.3 runs on Sun-3s or Sun-4s under SunOS~4.1.x
(Solaris~1).

\section{Overview}

You now need to do the following things to use ExFilter:
\begin{enumerate}

    \item
    Acquire your firewall machine and configure it as per our instructions
    in Chapter~\ref{C-FirewallConfig}.

    \item
    Check the distribution media you were sent, disc or tape.

    Un\TOK{tar} it into a temporary directory (say \TOK{/tmp}) and check
    that you have the following files:
    \begin{description}

        \item[\TOK{ExFilter.O.sun3-SunOS-4}:] the Sun-3 executable.

        \item[\TOK{ExFilter.O.sun4-SunOS-4}:] the Sun-4 executable.

        \item[\TOK{ExFilter.G.sun4-SunOS-4}:] the Sun-4 executable
            compiled with \TOK{gcc}; we do not officially support this
            but you may find it runs a little faster than the \TOK{.O.}
            version.

	\item[\TOK{README}:] a very quick (plain ASCII) guide to
	    ExFilter.

        \item[\TOK{tinyeg.conf}:] a very small example config file for
            ExFilter.

        \item[\TOK{spec.dvi}:] the {\TeX} `device-independent' version
            of this documentation; you can view it with a program such
            as \MITOK{xdvi}.

        \item[\TOK{unsupported/dp-2.3-patchlevel2-DamonMods.tar.Z}:]
            the source of the publicly-available Dialup-PPP package,
            with some of our modifications to make it work better with
            ExFilter.  This is not supported by us but you may find it
            useful.  We use it for our own IP WAN connections.

        \item[\TOK{unsupported/sping}:] a simple shell script we use to
            monitor link performance; set it to ping a host on the
            other side of a link you wish to monitor and it will
            provide a simple round-trip-time histogram on any
            terminal.

        \item[\TOK{unsupported/100359-06.tar.Z}:] Sun's jumbo STREAMS
            patch for SunOS~4.1.x.  You may wish to see if they have a
            later version or if it is unnecessary for your release of
            the OS.  It may be unnecessary for 4.1.3\_U1 and later
            releases of Solaris~1---please check with the supplier of
            your OS.

    \end{description}

    To untar it you will need to type a command such as:

    \TOK{tar xvf - /dev/rst8}

    for tape, or, for floppy disc:

    \TOK{tar xvf - /dev/rfd0}

    \item
    Make sure you have designed, implemented and understand your
    security policy.  You may need help from an external consultant, at
    least initially.  There are many good books on firewall security
    available now, too.

    \item
    Load ExFilter onto your firewall machine and configure it and the
    machine as described in Chapter~\ref{C-ExFilterConfig}.

    \item
    Back up your firewall machine and reboot.

    \item
    Ensure the configuration doesn't let through traffic you don't want
    it to, and conversely that it does let through what you do want it
    to.

    \item
    Periodically check the logs for refused traffic, and recheck that
    your firewall is stopping what you expect it too---don't just trust
    the logs on the firewall since the first things a cracker will do is
    tamper with the logs and logging.

\end{enumerate}

\section{Basic Operation}

ExFilter runs as a root d{\ae}mon process, and attaches itself to the
raw packet interface of each device you tell it about in its
configuration file.  It then looks at every packet that arrives on each
interface and decides whether or not to route it, and if so to which
other interface, depending on the packet's source and destination
addresses, protocol type, etc.  You must configure the kernel not to
route any packets since with would short-cut ExFilter's filtering
mechanisms that are used to screen out harmful packets.

ExFilter uses the \MITOK{NIT} (Network Interface Tap) connection, and
so can attach to any device (eg Ethernet, PPP, SLIP) device which
carries IP packets and provides an NIT interface.


%==============================================================================
\chapter{Setting Up Your Firewall System}\label{C-FirewallConfig}

To make a working firewall machine you need to strip down the kernel to
contain the minimum for speed and to provide the smallest possible
number of loop-holes and flaws for a hacker to break in through.  You
will need to turn off kernel routing so that ExFilter can choose what
to allow through and what to block.

You will also need to load and configure trusted software to provide
any application-level gateways you want to provide on the gateway, for
example an SMTP email gateway and proxy versions of programs such as
Telnet and FTP\@.  You may also want to provide (for example) a public
FTP service from the gateway.

You should not provide any user accounts other than a non-root
administrator account and root itself, and you should not allow remote
access to the machine over Telnet or a similar service---once entry is
gained via any unprivileged account root access can usually be
obtained fairly quickly by an experienced cracker (or UNIX sysadmin).
You should also turn off services such as NIS that may induce a
firewall machine to believe false information supplied form an external
source.  ExFilter, for example, uses static routing and avoids services
such as NIS as far as possible to prevent remote tampering with its
configuration.

Finally, you should turn off any non-essential services, such as
d{\ae}mons running from \MITOK{inetd}.

\section{Modifying Your Kernel}

You will almost certainly need to build a stripped down kernel to
remove the most hackable bits (such as \MI{NFS}, which you should not
need anyway since a firewall must be stand-alone), and to make your
systems as small and efficient as possible.

In general do not configure into the OS kernel module, or load or
enable any OS software from the distribution, that you do not
absolutely need (you don't {\em need} NFS or NIS for example, life is
somewhat tiresome without them, but only experienced administrators
should be on the firewall host anyway).  In particular, avoid all
software that makes your host in anyway dependent on
externally-provided information that may compromise your security.
Again, avoid NIS and NFS (and RFS, etc), server and client, don't use
\TOK{inetd}, etc.  DNS is fine if you configure it properly, and
preferably make it a primary or secondary for the network you are
protecting so that it will only get data about your network directly
from authoritative sources.

It is {\em vital} that you completely disable packet forwarding in the
kernel of your firewall machine else the ExFilter will be
short-circuited and no filtering or protection will be provided at
all.

An example \MI{firewall kernel configuration} for running ExFilter on,
in this case for a Sun-3, is:

\begin{verbatimlisting}
# @(#) FW 1.13@(#) 94/03/06 #
#
# FIREWALL KERNEL.
#   * Minimum disc-bootable kernel for Sun-3/50, Sun-3/60 or Sun-3/110.
#   * Loadable PPP 2.3 is used instead and loaded at runtime.
#   * IP forwarding is turned off here with IPFORWARDING=-1.
#   * We can also configure udp_checksum = 1 (in_proto.c).
#   * We can also expand the udp_ttl to 120 in in_proto.c.
#
# EDIT ../../netinet/in_proto.c IN ../FW BY HAND BEFORE BUILDING THE KERNEL.
#
# We allocate a little more space for file handles, etc, as we will be
# running a lot of networking daemons.
#
machine         "sun3"
cpu             "SUN3_50"       # Sun-3/50
cpu             "SUN3_60"       # Sun-3/60
cpu             "SUN3_110"      # Sun-3/110

#
# Name this kernel:
#
ident           "FW1.13"

# Expanded kernel for lots of UUCP/Sendmail/etc sessions.
maxusers        32

# Turn off all kernel IP forwarding.
options "IPFORWARDING=-1"

#options        QUOTA           # disk quotas for local disks
#options        SYSACCT         # process accounting, see acct(2) & sa(8)
#options        TCPDEBUG        # TCP debugging, see trpt(8)
options CRYPT           # software encryption
options INET            # basic networking support - mandatory
options OLDSCSI         # Old SCSI architecture - mandatory
options TMPFS           # tmp (anonymous memory) file system
options UFS             # filesystem code for local disks
options VDDRV           # loadable modules

config  vmunix  root on sd0 swap on sd0

pseudo-device   pty             # pseudo-tty's, also needed for SunView
pseudo-device   ether           # basic Ethernet support
pseudo-device   loop            # loopback network - mandatory
pseudo-device   win64           # window devices, allow 64 windows
pseudo-device   dtop2           # desktops (screens), allow 2
pseudo-device   ms              # mouse support
pseudo-device   kb              # keyboard support
pseudo-device   snit            # streams NIT
pseudo-device   pf              # packet filter
pseudo-device   nbuf            # NIT buffering module
pseudo-device   clone           # clone device

# connections for machine type 2 (SUN3_50)
controller      virtual 2 at nexus ?
controller      obmem 2 at nexus ?
controller      obio 2 at nexus ?

# connections for machine type 7 (SUN3_60)
controller      virtual 7 at nexus ?
controller      obmem 7 at nexus ?
controller      obio 7 at nexus ?

# connections for machine type 4 (SUN3_110)
controller      virtual 4 at nexus ?
controller      obmem 4 at nexus ?
controller      obio 4 at nexus ?
controller      vme16d16 4 at nexus ?
controller      vme24d16 4 at nexus ?
controller      vme32d16 4 at nexus ?
controller      vme16d32 4 at nexus ?
controller      vme24d32 4 at nexus ?
controller      vme32d32 4 at nexus ?

controller      si0 at obio ? csr 0x140000 priority 2
tape            st0 at si0 drive 040 flags 1
disk            sd0 at si0 drive 000 flags 0
device          zs0 at obio ? csr 0x20000 flags 3 priority 3
device          zs1 at obio ? csr 0x00000 flags 0x103 priority 3
device          le0 at obio ? csr 0x120000 priority 3
device          cgfour0 at obmem 7 csr 0xff300000 priority 4    # 3/60
device          cgfour0 at obmem 7 csr 0xff400000 priority 4    # 3/60
#device         cgsix0 at obmem 7 csr 0xff000000 priority 4     # 3/60
device          bwtwo0 at obmem 2 csr 0x100000 priority 4       # 3/50
device          bwtwo0 at obmem 7 csr 0xff000000 priority 4     # 3/60
device          bwtwo1 at obmem 7 csr 0xff300000 priority 4     # 3/60
#device         bwtwo1 at obmem 7 csr 0xff400000                # 3/60

# 3/110 stuff not in 3/50 or 3/60 config.
# comment out the sc0 lines to save memory if you don't have a SCSI-2 board
controller      sc0 at vme24d16 ? csr 0x200000 priority 2 vector scintr 0x40
tape            st0 at sc0 drive 040 flags 1
disk            sd0 at sc0 drive 000 flags 0
disk            sd1 at sc0 drive 001 flags 0
# comment out the si0 lines to save memory if you don't have a SCSI-3 board
controller      si0 at vme24d16 ? csr 0x200000 priority 2 vector siintr 0x40
device          ie0 at obio ? csr 0xc0000 priority 3
device          cgfour0 at obmem 4 csr 0xff000000 priority 4    # 3/110
#device         bwtwo0 at obmem 4 csr 0xff000000                # 3/110
\end{verbatimlisting}

A feature of this configuration is that it is short, because not much
is configured in.

The setup for a Sun-4 is very similar.  Start with a ``Generic'' or
``Generic Small'' configuration and cut away options from that, such as
NFS server and client support.


%==============================================================================
\chapter{Designing Your ExFilter Configuration}\label{C-ExFilterConfig}

An example \MITOK{/etc/ExFilter.conf} \MI{ExFilter configuration} file
is provided below.  For an explanation of the syntax, see
Chapter~\ref{C-Ref}.

This example is constructed for the following, realistic, configuration:
\begin{itemize}

\item

    You have an internal Class-C network number 1.2.3 (this is not a
    valid Class-C network) that you wish to connect to the Internet
    through ExFilter.

\item

    This network is an Ethernet on interface \MITOK{le0}, and the
    firewall's address on this network is 1.2.3.1.

\item

    You make the ExFilter program appear to be at address 1.2.3.254
    piggybacked on all interfaces, with standard gateway options.

\item

    You have a dial-up or permanent PPP link to the Internet on
    interface \MITOK{dp2}, via a~14k4bps (V.32b) modem.  Your address
    for \TOK{dp2} is~2.3.4.5.
    
\item

    The raw, uncompressed bandwidth available through your~V.32b modem
    with V.42 (error correction alone) is a little short of~1700cps; to
    keep average delay across the link down you should `throttle'
    bandwidth to somewhat less than this (delay increases sharply as
    the throughput approaches the available bandwidth).  Note that the
    `throttle' mechanism in ExFilter pretends that each packet takes up
    about the same number of bits as if passing across an Ethernet,
    which is roughly true though sometimes an underestimate and
    sometimes an overestimate, even ignoring the effects of any modem
    compression.  Turning on (V.42b) modem compression will usually
    give somewhat higher available bandwidth in return for a longer
    round-trip delay, which usually manifests itself as poorer
    interactive performance.

\item

    You are running an SMTP gateway for inbound and outbound traffic on
    the firewall machine, but allow direct connections for incoming
    traffic to the internal mailserver (\MITOK{mailhost}, 1.2.3.4) for
    efficiency.  This is reasonable since only the SMTP port is
    reachable from outside your net and you have decided your SMTP
    mailer is fairly secure.

\item
    
    You wish to allow access to Internet facilities such as \MI{WWW},
    \MI{Telnet}, \MI{FTP}, \MITOK{whois}, and \MITOK{finger} from a
    single host, \MITOK{safehost}, 1.2.3.5, whose security you control
    more tightly than most hosts so you can watch for and forestall
    potential security breaches.

\item

    You want to block and monitor any attempts by external hosts to
    pretend to be one of our external hosts, and a few other potential
    horrors.

\item

    You are initially debugging the link and want to monitor
    ExFilter activity fairly closely.

\end{itemize}

Note that a comment is a hash (\verb|#|) at the start of a line,
followed by a space and then arbitrary text.  Comments cannot be added
to the end of other lines.

\begin{verbatimlisting}
# Set verbosity at just high enough to watch throttle activity, etc.
verbosity 5

# # Set verbosity just above zero; only important things will be reported.
# verbosity 1

# Throttle data to dp2 to 1100--1400B/s including all IP and other headers.
# This does not allow for (for example) TCP header compression for
# outgoing PPP/SLIP links, nor all the link-level framing overhead (though
# it does include enough to cover all the Ethernet link-level headers
# and any padding), nor does it allow for retries done at the link level
# due to corruption, etc.
#
# Raw uncompressed bandwidth available on V.32b/V.42 link is about
# 1700Bps; V.42b compression should improve this marginally.
#
# To try to avoid huge delays make around 1000--1450
throttleto dp2 1300

# Try to prevent traffic to/from our Ethernet getting out of hand!
throttleto le0 200000

# We are interested in interfaces le0 and dp2.
if le0
if dp2

# This gateway appears at address 1.2.3.254.
#
# This gateway should behave itself and decrement TTLs on all packets
# passing through it, generate ICMP error packets where appropriate,
# and discard (not route) all incoming packets addressed directly
# to the underlying interfaces on the assumption that servers on the
# host will deal with any application-level routing necessary.
# The gateway will check and generate IP header checksums for packets
# in transit and generated locally, and will not route packets with IP
# header options.
#
# We do not run in `trace' mode unless we want to debug all traffic
# through the gateway for some reason.
#
gateway 1.2.3.254 decttl icmperrs parallel chksum noopts notrace

# -----------------------------------------------------------------------------
# ROUTING DIRECTIVES
# ==================

# Drop all packets arriving for our own interface addresses or for
# broadcast addresses, etc.
# That includes ignoring all packets arriving on our Ether interfaces
# for any machines on those nets.
#
# Beware of us getting output packets getting fed back on our input
# by nit and counted as input traffic.  This will distort throttling.
# (Some packet devices do this and some don't.  Sun's le0 Ethernet
# interface and out modified dp2.3 PPP drivers don't.)
#
# With the `parallel' option some of these rules are redundant and the rest
# should be logged in case of nasty surprises.
#
# route deny le0 any any from any any any to 1.2.3.0 255.255.255.0 any log
#
# Remember not to route packets destined for any of the other interfaces
# since SunOS will reply for all of them on any interface, generating
# double replies potentially in some cases.
#
route deny any any any between any any any and 1.2.3.1 only any
route deny any any any between any any any and 2.3.4.5 only any
#
# Log strangely-addressed packets.
#
route deny any any any between any any any and 127.0.0.0 255.0.0.0 any log
route deny any any any between any any any and 0.0.0.0 only any log
#
# Ignore discless-client reboot attempts.
#
route deny any any any between any any any and 255.255.255.255 only any
#
# Ignore attempts to talk to our broadcast addresses.
#
route deny any any any between any and any and 1.2.3.0 only any log
route deny any any any between any and any and 1.2.3.255 only any log

# ---------
# Spoofing attempts
# =================
#
# Block packets apparently from internal hosts on our subnet coming
# in from the connected Internet and log such packets.  It may be
# attempts by crackers to cripple or steal data from some of our
# machines by pretending to be our hosts.
#
route deny dp2 any any from 1.2.3.0 255.255.255.0 any to any any any log

# ---------
# NFS and other holes
# ===================
#
# Block all attempts to reach non-privileged NFS ports on our internal hosts.
#
# Log any traffic denied this way.
#
route deny dp2 le0 udp between any any any and 1.2.3.0 255.255.255.0 2049 log 

# ---------
# WWW
# ===
#
# Allow WWW packets to/from safehost for calls originated on safehost,
# ie allow hhtpd packets to or from port 80 on any external machine to
# any non-priv port on safehost.
#
# Limit to 50% of traffic when throttled.
route allow dp2 le0 tcp between any any 80 and 1.2.3.5 only nonpriv throttle50

# ---------
# TELNET/FTP
# ==========
#
# Allow telnet packets to/from safehost for calls originated on safehost,
# ie allow tcp packets to or from port 23 on any external machine to
# any non-priv port on safehost.
#
# Limit to 50% of traffic when throttled.
#
route allow dp2 le0 tcp between any any 23 and 1.2.3.5 only nonpriv throttle50
#
# Similarly for ftp on port 21 (and ftp-data on port 20)
#
# Limit to 50% of traffic when throttled.
route allow dp2 le0 tcp between any any 20 and 1.2.3.5 only nonpriv throttle50
route allow dp2 le0 tcp between any any 21 and 1.2.3.5 only nonpriv throttle50

# ---------
# FINGER/WHOIS
# ============
#
# Limit to 10% of traffic when throttled.
#
# Allow users on safehost to finger any remote host.
#
route allow dp2 le0 tcp between any any 79 and 1.2.3.5 only nonpriv throttle10
#
# Similarly for whois on port 43.
#
route allow dp2 le0 tcp between any any 43 and 1.2.3.5 only nonpriv throttle10

# ---------
# MAIL
# ====
#
# Allow mail directly to the SMTP mailer on mailhost (tcp->port 25).
#
# Mail does not have to be super-high-speed and so is limited to a lowish
# bandwidth.
#
# Limit to 15% of traffic when throttled.
#
route allow dp2 le0 tcp between any any any and 1.2.3.4 only 25 throttle15

# ---------
# PING
# ====
#
# This should be nearly last on the list so as to measure worst-case
# performance from the network and ExFilter.
#
# Allow pings to and from anywhere.
#
# Note that ICMP traffic cannot be throttled.
#
route allow dp2 le0 icmp between any any nonpriv and 1.2.3.0 255.255.255.0 nonpriv

# -----------------------------------------------------------------------------
# THINGS THAT SHOULDN'T GO THROUGH...

# Block attempts to contact our internal DNS name servers.
#
route deny any any any between any any any and 1.2.3.0 255.255.255.0 53 nothrottle

# Ignore attempts to get to one interface from another; these attempts
# arise from our listing all (or most of) our external addresses for each
# application-level gateway on the firewall.
#
route deny any any any between any any any and 1.2.3.1 only any
route deny any any any between any any any and 2.3.4.5 only any

# These are packets that shouldn't be getting here at all.
#
# Log them.
#
route deny any any any between any any any and any any any log
\end{verbatimlisting}


\section{Installing and Starting ExFilter}

First, you will need to select the appropriate binary and copy it to
the firewall's local disc; suitable candidate locations might be
\MITOK{/usr/local/bin} or \MITOK{/usr/etc}.

You should then start up ExFilter from \MITOK{/etc/rc.local} after all
interfaces are in place (ie after any loadable interface drivers have
been loaded and configured).  ExFilter has to be run as root ({\em not}
set-uid root which might be a security hazard) to bind to the low-level
interfaces.

Suitable lines in \MITOK{rc.local} might be:
\begin{verbatimlisting}
EXFILTER=/usr/local/bin/ExFilter.O.sun4-SunOS-4
if [ -f $EXFILTER ]; then
        echo 'Starting Exfilter.'
        ($EXFILTER &)   > /dev/console
fi
\end{verbatimlisting}

Note that the initial \MITOK{verbosity} (debugging level) of the
d{\ae}mon can be set with the optional \MITOK{-v} flag, and the
location of the configuration file with the optional \MITOK{-f} flag.

So you might start ExFilter with a configuration file of
\TOK{/etc/altExFilter.conf} rather than the default
\TOK{/etc/ExFilter.conf}, and with a verbosity level of~50\% rather
than the default~1\%, with:
\begin{verbatimlisting}
EXFILTER=/usr/local/bin/ExFilter.O.sun4-SunOS-4
if [ -f $EXFILTER ]; then
        echo 'Starting Exfilter in an alternative way.'
        ($EXFILTER -v 50 -f /etc/altExFilter.conf &)   > /dev/console
fi
\end{verbatimlisting}


%==============================================================================
\chapter{ExFilter Reference Guide}\label{C-Ref}

\section{The Format and Meaning of the Configuration File}

This section describes the format of the ExFilter configuration file,
by default found in the file \MITOK{/etc/ExFilter.conf}, which should
be owned by, and only writable by, root.

The file consists of a series of one-line records with
whitespace-separated fields.  The order of records and fields is
important.

Completely blank lines are ignored.

The first field on a line (which must start in column one) determines
the type of the record that that line is.

Case of alpha characters is significant.

Records are of unlimited length, but exceeding 256 bytes is
inadvisable.

The following initial fields (ie, record types) are valid:

\begin{description}

\item[\#] (starts a comment record)

    The content of such records is ignored.

\item[throttleto] (starts a traffic throttle record)

    Specifies the maximum amount of traffic in bytes per second that
    may flow out through an interface.  This is also taken to be the
    maximum data rate of traffic coming in through the interface to
    keep traffic roughly symmetrical and keep interactive response of
    (for example, telnet) sessions across the link good.

    The aim of the mechanism invoked by this record is to avoid
    saturating slow connections like PPP links to ensure reasonable
    responsiveness for interactive traffic.  Excess traffic is quenched
    where possible.

    Records referring to interfaces not mentioned in an \MITOK{if}
    record are invalid.

\item[verbosity] (starts a verbosity record)

    Says how verbose the filter program should be as a percentage.

\item[if] (starts an interface-name record)

    Names an interface we want to route packets to/from.

    The interface names \MITOK{none} and \MITOK{quench} are reserved.

\item[route] (starts a routing record)

    An ordered list (order in the file is significant---the first
    matching rule for an incoming packet is used) of instructions to
    route or drop packets with selection by protocol, source and
    destination address/mask/port, etc.  Packets can be specified to
    bypass any throttle.

    The port component is ignored for which it is meaningless, eg
    EGP.  It is mainly intended for UDP and TCP.

\item[gateway] (starts a gateway record)

    Sets overall parameters for the gateway.

\end{description}

\newcommand{\OR}{$|$}

Valid record syntax, in EBNF, is (non-literal parameters are {\it
thus}):
\begin{sloppypar}
\begin{description}

\item[\#] {\it any text}

\item[throttleto] {\it ifname} {\it Bps}

\item[verbosity] {\it percentage}

\item[if] {\it ifname}

\item[route]
        (deny{\OR}allow)
        ({\it Iif}{\OR}any) ({\it Oif}{\OR}any)
        ({\it proto}{\OR}any)
        (from{\OR}between)
        ({\it FRaddr}{\OR}any) ({\it FRmask}{\OR}any{\OR}only) {\it FRport}
        (to{\OR}and)
        ({\it TOaddr}{\OR}any) ({\it TOmask}{\OR}any{\OR}only) {\it TOport}
        [~[no]fragment~]
        [~[no]log~] \pagebreak[3]
        [~[no]throttle[{\it maxthpc}]~]

    (default options: fragment nolog throttle)

\item[gateway] IPaddr
        [~[no]chksum~]
        [~[no]decttl~]
        [~[no]icmperrs~]
        [~[no]parallel~]
        [~[no]opts~]
        [~[no]trace~]

    (default options: chksum nodecttl noicmperrs parallel noopts notrace)

\end{description}
\end{sloppypar}

Note that {\OR} indicates the item on the left {\rm or} the item on the
right.  Parentheses indicate grouping.  Square brackets indicate
optional items.

The meaning of the various parameters to the record types is given below.

\begin{description}

\item[FRaddr, IPaddr, TOaddr:] a dotted-quad host or net IP address,
    eg~1.2.3.4.

\item[fragment:] do packet fragmentation if required.   Also allow
    fragments though, ie parts of packets that have already been
    fragmented, which means ignoring port checking (etc) on all but the
    first fragment.

\item[FRmask, TOmask:] a dotted-quad mask in the style of a netmask;
    non-zero bits are those that will be matched.

\item[FRport, TOport:] port number; \MITOK{any} is any port,
    \MITOK{priv} is any port~$< 1024$ (privileged), and \MITOK{nonpriv}
    is any port~$>= 1024$.

    For protocols other than TCP and UDP this field is ignored with the
    following exception.

    For ICMP, if the FRaddr address matches then the FRport port value
    has the following meanings:

      * \MITOK{any} means any ICMP message is allowed from the given
        host(s).

      * A port number allows ICMP messages of that type through, eg~4
        is Source Quench.

      * If \MITOK{nonpriv}, only Echo and Echo Reply packets from that
        host are allowed.

    Note that when a \MITOK{between} routing record is used, the
    corresponding TOport value is used for packets travelling in the
    reverse direction.

\item[ifname, Iif, Oif:] an interface name, eg \MITOK{le0}; this must
    be an interface available to the router through \MI{NIT}, and must
    be mentioned in an \MITOK{if} record.

    The names \MITOK{none} and \MITOK{quench} are reserved and should
    not be declared as interface names in an ``if'' record.

\item[log:] log every packet matching this rule, whether blocked or
    routed.

\item[maxthpc:] the maximum throttle percentage.  If a link/route is
    being throttled (has a throttle in place and traffic is high enough
    to engage it) then this value (an integer in the closed (inclusive)
    range~0--100) determines the maximum percentage of link traffic
    that may be of this type, ie matching this rule.  This value only
    makes sense if used with \MITOK{throttle} rather than
    \MITOK{nothrottle} since it is ignored if traffic routes with the
    rule this is part of is not marked for throttling.  A rule marked
    for throttling but without a maxthpc value given is assumed to have
    a maxthpc of~100.

\item[proto:] a IP protocol number, or one of \MITOK{udp}, \MITOK{tcp}
    or \MITOK{icmp}.

\item[throttle:] include packets routed by this rule in any output
    throttling.

\end{description}

\section{Gateway Parameters}

The \MITOK{gateway} record is used to set a number of general
parameters for ExFilter, and is, in effect, mandatory.

The first parameter is the address ExFilter should use on outgoing
packets it generates such as on ICMP error packets (when packets are
denied passage through ExFilter, or when Source-quench messages are
being sent to regulate traffic through ExFilter).  You should allocate
an otherwise unused address from the same subnet as the firewall on one
of its interfaces for this, though you {\em may} get away with using
one of the firewall's own addresses.  ExFilter will appear as host
piggybacking an all the firewall's IP connections with this address, so
you might want to put up a DNS record for it for the benefit of remote
network administrators.

Then zero or more flags can be set to control gateway behaviour.
Although there are defaults, it is recommended that you set explicit
values for all the parameters.  As an example, to allow ExFilter to
generate ICMP error messages (eg for throttling), the parameter
\MITOK{icmperrs} can be supplied.  To turn it off \MITOK{noicmperrs}
can be supplied instead.

The meanings of the flags are:
\begin{description}

\item[\MITOK{decttl}:]  ExFilter decrements the `Time-To-Live' counter
    for packets it forwards, and discards packets whose TTL count has
    reached zero.  If ExFilter is a true gateway/firewall on you
    network, you should switch this on.  The default is
    \MITOK{nodecttl}.

\item[\MITOK{icmperrs}:] ExFilter sends `not-reachable' ICMP error
    messages out to the source of a packet it discards due to a
    \MITOK{deny} routing rule.  ExFilter also sends Source-quench ICMP
    error messages out to hosts sending too much traffic through
    ExFilter when the load on one or more connections is too high to be
    usable for interactive traffic.  You must have set a sensible and
    unique gateway address before enabling this.  The default is
    \MITOK{noicmperrs}.

\item[\MITOK{parallel}:] ExFilter discards any traffic sent to the
    network addresses of the host on which it is running, assuming that
    that host will deal with any such traffic itself.  This can be
    turned off with \MITOK{noparallel}, letting ExFilter examine all
    packets arriving at the interfaces, though this can be very
    CPU-intensive and require more complicated routing rules to handle
    properly.

\item[\MITOK{chksum}:] makes ExFilter check and generate IP header
    checksums in incoming and outgoing packets.  This should never
    normally be turned off, and is on by default.

\item[\MITOK{opts}:] lets ExFilter route packets with IP header
    options.  In fact, this is hardwired to \MITOK{noopts} for safety
    in this version of ExFilter.

\item[\MITOK{trace}:] turns on logging of all packets seen by ExFilter,
    and would only normally be wanted when debugging.  It is by default
    \MITOK{notrace}.

\end{description}

\section{Logging}

    ExFilter does most of its logging to the \MITOK{syslog}
    \MITOK{DAEMON} facility.  It logs information at five different
    internal levels (fatal, error, audit, information for tracing, and
    debugging) corresponding to the \TOK{syslog} levels \MITOK{ALERT},
    \MITOK{ERR}, \MITOK{WARNING}, \MITOK{INFO} and \MITOK{DEBUG}.

    ExFilter will log increasing amounts of information as its
    \MITOK{verbosity} level is increased.  Information logged at
    \MITOK{WARNING} and above relates to security and potential system
    failures and should find its way into audit trails and logs
    inspected from time to time by a human operator.  For example,
    warnings about packets that were `denied' transit by ExFilter are
    logged at \TOK{WARING} level.  Hourly stats reporting is also
    done at \TOK{WARNING} level.

    Information at \TOK{INFO} is of interest but not worth storing, so
    should probably go to the system console (throttling messages are
    logged at this level, for example), and \TOK{DEBUG} information
    will rarely be generated and you will probably want to make
    temporary changes to \TOK{syslog}'s configuration to capture it if
    you want it at all.

    The default level of \MITOK{verbosity} the system runs at is~1,
    which reports most important events and little else.  The level can
    be changes on the command line at start-up, in the configuration
    file, and with signals.

    In general, the volume of output increases as the \TOK{verbosity}
    increases.  The minimum level is~0 and the maximum~100.  Anything
    at~50 or above is really only for debugging the software, and~100
    will cripple the system with the amount of information generated,
    up to full dumps in hex of all packets seen.

    Although the exact levels may change in future, the following
    \TOK{verbosity} levels below~50 are currently implemented:
    \begin{description}

        \item[0:] Silent about all but major problems.

        \item[1:] All of~0 plus a few extra items.  This is the
            default.

        \item[2:] All of~1 plus description of interface configuration
            at start-up.

        \item[3:] All of~2 plus logging of line throttling going on and
             off.

        \item[4:] All of~3 plus reporting of overlong frames being
            dropped.

        \item[5:] All of~4 plus logging of setting up of routing
            tables.  This can be useful to ensure the machine
            interprets your routing instructions as you intended.

        \item[6:] All of~5 plus logging of ICMP Source Quench messages
            being sent.

        \item[7:] All of~6 plus logging of each packet being routed.

        \item[8:] All of~7 plus logging of each ARP-table lookup.

    \end{description}

\section{Signals}

    One aim of the design of ExFilter is to allow it to run non-stop.

    To change its configuration you do not have to kill it, change the
    configurations files and restart it, you can just update the
    configuration files and send ExFilter a signal with the
    \MITOK{kill} command to get it to reconfigure itself internally,
    dump statistics to the logs, etc.

    This causes minimal disturbance to the flow of data through
    ExFilter and thus to users of the filtered IP service.

    Those familiar with operation of the \MITOK{named} DNS/BIND
    d{\ae}mon will recognise the way that signals are used for
    interaction with ExFilter.

    When ExFilter starts it reads its configuration information from a
    file called \MITOK{/etc/ExFilter.conf}, of a format described
    above.  The ExFilter d{\ae}mon writes its process ID to a file
    called \MITOK{/etc/ExFilter.pid}.  This makes signaling the
    d{\ae}mon relatively painless.

    If you want to alter the configuration of ExFilter while it is
    running, edit the \TOK{/etc/ExFilter.conf} file appropriately, and
    send the ExFilter d{\ae}mon a `HUP' signal (see the UNIX manual
    pages for a discussion of the different signals and their original
    meanings) by issuing the shell command:

\begin{verbatimlisting}
    kill -HUP `cat /etc/ExFilter.pid`
\end{verbatimlisting}

    The full list of signals and their effects is:
    \begin{description}

    \item[HUP] reloads the configuration file \TOK{/etc/ExFilter.conf},
        and gets ExFilter to reconfigure itself as if killed and
        restarted.

    \item[INT] causes ExFilter to exit gracefully, after tidying up a
        little.  Useful if ExFilter is being run in the foreground on
        the command-line during testing or debugging.

    \item[ABRT] causes ExFilter to dump some loading and throughput
        statistics to the logs; ExFilter automatically does this every
        hour anyway.

    \item[TERM] causes ExFilter to exit immediately, with an error
        status.

    \item[USR1] increments the verbosity (debugging) level by one.

    \item[USR2] sets the verbosity level to zero.

    \end{description}

\section{Known Problems and Future Features}

There is a small number of known problems and missing features we would
like to provide in a future release.  These, and workarounds, are
listed below:
\begin{description}

\item[IP Packet Fragmentation]

    Packet fragmentation is not handled correctly, ie ExFilter cannot
    fragment outgoing packets going onto a connection with a smaller
    MTU than the packet.

    The solution it to ensure the MTU on all connections is either~$>=
    536$ for WAN connections (since most hosts should stick to a
    conservative MTU of~512 bytes plus IP header for non-local
    traffic), or ensure the MTU on all interfaces is the same (we
    ensure it is~1500 for all connections routed by ExFilter), so it
    need never fragment.

    Incoming fragments are handled correctly, but can be discarded if
    the `\MITOK{nofrag}' flag is used in the appropriate route
    description.

\item[Hard Limits]

    Currently ExFilter can handle a maximum of~256 \MITOK{route}
    routing directives and a maximum of~16 interfaces.  This is because
    the underlying tables are not dynamically sized.  A later release
    will fix this.  In addition, an interface name may not be longer
    than~16 characters, though under Solaris~1 this is never a
    problem.

\item[Quenching and \TOK{throttle}ing]

    ExFilter relies on sending ICMP Source-Quench messages to hosts
    that are originating large volumes of traffic that are overloading
    \MITOK{throttle}d links.  Some hosts (wrongly) ignore these
    messages and \MITOK{throttle}ing will not be able to regulate link
    traffic as well as it should.

    ExFilter keeps a small hashed table of hosts/ports to which it has
    recently sent quench messages to try to send a maximum of one such
    quench on each `connection' each second; this table may overflow
    with a large number of different end-points communicating.

    ExFilter cannot easily account for traffic originating to and from
    the firewall host itself, and such traffic will not be seen by the
    throttling mechanism and may allow the link to be more loaded than
    is desirable.  Minimise the volume of traffic to/from processes on
    the firewall machine to minimise this problem.

    In a future release regulation by round-trip time (RTT) will be
    added to help overcome some of these difficulties.

    ExFilter does not specifically recognise and expedite `interactive'
    packets at the moment, but the \MITOK{throttle} feature should be
    used to keep interactive performance reasonable at all times.

\item[Kernel-Directed Routing and ARP]

    ExFilter ignores all external routing information (is purely
    static) for security reasons.  It would be useful to have
    kernel-based routes followed when specifically allowed by ExFilter
    rules for non-critical traffic or for load sharing.  A copy of
    \MITOK{gated} or some other intelligent routing system can be run
    on the firewall to set the kernel routes.  A future release will
    allow this limited following of externally-supplied, dynamic
    routes.

    Note also that ExFilter relies on the kernel's ARP tables and
    broadcasts packets it cannot find and entry for in the host's ARP
    tables.

    Port-number range support will be added to the routing rules in a
    future release, in addition to the current fixed number,
    \MITOK{priv} and \MITOK{nonpriv} values.

\item[Multicast IP]

    ExFilter has not been tested for multicast IP.

\item[SNMP]

    SMNP monitoring is not provided, partly for reasons of security.

\item[Copying and Efficiency]

    Under Solaris~1 we run the router entirely in user space, so
    packets have to be copied into user space even to be discarded.  A
    Solaris~2 version will move as much as possible of the routing into
    the kernel in a loadable module.

\item[IP Header Checksum Generation]

    We do not currently use the RFC-recommended algorithm for checksum
    generation.  In practice this has not proven to be a problem, but
    we will switch to the `official' algorithm in a future release.

\item[IP Header Options]

    ExFilter will not route packets with IP header options.  This is a
    security measure to prevent circumvention of the filtering rules by
    non-obvious means.

\item[ICMP Error Messages]

    Under certain rare circumstances ExFilter may generate ICMP error
    messages for the second and subsequent fragments of a large packet.
    This is an error but a fairly innocuous one.

\item[NIT Interface Interaction]

    ExFilter will best be able to monitor and modulate throughput with
    the \TOK{throttle} directive if the underlying interface does not
    echo its output packets on the input side.  The supplied
    (unsupported) PPP has been modified to work this way.  Some Sun IP
    drivers work this way and some do not.

\end{description}


%==============================================================================
\chapter{Licence and Warranty Terms, and Contact Details}

This details the terms of the Right-To-Use (RTU) licence that you, the
Customer, have purchased directly or indirectly from us, ExNet Systems
Ltd for use of the software package called ExFilter~V1.1.3.

\begin{enumerate}

\item

    In case of trouble please refer first to the company you bought
    ExFilter from; they provide technical support and fixes and
    automatically forward to us those problems that we have to solve.

\item

    If you do contact us you must provide us with details of where and
    when you bought the software, which version you are running and in
    what environment (host and OS versions) and your serial number.  We
    will not provide technical assistance if you cannot provide us with
    a serial number, nor if your supplier or distributor can provide
    you with the assistance you require.

\item

    This agreement can only be varied or superseded by explicit notice
    in writing from a Director of ExNet Systems Ltd to the Customer.

\item

    When you purchase an RTU (Right-To-Use) licence, you purchase the
    right to execute at most one copy of the software for each RTU you
    purchase.  The RTU licence is non-exclusive and non-transferable,
    though with our explicit written consent, which will not be
    unreasonably withheld, you may transfer your licence to a third
    party; this automatically terminates your own licence for the copy
    or copies you have transferred, and confers any {\em remaining}
    period of warranty (if any) to the new licence holder.  Please
    note: you buy a licence to use the software, not the software
    itself, which remains the property of ExNet Systems Ltd.

\item

    You may, {\em for purposes of backup only}, keep more than one copy
    of the electronic and paper files and documentation provided; in no
    case will more than ten such copies be made of any file or
    document.

\item

    If you do have to come directly to us for assistance and your
    warranty has not expired, we will, at our sole discretion, replace
    your software or refund the list price of the RTU licence or the
    price you paid, whichever is the lower.  If your warranty has
    expired we will charge time and materials for any fixes you
    require, or offer you an upgraded version at a suitable discount
    where that will assist you and a suitable upgrade is available.

\item

    ExNet Systems Ltd warrants that the product supplied to you will be
    free of defects and fit for the purposes described in the
    accompanying manual for a period of one year from the date of
    purchase from a distributor or supplier authorised by us.

\item

    Our liability is strictly limited to the recommended retail (list)
    price of the software or the price you paid for it, whichever is
    the lower.  WE ARE NOT LIABLE FOR CONSEQUENTIAL LOSSES UNDER ANY
    CIRCUMSTANCES\@.
    
    Your first redress is against the supplier you bought the software
    from.

\item

    If you do not accept these terms, we do not allow you to use the
    software and you must return it immediately, unused, to your
    supplier.

\item

    You agree to submit to this agreement when you remove the software
    from the packaging it was supplied to you in, or execute any
    component of the software on any computer or examine the contents
    of any of the paper and electronic files and documentation that is
    part of this software package.

\item

    You may cancel this licence at any time by sending a notice to us
    and your suppliers (where possible) in writing confirming that you
    have destroyed all copies of the the software and related files and
    data.  Your RTU for the appropriate copy or copies of the software
    is then terminated.

\item

    If any clause of this agreement cannot be enforced in law it shall
    be deemed struck out and the other clauses shall still stand.

\item

    If ExNet Systems Ltd cannot fulfill any part of this agreement due
    to circumstances beyond its reasonable control (including, but not
    limited to, industrial action, natural disasters and Acts of God)
    it shall not be liable in any way for those failures.

\item

    This agreement is governed by the laws of England, and both parties
    agree to submit to the jurisdiction of the High Court of England,
    though ExNet Systems Ltd may enforce this agreement in any court of
    its choosing.

\end{enumerate}

\vfill

ExNet Systems Ltd, London, UK; tel:~+44~181~244~0077,
fax:~+44~181~244~0078, email:~\MITOK{info@exnet.com}.

\mbox{}
