Drawbridge 3.0b2
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 requires FreeBSD version 2.2.5-RELEASE or
2.2.6-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 network cards may be found on the FreeBSD web site along with
more specific information about the hardware requirements. (The 3Com 3c505
Etherlink+ is not supported by Drawbridge because the driver does not
support promiscuous mode). Please note that only a few network cards have
been tested with this version of Drawbridge so if you find one that doesn't
work, please let us know.
DOCUMENTATION
The Drawbridge web site is 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 .
CHANGES
The previous versions 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 . 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 . 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 . 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. They also assume 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.
WARNING: 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.
This kernel will be replaced by the Drawbridge package with one that
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 we 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'.
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 To install the Drawbridge package, first 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 find bash and screen
useful. When you are done, press enter and then select 'Install'.
Each package will be installed and you will be returned to the config
menu.
At this point you are finished with the installation. Return to the main
menu and select 'Exit Install' and the system will reboot.
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 '.
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
.
To install ssh, login as root and change to the drawbridge/src/ssh-port
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.
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 need to be opened for the IP address of the
Drawbridge system in the filter.config file.
SOURCE FILES
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 directory, edit the file DRAWBRIDGE using the file
LINT as a guide, and then type 'make install'. Information about
configuring a FreeBSD kernel may be found at .
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
bytes/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. Future versions of Drawbridge
will probably 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 and
there should never be a redundant bridge path, this is not 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 really slow performance. The best method for logging is to
use another computer on the outside of the firewall.
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.