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

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

Bro requires the following libraries and tools to be installed
before you begin:

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

    * Perl  (used only during the Bro build process)

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

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

    * BIND8 headers and libraries

    * Libmagic

    * Libz

    * SWIG                              http://www.swig.org

    * Bison (GNU Parser Generator)

    * Flex  (Fast Lexical Analyzer)

    * Bash  (for BroControl)


Bro can make use of some optional libraries and tools if they are found at
build time:

    * LibGeoIP (for geo-locating IP addresses)

    * gperftools (tcmalloc is used to improve memory and CPU usage)

    * sendmail (for BroControl)

    * ipsumdump (for trace-summary)     http://www.cs.ucla.edu/~kohler/ipsumdump

    * Ruby executable, library, and headers (for Broccoli Ruby bindings)


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

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

    ./configure
    make
    make install

This will first build Bro in 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. Some of them
will be automatically built and installed along with Bro. There are
``--disable-*`` options that can be given to the configure script to
turn off unwanted auxiliary projects that would otherwise be installed
automatically.  Finally, use ``make install-aux`` to install some of
the other programs that are in the ``aux/bro-aux`` directory.

OpenBSD users, please see our FAQ at
http://www.bro-ids.org/documentation/faq.html if you are having
problems installing Bro.

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
at 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>