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

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``::
> ./configure
> make
> make install
./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
@ -50,7 +50,7 @@ required files into ``/usr/local/bro``, including the Bro binary in
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
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
with it. A good place for newcomers to start is the quick start guide
available here:
http://www.bro-ids.org/documentation/quickstart.html
with it. A good place for newcomers to start is the
:doc:`quick start guide <quickstart>`.
For developers that wish to run Bro directly from the ``build/``
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
``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:
Bro binary directly::
> ./configure
> make
> source build/bro-path-dev.sh
> bro <options>
./configure
make
source build/bro-path-dev.sh
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
-------------------------------
* 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
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.

12
doc/faq.rst
View file

@ -80,7 +80,7 @@ required to capture packets to the ``bro`` executable file like this:
.. 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
using Bro provided that they have the traditional file permissions to
@ -98,8 +98,8 @@ it using libpcap.
.. console::
> sudo chgrp admin /dev/bpf*
> sudo chmod g+r /dev/bpf*
sudo chgrp admin /dev/bpf*
sudo chmod g+r /dev/bpf*
* Example of configuring devfs to set permissions of BPF devices, adding
entries to ``/etc/devfs.conf`` to grant ``admin`` group permission to
@ -107,9 +107,9 @@ it using libpcap.
.. console::
> sudo sh -c 'echo "own bpf root:admin" >> /etc/devfs.conf'
> sudo sh -c 'echo "perm bpf 0640" >> /etc/devfs.conf'
> sudo service devfs restart
sudo sh -c 'echo "own bpf root:admin" >> /etc/devfs.conf'
sudo sh -c 'echo "perm bpf 0640" >> /etc/devfs.conf'
sudo service devfs restart
.. 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

84
doc/quickstart.rst
View file

@ -3,6 +3,7 @@
.. _MacPorts: http://www.macports.org
.. _Fink: http://www.finkproject.org
.. _Homebrew: http://mxcl.github.com/homebrew
.. _bro downloads page: http://bro-ids.org/download/index.html
=================
Quick Start Guide
@ -26,20 +27,19 @@ source code forms.
Pre-Built Binary Release Packages
---------------------------------
See the `downloads page <{{docroot}}/download/index.html>`_ for currently
supported/targeted platforms.
See the `bro downloads page`_ for currently supported/targeted platforms.
* RPM
.. console::
> sudo yum localinstall Bro-all*.rpm
sudo yum localinstall Bro-all*.rpm
* DEB
.. console::
> sudo gdebi Bro-all-*.deb
sudo gdebi Bro-all-*.deb
* MacOS Disk Image with Installer
@ -60,13 +60,13 @@ Required Dependencies
.. 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:
.. 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
@ -75,7 +75,7 @@ Required Dependencies
.. console::
> sudo pkg_add -r cmake swig bison python
sudo pkg_add -r cmake swig bison python
* Mac OS X
@ -102,19 +102,19 @@ and sendmail for sending emails.
.. 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:
.. 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
.. console::
> sudo pkg_add -r GeoIP
sudo pkg_add -r GeoIP
libz, libmagic, and sendmail are typically already available.
@ -125,20 +125,20 @@ and sendmail for sending emails.
Fink Homebrew), they should be automatically detected and Bro will compile
against them.
Additional steps may be needed to `get the right GeoIP database
<{{git('bro:doc/geoip.rst')}}>`_.
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 `downloads page <{{docroot}}/download/index.html>`_.
available from the `bro downloads page`_.
The latest Bro development versions are obtainable through git repositories
hosted at `git.bro-ids.org <http://git.bro-ids.org>`_. See our `git development
documentation <{{docroot}}/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:
The latest Bro development versions are obtainable through git
repositories hosted at `git.bro-ids.org <http://git.bro-ids.org>`_. See
our `git development documentation
<http://bro-ids.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::
@ -157,9 +157,9 @@ desired root install path):
.. console::
> ./configure --prefix=/desired/install/path
> make
> make install
./configure --prefix=/desired/install/path
make
make install
The default installation prefix is ``/usr/local/bro``, which would typically
require root privileges when doing the ``make install``.
@ -174,13 +174,13 @@ Bourne-Shell Syntax:
.. console::
> export PATH=/usr/local/bro/bin:$PATH
export PATH=/usr/local/bro/bin:$PATH
C-Shell Syntax:
.. 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.
@ -211,7 +211,7 @@ Now start the BroControl shell like:
.. console::
> broctl
broctl
Since this is the first-time use of the shell, perform an initial installation
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
network traffic. If you are not root, you may need to grant further
privileges to the account you're using; see the `FAQ
<{{docroot}}/documentation/faq.html>`_. Also, if it
looks like Bro is not seeing any traffic, check out the FAQ entry
checksum offloading.
privileges to the account you're using; see the :doc:`FAQ <faq>`.
Also, if it looks like Bro is not seeing any traffic, check out
the FAQ entry on checksum offloading.
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
We also recommend to insert the following entry into `crontab`:
.. console::
We also recommend to insert the following entry into `crontab`::
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.
So let's continue on our path to modify the behavior for the two SSL
and SSH notices. Looking at
`$PREFIX/share/bro/base/frameworks/notice/main.bro
<{{autodoc_bro_scripts}}/scripts/base/frameworks/notice/main.html>`_,
and SSH notices. Looking at :doc:`scripts/base/frameworks/notice/main`,
we see that it advertises:
.. 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
understanding of the language and how you can start writing your own custom
analysis.
* Review the `FAQ <{{docroot}}/documentation/faq.html>`_.
* Check out more `documentation <{{docroot}}/documentation/index.html>`_.
* Review the :doc:`FAQ <faq>`.
* Continue reading below for another mini-tutorial on using Bro as a standalone
command-line utility.
@ -496,7 +490,7 @@ Analyzing live traffic from an interface is simple:
.. 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
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.
.. 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
relevant at this point.
@ -513,7 +507,7 @@ command-line:
.. console::
> bro -i en0 local
bro -i en0 local
This will cause Bro to print a warning about lacking the
``Site::local_nets`` variable being configured. You can supply this
@ -522,7 +516,7 @@ in place of the example subnets):
.. 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
@ -533,7 +527,7 @@ like this:
.. 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
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::
> bro -r mypackets.trace
bro -r mypackets.trace
Bro will output log files into the working directory.
@ -553,7 +547,7 @@ script that we include as a suggested configuration:
.. console::
> bro -r mypackets.trace local
bro -r mypackets.trace local
Telling Bro Which Scripts to Load
@ -563,7 +557,7 @@ A command-line invocation of Bro typically looks like:
.. console::
> bro <options> <policies...>
bro <options> <policies...>
Where the last arguments are the specific policy scripts that this Bro
instance will load. These arguments don't have to include the ``.bro``
@ -578,7 +572,7 @@ logging) and adds SSL certificate validation.
.. 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
``@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
load Bro's ``signature.bro`` script. This script contains a default
event handler that raises ``SensitiveSignature`` `Notices
<notices.html>`_ (as well as others; see the beginning of the script).
event handler that raises ``SensitiveSignature`` :doc:`Notices <notice>`
(as well as others; see the beginning of the script).
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

13
doc/upgrade.rst
View file

@ -39,7 +39,7 @@ version. The two rules of thumb are:
if you need help.
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.
Default Scripts
@ -131,8 +131,8 @@ Logging Framework
endpoint.
- The new logging framework makes it possible to extend, customize,
and filter logs very easily. See `the logging framework
<{{git('bro:doc/logging.rst')}}>`_ more information on usage.
and filter logs very easily. See the :doc:`logging framework <logging>`
more information on usage.
- A common pattern found in the new scripts is to store logging stream
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
order to make it easier to define a site policy and more extensible
for adding customized actions. See the `the notice framework
<{{git('bro:doc/notice.rst')}}>`_.
for adding customized actions. See the :doc:`notice framework <notice>`.
New Default Settings
@ -198,7 +197,7 @@ Variable Naming
- Identifiers may have been renamed to conform to new `scripting
conventions
<{{docroot}}/development/script-conventions.html>`_
<http://www.bro-ids.org/development/script-conventions.html>`_
BroControl
@ -240,7 +239,7 @@ Development Infrastructure
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
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
top-level Bro repository includes them as git submodules so it's easu
to check them all out simultaneously.