
		    	Filter 2.0

Filter (filter.exe) is the part of Drawbridge that runs on a PC
and actually performs the packet filtering. It takes full control
of the PC once started and cannot be used in conjunction with any
other software.  DOS 5.0 is recommended. I haven't been able to
get NDIS + Drawbridge to work under DOS 6.22 (though I haven't
tried to find out what the problem was either.)

System Requirements
-------------------

Filter is a program written in ANSI C and Intel assembly language, and
compiled with Borland C++ 4.02 and Borland's Turbo Assembler 4.0.  It
will run on 386 class PC's and higher. It requires at least 2MB of
memory since it now uses XMS memory. 486 class machines and higher are
recommended for performance reasons.

The previous versions of Filter were coded to use only the Elite16
(8013) series of ethernet cards from SMC. This release now interfaces
to cards using the NDIS 2.01 API. Any card that has a DOS NDIS 2.01
driver can be used. Two cards are needed for Filter; one interfaces to
the internal network while the other interfaces to the external
network.

NOTE! The drivers for the cards *must* support promiscuous mode and
*must* allow you to configure the driver to support two cards in one
PC. They *must* also provide access to the native media framing (i.e.
802.3 emulation mode will NOT work on FDDI adapters; the driver must
provide access to FDDI frames). Be careful to confirm this before you
settle on any adapters. Some adapters do not support these features.
Most ethernet adapters do.

An executable version of Filter is supplied along with the source
code.  If you wish to modify and/or compile the code yourself you
will need Borland C++. (I recommend 4.02 or higher and Borland
Turbo Assembler 4.0 or higher though 3.0 will work.) The makefile
has been included. The compiling process should go quietly.

System Setup
------------

First, before you settle on certain cards make sure that the drivers
support the necessary features mentioned in the previous section. If
they do not support these features then you will not be able to use
these cards with Filter.

			vvvv NOTE vvvv

There is a bug in the SMC SMC8000.DOS drivers *at least* up to the
3.04 version that affects Drawbridge when used with two SMC cards.
You must specify that Filter's bindings (the Outside= and Inside=
lines) be *opposite* of what you want. This is not a problem if
you use only one SMC card and some other manufacturer's board.

SMC seems to be unwilling to fix this bug for me so for now if you
have a version of SMC8000.DOS later than 3.04, test it and if it is
still a problem please report it to SMC.

			^^^^ NOTE ^^^^

Next, configure your config.sys to load the NDIS Protocol Manager and
the driver for your cards. (This distribution of Drawbridge includes an
NDIS 2.01 tool ZIP file, and sample protocol.ini, autoexec.bat and
config.sys files.) Also enable HIMEM.SYS in your config.sys. This
enables XMS which is required by Filter. It also allows you to load DOS
high which I highly recommend.

Next, configure your protocol.ini file. All of the configuration for
Filter except for the password is in this file. Note that all
management occurs over IP now so you must allocate and assign an IP
address to Filter. Also, Filter does not listen to ICMP redirects so
choose your default gateway carefully.

The following is an example of how to configure the Drawbridge portion
of the protocol.ini file. An explanation of each parameter and its
settings follows. Note that IP addresses and MAC addresses must be
enclosed in double quotes.

[DRAWBRIDGE]
  DriverName = DRAWBRDG
  Listen = both
  Inside = SMC80002_NIF
  Outside = SMC8000_NIF
  IpAddress = "123.123.123.43"
  SubnetMask = "255.255.255.0"
  Gateway = "123.123.123.1"
  Manager = "123.123.1.2","123.123.23.3"
  NonIp = discard
  OtherIp = discard
  SuspectOffset = discard
  InternalMac = "08:01:01:01:01:01"
  Buffers = 40
  LogHost = "123.123.32.3"
  LogFacility = "local4"
  LogMask = 0x1FFEF

o DriverName
	This parameter must be included as shown.
o Listen
	This parameter can have the following values: both, inside, 
	outside. If the parameter line is commented out then network 
	management (and all IP functionality) is disabled.
o Inside
	This parameter tells Filter which NDIS driver to consider 
	the "inside".
o Outside
	This parameter tells Filter which NDIS driver to consider 
	the "outside".
o IpAddress
	This sets the IP address of Filter. Not necessary if network
	management is disabled.
o SubnetMask
	This sets the IP subnet mask if Filter. Not necessary if network
	management is disabled.
o Gateway
	The default router that Filter should use. Not necessary if
	network management is disabled. If there is no default gateway
	(i.e. you only have one network) you can comment out this
	line.
o Manager
	This parameter specifies the IP addresses that are allowed to
	manage Filter. Note that these IP addresses must also have the
	correct password for management to occur. If you comment this
	line out then no management will be allowed but the IP stack
	will be active (depending on the setting of Listen). There is
	a maximum of 10 managers allowed.
o NonIp
	This parameter controls whether MAC layer traffic other than 
	IP/ARP/RARP is passed by Filter. The possible settings are pass
	and discard. The default setting is pass.
o OtherIp
	This parameter controls whether IP layer traffic other than
	TCP/UDP/ICMP is passed by Filter. The possible settings are
	pass and discard. The default setting is pass.

	There is also some code included in the sources which filters
	all IP multicast. To enable it, see the note at the top of the
	makefile.  It is by default disabled since some important
	legitimate uses for IP multicast exist (OSPF for example).
o SuspectOffset
	This parameter controls whether TCP/IP fragments with suspect
	IP offsets should be passed by Filter. This is mainly used to
	protect internal machines that may have poorly written IP
	fragment reassembly routines. The possible settings are pass
	and discard. The default setting is pass since discarding these
	packets may (though it is highly unlikely) discard valid 
	traffic.
o InternalMac
	This is used exclusively for FDDI configurations. Refer to the
	discussion below concerning FDDI. It is not necessary for 
	Ethernet configurations.
o Buffers
	This parameter is rarely used. It controls the number of packet
	buffers Filter will attempt to allocate on start up. If you
	see an excessive number of dropped packets (via the Filter 
 	statistics) setting this parameter to a higher value *may* help.
	It defaults to 20.
o LogHost
	This enables logging of messages via the syslog mechanism to
	the specified IP address. If this parameter is not set then
	no syslogging of events occurs. To interpret the meaning
	of the syslog messages you just need to in general add
	"filtered" to the beginning of the message.
o LogFacility
	This sets the syslog "facility" to log the messages at. The
	default is "local0". Valid values are "local0" thru "local7".
o LogMask
	This sets the message mask for the syslog service. This
	controls which syslog messages Filter will actually send to the
	LogHost. Depending on the traffic on your network, you may be
	inundated by useless syslog messages when you enable syslogging
	with the default mask. The value is a hexadecimal or decimal
	number such as 0x1234ABCD or 305441741. The default value is
	0x1FFFF. This corresponds to all syslog messages generated
	being sent to the LogHost.

	The following table of syslog messages and values can be used
	to generate a mask. Just sum up the values for the messages
	you wish to receive and set LogMask to that value.

 Message					Hex Value  (Decimal)
 --------------------------------------------------------------------
 unknown event					0x00000001 (      1)
 incoming class D ...				0x00000002 (      2)
 outgoing class D ...				0x00000004 (      4)
 incoming port ...				0x00000008 (      8)
 outgoing port ...				0x00000010 (     16)
 outgoing via allow ...				0x00000020 (     32)
 incoming header too short ...			0x00000040 (     64)
 outgoing header too short ...			0x00000080 (    128)
 incoming via reject ...			0x00000100 (    256)
 incoming IP ...				0x00000200 (    512)
 outgoing IP ...				0x00000400 (   1024)
 incoming MAC layer protocol			0x00000800 (   2048)
 outgoing MAC layer protocol			0x00001000 (   4096)
 beginning filtering				0x00002000 (   8192)
 heartbeat (not currently used)			0x00004000 (  16384)
 incoming fragment with IP offset == 1 ...	0x00008000 (  32768)
 outgoing fragment with IP offset == 1 ...	0x00010000 (  65536)


Now create an autoexec.bat file that runs netbind.exe (an included NDIS
tool) and then starts filter.exe. If, when you run Filter it says that
it could not get the PROTOCOL.INI image from the Protocol Manager then
add readpro.exe after the netbind.exe. This may or may not be necessary
based on memory usage. I typically put filter in its own directory and
cd to it before starting it up. Filter writes and reads all files from
its current working directory on startup. An example autoexec.bat file
is included.

If you wish Filter to be securely managable immediately, then create a
file called PASSWORD in the same directory that will be the current
directory when Filter starts. Put an eight character white space
delimited password on the first line of this file.

Now you should be set to go.

NOTE: You should burn in a PC configuration before you start using it.
      You should also arrange for appropriate cooling and power for
      the PC before installing it. You may also want to have an extra 
      fully configured and tested PC as a backup in case of failures.

Using Filter
------------

Once you have configured and booted Filter, all management activity
occurs on the Filter Manager (fm) host. If you do not wish to use the
management software you can just take the output files from Filter
Compiler (fc) (using the byte reversal switch "-b") and then copy them
to the same directory on the PC that Filter is located. Note that
when the "-b" switch is used on fc the output filenames change to
what Filter expects them to be.

To halt Filter once it is running, just go to the keyboard and type
a '$'. This will cause Filter to exit and return you to the DOS
prompt.  If you never intend to access the PC physically once it
is installed and if your PC's BIOS supports it, you may be able to
remove the monitor, monitor card and keyboard.  If you do leave
the keyboard attached, it is suggested that you lock the keyboard
to prevent accidental halting of Filter.

To print statistics at the console of the PC, hit the 'S' key. (See
the MANAGER documentation for more discussion of the statistics.
They are the same ones that are reported via fm.) To clear the
statistics hit the 'C' key. Note that these are both capital letters.

Filter's syslog capability is primarily used for logging events
related to the filtering. In most cases, packets that are dropped
due to the filtering rules will cause a message to be logged to
the log host.

Problems With Filter
--------------------

Typically the most troublesome part of installing Drawbridge is getting
the NDIS drivers configured properly. The symptoms of this are a
binding error message from Filter when it tries to start up. It varies
wildly from manufacturer to manufacturer as to how to install their
driver for two cards. Sometimes you must list the driver twice in the
CONFIG.SYS file and sometimes you must put odd syntax in the
PROTOCOL.INI file to get the Protocol Manager to recognize both cards.

Also, Filter was developed against the SMC Ethernet driver and the
Network Peripherals FDDI driver and has not had much exposure to other
drivers. It may still require some minor tweaks for your particular
driver. Send email to drawbridge@net.tamu.edu if you think this might
be your problem.

Filter on FDDI
--------------------

The main problem with Filter on FDDI is with the FDDI media itself.
When an FDDI card sends a packet onto an FDDI ring it relies on
the source address in the packet to pull it back off. This breaks
when you are trying to transparently bridge (the source address is
rarely that of the sending card's). There are a couple of recommended
techniques for doing it but they all involve hardware support. To
date I have not found any cards that support this.

The configuration that will work is shown below. The Filter acts
as a "smart wire" between two routers (a rather expensive option).

                            Internet
                               |
                               |
                            Router 1
                          -----+------
                         |outside ring|
                          -----+------
                             Filter
                          -----+-----
                         |inside ring|
                          -----+-----
                            Router 2
                               |
                               |
                         Campus Network

You must disable bridging on the two involved interfaces of the
routers. Then you put the MAC address of Router 2 on the PC's FDDI
card connected to Router 1 and vice versa. Note that you cannot
have any other devices on the two rings. You can't even manage any
FDDI concentrators that you may use. This whole configuration
relies on the fact that on the outside ring the source address of
all packets that Filter receives will *always* be that of Router
1. The same thing applies in reverse to the inside ring.

You may also wish to consider Fast Ethernet (which of course doesn't
have this problem) but we didn't want to take the hit of the smaller
MTU sizes (1500 bytes) between our campus FDDI and our Internet
connection (4470 bytes each). Fast Ethernet cards *should* work
with this version of Drawbridge (though none have been tested).

If you do wish to use FDDI then you must use Filter's InternalMac
switch in the PROTOCOL.INI file. This sets up a "fake" MAC address
that Drawbridge will use for management. You must also override
the MAC addresses on the FDDI cards such that the address on one
card is the MAC address of the router on the *other* card's ring.

To date, we have only been able to make FDDI boards from Network
Peripherals work. 3Com FDDI boards definitely do not work due to
problems with the NDIS drivers.

