==============
Installing Bro
==============

Prerequisites
=============

Bro relies on the following libraries and tools, which need to be installed
before you begin:

    * CMake 2.6 or greater              http://www.cmake.org

    * Libpcap (headers and libraries)   http://www.tcpdump.org

    * OpenSSL (headers and libraries)   http://www.openssl.org

    * Libmagic  For identifying file types (e.g., in FTP transfers).

    * Libz      For decompressing HTTP bodies by the HTTP analyzer, and for
                compressed Bro-to-Bro communication.

Bro can make uses of some optional libraries if they are found at
installation time:

    * LibGeoIP  For geo-locating IP addresses.

Bro also needs the following tools, but on most systems they will
already come preinstalled:

    * BIND8 (headers and libraries)
    * Bison (GNU Parser Generator)
    * Flex  (Fast Lexical Analyzer)
    * Perl  (Used only during the Bro build process)

Installation
============

To build and install into ``/usr/local/bro``::

    > ./configure
    > make
    > make install

This will first build Bro into a directory inside the distribution
called ``build/``, using default build options. It then installs all
required files into ``/usr/local/bro``, including the Bro binary in
``/usr/local/bro/bin/bro``.

You can specify a different installation directory with::

    > ./configure --prefix=<dir>

Note that ``/usr`` and ``/opt/bro`` are the standard prefixes for
binary Bro packages to be installed, so those are typically not good
choices unless you are creating such a package.

Run ``./configure --help`` for more options.

Depending on the Bro package you downloaded, there may be auxiliary
tools and libraries available in the ``aux/`` directory. All of them
except for ``aux/bro-aux`` will also be built and installed by doing
``make install``.  To install the programs that come in the
``aux/bro-aux`` directory, use ``make install-aux``. There are
``--disable-*`` options that can be given to the configure script to
turn off unwanted auxiliary projects.


Running Bro
===========

Bro is a complex program and it takes a bit of time to get familiar
with it.  A good place for newcomers to start is the quick start guide
available here:

    http://www.bro-ids.org/documentation/quickstart.html


For developers that wish to run Bro directly from the ``build/``
directory (i.e., without performing ``make install``), they will have
to first adjust ``BROPATH`` to look for scripts inside the build
directory.  Sourcing either ``build/bro-path-dev.sh`` or
``build/bro-path-dev.csh`` as appropriate for the current shell
accomplishes this and also augments your ``PATH`` so you can use the
Bro binary directly:

    > ./configure
    > make
    > source build/bro-path-dev.sh
    > bro <options>