Exercise: Getting Started

Note: Our current website is at www.zeek.org. This website is unmaintained and contains outdated information.

Note: In this exercise, "<PREFIX>" represents the Bro install directory. Also, if you already have Bro compiled and installed on your machine, then skip to step 5 below.

Configure Bro source code.

In order to build Bro, there are some other packages that must first be installed on your system. For RPM/RedHat-based Linux, you need these packages: cmake, make, gcc, gcc-c++, flex, bison, libpcap-devel, openssl-devel, python-devel, and swig. For DEB/Debian-based Linux you need: cmake, make, gcc, g++, flex, bison, libpcap-dev, libssl-dev, python-dev, and swig. For FreeBSD you need: cmake, swig, bison, and python. For Mac OS X you need: cmake and swig.

There are some optional dependencies (you can build Bro without these, but if available they provide additional functionality). For RPM/RedHat-based Linux, these are: zlib-devel, file-devel, GeoIP-devel, sendmail, and libcap. For DEB/Debian-based Linux, these are: zlib1g-dev, libmagic-dev, libgeoip-dev, sendmail, and libcap2-bin. For FreeBSD these are: GeoIP. For Mac OS X, these are: libmagic and libGeoIP.

Next, you need to "cd" into the top-level Bro source directory where the "configure" script is located.

By default, Bro will be installed into "/usr/local/bro", but this normally requires superuser privileges, so for this exercise we will choose our own install path (if you follow this example, then substitute "<PREFIX>" throughout the rest of this exercise with "~/install"):
```
./configure --prefix=~/install
```
If the last line of output contains the text "Build files have been written to:", then configuration should be complete. However, if you see an error, then check that you have all required dependencies and try again.
Compile Bro.

Next, compile the Bro source:
```
make
```
After a few minutes, it should complete successfully.
Install Bro.

Next, install Bro:
```
make install
```
Bro should now be installed.
Set privileges on Bro (Linux only).

If you are not running Bro on Linux, or if you want to run Bro as the "root" user, then skip this step.

Bro needs certain privileges to capture network traffic, but it does not need all privileges of the "root" user. On Linux, you can run this command to set the necessary privileges (if you don’t do this, then you would usually need to run Bro as the "root" user):
```
sudo setcap cap_net_raw,cap_net_admin=eip <PREFIX>/bin/bro
```
Update PATH.

To test that everything is setup correctly, the following command should report the installed version of Bro (should be "2.0-beta" or newer):
```
bro -v
```
If the correct version of Bro is not shown, then update your PATH environment variable and try again:
```
export PATH=<PREFIX>/bin:$PATH
bro -v
```
Run BroControl.

BroControl is an interactive shell that is a convenient way to manage Bro.

Before using BroControl, you must determine which network interface Bro should monitor. If it is not "eth0", then you will need to edit the "<PREFIX>/etc/node.cfg" file, and change the line "interface=eth0" with the correct network interface for Bro to monitor.

Also, normally you should edit the "<PREFIX>/etc/broctl.cfg" file and make any needed changes (such as changing the "MailTo" email address), but for this exercise this is not necessary.

Start up BroControl:
```
broctl
```
The first time that you run BroControl, you must install the BroControl configuration:
```
[BroControl] > install
```
Next, start an instance of Bro:
```
[BroControl] > start
```
You can check the status of Bro (make sure you see the word "running" under the "Status" column):
```
[BroControl] > status
```
If you want to stop Bro before exiting BroControl, you must issue the "stop" command:
```
[BroControl] > stop
```
Check to see that Bro is no longer running (you should see the word "stopped" under the "Status" column):
```
[BroControl] > status
```
There are many more commands available in BroControl. To see a list, use the "help" command:
```
[BroControl] > help
```
When done using BroControl, you can exit using the "exit" or "quit" commands:
```
[BroControl] > exit
```
Look at Bro log files.

If you look in the "<PREFIX>/logs" directory, you should see a subdirectory named with today’s date (in the form YYYY-MM-DD). In that subdirectory, you should see various log files (all of them are gzipped) that were copied to this directory when Bro was stopped. To see what a log file looks like, choose one (here we use the "dns" log file) and run this command:
```
gunzip -dc <PREFIX>/logs/2011-11-08/dns.* | less
```
Run Bro directly.

If you don’t want to use BroControl, then you can run Bro directly. When you run Bro directly, it creates its log files in the current working directory. Therefore, it is a good idea to create a temporary directory so that you can more easily see which files are generated by Bro:
```
mkdir brotmp
cd brotmp
```
Bro can capture live network traffic, or it can read a packet capture (pcap) file. In this exercise, we will read a pcap file dns-session.pcap:
```
bro -r dns-session.pcap
```
You should see a variety of log files produced by Bro. These logs are not gzipped, so you can look at them directly.

You can delete these log files when you are done.