# @(#) configfilespec 1.30@(#) E% #

This outlines the format of a dhdfilter configuration file.

It consists of a series of 1-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 1) 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 are valid:

 1) # (starts a comment record)

    The content of such records is ignored.

 2) thottleto (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.

    You can optionally specify a maximum working round-trip time (RTT)
    (for minimal-length ping messages) in milliseconds and an IP
    address to send the ping messages to (for PPP links this defaults
    to the other end of the link).  For fast links 50ms would be a good
    value to preserve interactive response as this represents about
    half the 100ms budget for interactive operations.  This will have
    to be set higher for slow links or 64kbps or less.  There is no RTT
    assumed if one is not specified, since you may not be interested in
    interactive response times.  If you have specified an RTT you may then
    optionally specify a maximum (integer) factor by which the
    bytes-per-second thoughput value may be scaled up or down to allow
    for compression (or lack of) on the link.  The throughput value is
    increased until the RTT is exceeded and decreased until it is
    within bounds.  If no scale limit is supplied it is assumed to be 2
    (two).

    The aim is to avoid saturating slow connections like PPP links to
    ensure reasonable responsiveness of interactive traffic.  Excess
    traffic is quenched, or queued in the router, or dropped depending
    on the amount of excess, though certain specified types of packet
    (eg ntp packets) can bypass any queueing for minimum delay.

    By default any traffic that the filter can see passing through the
    link (eg even incoming traffic to the host not being routed) is
    included in the throttle calculations.

    Records referring to interfaces not mentioned in an ``if'' record
    are ignored.

 3) verbosity (starts a verbosity record)

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

 4) if (starts an interface-name record)

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

    The interface names ``none'' and ``quench'' are reserved.

 5) route (starts a routing record)

    An ordered list 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.

 6) gateway (starts a gateway record)

    Sets overall parameters for the gateway.

 7) arp (starts an arp record)

    Analagous to kernel routing table static routes; describes which
    hosts are directly routed to from one of our interfaces and which
    go through another machine.  Used during ARP to establish when we
    should try to get the Ether address of the gateway machine rather
    than the host itself.  Only used when talking over Ethernet rather
    than point-to-point links where no Ether address is needed.

 8) statstonews (starts a stats-to-news record)

    Gives the newsgroup(s) and distribution to dump stats reports to
    and whether to dump them on every SIGABRT or only hourly.


Valid record syntax (non-literal parameters are brackets <thus>):

  * # <any text>

  * throttleto <ifname> <Bps> [ <RTT> [ <scalefactor> [ <TOaddr> ] ] ]

  * verbosity <percentage>

  * if <ifname>

  * route
        deny|allow
        <Iif>|any <Oif>|any
        <proto>|any
        from|between
        <FRaddr>|any <FRmask>|any|only <FRport>
        to|and
        <TOaddr>|any <TOmask>|any|only <TOport>
        [ [no]count ]
        [ [no]fragment ]
        [ [no]log ]
        [ [no]throttle[<maxthpc>] ]

    (default options: count fragment nolog throttle)

  * gateway IPaddr
        [ [no]chksum ]
        [ [no]decttl ]
        [ [no]icmperrs ]
        [ [no]parallel ]
        [ [no]opts ]
        [ [no]trace ]

    (default options: chksum nodecttl noicmperrs parallel noopts notrace)

  * arp TOaddr TOmask VIAaddr

  * statstonews newsgroups distribution [ [no]everysig ]

    (default options: noeverysig)

count: bypass any traffic throttle but still count the bytes in packets
    routed with this rule for the throttle so that in effect these
    packets have priority but shouldn't cause the throttle value to be
    exceeded.

distributions: one or more distributions in exactly the format of a
    USENET news article; multiple distributions are separated with
    commas.  If you want world distributions you'll have to say so
    explicitly since an empty field isn't allowed; `local' would be
    more typical.

FRaddr, IPaddr, TOaddr: a dotted-quad host or net address.

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

FRmask, TOmask: a dotted-quad mask in the style of a netmask; 1 bits are
    those that will be matched.

FRport, TOport: port number; ``any'' is any port, ``priv'' is any port <
    1024, and ``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:

      * ``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 `nonpriv'' only Echo and Echo Reply packets from that host
        are allowed.

    Note that when a ``between'' routing record is used, the
    corresponding ``TOport'' value is used for packets travelling in
    the reverse direction.

ifname,Iif,Oif: an interface name, eg ``le0''; this must be an
    interface available to the router through nit, and must be
    mentioned in an ``if'' record.

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

log: log every packet matching this rule.

maxthpc: the maximum throttle percentage.  If a link 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 (eg matching this rule.  This value only makes sense if
    used with ``throttle'' rather than ``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.  Packets
    matching this rule can match any unused bandwidth upto the throttle
    value, but may be delayed until it has been determined that that
    bandwidth is otherwise unused.

newsgroups: one or more newsgroups in exactly the format of a USENET
    news article; multiple newsgroups are separated with commas.

proto: a protocol, numeric or one of ``udp'', ``tcp'', ``icmp''.

RTT: round-trip time in milliseconds.

throttle: include this packet in any output throttling.
