User Manual: Installation and Configuration
From BroWiki
Contents |
Download
Download Bro from: [1]
You can unpack the distribution anywhere except into the directory you plan to install into. To untar the file, type:
tar xzf <current-bro-release>.tar.gz
Install
For a stand-alone (default) Bro 1.5 installation:
Navigate to the expanded source directory
> cd /path/to/bro/source/distribution
By default Bro is installed in /usr/local/bro.
This location
is referred to in the rest of the manual as $BROHOME.
To install Bro in a location other than @file{/usr/local/bro}, use:
> ./configure --prefix=/path/to/bro
By default Bro uses the version of libpcap that is installed on the system. If your system version older than version 0.7.2, you can run configure Bro with --enable-shippedpcap to use the version of libpcap that comes packaged with Bro. For example:
> ./configure --enable-shippedpcap
Then type:
> make > make install-broctl
The installation installs three configuration files which you should edit:
$BROHOME/etc/broctl.cfg is the overall _BroControl_ configuration. Initially, you probably only need to edit the email address for mails sent by the framework; that's the +MailTo+ line.
In $BROHOME/etc/nodes.cfg, you need to specify the network interface Bro is to monitor; that's the +interface+ line.
In $BROHOME/etc/networks.cfg, list all the networks which Bro should consider as local to the monitored enviroment.
Once you have updated these files, install the modified configuration:
> broctl install
Some tasks need to be run on a regular basis. Insert a line like this into your crontab:
0-59/5 * * * * /usr/local/bro/bin/broctl cron
Finally, you can start Bro:
> broctl start
Install (old)
You'll need to collect the following information before beginning the installation.
- localnets: a list of local subnets for your network. Bro needs to know which networks are "internal" and which are "external".
- interface names: the names of the capture interfaces in your host (e.g. sk0 or en1). Use
ifconfig -ato get the list of all network interfaces on your Bro host.
If you want to use Bro's periodic email report feature, you'll also need:
- email list: a list of email addresses to send the reports to.
- PGP keys: if you want to encrypt all email reports, the location of the
GPG keyring of all recipients.
Bro is easy to install. Log in as root, and type:
./configure
By default Bro is installed in /usr/local/bro.
This location
is referred to in the rest of the manual as $BROHOME.
To install Bro in a location other than @file{/usr/local/bro}, use:
./configure --prefix=/path/to/bro
By default Bro uses the version of libpcap that is installed on the system. If your system version older than version 0.7.2, you can run configure Bro with --enable-shippedpcap to use the version of libpcap that comes packaged with Bro. For example:
./configure --enable-shippedpcap
Then type:
make make install
or
make install-brolite
Use make install to install all the Bro binaries and policy script files. Use
make install-brolite to also run the configuration script (described in the next section) and install all the configuration files and cron jobs. make install can be run as any user, but make install-brolite requires
you to be root.
To update an existing Bro installation with new binaries and standard policy files, instead
of "make install" do a "make update". This will preserve all your local customizations.
Then add $BROHOME/bin and $BROHOME/scripts to your $PATH to use
Bro's utilities and scripts.
Also note that this documentation is installed in $BROHOME/docs as both HTML and PDF versions.
Bro Configuration
The Bro-Lite configuration script can be used to automatically configure (or reconfigure) Bro for you. It
checks your system's BPF settings, creates a "bro" user account, installs
a script to start Bro at boot time, installs the report generation package,
and installs a number of cron jobs
to checkpoint Bro every night, run periodic reports, and manage log files.
To run this configuration script type:
bro_config
This script creates the file @file{$BROHOME/etc/bro.cfg}.
bro_config will ask a number of simple questions. Note
that the full functionality of this script is only supported
under FreeBSD. Some additional configuration may need to be
done by hand under Linux.
Sample output of bro_config, along with explanation, is shown below:
Running Bro Configuration Utility Checking interfaces .... Done. Reading /usr/local/bro/etc/bro.cfg.example for defaults.
The bro_config script looks first at ./bro.cfg, then /usr/local/bro/etc, for default values to use below.
Bro Log archive location [/usr/local/bro/archive]
This is the directory where log file archives are kept. If you expect the log files to be very large, it is recommended to put these in a separate disk partition.
User id to install and run Bro under [bro] bro_config will create a new user account with this username if the user does not exist. Interface names to listen on. [en1,en2] bro_config looks for all network interfaces and does a short test to determine which interfaces see the most traffic, and selects these interfaces as the default. Site name for reports (i.e. LBNL, FOO.COM, BAZ.ORG) [] Starting Report Time [0600] Report interval (in hours) [24] Email addresses for reports [bro@localhost]
Daily reports will be created. Enter the site name you want to appear at the top and in the subject of all email reports. The "start time" and "interval" define the window of network activity that the daily report will cover, starting at "Starting Report Time" and lasting through "Report interval". The start time should be entered using 24hr clock notation. For example: 12:30AM = 0030, 2PM = 1400
Do you want to encrypt the email reports (Y/N) [N] Y
If you want the email reports encrypted, you will need to set up GPG ([2]) and create a GPG keyring containing the public keys of all email recipients. Instructions for this are in Encrypted Reports. require GPG, not PGP}.
Running script to determine your local subnets ... Your Local subnets [198.129.224.1/32]
Bro needs to know a list of your local subnets. bro_config runs a tool that attempts to discover this automatically. You should always verify the results of this tool. The format is a list of subnet/significant bits of address. For example: 131.243.0.0/16, 198.128.0.0/18, 198.129.224.1/32 This information will be stored in the file $BROHOME/site/local.site.bro
Saving settings to file: /usr/local/bro/etc/bro.cfg Bro configuration finished. To change these values, you can rerun bro_config at any time.
Indicates that the script finished successfully.
For site monitoring very high traffic rates on Gigabit Ethernet, there is some additional system tuning that should be done. See the Performance Tuning section for more details.
To reconfigure Bro, run:
BRHOME/scripts/bro_config
This will update your /usr/local/bro/etc/bro.cfg file. You can also edit this file using your favorite editor if you prefer.
For other site customizations, you can edit the file $BROHOME/site/brohost.bro. For example, to tell bro to not look at traffic for host 198.162.44.66, add:
redef restrict_filters += {
["ignore host 198.162.44.66 "] = "not host 198.162.44.66"
};
More details are available in the section on Customizing Bro.
OS Configuration
This section contains information on critical OS tuning items. More detailed tuning information can be found in the section on Performance Tuning.
FreeBSD Configuration
The standard FreeBSD kernel imposes a per-process limit of 512 MB of memory. This is not enough for most Bro installations.
To check your current limit type:
limits -H
Unfortunately the only way to increase this limit in FreeBSD 4.x
is to reconfigure and rebuild the kernel.
In FreeBSD 5.x it is much easier. Just increase
kern.maxdsiz in /boot/defaults/loader.conf and reboot.
For example:
kern.maxdsiz="2G"
and look at the datasize setting, which should be the same
as your amount of RAM. If this is not true, see section Hardware and OS Tuning
for information on fixing this.
For FreeBSD 5.3+, BPF devices are no longer created using MAKEDEV, but rather are
created on demand. This is configured automatically by running 'make install-brolite',
or you can figure it by hand by adding the following to /etc/rc.local
devfs ruleset 15 devfs rule add 15 path 'bpf*' mode 660 user bro
Linux Configuration
You may want increase these for a high traffic environment.
not done: need to get recommended values for these:
/proc/sys/net/core/rmem_default (IP-Stack socket receive queue) /proc/sys/net/core/rmem_max (similar to rmem_default) /proc/sys/net/core/netdev_max_backlog (queue between driver and socket)
Encrypted Reports
Bro can use GPG ([3]) to encrypt the reports that it sends. To have Bro encrypt your reports you must have said "yes" to the bro_config question to encrypt your reports. Then each email recipient much generate a public/private key pair, and their public key must be installed on the Bro machine in the home directory of the user running the Bro process.
To create a key-pair:
gpg --gen-key
To export the public key:
gpg --armor --output mykey.gpg --export myemail@address.com
Then login to the machine running Bro and import the list of public keys:
gpg --import mykey.gpg
Then you must to make the list of keys "trusted" so that they can be used to encrypt the email reports. To do this, you must edit the key to add "ultimate" trust to the key.
gpg --edit-key myemail@address.com
pub 1024D/4A872E40 created: 2001-02-05 expires: never trust: -/f sub 3072g/B72DD7FE created: 2001-02-05 expires: never (1). Some R. User <myemaill@address.com>
Command> trust pub 1024D/4A872E40 created: 2001-02-05 expires: never trust: -/f sub 3072g/B72DD7FE created: 2001-02-05 expires: never (1). Some R. User <myemail@address.com>
Please decide how far you trust this user to correctly verify other users' keys (by looking at passports, checking fingerprints from different sources...)?
1 = Don't know 2 = I do NOT trust 3 = I trust marginally 4 = I trust fully 5 = I trust ultimately m = back to the main menu
Your decision? 5 Do you really want to set this key to ultimate trust? yes
pub 1024D/4A872E40 created: 2001-02-05 expires: never trust: u/u sub 3072g/B72DD7FE created: 2001-02-05 expires: never (1). Some R. User <myemail@address.com>
Command> quit
For more information on GPG see [4]
Generating Reports on a Separate Host
Warning: this section assumes a reasonably high level of Unix system administration skills!
If your site has lots of traffic, lots of connections, or if Bro is using on average more than around 40% of your CPU, you'll want to use a second host for generating reports.
To do this, on the Bro host, run bro_config, and say "N" to all report generation questions. Then install Bro on the second host using the following:
./configure make make install-reports
Then follow the instructions in Bro Configuration for setting up report generation.
You'll also need to set up a method to copy files from the Bro host to the report generation
host. One way to do this is using rsync, and the Bro script push_logs.sh
does this for you. For example, you can set up a cron job
like this on the Bro host:
1 1 * * * (push_logs.sh /usr/local/bro/etc/bro.cfg host:/home/bro) >> /tmp/bro-push.log
To make sure your rsync command has time to transfer
all log files before your report generation
script is run, the push_logs.sh script is designed to be used with the scripts
frontend-site-report.sh and frontend-mail-report.sh on the frontend host.
These frontend scripts wait for a file with a particular name to exist before running.
It is also important to use the nice
command to help ensure the network copy does not unduly divert processing away from Bro.
You may want to rsync the log files over a secure ssh connection. To do this,
you need to first generate a ssh key pair on the Bro capture host with no passphrase:
ssh-keygen -t rsa -C "batch key" -f ./batch.key
Put this in user bro's .ssh/config file, also on the Bro capture host
Host recvhost brohost.foo.com IdentityFile ~/.ssh/batch.key
On the frontend host where the log files will be processed, add batch.pub to the authorized_keys file
cat batch.key.pub >> authorized_keys
Then create a cron entry on the Bro capture host
1 1 * * * nice -n 20 rsync -e 'ssh' -azv \ /usr/local/bro/logs host:/home/bro
|
Overview of Bro | Requirements | Installation and Configuration Running Bro | Bro Output | Analysis of Incidents and Alarms | Customizing Bro Intrusion Prevention Using Bro | Performance Tuning | Bulk Traces and Off-line Analysis |
