mirror of
https://github.com/zeek/zeek.git
synced 2025-10-01 22:28:20 +00:00
Merge remote-tracking branch 'origin/topic/documentation'
I'm merging in the documentation branch to avoid that it keeps getting out of sync. We still need to work on this a bit more, I'll summarize in a mail. * origin/topic/documentation: (68 commits) Going over initial parts of the scripting overview. Adding lines in scripting/index.txt. No other change. Updating submodule. Pass over the Using Bro section. Applying doc updates from BIT-1063. (Anthony Verez) Breaking lines in using/*. More doc reorg, and a light pass over the first 3 sections. Starting to put a new structure in place. Updating submodule(s). Updating submodule(s). Adding some temporary testing/demonstration to front page. Switching btest to topic/robin/parts branch. Basic cross-referencing UIDs between files, btests, and baselines. A truly embarassing number of spelling corrections. Using redirection with bro-cut. Include initial btests for this document. Corrected a mis-typed RST include. Initial start for "Using Bro". Spelling corrections. Include Notice Policy shortcuts in the Scripting User Manual. Notice::policy hooks and tests. ... Conflicts: src/3rdparty
This commit is contained in:
Robin Sommer
commit
ac66db286a
309 changed files with 11468 additions and 1312 deletions
313
INSTALL
313
INSTALL
|
|
@ -1,314 +1,3 @@
|
|||
.. _CMake: http://www.cmake.org
|
||||
.. _SWIG: http://www.swig.org
|
||||
.. _Xcode: https://developer.apple.com/xcode/
|
||||
.. _MacPorts: http://www.macports.org
|
||||
.. _Fink: http://www.finkproject.org
|
||||
.. _Homebrew: http://mxcl.github.com/homebrew
|
||||
.. _bro downloads page: http://bro.org/download/index.html
|
||||
|
||||
==============
|
||||
Installing Bro
|
||||
==============
|
||||
See doc/install/install.rst for installation instructions.
|
||||
|
||||
Bro can be downloaded in either pre-built binary package or
|
||||
source code forms.
|
||||
|
||||
Prerequisites
|
||||
=============
|
||||
|
||||
Bro requires the following libraries and tools to be installed
|
||||
before you begin:
|
||||
|
||||
* Libpcap http://www.tcpdump.org
|
||||
|
||||
* OpenSSL libraries http://www.openssl.org
|
||||
|
||||
* BIND8 library
|
||||
|
||||
* Libmagic
|
||||
|
||||
* Libz
|
||||
|
||||
* Bash (for BroControl)
|
||||
|
||||
To build Bro from source, the following additional dependencies are required:
|
||||
|
||||
* CMake 2.6.3 or greater http://www.cmake.org
|
||||
|
||||
* SWIG http://www.swig.org
|
||||
|
||||
* Bison (GNU Parser Generator)
|
||||
|
||||
* Flex (Fast Lexical Analyzer)
|
||||
|
||||
* Libpcap headers http://www.tcpdump.org
|
||||
|
||||
* OpenSSL headers http://www.openssl.org
|
||||
|
||||
* libmagic headers
|
||||
|
||||
* zlib headers
|
||||
|
||||
* Perl
|
||||
|
||||
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)
|
||||
|
||||
|
||||
Installing From Pre-Built Binary Release Packages
|
||||
=================================================
|
||||
|
||||
See the `bro downloads page`_ for currently supported/targeted platforms.
|
||||
|
||||
* RPM
|
||||
|
||||
.. console::
|
||||
|
||||
sudo yum localinstall Bro-*.rpm
|
||||
|
||||
* DEB
|
||||
|
||||
.. console::
|
||||
|
||||
sudo gdebi Bro-*.deb
|
||||
|
||||
* MacOS Disk Image with Installer
|
||||
|
||||
Just open the ``Bro-*.dmg`` and then run the ``.pkg`` installer.
|
||||
Everything installed by the package will go into ``/opt/bro``.
|
||||
|
||||
The primary install prefix for binary packages is ``/opt/bro``.
|
||||
Non-MacOS packages that include BroControl also put variable/runtime
|
||||
data (e.g. Bro logs) in ``/var/opt/bro``.
|
||||
|
||||
|
||||
Installing From Source
|
||||
======================
|
||||
|
||||
Required Dependencies
|
||||
~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
The following dependencies are required to build Bro:
|
||||
|
||||
* RPM/RedHat-based Linux:
|
||||
|
||||
.. console::
|
||||
|
||||
sudo yum install cmake make gcc gcc-c++ flex bison libpcap-devel openssl-devel python-devel swig zlib-devel file-devel
|
||||
|
||||
* DEB/Debian-based Linux:
|
||||
|
||||
.. console::
|
||||
|
||||
sudo apt-get install cmake make gcc g++ flex bison libpcap-dev libssl-dev python-dev swig zlib1g-dev libmagic-dev
|
||||
|
||||
* FreeBSD
|
||||
|
||||
Most required dependencies should come with a minimal FreeBSD install
|
||||
except for the following.
|
||||
|
||||
.. console::
|
||||
|
||||
sudo pkg_add -r bash cmake swig bison python
|
||||
|
||||
Note that ``bash`` needs to be in ``PATH``, which by default it is
|
||||
not. The FreeBSD package installs the binary into
|
||||
``/usr/local/bin``.
|
||||
|
||||
* Mac OS X
|
||||
|
||||
Compiling source code on Macs requires first downloading Xcode_,
|
||||
then going through its "Preferences..." -> "Downloads" menus to
|
||||
install the "Command Line Tools" component.
|
||||
|
||||
Lion (10.7) and Mountain Lion (10.8) come with all required
|
||||
dependencies except for CMake_, SWIG_, and ``libmagic``.
|
||||
|
||||
Distributions of these dependencies can likely be obtained from your
|
||||
preferred Mac OS X package management system (e.g. MacPorts_, Fink_,
|
||||
or Homebrew_).
|
||||
|
||||
Specifically for MacPorts, the ``swig``, ``swig-ruby``, ``swig-python``
|
||||
and ``file`` packages provide the required dependencies.
|
||||
|
||||
Optional Dependencies
|
||||
~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Bro can use libGeoIP for geo-locating IP addresses, and sendmail for
|
||||
sending emails.
|
||||
|
||||
* RedHat Enterprise Linux:
|
||||
|
||||
.. console::
|
||||
|
||||
sudo yum install geoip-devel sendmail
|
||||
|
||||
* CentOS Linux:
|
||||
|
||||
.. console::
|
||||
|
||||
sudo yum install GeoIP-devel sendmail
|
||||
|
||||
* DEB/Debian-based Linux:
|
||||
|
||||
.. console::
|
||||
|
||||
sudo apt-get install libgeoip-dev sendmail
|
||||
|
||||
* Ports-based FreeBSD
|
||||
|
||||
.. console::
|
||||
|
||||
sudo pkg_add -r GeoIP
|
||||
|
||||
sendmail is typically already available.
|
||||
|
||||
* Mac OS X
|
||||
|
||||
Vanilla OS X installations don't ship with libGeoIP, but
|
||||
if installed from your preferred package management system (e.g. MacPorts,
|
||||
Fink, or Homebrew), they should be automatically detected and Bro will
|
||||
compile against them.
|
||||
|
||||
Additional steps may be needed to :doc:`get the right GeoIP database <geoip>`.
|
||||
|
||||
Compiling Bro Source Code
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Bro releases are bundled into source packages for convenience and
|
||||
available from the `bro downloads page`_.
|
||||
|
||||
Alternatively, the latest Bro development version can be obtained through git
|
||||
repositories hosted at `git.bro.org <http://git.bro.org>`_. See
|
||||
our `git development documentation
|
||||
<http://bro.org/development/process.html>`_ for comprehensive
|
||||
information on Bro's use of git revision control, but the short story
|
||||
for downloading the full source code experience for Bro via git is:
|
||||
|
||||
.. console::
|
||||
|
||||
git clone --recursive git://git.bro.org/bro
|
||||
|
||||
.. note:: If you choose to clone the ``bro`` repository non-recursively for
|
||||
a "minimal Bro experience", be aware that compiling it depends on
|
||||
BinPAC, which has its own ``binpac`` repository. Either install it
|
||||
first or initialize/update the cloned ``bro`` repository's
|
||||
``aux/binpac`` submodule.
|
||||
|
||||
The typical way to build and install from source is (for more options,
|
||||
run ``./configure --help``):
|
||||
|
||||
.. console::
|
||||
|
||||
./configure
|
||||
make
|
||||
make install
|
||||
|
||||
The default installation path is ``/usr/local/bro``, which would typically
|
||||
require root privileges when doing the ``make install``. A different
|
||||
installation path can be chosen by specifying the ``--prefix`` option.
|
||||
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.
|
||||
|
||||
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.org/documentation/faq.html if you are having
|
||||
problems installing Bro.
|
||||
|
||||
|
||||
Upgrading From a Previous Version of Bro
|
||||
========================================
|
||||
|
||||
If you're doing an upgrade install (rather than a fresh install),
|
||||
there's two suggested approaches: either install Bro using the same
|
||||
installation prefix directory as before, or pick a new prefix and copy
|
||||
local customizations over.
|
||||
|
||||
Re-Use Previous Install Prefix
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
If you choose to configure and install Bro with the same prefix
|
||||
directory as before, local customization and configuration to files in
|
||||
``$prefix/share/bro/site`` and ``$prefix/etc`` won't be overwritten
|
||||
(``$prefix`` indicating the root of where Bro was installed). Also, logs
|
||||
generated at run-time won't be touched by the upgrade. (But making
|
||||
a backup of local changes before upgrading is still recommended.)
|
||||
|
||||
After upgrading, remember to check ``$prefix/share/bro/site`` and
|
||||
``$prefix/etc`` for ``.example`` files, which indicate the
|
||||
distribution's version of the file differs from the local one, which may
|
||||
include local changes. Review the differences, and make adjustments
|
||||
as necessary (for differences that aren't the result of a local change,
|
||||
use the new version's).
|
||||
|
||||
Pick a New Install prefix
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
If you want to install the newer version in a different prefix
|
||||
directory than before, you can just copy local customization and
|
||||
configuration files from ``$prefix/share/bro/site`` and ``$prefix/etc``
|
||||
to the new location (``$prefix`` indicating the root of where Bro was
|
||||
originally installed). Make sure to review the files for difference
|
||||
before copying and make adjustments as necessary (for differences that
|
||||
aren't the result of a local change, use the new version's). Of
|
||||
particular note, the copied version of ``$prefix/etc/broctl.cfg`` is
|
||||
likely to need changes to the ``SpoolDir`` and ``LogDir`` settings.
|
||||
|
||||
|
||||
Configure the Run-Time Environment
|
||||
==================================
|
||||
|
||||
Just remember that you may need to adjust your ``PATH`` environment variable
|
||||
according to the platform/shell/package you're using. For example:
|
||||
|
||||
Bourne-Shell Syntax:
|
||||
|
||||
.. console::
|
||||
|
||||
export PATH=/usr/local/bro/bin:$PATH
|
||||
|
||||
C-Shell Syntax:
|
||||
|
||||
.. console::
|
||||
|
||||
setenv PATH /usr/local/bro/bin:$PATH
|
||||
|
||||
Or substitute ``/opt/bro/bin`` instead if you installed from a binary package.
|
||||
|
||||
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.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>
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue