Mirror/zeek
1
0
Fork 0
mirror of https://github.com/zeek/zeek.git synced 2025-10-02 14:48:21 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 2

Fix documentation interlinkage and normalize console directive bodies.

Browse source
This commit is contained in:
Jon Siwek 2011-11-15 16:27:06 -06:00
parent ea2c89f2d7
commit 72aa13968b
7 changed files with 69 additions and 77 deletions
Download patch file Download diff file Expand all files Collapse all files

25
INSTALL
View file

@ -39,9 +39,9 @@ Installation
To build and install into ``/usr/local/bro``:: To build and install into ``/usr/local/bro``::
> ./configure ./configure
> make make
> make install make install
This will first build Bro into a directory inside the distribution This will first build Bro into a directory inside the distribution
called ``build/``, using default build options. It then installs all called ``build/``, using default build options. It then installs all
@ -50,7 +50,7 @@ required files into ``/usr/local/bro``, including the Bro binary in
You can specify a different installation directory with:: You can specify a different installation directory with::
> ./configure --prefix=<dir> ./configure --prefix=<dir>
Note that ``/usr`` and ``/opt/bro`` are the standard prefixes for Note that ``/usr`` and ``/opt/bro`` are the standard prefixes for
binary Bro packages to be installed, so those are typically not good binary Bro packages to be installed, so those are typically not good
@ -71,11 +71,8 @@ Running Bro
=========== ===========
Bro is a complex program and it takes a bit of time to get familiar 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 with it. A good place for newcomers to start is the
available here: :doc:`quick start guide <quickstart>`.
http://www.bro-ids.org/documentation/quickstart.html
For developers that wish to run Bro directly from the ``build/`` For developers that wish to run Bro directly from the ``build/``
directory (i.e., without performing ``make install``), they will have directory (i.e., without performing ``make install``), they will have
@ -83,9 +80,9 @@ to first adjust ``BROPATH`` to look for scripts inside the build
directory. Sourcing either ``build/bro-path-dev.sh`` or directory. Sourcing either ``build/bro-path-dev.sh`` or
``build/bro-path-dev.csh`` as appropriate for the current shell ``build/bro-path-dev.csh`` as appropriate for the current shell
accomplishes this and also augments your ``PATH`` so you can use the accomplishes this and also augments your ``PATH`` so you can use the
Bro binary directly: Bro binary directly::
> ./configure ./configure
> make make
> source build/bro-path-dev.sh source build/bro-path-dev.sh
> bro <options> bro <options>

1
doc/CHANGES Symbolic link
View file

@ -0,0 +1 @@
../CHANGES

5
doc/README
View file

@ -29,10 +29,11 @@ clean the resulting documentation.
Notes for Writing Documentation Notes for Writing Documentation
------------------------------- -------------------------------
* If you want to refer to a Bro script that's part of the * If you want to refer to a document that's part of the
distribution, it currently needs to be copied or otherwise symlinked distribution, it currently needs to be copied or otherwise symlinked
somewhere in to this Sphinx source tree. Then, it can be referenced somewhere in to this Sphinx source tree. Then, it can be referenced
in a toc tree or with the :doc: role. in a toc tree or with the :doc: role. Use the :download: role to
refer to static files that will not undergo sphinx rendering.
* If you want to refer to a page on the Bro web site, use an HTTP URL. * If you want to refer to a page on the Bro web site, use an HTTP URL.

12
doc/faq.rst
View file

@ -80,7 +80,7 @@ required to capture packets to the ``bro`` executable file like this:
.. console:: .. console::
> sudo setcap cap_net_raw,cap_net_admin=eip /path/to/bro sudo setcap cap_net_raw,cap_net_admin=eip /path/to/bro
Now any unprivileged user should have the capability to capture packets Now any unprivileged user should have the capability to capture packets
using Bro provided that they have the traditional file permissions to using Bro provided that they have the traditional file permissions to
@ -98,8 +98,8 @@ it using libpcap.
.. console:: .. console::
> sudo chgrp admin /dev/bpf* sudo chgrp admin /dev/bpf*
> sudo chmod g+r /dev/bpf* sudo chmod g+r /dev/bpf*
* Example of configuring devfs to set permissions of BPF devices, adding * Example of configuring devfs to set permissions of BPF devices, adding
entries to ``/etc/devfs.conf`` to grant ``admin`` group permission to entries to ``/etc/devfs.conf`` to grant ``admin`` group permission to
@ -107,9 +107,9 @@ it using libpcap.
.. console:: .. console::
> sudo sh -c 'echo "own bpf root:admin" >> /etc/devfs.conf' sudo sh -c 'echo "own bpf root:admin" >> /etc/devfs.conf'
> sudo sh -c 'echo "perm bpf 0640" >> /etc/devfs.conf' sudo sh -c 'echo "perm bpf 0640" >> /etc/devfs.conf'
> sudo service devfs restart sudo service devfs restart
.. note:: As of Mac OS X 10.6, the BPF device is on devfs, but the used version .. note:: As of Mac OS X 10.6, the BPF device is on devfs, but the used version
of devfs isn't capable of setting the device permissions. The permissions of devfs isn't capable of setting the device permissions. The permissions

86
doc/quickstart.rst
View file

@ -3,6 +3,7 @@
.. _MacPorts: http://www.macports.org .. _MacPorts: http://www.macports.org
.. _Fink: http://www.finkproject.org .. _Fink: http://www.finkproject.org
.. _Homebrew: http://mxcl.github.com/homebrew .. _Homebrew: http://mxcl.github.com/homebrew
.. _bro downloads page: http://bro-ids.org/download/index.html
================= =================
Quick Start Guide Quick Start Guide
@ -26,20 +27,19 @@ source code forms.
Pre-Built Binary Release Packages Pre-Built Binary Release Packages
--------------------------------- ---------------------------------
See the `downloads page <{{docroot}}/download/index.html>`_ for currently See the `bro downloads page`_ for currently supported/targeted platforms.
supported/targeted platforms.
* RPM * RPM
.. console:: .. console::
> sudo yum localinstall Bro-all*.rpm sudo yum localinstall Bro-all*.rpm
* DEB * DEB
.. console:: .. console::
> sudo gdebi Bro-all-*.deb sudo gdebi Bro-all-*.deb
* MacOS Disk Image with Installer * MacOS Disk Image with Installer
@ -60,13 +60,13 @@ Required Dependencies
.. console:: .. console::
> sudo yum install cmake make gcc gcc-c++ flex bison libpcap-devel openssl-devel python-devel swig sudo yum install cmake make gcc gcc-c++ flex bison libpcap-devel openssl-devel python-devel swig
* DEB/Debian-based Linux: * DEB/Debian-based Linux:
.. console:: .. console::
> sudo apt-get install cmake make gcc g++ flex bison libpcap-dev libssl-dev python-dev swig sudo apt-get install cmake make gcc g++ flex bison libpcap-dev libssl-dev python-dev swig
* FreeBSD * FreeBSD
@ -75,7 +75,7 @@ Required Dependencies
.. console:: .. console::
> sudo pkg_add -r cmake swig bison python sudo pkg_add -r cmake swig bison python
* Mac OS X * Mac OS X
@ -102,21 +102,21 @@ and sendmail for sending emails.
.. console:: .. console::
> sudo yum install zlib-devel file-devel GeoIP-devel sendmail sudo yum install zlib-devel file-devel GeoIP-devel sendmail
* DEB/Debian-based Linux: * DEB/Debian-based Linux:
.. console:: .. console::
> sudo apt-get install zlib1g-dev libmagic-dev libgeoip-dev sendmail sudo apt-get install zlib1g-dev libmagic-dev libgeoip-dev sendmail
* Ports-based FreeBSD * Ports-based FreeBSD
.. console:: .. console::
> sudo pkg_add -r GeoIP sudo pkg_add -r GeoIP
libz, libmagic, and sendmail are typically already available. libz, libmagic, and sendmail are typically already available.
* Mac OS X * Mac OS X
@ -125,20 +125,20 @@ and sendmail for sending emails.
Fink Homebrew), they should be automatically detected and Bro will compile Fink Homebrew), they should be automatically detected and Bro will compile
against them. against them.
Additional steps may be needed to `get the right GeoIP database Additional steps may be needed to :doc:`get the right GeoIP database <geoip>`
<{{git('bro:doc/geoip.rst')}}>`_.
Compiling Bro Source Code Compiling Bro Source Code
~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~
Bro releases are bundled into source packages for convenience and Bro releases are bundled into source packages for convenience and
available from the `downloads page <{{docroot}}/download/index.html>`_. available from the `bro downloads page`_.
The latest Bro development versions are obtainable through git repositories The latest Bro development versions are obtainable through git
hosted at `git.bro-ids.org <http://git.bro-ids.org>`_. See our `git development repositories hosted at `git.bro-ids.org <http://git.bro-ids.org>`_. See
documentation <{{docroot}}/development/process.html>`_ for comprehensive our `git development documentation
information on Bro's use of git revision control, but the short story for <http://bro-ids.org/development/process.html>`_ for comprehensive
downloading the full source code experience for Bro via git is: 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:: .. console::
@ -157,9 +157,9 @@ desired root install path):
.. console:: .. console::
> ./configure --prefix=/desired/install/path ./configure --prefix=/desired/install/path
> make make
> make install make install
The default installation prefix is ``/usr/local/bro``, which would typically The default installation prefix is ``/usr/local/bro``, which would typically
require root privileges when doing the ``make install``. require root privileges when doing the ``make install``.
@ -174,13 +174,13 @@ Bourne-Shell Syntax:
.. console:: .. console::
> export PATH=/usr/local/bro/bin:$PATH export PATH=/usr/local/bro/bin:$PATH
C-Shell Syntax: C-Shell Syntax:
.. console:: .. console::
> setenv PATH /usr/local/bro/bin:$PATH setenv PATH /usr/local/bro/bin:$PATH
Or substitute ``/opt/bro/bin`` instead if you installed from a binary package. Or substitute ``/opt/bro/bin`` instead if you installed from a binary package.
@ -211,7 +211,7 @@ Now start the BroControl shell like:
.. console:: .. console::
> broctl broctl
Since this is the first-time use of the shell, perform an initial installation Since this is the first-time use of the shell, perform an initial installation
of the BroControl configuration: of the BroControl configuration:
@ -233,10 +233,9 @@ policy and output the results in ``$PREFIX/logs``.
.. note:: The user starting BroControl needs permission to capture .. note:: The user starting BroControl needs permission to capture
network traffic. If you are not root, you may need to grant further network traffic. If you are not root, you may need to grant further
privileges to the account you're using; see the `FAQ privileges to the account you're using; see the :doc:`FAQ <faq>`.
<{{docroot}}/documentation/faq.html>`_. Also, if it Also, if it looks like Bro is not seeing any traffic, check out
looks like Bro is not seeing any traffic, check out the FAQ entry the FAQ entry on checksum offloading.
checksum offloading.
You can leave it running for now, but to stop this Bro instance you would do: You can leave it running for now, but to stop this Bro instance you would do:
@ -244,9 +243,7 @@ You can leave it running for now, but to stop this Bro instance you would do:
[BroControl] > stop [BroControl] > stop
We also recommend to insert the following entry into `crontab`: We also recommend to insert the following entry into `crontab`::
.. console::
0-59/5 * * * * $PREFIX/bin/broctl cron 0-59/5 * * * * $PREFIX/bin/broctl cron
@ -373,9 +370,7 @@ the variable's value may not change at run-time, but whose initial value can be
modified via the ``redef`` operator at parse-time. modified via the ``redef`` operator at parse-time.
So let's continue on our path to modify the behavior for the two SSL So let's continue on our path to modify the behavior for the two SSL
and SSH notices. Looking at and SSH notices. Looking at :doc:`scripts/base/frameworks/notice/main`,
`$PREFIX/share/bro/base/frameworks/notice/main.bro
<{{autodoc_bro_scripts}}/scripts/base/frameworks/notice/main.html>`_,
we see that it advertises: we see that it advertises:
.. code:: bro .. code:: bro
@ -477,8 +472,7 @@ tweak the most basic options. Here's some suggestions on what to explore next:
* Reading the code of scripts that ship with Bro is also a great way to gain * Reading the code of scripts that ship with Bro is also a great way to gain
understanding of the language and how you can start writing your own custom understanding of the language and how you can start writing your own custom
analysis. analysis.
* Review the `FAQ <{{docroot}}/documentation/faq.html>`_. * Review the :doc:`FAQ <faq>`.
* Check out more `documentation <{{docroot}}/documentation/index.html>`_.
* Continue reading below for another mini-tutorial on using Bro as a standalone * Continue reading below for another mini-tutorial on using Bro as a standalone
command-line utility. command-line utility.
@ -496,7 +490,7 @@ Analyzing live traffic from an interface is simple:
.. console:: .. console::
> bro -i en0 <list of scripts to load> bro -i en0 <list of scripts to load>
``en0`` can be replaced by the interface of your choice and for the list of ``en0`` can be replaced by the interface of your choice and for the list of
scripts, you can just use "all" for now to perform all the default analysis scripts, you can just use "all" for now to perform all the default analysis
@ -504,7 +498,7 @@ that's available.
Bro will output log files into the working directory. Bro will output log files into the working directory.
.. note:: The `FAQ <{{docroot}}/documentation/faq.html>`_ entries about .. note:: The :doc:`FAQ <faq>` entries about
capturing as an unprivileged user and checksum offloading are particularly capturing as an unprivileged user and checksum offloading are particularly
relevant at this point. relevant at this point.
@ -513,7 +507,7 @@ command-line:
.. console:: .. console::
> bro -i en0 local bro -i en0 local
This will cause Bro to print a warning about lacking the This will cause Bro to print a warning about lacking the
``Site::local_nets`` variable being configured. You can supply this ``Site::local_nets`` variable being configured. You can supply this
@ -522,7 +516,7 @@ in place of the example subnets):
.. console:: .. console::
> bro -r mypackets.trace local "Site::local_nets += { 1.2.3.0/24, 5.6.7.0/24 }" bro -r mypackets.trace local "Site::local_nets += { 1.2.3.0/24, 5.6.7.0/24 }"
Reading Packet Capture (pcap) Files Reading Packet Capture (pcap) Files
@ -533,7 +527,7 @@ like this:
.. console:: .. console::
> sudo tcpdump -i en0 -s 0 -w mypackets.trace sudo tcpdump -i en0 -s 0 -w mypackets.trace
Where ``en0`` can be replaced by the correct interface for your system as Where ``en0`` can be replaced by the correct interface for your system as
shown by e.g. ``ifconfig``. (The ``-s 0`` argument tells it to capture shown by e.g. ``ifconfig``. (The ``-s 0`` argument tells it to capture
@ -544,7 +538,7 @@ and tell Bro to perform all the default analysis on the capture which primarily
.. console:: .. console::
> bro -r mypackets.trace bro -r mypackets.trace
Bro will output log files into the working directory. Bro will output log files into the working directory.
@ -553,7 +547,7 @@ script that we include as a suggested configuration:
.. console:: .. console::
> bro -r mypackets.trace local bro -r mypackets.trace local
Telling Bro Which Scripts to Load Telling Bro Which Scripts to Load
@ -563,7 +557,7 @@ A command-line invocation of Bro typically looks like:
.. console:: .. console::
> bro <options> <policies...> bro <options> <policies...>
Where the last arguments are the specific policy scripts that this Bro Where the last arguments are the specific policy scripts that this Bro
instance will load. These arguments don't have to include the ``.bro`` instance will load. These arguments don't have to include the ``.bro``
@ -578,7 +572,7 @@ logging) and adds SSL certificate validation.
.. console:: .. console::
> bro -r mypackets.trace protocols/ssl/validate-certs bro -r mypackets.trace protocols/ssl/validate-certs
You might notice that a script you load from the command line uses the You might notice that a script you load from the command line uses the
``@load`` directive in the Bro language to declare dependence on other scripts. ``@load`` directive in the Bro language to declare dependence on other scripts.

4
doc/signatures.rst
View file

@ -47,8 +47,8 @@ piece of payload which triggered the pattern match.
To turn such ``signature_match`` events into actual alarms, you can To turn such ``signature_match`` events into actual alarms, you can
load Bro's ``signature.bro`` script. This script contains a default load Bro's ``signature.bro`` script. This script contains a default
event handler that raises ``SensitiveSignature`` `Notices event handler that raises ``SensitiveSignature`` :doc:`Notices <notice>`
<notices.html>`_ (as well as others; see the beginning of the script). (as well as others; see the beginning of the script).
As signatures are independent of Bro's policy scripts, they are put As signatures are independent of Bro's policy scripts, they are put
into their own file(s). There are two ways to specify which files into their own file(s). There are two ways to specify which files

13
doc/upgrade.rst
View file

@ -39,7 +39,7 @@ version. The two rules of thumb are:
if you need help. if you need help.
Below we summarize changes from 1.x to 2.x in more detail. This list Below we summarize changes from 1.x to 2.x in more detail. This list
isn't complete, see the `CHANGES <{{git('bro:CHANGES', 'txt')}}>`_ file in the isn't complete, see the :download:`CHANGES <CHANGES>` file in the
distribution for the full story. distribution for the full story.
Default Scripts Default Scripts
@ -131,8 +131,8 @@ Logging Framework
endpoint. endpoint.
- The new logging framework makes it possible to extend, customize, - The new logging framework makes it possible to extend, customize,
and filter logs very easily. See `the logging framework and filter logs very easily. See the :doc:`logging framework <logging>`
<{{git('bro:doc/logging.rst')}}>`_ more information on usage. more information on usage.
- A common pattern found in the new scripts is to store logging stream - A common pattern found in the new scripts is to store logging stream
records for protocols inside the ``connection`` records so that records for protocols inside the ``connection`` records so that
@ -155,8 +155,7 @@ Notice Framework
The way users interact with "notices" has changed significantly in The way users interact with "notices" has changed significantly in
order to make it easier to define a site policy and more extensible order to make it easier to define a site policy and more extensible
for adding customized actions. See the `the notice framework for adding customized actions. See the :doc:`notice framework <notice>`.
<{{git('bro:doc/notice.rst')}}>`_.
New Default Settings New Default Settings
@ -198,7 +197,7 @@ Variable Naming
- Identifiers may have been renamed to conform to new `scripting - Identifiers may have been renamed to conform to new `scripting
conventions conventions
<{{docroot}}/development/script-conventions.html>`_ <http://www.bro-ids.org/development/script-conventions.html>`_
BroControl BroControl
@ -240,7 +239,7 @@ Development Infrastructure
Bro development has moved from using SVN to Git for revision control. Bro development has moved from using SVN to Git for revision control.
Users that like to use the latest Bro developments by checking it out Users that like to use the latest Bro developments by checking it out
from the source repositories should see the `development process from the source repositories should see the `development process
<{{docroot}}/development/process.html>`_. Note that all the various <http://www.bro-ids.org/development/process.html>`_. Note that all the various
sub-components now reside on their own repositories. However, the sub-components now reside on their own repositories. However, the
top-level Bro repository includes them as git submodules so it's easu top-level Bro repository includes them as git submodules so it's easu
to check them all out simultaneously. to check them all out simultaneously.