
		  Filter Compiler 1.0 (Beta Release)

The filter compiler (fc) is used to compile source files into the
tables used by the Filter portion of the Drawbridge filtering package.
This document will cover the source language and running the compiler.

Filter Language
---------------

o Comments

A comment starts with a '#' and extend to the end of line.  Comments
can appear anywhere.

o Service Specification

The basic element of the language is a service specification.  The
service specification contains four pieces of information: the
service, protocol, source or destination, and traffic direction.  The
service can be either an entry from /etc/services, or a numeric port.
Service ranges can also be used.  The protocol specifies the protocol
the service uses.  This can be any recognized protocol, but the
compiler currently will silently ignore anything but UDP and TCP.  If
unspecified, the default is TCP. The source or destination indicates
whether the filter should use the source port or the destination port.
The default is destination port.  Finally, the traffic direction
indicates whether this is for outbound packets or inbound packets,
or both.

Examples:

        <smtp in-out>		# Allow smtp connections, either direction.
        <1-65535 out>		# Allow all outbound connections.
	<ntp/udp in>		# Allow UDP based network time protocol.
	<src=ftp-data in>	# Allow data connect for outbound ftp.

Certain combinations are accepted, but will generate no output, as the
filter currently does not use them.  For example, since the filter does
not do outbound UDP filtering, the specification <!tftp/udp out> will
be ignored by the compiler.  See the paper FILTER for more information on
what filtering is available.

Prefacing the service specification with an exclamation mark, ('!'),
indicates that this service is not allowed.  The section on 'Combining
Service Specifications' explains what this means.

Examples:
	<!tftp/udp in>		# No tftp!!
	<!login in>		# Never allow rlogin
	<!2049/udp in>		# NFS usually lives here... don't allow it in

o Groups

Groups of service specifications can be defined to prevent having to
repeatedly entering the same data and introducing typos.  Groups can
also be used to quickly change the access characteristics of an entire
set of machines.  A group is a list of comma separated service
specifications or other previously defined groups, terminated by
a semicolon (';'). For example:

	define normal <smtp in>, <gopher in>;

This example creates a group called 'normal' which includes inbound SMTP
and inbound GOPHER..  This group can be used in other groups to
build up larger groups:

	define server normal, <telnet in>;

In this example, the new group 'server' includes SMTP, GOPHER and TELNET
in.

The special group 'default' is used to define access class #0, which
is the default access for any machine not explicitely defined in the
config file.  For example:

	define default <1-65535 out>, <src=ftp-data in>, <smtp in>;

Allows all outbound connections, email in and ftp's data connections in
for all machines which do not appear in the config file.  Normally,
all machines in the config file will want the default services as
well, therefore, group 'default' should be added to the machines
in the config file.

o Defining Host Access

To define the access for a particular host, simply give the hostname
and a comma separated list of service specifications and/or group
names.

	host myhost default, normal;
	host newshost default, <nntp in>;

Using the previous definitions for normal and default, host 'myhost'
will have:
	<1-65535 out>, <src=ftp-data in>, <smtp in>,
	<gopher in>, <telnet in>;

and host 'newshost' will have:
	<1-65535 out>, <src=ftp-data in>, <smtp in>,
	<gopher in>, <nntp in>;

o Defining Network Access

If you want to specify access for an entire range of addresses, you
can use the 'network' command, which is similar to the `host' command.

        #       Address range              Netmask
	network 123.45.67.0-123.45.68.255 255.255.255.0 <!1-65535 in-out>;
	network 123.45.69.0               255.255.255.0 <!1-65535 in>;

The first entry allows no TCP connections *in* or *out* for
123.45.67.* and 123.45.68.*.  The second allows no incoming connections
for 123.45.69.*.  Notice that the second example is an implicit range
of 123.45.69.0-123.45.69.255.  In the first example, you must fully specify
the full range.  For example, the range 123.45.67.0-123.45.68.0 would *not*
include the hosts 123.45.68.1-123.45.68.255.

If a host is defined in more than one 'host' or 'network' command, the
last one is the one that is used (this will generate an error/warning
in later versions).

o Combining Service Specifications

When multiple service specifications appear in a group definition or
host/network command, they are merged.  Service specifications are
merged by 'or'ing the _allowed_ services, then _REMOVING_ those which
are explicitly disallowed.  For example:

	define group1 <telnet in>, <!login in>, <!tftp/udp in>;
	define group2 <telnet out>, <smtp in>, <login in>;
	define group3 group1 group2 <tftp/udp in>;

'group3' will have <telnet in-out>, <smtp in>.  Note that even though
'group2' allows <login in>, it is not possible to override the
<!login in> specified in 'group1' (the same applies to 'tftp').  In
addtion, 'group3' inherits the <!login in>.  In other words, the
actual value of group3 is:

	<telnet in-out>, <smtp in>, <!login in>, <!tftp/udp in>

Also notice that the <telnet in> and <telnet out> in the combined group
are equivalent to <telnet in-out>.

o Generation of Classes

As a host's access capability is specified, either by use of a 'host'
or 'network' command, classes of hosts are generated.  All the members
of a specific class have the same access allowed to them.  It doesn't
matter in what order the accesses were given, only that in the end,
they have the exact same access.  There can be up to 256 different
classes, with class 0 reserved for those hosts which are not specified
in the config file.  Class 0's capabilities are defined by the special
group 'default'.  Each class can have up to 32 port *ranges* for each of
incoming TCP, outgoing TCP, incoming TCP srcport and incoming UDP.
'fc' automatically merges adjacent service specifications into ranges.

o Other Commands

	include filename

You can break the config file up and include the separate files to create
the filter control files.

	include part1;
	include part2;

Nesting is allowed up to memory capabilities... include loops are
detected. 


	reject address netmask

Reject all incoming packets coming from a network address.

	reject 18.23.0.0 255.255.255.0;

The upper limit on the number of reject networks is currently small [8?].


	allow address netmask [service-specification list];

Allow outbound packets to this destination, even if the access for
the source host doesn't allow it.  The expected use of the 'allow'
subcommand is in situations where a restricted machine is being
granted to a network service.  For example, if lab PC's normally
do not have access to the Internet, the 'allow' subcommand can allow
these machines to access a service on a specific machine/network.


The Compiler
------------

The compiler 'filtgen' generates the filter control tables from the
config file.  These tables can then be loaded into the filter using
the 'fm' command.

Usage:  filtgen config-file

The compiler will write out a few statistics on number of classes and
how big the tables are within them.  It will also create the file
'class_tables' which contains the classes and is about 128k.  Also, a
file will be created for each IP network found in the file.  The size
of these files will depend on the class of the network.  A class C
network will generate files around 260 bytes, and class B will
generate files around 65540 bytes.  The names of the network file will
be the IP address of the network in dotted decimal format.  The
network files contain the indices into the class tables for each host
on that network.  Note that if you have multiple networks, you will
still only have one set of class tables.  Note that 'network', does not
mean 'network' commands.  This means any network which is referenced
via a 'network' or 'host' command.

Output files of importance:
	class_tables		# Contains class tables
	(networkaddr)		# One for each network in config file.
	reject_table		# Any 'reject' rules
	allow_table		# Any 'allow' rules

# Example config file
#------------------------------------------------------------------------
#
# Defaults for any machine not listed in this file.
#
define tcpdefault <1-65535 out>, <src=ftp-data in>, <smtp in>, <auth in>,
		<gopher in>;
define udpdefault <1-65535/udp in>, <!tftp/udp in>, <!2049/udp in>, 
	<!sunrpc/udp in>;
define default tcpdefault, udpdefault;

# Include 'default' in telftp since most will need defaults as well.
define telftp default, <telnet in>, <ftp in>;

# Admin requested no access in/out for these subnets
network 123.45.58.0 255.255.255.0 <!1-65535 in-out>;
network 123.45.39.0 255.255.255.0 <!1-65535 in-out>;
network 123.45.40.0 255.255.255.0 <!1-65535 in-out>;
#------------------------------------------------------------------------
# 
host m1.dt.tamu.edu		telftp, <domain in>;
#------------------------------------------------------------------------
# NNTP host and CSO phonebook server
host mailnews.tamu.edu		telftp,
				<nntp in>, <time in>,
				<csnet-ns in>, <domain in>,
				<finger in>;
host slow.tamu.edu		telftp;
host previous.tamu.edu 		telftp, <domain in>;
host mvt.tamu.edu		telftp;
# IRC server on here...
host ick.tamu.edu		<1-65535 out>, <6667 in>, <smtp in>, <auth in>,
				udpdefaults;
#
# Machine (PC) in library which use tftp to do document transfers
host sender.tamu.edu		<1-65535/udp in>;
#------------------------------------------------------------------------
host h1.tamu.edu		default, telftp;
#------------------------------------------------------------------------
# These are all the VMS machines which have been cleared for telnet/ftp.
host h2.tamu.edu		telftp;
host h3.tamu.edu		telftp;
host h4.tamu.edu		telftp, <domain in>; # zone transfers
host h5.tamu.edu		telftp;
host h6.tamu.edu		telftp;
host h7.tamu.edu		telftp;
host h8.tamu.edu		telftp;
host h9.tamu.edu		telftp;
host h10.tamu.edu		telftp;
# Research group using port 4211
host h11.tamu.edu		telftp, <4211 in>;
host h12.tamu.edu		telftp;
host h13.tamu.edu		telftp;
host h14.tamu.edu		telftp;
# NTP time server
host h15.tamu.edu		telftp, <ntp in>, 
				<time in>;
#------------------------------------------------------------------------
host s1.tamu.edu		telftp;
host fast.tamu.edu		telftp;
host dunno.tamu.edu		telftp;
host meat.tamu.edu		telftp, <finger in>;
# A PC FTP server
host somepc.tamu.edu		default, <ftp in>;
# Has to have X11
host arrow.tamu.edu		default, <ftp in>, <6000 in>;
host d2.tamu.edu		default, <ftp in>;
host trouble.tamu.edu		default, telftp;
#
host td.tamu.edu 		default,
				<ftp in>, <auth in>, <domain in>;
# No access in/out
host bee.tamu.edu		<!1-65535 in-out>;
host g1.tamu.edu		<!1-65535 in-out>;
host see.tamu.edu		<!1-65535 in-out>;
host bam.tamu.edu		<!1-65535 in-out>;
# NTP server
host bird.tamu.edu		default, <ntp in>, <time in>;
#------------------------------------------------------------------------
# Gotta have X...
host gotta.tamu.edu		default, <6000 in>;
host be.tamu.edu		default, <6000 in>;
host very.tamu.edu		default, <6000 in>;
host slow.tamu.edu		default, <6000 in>;
#------------------------------------------------------------------------
# More name servers for subdomains
host add.tamu.edu		default, <domain in>;
host bigadd.math.tamu.edu	default, <domain in>;
#
host dead.tamu.edu		telftp;
#
host someone.tamu.edu		default, <ftp in>;
# Nuclear Engineering
host hot.tamu.edu		default, <ftp in>;
#
# Robotics Lab.   For demo. until 12/19?
host sp1.dt.tamu.edu		telftp,
				<2650 in>, <2655 in>, <2700-2702 in>,
				<3200-3202 in>, <3300-3302 in>, <3500-3502 in>;

# Local MUD's
host someklingon.tamu.edu		default, <2000 in>;
host hmmmmm.tamu.edu			default, <2000 in>;


