
		    Filter Manager 1.0 (Beta Release)

Filter Manager (fm) is a tool for managing a PC running the Filter
portion of the Drawbridge filtering package. It allows you to load
new tables into the Filter and inspect them.

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

Currently fm can only run on Sun4 systems running SunOS 4.1.X with a
kernel that has the Network Interface Tap (NIT) driver configured in.
No other platforms or packet drivers are currently supported though
ports are planned.

If you can not meet these system requirments, you can bypass fm and
just copy the fc output files to the PC with a floppy. See the FILTER
file for more details.

How To Install
--------------

You can either build fm with a "make" in the fm directory or just copy
the executable that is included. Note that the code for fm is ANSI C so
you will need an ANSI compiler to compile it (it has only been tested
under the GNU C Compiler so far). The executable can be installed
anywhere and does not need any support files but does need to be
installed setuid root. fm stays root only long enough to open the
network interface and then setuids to the real user.

How To Use
----------

o Introduction

fm is an interactive program modeled after lpc. It provides more
feedback and help than your typical Unix tool however. The following is
the usage for fm:

fm [-i <interface>]

fm will pick a likely device on the machine if no interface is
specified. (You can use the "netstat -i" command to figure out which
interface to use.) Make sure that you choose the interface that is
physically connected to the same network that the PC running Filter is
physically connected to. If fm's standard input is not a tty it will
not print any information out on standard output but will still send
error messages to standard error.

o Commands

Once you have started fm, you can use "help" or "?" to get help. The
following is a list of supported commands:

        set (verbose|target|key) <args>
        load (network|classes|allow|reject) <filename>
        show (host|class|allow|reject|target|verbose|key) [<args>]
        query (host|class|allow|reject|stats) [<args>]
        upload (networks|classes|allow|reject)
        write
        release (classes|allow|reject|network) [<args>]
        ping
        reboot
        clear
        reset
        newkey <name>
        genkey <name>
        quit

A "#" at the beginning of a line comments the entire line. Also,
"!" can be used as a shell escape. If you type "help command", fm will
print help about that particular command.

o Caveats

To communicate with Filter, you will need to tell fm the Ethernet
address of the Ethernet card on the PC that is connected to the same
network as you. This is done using "set target". You must specify the
correct card or you will not able to communicate with Filter. Also the
Filter must be on the same bridged network as the managing host since
fm uses a non-routable protocol (to prevent remote routed attacks).
And lastly, make sure that Filter was started up with the correct
switches to enable communication with fm. (See the file FILTER.)

When Filter is first run, it will not have any tables loaded and will
apply default rules for all packet filtering. You must build a
configuration file and use Filter Compiler (see the file COMPILER) to
generate the filtering tables from there.

Filter will also not be using DES by default. You can use the
"newkey" command in fm to install a key in Filter to enable DES.
This will create a ~/.fmkey.[name] file which will hold your DES
key.  (Note that newkey will perform a "set key <name>" command
implicitly.) In this first case the key will go across the network
unencrypted though all subsequent "newkey" generated keys will be
encrypted with the previous key. If you are extremely concerned
about security, you can use the "genkey" command and copy the first
DES key to the Filter PC using a floppy.

DES is only used for authentication and NOT to encrypt every packet.
This is used to prevent spoofing of the fm host or the Filter. All
filter data goes across the network unencrypted except for sequence
numbers which are used for the authentication. An exception to this
rule is when a new DES key is installed. The new key is encrypted
with the current key before it is sent across the network.

o Using Tables

Once you have created filtering tables with the Filter Compiler (fc),
you load them into fm with "load" commands.  You can load multiple
networks into fm but only one each of classes, allow and reject tables.
Each table is loaded in with separate "load" commands.  You can inspect
these loaded tables with the "show" command.

Once you are satisified with the loaded tables, you can load the
information into Filter using the "upload" command.  Note that "upload
networks" will upload all of the networks at once. Once the uploaded
information has been successfully transfered, it will take immediate
effect.  However, it will not be made permanent until you issue a
"write" command which will tell Filter to write its currently loaded
tables to disk.

You can inspect what Filter currently has loaded with the "query"
command.  It's usage is analogous to the "show" command but queries
loaded tables in Filter, not fm.

If at some point you wish to delete tables loaded into Filter you can
use the "release" command. This command takes effect immediately and
deletes the tables from disk. The Filter will revert to default
behavior for the deleted tables until new ones are loaded.

o Configuration Files

fm reads the file ~/.fmrc on startup and executes all commands
found in that file. The .fmrc file usually just contains a "set
target" command so that you can communicate with the filter
on startup of fm. For example:

set target 00:00:C0:B8:BE:43

If you are using DES, you can also add a "set key" command to the .fmrc
file so that you do not have to do a "set key <name>" command everytime
you startup fm.

The ~/.fmkey.* files contain DES keys so that you can manage Filter in
a secure manner. Note that it is assumed that a machine that is running
fm in the secure mode is itself secure. Otherwise the key can be stolen
and Filter accessed without your knowledge. If you happen to lose your
DES key on the fm host, then you must go to the filter and delete the
DES.KEY file. This will put Filter back in the insecure mode.

Both ~/.fmrc and ~/.fmkey.* files must be in mode 400 or fm will complain.

o Miscellaneous

You can use the fm "ping" command to determine if you can talk to the
filter. The "reboot" command can be used to cause Filter to cold boot
the PC. Note that the AUTOEXEC.BAT file on the PC must be configured
to correctly restart the Filter for this to work effectively.

The "reset" and "clear" commands can be used to reset fm. The "reset"
command completely resets the internal state of fm and causes the .fmrc
file to be reread. The "clear" command only causes the currently loaded
tables to be unloaded.

Future Improvements
-------------------

Planned future improvements for fm include

1.) Making fm portable.
2.) Providing support for other packet drivers.
3.) Improving the reliability of the protocol.
4.) Supporting statistics reporting.
