Drawbridge 3.1
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 while allowing custom
filters 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 code, the
Drawbridge Manager, and the Drawbridge Filter Compiler. These three
components run on a FreeBSD system where the filter code is built into the
kernel and the manager and compiler are user level applications.
REQUIREMENTS
This version of Drawbridge will work with FreeBSD 3.4-RELEASE or
4.0-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.
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) and contain the same information as the
COMPILER and MANAGER files. Documentation for FreeBSD is available at the
FreeBSD web site .
HISTORY
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 code 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.
The compiler may still be run on another system if desired. 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
in 3.x 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 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 1.x and 2.x 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
for wich the package is built.
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. 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 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 ISA 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 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 for
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 probably create a small swap 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 FTP 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. In
fact, if you installed from CD-ROM, you may have to skip this
step because there appears to be a bug in the installer that
makes it impossible to switch the installation media from CD-ROM
to FTP.
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 ' where 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.
CONFIGURATION AND USAGE
After the kernel configuration, the system will finish booting. During
the boot sequence, you will see the message "Drawbridge is not configured -
edit /etc/rc.conf". You must edit the /etc/rc.conf file before Drawbridge
will initialize and function. The mandatory variables that you will need
to set in the rc.conf are "db_inside_if" and "db_outside_if". The config
variables in rc.conf are discussed below.
db_enable=
Should be self explanatory, set to "YES" to enable Drawbridge or "NO" to
disable Drawbridge.
db_inside_if=
db_outside_if=
These variables must be set to the device names of the network interface
cards that you are using for the inside and outside connections. This
might be a good place to mention that only one of the devices can have
an IP address assigned to it.
db_ifconfig_inside_if=
db_ifconfig_outside_if=
These two are optional. They may be used to issue ifconfig statements
to the inside and/or outside interface devices. For example, depending
on the device, you could set both to "mediaopt full-duplex" to enable
full duplex operation for both interfaces.
db_mirror_mode=
If you install Drawbridge between two switches using full duplex
connections, then you can't easily monitor the traffic flowing through
Drawbridge. To make traffic monitoring possible, you can mirror packets
to a third interface. This variable determines which packets will be
sent to the mirror interface. It may be set to one of the following:
DISabled - no packets
InSide - packets received or sent by the inside interface
OutSide - packets received or sent by the outside interface
BRidged - packets which are forwarded between interfaces
FILtered - packets which were discarded by any filter
FILtered_InSide - packets which were discarded by an inside filter
FILtered_OutSide - packets which were discarded by an outside filter
BRidged_FILtered - any forwarded or discarded packet
BRidged_FILtered_InSide - any forwarded or discarded by inside filter
BRidged_FILtered_OutSide - any forwarded or discarded by outside filter
db_mirror_if=
If you have configured mirroring, set this to the device name of the
third network interface card.
db_ifconfig_mirror_if=
May be used to issue ifconfig statements to the mirror interface device.
db_listen_if=
This variables controls whether the FreeBSD kernel will see packets from
the Drawbridge interfaces. The possible values are 'none', 'inside',
'outside', or 'both'. If set to 'none', then no packets from either
interface will be passed up to or down from the kernel protocol stack.
This means no packets, not even arp. The Drawbridge host will be
completely isolated from outside communication or attack but at the cost of
remote management and DNS name resolution (unless you run named on
Drawbridge). A setting of 'inside' will allow packets to/from the inside
interface only to be received/sent by the kernel. Conversely, 'outside'
will allow packets to/from the outside interface only. And as you would
expect, a setting of 'both' allows the kernel protocol stack to receive/
send packets to/from either interface. Setting this variable only makes
sense if you have an IP address assigned to either the inside or outside
interface.
db_log_facility=
Controls which syslog facility Drawbridge will use for syslog messages.
It may be set to any valid syslog facility such as "user", "daemon", or
"local0".
db_log_mask=
Controls which syslog messages will be generated by Drawbridge. The value
of the mask is a hexadecimal or decimal number such as 0x123ABC or 1194684.
The default log mask is 0 which disables all filter messages. Each filter
message may be enabled or disabled by setting or clearing the appropriate
bit in the log mask. See the MANAGER doc file or type "dbmgr help set
logmask" at the command prompt for details.
db_filters_file=
Specifies the location of the compiled filter file to be loaded at boot
time.
The Drawbridge startup script is located in /usr/local/drawbridge/etc/rc.d
and is called 'start.sh'. All of it's input is taken from the /etc/rc.conf
variables so you shouldn't have to make changes to it.
The Drawbridge documentation may be found in /usr/local/drawbridge/doc
after installation. The filter configuration file is located in
drawbridge/etc and is named 'filter.config'. There's 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 an example shell
script called 'update' in the drawbridge/etc directory that will compile
and load the filter configuration.
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 '.
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 make it easy to install ssh, there's a shell script in /usr/local/
drawbridge/src/ssh-port called install_ssh.sh which will do all the work
for you. It will automatically retrieve the source via FTP, compile it,
and install ssh. Before running the script, you must be logged in as root,
be connected to the network, have "listen" set correctly, and have the
filters set to allow ftp and name resolution to Drawbridge. If the script
still can't ftp the needed source files, then try disabling drawbridge by
typing "dbmgr stop" at the shell command prompt and then run the script.
After ssh is installed, you must either reboot or start sshd by hand.
After that, 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 and the listen interface set correctly.
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/config-
directory and edit the file DRAWBRIDGE using the file LINT as a guide.
Information about configuring a FreeBSD kernel may be found at
. After that, type 'make patched'
in the directory drawbridge/src/kernel. Make your changes/patches to
drawbridge/src/kernel/sys and then run 'make' in drawbridge/src/kernel.
To install the new kernel, type 'make install'.
SECURITY
One of the primary requirements of a firewall is that it be invulnerable
to attacks. Because Drawbridge 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 code and never make it past the interface layer
of the kernel.
o The filter code resides in the interface layer of the kernel, just
above the hardware drivers. All incoming and outgoing packets must pass
through the filter code, including packets addressed to the Drawbridge
system itself. Ports may be opened or closed for the Drawbridge host
just like any other host on the internal network. For the Drawbridge
host, 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 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 from the time the monitor was started, not since
Drawbridge was started. Use screen to keep a monitor running if you want
long term peaks.
o In order to syslog to an external host, you will have to edit the file
/etc/rc.conf and remove the line that says 'syslogd_flags="-s"'. See the
syslogd man page for information about the -s parameter.
o Drawbridge is no longer limited by IP classes so you can now specify any
host IP in the filter config file using the 'host' or 'network' commands.
However, as before, you are still limited to defining filters for inside
hosts only. This is because the filters are unidirectional. Only the
dest address of incoming and the src address of outgoing packets are
checked. If you specify the address of an outside host with the 'host'
or 'network' command, no filters will be applied to the address so it
will effectively be ignored. There are plans to implement bidirectional
filters along with source/destination combination filters in the future.
o Entries in the bridge table are not "aged" and never expire. You can
clear the bridge table with the command 'dbmgr clear bridge'.
o The spanning tree bridge protocol is not currently implemented. It may
be implemented in the future so that two identical drawbridge firewalls
may be installed in parallel for redundancy. If one failed, the other
would take over.
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 or use the new port mirroring feature.
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.x was written by:
Russell Neeper
Much of the code was derived from Drawbridge 2.x 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.