                        
                           Drawbridge 3.0 Release

INTRODUCTION

Drawbridge is a firewall package that was developed at Texas A&M University
and was designed with a large academic environment in mind.  It is a
copyrighted, but freely distributable, bridging IP packet filter with a
powerful filter language and good performance.  It's greatest strength is
the ability to perform high speed packet filtering for a large number of
individual hosts within an intranetwork.  It uses a constant-time table
lookup algorithm so it can provide the same level of packet throughput
regardless of the number of filters defined.  Drawbridge is composed of
three components: the Drawbridge filter engine, the Drawbridge Manager, and
the Drawbridge Filter Compiler.  These three components run on a FreeBSD
system where the filter engine is built into the kernel and the manager and
compiler are user level applications. 


REQUIREMENTS

This version of Drawbridge will work with FreeBSD version 2.2.6-RELEASE,
2.2.7-RELEASE, or 2.2.8-RELEASE.  The Drawbridge FreeBSD system runs on a
dedicated industry standard PC with at least 8 megabytes of memory, 120
megabytes of hard disk, and 2 network interface cards.  The recommended
configuration consists of a 100MHz or faster processor, 16 megabytes of
memory, a 250 megabyte or larger hard drive, and PCI network interface
cards.  Both Ethernet to Ethernet and FDDI to FDDI configurations are
supported.  A list of supported hardware may be found on the FreeBSD web
site in part 1 section 2.1 of the FreeBSD handbook.  Please note that not
all network cards have been tested with Drawbridge 3.x.  If you find one
that doesn't work, please let us know.  Cards which are known *not* to work
with Drawbridge 3.x due to driver issues are:  3Com 3c505 Etherlink+, cards
using the 'ie' driver (Intel 82586 chip set), and cards using the 'wl'
driver (wavelan cards).


DOCUMENTATION

The Drawbridge web site is <http://drawbridge.tamu.edu/> and all of the
documents mentioned in this readme file may be found there.  To get an idea
of how Drawbridge works and how it is used, take a look at the background
information available in the document tamu-security.pdf.  It describes
Drawbridge in detail and outlines the philosophy behind the entire suite of
TAMU security tools.  Unfortunately, this document is out of date and
discusses an older version of software but the concepts still apply.  You
may also find the documents filtering.pdf and firewall.pdf of interest.
The Drawbridge Filter Compiler and filter language are documented in the
file COMPILER.  The Drawbridge Manager is documented in the file MANAGER.
All of these files may also be found in the Drawbridge doc directory after
the package is installed.  The man pages for the compiler and manager are
installed as dbfc(8) and dbmgr(8).  Documentation for FreeBSD is available
at the FreeBSD web site <http://www.FreeBSD.org>.


CHANGES

Version 2.x of Drawbridge ran on a dedicated DOS system with NDIS drivers
and required a remote unix system for the management software and compiler.
Version 3.x has been completely rewritten for the FreeBSD operating system
and no longer requires a remote unix system for management.  The new
Drawbridge filter engine has been integrated into the FreeBSD kernel and
the Drawbridge Filter Compiler (dbfc) and Drawbridge Manager (dbmgr) can
now both be run on the Drawbridge FreeBSD system as user level applications.
Information about the changes to the code may be found in the CHANGES
document in the doc directory.  The filter language has also undergone a
few slight changes so if you are currently using Drawbridge 1.x or 2.x, you
will need to modify your filter configuration file before it will compile
on 3.x.  See FIL_LANG_CHANGES in the doc directory for details.


AVAILABILITY

Information about the current version of Drawbridge may be found at the web
site <http://drawbridge.tamu.edu>.  The latest version of Drawbridge may be
found on the anonymous ftp site net.tamu.edu in the directory
/pub/security/TAMU along with the previous versions.  Unlike the previous
versions, Drawbridge 3.x is distributed as a FreeBSD package and is not
intended to be uncompressed and untarred directly.  Instead, it should be
installed by using the FreeBSD installation program during the system
installation or by using the pkg_add utility immediately after the system
is initially set up. 

If you retrieve the Drawbridge package via ftp or http, you need to be sure
to get the correct package file for the version of FreeBSD that you are
planning to use.  The format of the package name is "drawbridge-x.x-y.y.y"
where 'x.x' is the Drawbridge version and 'y.y.y' is the FreeBSD version
that the package is built for. 


INSTALLATION

This section contains information needed to install FreeBSD for Drawbridge
and the Drawbridge package.  It does not include general information about
FreeBSD.  If you are unfamiliar with FreeBSD, you should start by reading
the FreeBSD handbook <http://www.freebsd.org/handbook/>.  The installation
section of the handbook will explain where to get FreeBSD.  The requirements
section of this document lists the supported versions of FreeBSD.  You
should try to install one of these versions from an ftp site near you.  If
you are unable to install from one of the official FreeBSD sites for some
reason, you may install from <ftp://net.tamu.edu/pub/FreeBSD>.  FreeBSD
should be installed with a custom distribution set consisting of the bin
files, the man pages, and the kernel sources.

These instructions assume that you will be installing FreeBSD via FTP but
you may install from other media if you wish.  It is also assumed that you
will be installing the Drawbridge package at the same time as FreeBSD but
you may also use the pkg_add utility after installing FreeBSD.  If you
choose to use pkg_add to install Drawbridge, be sure to get the correct
Drawbridge package for the version of FreeBSD that you are using.

IMPORTANT:  The Drawbridge package makes changes to files in the system /etc
directory and therefore should not be installed on an existing system that
has already been customized.

The first step is to assemble the Drawbridge computer based on the hardware
requirements listed previously.  For the install, you will need to connect
one of the network interface cards to your network.  Once you have obtained
the FreeBSD boot disk image and created the boot disk, follow these steps:

o Boot the Drawbridge computer from the FreeBSD boot disk.  The kernel
  config options will be presented.  If you are using PCI network interface
  cards, you may press ENTER or Q to bypass this step for now.  If you are
  using ISA NIC's, you will probably have to configure the kernel.  Visual
  mode is the recommended choice.  Note that the generic kernel on the boot
  disk supports only one NIC of each type so configure the kernel for the
  IRQ and IO settings of the NIC that you have connected to your network.
  The generic kernel will later be replaced with the Drawbridge kernel
  which supports two of each type of NIC.

o After finishing with kernel configuration, the system will boot and you
  should now see the FreeBSD installation main menu.  Read the 'Usage'
  section to become familiar with how to navigate the menu system.  You may
  also want to read the 'Doc' section containing FreeBSD installation
  instructions.  Keep in mind that you will be doing a custom install to
  support Drawbridge.

o Select 'Custom' from the main menu.  You should see the custom install
  options.  You will need to go through each item of this menu except for
  'Options'.  The menu items are listed in the following steps.

o Partition - Since this computer will be dedicated to Drawbridge, use the
  'A' option to select the entire disk for FreeBSD.  Answer NO to the
  question about using a true partition entry.  Press 'Q' when done.
  
o Label - If you have a 300MB drive or larger, the best option is 'A' to
  automatically setup the disk label.  If your drive is smaller than 300MB,
  then you should create a small swap of around 8MB and allocate the rest
  to the root file system.  Press F1 if you need help with this section.
  Press 'Q' when done.

o Distributions - Select 'Custom' distribution set.  You will see a list of
  available distributions to install.  You must select the required 'bin'
  distribution.  You should also select 'man' and 'src'.  On the src
  sub-menu, select 'sys'.  When you are done, exit back to the custom
  install menu.

o Media - For an FTP install, select 'FTP' from the media menu.  Choose an
  FTP site near you from the available list.  If you are unable to install
  from an official FreeBSD site, you may select 'URL' and enter
  ftp://net.tamu.edu/pub/FreeBSD.  After selecting the site, you will be
  asked to select a network interface card and then configure it.

o Commit - This will actually perform the partitioning and formatting of
  the hard drive and install FreeBSD.  After the installation finishes, you
  will be asked if you want to go to the general configuration menu.  You
  should select yes.  

o You should now see a list of configuration options.  Most of the options
  are not relevant for a Drawbridge system.  You may wish to set the time
  zone and the root password at this time.

o From the Configuration Menu, select 'Media', and change the installation
  media to the URL ftp://net.tamu.edu/pub/FreeBSD.  Back at the Configuration
  Menu, select 'Packages' and then 'All'.  Mark the Drawbridge package for
  installation.  You may also mark bash and screen for installation if you
  like.  When you are done, press enter and then select 'Install'.  Each
  package will be installed and you will be returned to the config menu.
  (Note: you may skip this step if you wish and install the Drawbridge
   package manually using pkg_add after the system first boots).

At this point you are finished with the installation.  Return to the main
menu and select 'Exit Install' and the system will reboot.
 
If you skipped the step to install the Drawbridge package during the FreeBSD
installation, you should install it now using the pkg_add utility.  To do
this, retrieve the correct Drawbridge package from ftp://net.tamu.edu/pub/
security/TAMU/ or a mirror site and and copy it to the FreeBSD system that
you just set up.  Alternately, you may retrieve the Drawbridge source code
and build the package yourself by typing 'make package' in the top level
source code directory.  After you have the Drawbridge package, as root, type
'pkg_add <pkgname>' where <pkgname> is the name of the Drawbridge package.
When pkg_add completes, reboot the system.

When the Drawbridge package was installed it replaced the kernel so you
will need to go through the kernel configuration procedure one more time.
You should not skip this step this time even if you are using PCI network
cards.  Using visual mode, you should disable any devices that you are not
using and configure any devices necessary.  Note: PCI devices are listed in
the PCI section so PCI NIC's will not show up in the 'network' section.
PCI devices can not be disabled.  When done, 'Q' will quit and save.

After the kernel configuration, the system will finish booting.  During the
boot process, the Drawbridge startup script will be executed.  Drawbridge
should now be up and running.

If you ever need to compile a custom kernel, change to the directory /usr/
local/drawbridge/kernel, edit the Drawbridge kernel config file 'DRAWBRIDGE',
and type 'make'.  To install the new kernel, type 'make install'.


ACCOUNTS

When the Drawbridge package was installed, it created the two accounts
'manager' and 'monitor'.  These accounts are disabled by default.  To
enable the accounts, simply set a password for them.  It is recommended
that you enable and use the 'manager' account for day-to-day operations.
The 'monitor' account has read only access to the system and to Drawbridge
and can be enabled to allow others to view system information and stats
without the ability to make changes.  To set a password for these accounts,
login as root and type 'passwd <account name>'.


CONFIGURATION AND USAGE

The Drawbridge files may be found in /usr/local/drawbridge.  The first
thing that you should do is login and look at the documentation files in
the directory drawbridge/doc.  The filter configuration file is located in
drawbridge/etc and is named 'filter.config'.  There is also a sample
filter config file in the same directory called 'sample.filter.config'.
Using the information found in the compiler documentation, you should edit
the filter.config file for your environment.  After editing the file, it
must be compiled using the Drawbridge filter compiler (dbfc).  The
compiler will generate the output file 'db_filters'.  The compiled filters
are then loaded by using the Drawbridge Manager (dbmgr).  There is a shell
script called 'update' in the drawbridge/etc directory that will compile
and load the filter configuration.

The Drawbridge startup script is executed each time the system boots.  It
is located in drawbridge/etc/rc.d and is called 'start.sh'.  It performs
the following functions: sets the log facility and mask, initializes
Drawbridge, loads the compiled filters file 'db_filters' from
drawbridge/etc, sets operational flags if any, and starts Drawbridge.

The startup script makes certain assumptions.  It assumes that the
interface that has been configured with an IP address is the 'inside'
interface and that the other interface is the 'outside' interface.
(Drawbridge requires that only one of the two interfaces be configured
with an IP address).  It also assumes that 'listen' should be enabled for
the inside interface and disabled for the outside interface.  There are no
discard flags set by default (see MANAGER documentation for info about the
discard flags).  If this behavior is not correct for your environment, you
will need to edit the startup script to suit your needs.


REMOTE MANAGEMENT

Because the Drawbridge firewall will most likely be placed in a machine
room or other inaccessible location, remote management is usually a
necessity.  In order to maintain a high level of security, the recommended
method of accessing the Drawbridge system remotely is with the Secure Shell
(ssh) package.  Information about ssh may be found on the ssh home page
<http://www.cs.hut.fi/ssh/>.

To install ssh, login as root and change to the drawbridge/src/ssh-port/ssh
directory.  Type 'make USA_RESIDENT=YES install' or 'make USA_RESIDENT=NO
install' depending upon whether you are a United States resident or not.
(This has to do with export restrictions and copyrights).  The ssh package
will automatically be retrieved via FTP, compiled, and installed.  Keep in
mind that the Drawbridge host must be able to retrieve the ssh package over
the Internet so you should either install ssh before you put Drawbridge into
production or set the 'listen' mode to 'outside' or 'both' (see the MANAGER
documentation).

After rebooting, all you need to do to use ssh is add the ssh public keys
of the people that should have access to an account to that account's
'.ssh/authorized_keys' file.  The ssh port (port 22) will also need to be
opened for the IP address of the Drawbridge system in the filter.config file.


SOURCE FILES

After installation, the full Drawbridge source code is available in
/usr/local/drawbridge/src.  If you need to build a new kernel for some
reason, you should cd to the drawbridge/src/kernel/<version> directory, edit
the file DRAWBRIDGE using the file LINT as a guide, and then type 'make
install' in the directory drawbridge/src/kernel.  Information about
configuring a FreeBSD kernel may be found at <http://www.freebsd.org/
handbook/>.


SECURITY

One of the primary requirements of a firewall is that it be invulnerable
to attacks.  Because Drawbridge now runs on unix, some would say that
makes it insecure.  This was taken into consideration during the design.
There are several layers of protection built into the FreeBSD version of
Drawbridge to protect the system against attack: 

o The listening interfaces can be controlled, just like in the DOS
  version.  Packets may be allowed from the inside, outside, both, or
  neither interfaces.  If listening is disabled for an interface, packets
  from that interface which are addressed to the Drawbridge system will be
  dropped by the filter engine and never make it past the interface layer
  of the kernel.  If listening is disabled for both interfaces, the system
  will be completely isolated from the network.

o The filter engine resides in the interface layer of the kernel, just
  above the hardware drivers.  All incoming and outgoing packets must pass
  through the Drawbridge filter code, including packets addressed to the
  Drawbridge system itself.  Ports may be opened or closed for the
  Drawbridge system just as they may be for any other host on the internal
  network.  (For packets addressed to Drawbridge, both network interfaces
  are considered to be on the 'outside' while the kernel and the rest of
  the system is considered to be on the 'inside').

o When the Drawbridge package is installed, portmapper, inetd, sendmail,
  ftp, and all other daemons are disabled and all ports to the outside
  shut down.  If you want to manage the system remotely, you will have to
  specifically allow access.  Though it couldn't be included in the
  Drawbridge package, ssh (secure shell) should be used for remote access
  if desired.  Ssh can encrypt packets to/from Drawbridge and should
  provide a reasonable level of security for remote management. 


GENERAL COMMENTS

o On the dbmgr monitor stats page, the peak values for packets/sec and
  bits/sec are peaks since the monitor was started, not since Drawbridge
  was started.  Use screen to keep a monitor going if you want long term
  peaks.

o If you want to syslog to another computer, you will have to edit the file
  /etc/rc.config.local and remove the line that says 'syslogd_flags="-s"'.
  See the syslogd man page for information about the -s parameter.

o Drawbridge does not yet understand CIDR (Classless Inter-Domain Routing)
  blocks and is still based on the network class system.  Currently, the
  Drawbridge compiler automatically determines a host's network class, and
  thus the network size, by looking at the first few bits of the host
  addresses specified in the config file.  A future version of Drawbridge
  is planned, possibly 4.0, to be based on CIDR blocks instead of network
  classes.

o Entries in the bridge table are not "aged" and never expire.

o Spanning tree is not implemented.  Because Drawbridge is a firewall,
  there should never be a redundant bridge path so spanning tree is not
  considered necessary.

o If a host name in the filter config file is not defined in DNS, the
  compiler will stop with an error.  This will probably be changed to
  a warning in a future version.

o The compiler will not work with host names that resolve to multiple IP
  addresses.  In this situation, the IP addresses should be specified in
  the filter config file instead of the host name.

o Logging can significantly slow performance.  The best method for logging
  is to use another computer on the outside of the firewall to monitor
  traffic.

o The AttackICMP filter detects the smurf/pong attack and fragmented ICMP
  packets usually used to flood a host.  This filter was added because of
  local need and is not intended to catch all types of ICMP attacks.


CONTACTS

Any and all feedback on the Drawbridge package is welcome.

There is a mailing list for questions and discussion about Drawbridge.
To subscribe, send email to drawbridge-request@net.tamu.edu and put the
word subscribe in the the subject line.  When you subscribe, a welcome
message containing information about the list and how to use it will be
sent back to you.

The use of the mailing list is highly encouraged but, if for some reason
you would like to keep your suggestions or comments private, mail can be
sent directly to the maintainers at drawbridge-owner@net.tamu.edu.

Drawbridge 3.0 was written by:

Russell Neeper

Much of the code was derived from Drawbridge 2.0 which was designed
and written by:

David K. Hess
Douglas Lee Schales
David R. Safford

----
FreeBSD is copyrighted by The Regents of the University of California.
Drawbridge is copyrighted by Texas A&M University.
