mirror of
https://github.com/zeek/zeek.git
synced 2025-10-02 06:38:20 +00:00
25bf563e1c
I'm merging in the remaining pieces from the former doc directory and restructuring things into sub-directories. |
||
|---|---|---|
| .. | ||
| README.rst | ||
.. Autogenerated. Do not edit.
.. -*- mode: rst-mode -*-
..
.. Note: This file includes further autogenerated ones.
..
.. Version number is filled in automatically.
.. |version| replace:: 1.1-3
==========
BroControl
==========
.. rst-class:: opening
This document summarizes installation and use of *BroControl*,
Bro's interactive shell for operating Bro installations. *BroControl*
has two modes of operation: a *stand-alone* mode for
managing a traditional, single-system Bro setup; and a *cluster*
mode for maintaining a multi-system setup of coordinated Bro
instances load-balancing the work across a set of independent
machines. Below, we describe the installation process separately
for the two modes. Once installed, the operation is pretty similar
for both types; just keep in mind that if this document refers to
"nodes" and you're in a stand-alone setup, there is only a
single one and no worker/proxies.
.. contents::
Download
--------
You can find the latest BroControl release for download at
http://www.bro.org/download.
BroControl's git repository is located at
`git://git.bro.org/broctl <git://git.bro.org/broctl>`_. You
can browse the repository `here <http://git.bro.org/broctl>`_.
This document describes BroControl |version|. See the ``CHANGES``
file for version history.
Prerequisites
-------------
Running *BroControl* requires the following prerequisites:
- A Unix system. FreeBSD, Linux, and MacOS are supported and
should work out of the box. Other Unix systems will quite likely
require some tweaking. Note that in a cluster setup, all systems
must be running exactly the *same* operating system.
- A version of *Python* >= 2.6.
- A *bash* (note in particular, that on FreeBSD, *bash* is not
installed by default).
Installation
------------
Stand-alone Bro
~~~~~~~~~~~~~~~
For installing a stand-alone Bro setup, just follow the
Bro :doc:`Quick Start Guide<../../quickstart>`.
Bro Cluster
~~~~~~~~~~~
A *Bro Cluster* is a set of systems jointly analyzing the traffic of
a network link in a coordinated fashion. *BroControl* is able to
operate such a setup from a central manager system pretty much
transparently, hiding much of the complexity of the multi-machine
installation.
A cluster consists of four types of components:
Frontends.
One or more frontends: Frontends load-balance the traffic
across a set of worker machines.
Worker nodes.
Workers are doing the actual analysis, with each seeing a
slice of the overall traffic as split by the frontend(s).
One or more proxies.
Proxies relay the communication between worker nodes.
One manager.
The manager provides the cluster's user-interface for
controlling and logging. During operation, the user only
interacts with the manager; this is where *BroControl* is
running.
For more information about the cluster architecture, including options
for the frontend, see the :doc:`Bro Cluster<../../cluster>` documentation.
This document focuses on the installation of manager,
workers, and the proxies. If not otherwise
stated, in the following we use the terms "manager", "worker", and
"proxy" to refer to Bro instances, not to physical machines; rather,
we use the term "node" to refer to physical machines. There may be
multiple Bro instances running on the same node. For example, it's
possible to run a proxy on the same node as the manager is operating
on.
In the following, as an example setup, we will assume that our
cluster consists of four nodes (not counting the frontend). The host
names of the systems will be ``host1``, ``host2``, ``host3``, and
``host4``. We will configure the cluster so that ``host1`` runs the
manager and the (only) proxy, and ``host{2,3,4}`` are each running
one worker. This is a typical setup, which will work well for many
sites.
When installing a cluster, in addition to the prerequisites
mentioned above, you need to
- have the same user account set up on all nodes. On the worker
nodes, this user must have access to target network interface in
promiscuous mode. ``ssh`` access from the manager node to this
user account must be setup on all machines, and must work
without asking for a password/passphrase.
- have some storage available on all nodes under the same path,
which we will call the cluster's *prefix* path. In the
following, we will use ``/usr/local/bro`` as an example. The Bro
user must be able to either create this directory or, where it
already exists, must have write permission inside this directory
on all nodes.
- have ``ssh`` and ``rsync`` installed.
With all prerequisites in place, perform the following steps to
install a Bro cluster (as the Bro user) if you install from the Bro source
code (which includes BroControl):
- Configure and compile the Bro distribution using the cluster's
prefix path as ``--prefix``::
> cd /path/to/bro/source/distribution
> ./configure --prefix=/usr/local/bro && make && make install
- Add ``<prefix>/bin`` to your ``PATH``.
- Create a cluster configuration file. There is an example provided,
which you can edit according to the instructions in the file::
> cd /usr/local/bro
> vi etc/broctl.cfg
- Create a node configuration file to define where manager, workers,
and proxies are to run. There is again an example, which defines
the example scenario described above and can be edited as needed::
> cd /usr/local/bro
> vi etc/node.cfg
- Create a network configuration file that lists all of the networks
which the cluster should consider as local to the monitored
environment. Once again, the installation installs a template for
editing::
> cd /usr/local/bro
> vi etc/networks.cfg
- Install workers and proxies using *BroControl*::
> broctl install
This installation process uses ``ssh`` and ``rdist`` to copy the
configuration over to the remote machines so, as described above,
you need to ensure that logging in via SSH works before the install will
succeed.
- Some tasks need to be run on a regular basis. On the manager node,
insert a line like this into the crontab of the user running the
cluster::
0-59/5 * * * * <prefix>/bin/broctl cron
- Finally, you can start the cluster::
> broctl start
Getting Started
---------------
*BroControl* is an interactive interface to the cluster which allows
you to, e.g., start/stop the monitoring or update its configuration.
It is started with the ``broctl`` script and then expects commands
on its command-line (alternatively, ``broctl`` can also be started
with a single command directly on the shell's command line)::
> broctl
Welcome to BroControl x.y
Type "help" for help.
[BroControl] >
As the message says, type help_ to see a list of
all commands. We will now briefly summarize the most important
commands. A full reference follows `Command Reference`_.
Once ``broctl.cfg`` and ``node.cfg`` are set up as described above,
the monitoring can be started with the start_ command. In the cluster
setup, this will successively start manager, proxies, and workers. The
status_ command should then show all nodes as operating. To stop the
monitoring, issue the stop_ command. exit_ leaves the shell.
On the manager system (and on the stand-alone system), you find the
current set of (aggregated) logs in ``logs/current`` (which is a
symlink to the corresponding spool directory). The proxies and workers
log into ``spool/proxy/`` and ``spool/<worker-name>/``, respectively.
The manager/stand-alone logs are archived in ``logs/``, by default
once a day. Log files of workers and proxies are discarded at the
same rotation interval.
Whenever the *BroControl* configuration is modified in any way
(including changes to configuration files and site-specific policy
scripts), install_ installs the new version. *No changes will take
effect until* install_ *is run*. Before you run install_, check_ can be
used to check for any potential errors in the new configuration, e.g.,
typos in scripts. If check_ does not report any problems, doing
install_ will pretty likely not break anything.
Note that generally configuration changes only take effect after a
restart of the affected nodes. The restart_ command triggers this.
Some changes however can be put into effect on-the-fly without
restarting any of the nodes by using the update_ command (again only
after doing install_ first). Such dynamic updates generally work with
all changes done which only modify const variables declared as
*redefinable* (i.e., with Bro's *&redef* attribute).
Generally, site-specific tuning needs to be done with local policy
scripts, as in any Bro setup. This is described in
`Site-specific Customization`_.
*BroControl* provides various options to control the behavior of
the setup. These options can be set by editing ``broctl.cfg``.
The config_ command gives a list of all options
with their current values. A list of the most important options also
follows `Option Reference`_.
Site-specific Customization
---------------------------
You'll most likely want to adapt the Bro policy to the local
environment and much of the more specific tuning requires writing
local policy files.
During the initial install, sample local policy scripts (which you can edit)
are installed in ``share/bro/site``. In the stand-alone setup, a single
file called ``local.bro`` gets loaded automatically. In the cluster
setup, the same ``local.bro`` gets loaded, followed by one of three
other files: ``local-manager.bro``, ``local-worker.bro``, and
``local-proxy.bro`` are loaded by the manager, workers, and proxy,
respectively.
In the cluster setup, the main exception to putting everything into
``local.bro`` is notice filtering, which should be done only on the
manager.
The next scripts that are loaded are the ones that are automatically
generated by BroControl. These scripts are created from the
``networks.cfg`` and ``broctl.cfg`` files.
The last scripts loaded are any node-specific scripts specified with the
option ``aux_scripts`` in ``node.cfg``. This option can be used to
load additional scripts to individual nodes only. For example, one could
add a script ``experimental.bro`` to a single worker for trying out new
experimental code.
The scripts_ command shows precisely which policy scripts get loaded (and
in what order) by a node; that can be very helpful.
If you want to change which local policy scripts are loaded by the nodes,
you can set SitePolicyStandalone_ for all Bro instances,
SitePolicyManager_ for the manager, and SitePolicyWorker_ for the
workers. To change the directory where local policy scripts are
located, set the option SitePolicyPath_ to a different path. These
options can be changed in the ``broctl.cfg`` file.
Command Reference
-----------------
The following summary lists all commands supported by *BroControl*.
All commands may be either entered interactively or specified on the
shell's command line. If not specified otherwise, commands taking
*[<nodes>]* as arguments apply their action either to the given set of
nodes, or to all nodes if none is given.
[?1034h.. Automatically generated. Do not edit.
.. _attachgdb:
*attachgdb* *[<nodes>]*
Primarily for debugging, the command attaches a *gdb* to the main Bro
process on the given nodes.
.. _capstats:
*capstats* *[<nodes>] [<interval>]*
Determines the current load on the network interfaces monitored by
each of the given worker nodes. The load is measured over the
specified interval (in seconds), or by default over 10 seconds. This
command uses the `capstats tool
<http://www.bro.org/files/capstats-release/README.html>`_,
which is installed along with ``broctl``.
(Note: When using a CFlow and the CFlow command line utility is
installed as well, the ``capstats`` command can also query the device
for port statistics. *TODO*: document how to set this up.)
.. _check:
*check* *[<nodes>]*
Verifies a modified configuration in terms of syntactical correctness
(most importantly correct syntax in policy scripts). This command
should be executed for each configuration change *before*
install_ is used to put the change into place. Note
that ``check`` is the only command which operates correctly without a
former install_ command; ``check`` uses the policy
files as found in SitePolicyPath_ to make
sure they compile correctly. If they do, install_
will then copy them over to an internal place from where the nodes
will read them at the next start_. This approach
ensures that new errors in a policy script will not affect currently
running nodes, even when one or more of them needs to be restarted.
.. _cleanup:
*cleanup* *[--all] [<nodes>]*
Clears the nodes' spool directories (if they are not running
currently). This implies that their persistent state is flushed. Nodes
that were crashed are reset into *stopped* state. If ``--all`` is
specified, this command also removes the content of the node's
TmpDir_, in particular deleteing any data
potentially saved there for reference from previous crashes.
Generally, if you want to reset the installation back into a clean
state, you can first stop_ all nodes, then execute
``cleanup --all``, and finally start_ all nodes
again.
.. _config:
*config*
Prints all configuration options with their current values.
.. _cron:
*cron* *[enable|disable|?] | [--no-watch]*
This command has two modes of operation. Without arguments (or just
``--no-watch``), it performs a set of maintenance tasks, including
the logging of various statistical information, expiring old log
files, checking for dead hosts, and restarting nodes which terminated
unexpectedly. The latter can be suppressed with the ``--no-watch``
option if no auto-restart is desired. This mode is intended to be
executed regularly via *cron*, as described in the installation
instructions. While not intended for interactive use, no harm will be
caused by executing the command manually: all the maintenance tasks
will then just be performed one more time.
The second mode is for interactive usage and determines if the regular
tasks are indeed performed when ``broctl cron`` is executed. In other
words, even with ``broctl cron`` in your crontab, you can still
temporarily disable its execution by running ``cron disable``, and
then later reenable with ``cron enable``. This can be helpful while
working, e.g., on the BroControl configuration and ``cron`` would
interfere with that. ``cron ?`` can be used to query the current state.
.. _df:
*df* *[<nodes>]*
Reports the amount of disk space available on the nodes. Shows only
paths relevant to the broctl installation.
.. _diag:
*diag* *[<nodes>]*
If a node has terminated unexpectedly, this command prints a (somewhat
cryptic) summary of its final state including excerpts of any
stdout/stderr output, resource usage, and also a stack backtrace if a
core dump is found. The same information is sent out via mail when a
node is found to have crashed (the "crash report"). While the
information is mainly intended for debugging, it can also help to find
misconfigurations (which are usually, but not always, caught by the
check_ command).
.. _exec:
*exec* *<command line>*
Executes the given Unix shell command line on all nodes configured to
run at least one Bro instance. This is handy to quickly perform an
action across all systems.
.. _exit:
*exit*
Terminates the shell.
.. _help:
*help*
Prints a brief summary of all commands understood by the shell.
.. _install:
*install*
Reinstalls the given nodes, including all configuration files and
local policy scripts. This command must be executed after *all*
changes to any part of the broctl configuration, otherwise the
modifications will not take effect. Usually all nodes should be
reinstalled at the same time, as any inconsistencies between them will
lead to strange effects. Before executing ``install``, it is recommended
to verify the configuration with check_.
.. _netstats:
*netstats* *[<nodes>]*
Queries each of the nodes for their current counts of captured and
dropped packets.
.. _nodes:
*nodes*
Prints a list of all configured nodes.
.. _peerstatus:
*peerstatus* *[<nodes>]*
Primarily for debugging, ``peerstatus`` reports statistics about the
network connections cluster nodes are using to communicate with other
nodes.
.. _print:
*print* *<id> [<nodes>]*
Reports the *current* live value of the given Bro script ID on all of
the specified nodes (which obviously must be running). This can for
example be useful to (1) check that policy scripts are working as
expected, or (2) confirm that configuration changes have in fact been
applied. Note that IDs defined inside a Bro namespace must be
prefixed with ``<namespace>::`` (e.g., ``print SSH::did*ssh*version`` to
print the corresponding table from ``ssh.bro``.)
.. _process:
*process* *<trace> [options] [-- <scripts>]*
Runs Bro offline on a given trace file using the same configuration as
when running live. It does, however, use the potentially
not-yet-installed policy files in SitePolicyPath_ and disables log
rotation. Additional Bro command line flags and scripts can
be given (each argument after a ``--`` argument is interpreted as
a script).
Upon completion, the command prints a path where the log files can be
found. Subsequent runs of this command may delete these logs.
In cluster mode, Bro is run with *both* manager and worker scripts
loaded into a single instance. While that doesn't fully reproduce the
live setup, it is often sufficient for debugging analysis scripts.
.. _quit:
*quit*
Terminates the shell.
.. _restart:
*restart* *[--clean] [<nodes>]*
Restarts the given nodes, or all nodes if none are specified. The
effect is the same as first executing stop_ followed
by a start_, giving the same nodes in both cases.
This command is most useful to activate any changes made to Bro policy
scripts (after running install_ first). Note that a
subset of policy changes can also be installed on the fly via the
update_, without requiring a restart.
If ``--clean`` is given, the installation is reset into a clean state
before restarting. More precisely, a ``restart --clean`` turns into
the command sequence stop_, cleanup_ --all, check_, install_, and
start_.
.. _scripts:
*scripts* *[-c] [<nodes>]*
Primarily for debugging Bro configurations, the ``scripts``
command lists all the Bro scripts loaded by each of the nodes in the
order they will be parsed by the node at startup.
If ``-c`` is given, the command operates as check_ does: it reads
the policy files from their *original* location, not the copies
installed by install_. The latter option is useful to check a
not yet installed configuration.
.. _start:
*start* *[<nodes>]*
Starts the given nodes, or all nodes if none are specified. Nodes
already running are left untouched.
.. _status:
*status* *[<nodes>]*
Prints the current status of the given nodes.
.. _stop:
*stop* *[<nodes>]*
Stops the given nodes, or all nodes if none are specified. Nodes not
running are left untouched.
.. _top:
*top* *[<nodes>]*
For each of the nodes, prints the status of the two Bro
processes (parent process and child process) in a *top*-like
format, including CPU usage and memory consumption. If
executed interactively, the display is updated frequently
until key ``q`` is pressed. If invoked non-interactively, the
status is printed only once.
.. _update:
*update* *[<nodes>]*
After a change to Bro policy scripts, this command updates the Bro
processes on the given nodes *while they are running* (i.e., without
requiring a restart_). However, such dynamic
updates work only for a *subset* of Bro's full configuration. The
following changes can be applied on the fly: The value of all
const variables defined with the ``&redef`` attribute can be changed.
More extensive script changes are not possible during runtime and
always require a restart; if you change more than just the values of
``&redef``-able consts and still issue ``update``, the results are
undefined and can lead to crashes. Also note that before running
``update``, you still need to do an install_ (preferably after
check_), as otherwise ``update`` will not see the changes and it will
resend the old configuration.
Option Reference
----------------
This section summarizes the options that can be set in ``broctl.cfg``
for customizing the behavior of *BroControl*. Usually, one only needs
to change the "user options", which are listed first. The "internal
options" are, as the name suggests, primarily used internally and set
automatically. They are documented here only for reference.
.. Automatically generated. Do not edit.
User Options
~~~~~~~~~~~~
.. _BroArgs:
*BroArgs* (string, default _empty_)
Additional arguments to pass to Bro on the command-line.
.. _CFlowAddress:
*CFlowAddress* (string, default _empty_)
If a cFlow load-balancer is used, the address of the device (format: <ip>:<port>).
.. _CFlowPassword:
*CFlowPassword* (string, default _empty_)
If a cFlow load-balancer is used, the password for accessing its configuration interface.
.. _CFlowUser:
*CFlowUser* (string, default _empty_)
If a cFlow load-balancer is used, the user name for accessing its configuration interface.
.. _CommTimeout:
*CommTimeout* (int, default 10)
The number of seconds to wait before assuming Broccoli communication events have timed out.
.. _CompressCmd:
*CompressCmd* (string, default "gzip -9")
If archived logs will be compressed, the command to use for that. The specified command must compress its standard input to standard output.
.. _CompressExtension:
*CompressExtension* (string, default "gz")
If archived logs will be compressed, the file extension to use on compressed log files. When specifying a file extension, don't include the period character (e.g., specify 'gz' instead of '.gz').
.. _CompressLogs:
*CompressLogs* (bool, default 1)
True to compress archived log files.
.. _CronCmd:
*CronCmd* (string, default _empty_)
A custom command to run everytime the cron command has finished.
.. _Debug:
*Debug* (bool, default 0)
Enable extensive debugging output in spool/debug.log.
.. _HaveNFS:
*HaveNFS* (bool, default 0)
True if shared files are mounted across all nodes via NFS (see FAQ).
.. _IPv6Comm:
*IPv6Comm* (bool, default 1)
Enable IPv6 communication between cluster nodes (and also between them and BroControl)
.. _LogDir:
*LogDir* (string, default "$\{BroBase}/logs")
Directory for archived log files.
.. _LogExpireInterval:
*LogExpireInterval* (int, default 0)
Number of days log files are kept (zero means disabled).
.. _LogRotationInterval:
*LogRotationInterval* (int, default 3600)
The frequency of log rotation in seconds for the manager/standalone node.
.. _MailAlarmsTo:
*MailAlarmsTo* (string, default "$\{MailTo}")
Destination address for alarm summary mails. Default is to use the same address as MailTo.
.. _MailFrom:
*MailFrom* (string, default "Big Brother <bro@localhost>")
Originator address for broctl-generated mails.
.. _MailReplyTo:
*MailReplyTo* (string, default _empty_)
Reply-to address for broctl-generated mails.
.. _MailSubjectPrefix:
*MailSubjectPrefix* (string, default "[Bro]")
General Subject prefix for mails.
.. _MailTo:
*MailTo* (string, default "<user>")
Destination address for non-alarm mails.
.. _MakeArchiveName:
*MakeArchiveName* (string, default "$\{BroBase}/share/broctl/scripts/make-archive-name")
Script to generate filenames for archived log files.
.. _MemLimit:
*MemLimit* (string, default "unlimited")
Maximum amount of memory for Bro processes to use (in KB, or the string 'unlimited').
.. _MinDiskSpace:
*MinDiskSpace* (int, default 5)
Percentage of minimum disk space available before warning is mailed.
.. _PFRINGClusterID:
*PFRINGClusterID* (int, default @PF_RING_CLUSTER_ID@)
If PF_RING flow-based load balancing is desired, this is where the PF_RING cluster id is defined. The default value is configuration-dependent and determined automatically by CMake at configure-time based upon whether PF_RING's enhanced libpcap is available. Bro must be linked with PF_RING's libpcap wrapper for this option to work.
.. _Prefixes:
*Prefixes* (string, default "local")
Additional script prefixes for Bro, separated by colons. Use this instead of @prefix.
.. _SaveTraces:
*SaveTraces* (bool, default 0)
True to let backends capture short-term traces via '-w'. These are not archived but might be helpful for debugging.
.. _SendMail:
*SendMail* (string, default "@SENDMAIL@")
Location of the sendmail binary. Make this string blank to prevent email from being sent. The default value is configuration-dependent and determined automatically by CMake at configure-time.
.. _SitePluginPath:
*SitePluginPath* (string, default _empty_)
Directories to search for custom plugins, separated by colons.
.. _SitePolicyManager:
*SitePolicyManager* (string, default "local-manager.bro")
Space-separated list of local policy files for manager.
.. _SitePolicyPath:
*SitePolicyPath* (string, default "$\{PolicyDir}/site")
Directories to search for local policy files, separated by colons.
.. _SitePolicyStandalone:
*SitePolicyStandalone* (string, default "local.bro")
Space-separated list of local policy files for all Bro instances.
.. _SitePolicyWorker:
*SitePolicyWorker* (string, default "local-worker.bro")
Space-separated list of local policy files for workers.
.. _StopTimeout:
*StopTimeout* (int, default 60)
The number of seconds to wait before sending a SIGKILL to a node which was previously issued the 'stop' command but did not terminate gracefully.
.. _TimeFmt:
*TimeFmt* (string, default "%d %b %H:%M:%S")
Format string to print date/time specifications (see 'man strftime').
.. _TimeMachineHost:
*TimeMachineHost* (string, default _empty_)
If the manager should connect to a Time Machine, the address of the host it is running on.
.. _TimeMachinePort:
*TimeMachinePort* (string, default "47757/tcp")
If the manager should connect to a Time Machine, the port it is running on (in Bro syntax, e.g., 47757/tcp).
.. _ZoneID:
*ZoneID* (string, default _empty_)
If the host running BroControl is managing a cluster comprised of nodes with non-global IPv6 addresses, this option indicates what RFC 4007 zone_id to append to node addresses when communicating with them.
Internal Options
~~~~~~~~~~~~~~~~
.. _BinDir:
*BinDir* (string, default "$\{BroBase}/bin")
Directory for executable files.
.. _BroBase:
*BroBase* (string, default _empty_)
Base path of broctl installation on all nodes.
.. _CapstatsPath:
*CapstatsPath* (string, default "$\{bindir}/capstats")
Path to capstats binary; empty if not available.
.. _CfgDir:
*CfgDir* (string, default "$\{BroBase}/etc")
Directory for configuration files.
.. _DebugLog:
*DebugLog* (string, default "$\{SpoolDir}/debug.log")
Log file for debugging information.
.. _HelperDir:
*HelperDir* (string, default "$\{BroBase}/share/broctl/scripts/helpers")
Directory for broctl helper scripts.
.. _LibDir:
*LibDir* (string, default "$\{BroBase}/lib")
Directory for library files.
.. _LibDirInternal:
*LibDirInternal* (string, default "$\{BroBase}/lib/broctl")
Directory for broctl-specific library files.
.. _LocalNetsCfg:
*LocalNetsCfg* (string, default "$\{CfgDir}/networks.cfg")
File defining the local networks.
.. _LockFile:
*LockFile* (string, default "$\{SpoolDir}/lock")
Lock file preventing concurrent shell operations.
.. _NodeCfg:
*NodeCfg* (string, default "$\{CfgDir}/node.cfg")
Node configuration file.
.. _OS:
*OS* (string, default _empty_)
Name of operating system as reported by uname.
.. _PluginDir:
*PluginDir* (string, default "$\{LibDirInternal}/plugins")
Directory where standard plugins are located.
.. _PolicyDir:
*PolicyDir* (string, default "$\{BroBase}/share/bro")
Directory for standard policy files.
.. _PolicyDirSiteInstall:
*PolicyDirSiteInstall* (string, default "$\{SpoolDir}/installed-scripts-do-not-touch/site")
Directory where the shell copies local policy scripts when installing.
.. _PolicyDirSiteInstallAuto:
*PolicyDirSiteInstallAuto* (string, default "$\{SpoolDir}/installed-scripts-do-not-touch/auto")
Directory where the shell copies auto-generated local policy scripts when installing.
.. _PostProcDir:
*PostProcDir* (string, default "$\{BroBase}/share/broctl/scripts/postprocessors")
Directory for log postprocessors.
.. _ScriptsDir:
*ScriptsDir* (string, default "$\{BroBase}/share/broctl/scripts")
Directory for executable scripts shipping as part of broctl.
.. _SpoolDir:
*SpoolDir* (string, default "$\{BroBase}/spool")
Directory for run-time data.
.. _StandAlone:
*StandAlone* (bool, default 0)
True if running in stand-alone mode (see elsewhere).
.. _StateFile:
*StateFile* (string, default "$\{SpoolDir}/broctl.dat")
File storing the current broctl state.
.. _StaticDir:
*StaticDir* (string, default "$\{BroBase}/share/broctl")
Directory for static, arch-independent files.
.. _StatsDir:
*StatsDir* (string, default "$\{LogDir}/stats")
Directory where statistics are kept.
.. _StatsLog:
*StatsLog* (string, default "$\{SpoolDir}/stats.log")
Log file for statistics.
.. _Time:
*Time* (string, default _empty_)
Path to time binary.
.. _TmpDir:
*TmpDir* (string, default "$\{SpoolDir}/tmp")
Directory for temporary data.
.. _TmpExecDir:
*TmpExecDir* (string, default "$\{SpoolDir}/tmp")
Directory where binaries are copied before execution.
.. _TraceSummary:
*TraceSummary* (string, default "$\{bindir}/trace-summary")
Path to trace-summary script (empty if not available). Make this string blank to disable the connection summary emails.
.. _Version:
*Version* (string, default _empty_)
Version of the broctl.
Writing Plugins
---------------
BroControl provides a plugin interface to extend its functionality. A
plugin is written in Python and can do any, or all, of the following:
* Perform actions before or after any of the standard BroControl
commands is executed. When running before the actual command, it
can filter which nodes to operate or stop the execution
altogether. When running after the command, it gets access to
the commands success on a per-node basis (where applicable).
* Add custom commands to BroControl.
* Add custom options to BroControl defined in ``broctl.cfg``.
* Add custom keys to nodes defined in ``node.cfg``.
A plugin is written by deriving a new class from BroControl class
`Plugin`_. The Python script with the new plugin is then copied into a
plugin directory searched by BroControl at startup. By default,
BroControl searches ``<prefix>/lib/broctl/plugins``; further may be
configured by setting the PluginDir_ option. Note that any plugin
script must end in ``*.py`` to be found. BroControl comes with some
example plugins that can be used as a starting point; see
the ``<prefix>/lib/broctl/plugins`` directory.
In the following, we document the API that is available to plugins. A
plugin must be derived from the `Plugin`_ class, and can use its
methods as well as those of the `Node`_ class.
.. _Plugin:
Class ``Plugin``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
class **Plugin**
The class ``Plugin`` is the base class for all BroControl plugins.
The class has a number of methods for plugins to override, and every
plugin must at least override ``name()`` and ``pluginVersion()``.
For each BroControl command ``foo``, there are two methods,
``cmd_foo_pre`` and ``cmd_foo_post``, that are called just before the
command is executed and just after it has finished, respectively. The
arguments these methods receive correspond to their command-line
parameters, and are further documented below.
The ``cmd_<XXX>_pre`` methods have the ability to prevent the command's
execution, either completely or partially for those commands that take
nodes as parameters. In the latter case, the method receives a list of
nodes that the command is to be run on, and it can filter that list and
returns modified version of nodes to actually use. The standard case would
be returning simply the unmodified ``nodes`` parameter. To completely
block the command's execution, return an empty list. To just not execute
the command for a subset, remove the affected ones. For commands that do
not receive nodes as arguments, the return value is interpreted as boolean
indicating whether command execution should proceed (True) or not (False).
The ``cmd_<XXX>_post`` methods likewise receive the commands arguments as
their parameter, as documented below. For commands taking nodes, the list
corresponds to those nodes for which the command was actually executed
(i.e., after any ``cmd_<XXX>_pre`` filtering). Each node is given as a
tuple ``(node, bool)`` with *node* being the actual `Node`_, and the boolean
indicating whether the command was successful for it.
Note that if a plugin prevents a command from executing either completely or
partially, it should report its reason via the ``message*()`` or
``error()`` methods.
If multiple plugins hook into the same command, all their
``cmd_<XXX>_{pre,post}`` are executed in undefined order. The command is
executed on the intersection of all ``cmd_<XXX>_pre`` results.
Finally, note that the ``restart`` command doesn't have its own method as
it's just a combination of other commands and thus their callbacks are
run.
.. _Plugin.debug:
**debug** (self, msg)
Logs a debug message in BroControl's debug log if enabled.
.. _Plugin.error:
**error** (self, msg)
Reports an error to the user.
.. _Plugin.execute:
**execute** (self, node, cmd)
Executes a command on the host for the given *node* of type
`Node`_. Returns a tuple ``(success, output)`` in which ``success`` is
True if the command ran successfully and ``output`` is the combined
stdout/stderr output.
.. _Plugin.executeParallel:
**executeParallel** (self, cmds)
Executes a set of commands in parallel on multiple hosts. ``cmds``
is a list of tuples ``(node, cmd)``, in which the *node* is a `Node`_
instance and *cmd* is a string with the command to execute for it. The
method returns a list of tuples ``(node, success, output)``, in which
``success`` is True if the command ran successfully and ``output`` is
the combined stdout/stderr output for the corresponding ``node``.
.. _Plugin.getGlobalOption:
**getGlobalOption** (self, name)
Returns the value of the global BroControl option or state
attribute *name*. If the user has not set the options, its default
value is returned. See the output of ``broctl config`` for a complete
list.
.. _Plugin.getOption:
**getOption** (self, name)
Returns the value of one of the plugin's options, *name*. The
returned value will always be a string.
An option has a default value (see *options()*), which can be
overridden by a user in ``broctl.cfg``. An option's value cannot be
changed by the plugin.
.. _Plugin.getState:
**getState** (self, name)
Returns the current value of one of the plugin's state variables,
*name*. The returned value will always be a string. If it has not yet
been set, an empty string will be returned.
Different from options, state variables can be set by the plugin and
are persistent across restarts. They are not visible to the user.
Note that a plugin cannot query any global BroControl state variables.
.. _Plugin.hosts:
**hosts** (self, nodes)
Returns a list of all hosts running at least one node from the list
of Nodes_ objects in *nodes*, or configured in if *nodes* is empty.
.. _Plugin.message:
**message** (self, msg)
Reports a message to the user.
.. _Plugin.nodes:
**nodes** (self)
Returns a list of all configured `Node`_ objects.
.. _Plugin.parseNodes:
**parseNodes** (self, names)
Returns `Node`_ objects for a string of space-separated node names.
If a name does not correspond to a known node, an error message is
printed and the node is skipped from the returned list. If no names
are known, an empty list is returned.
.. _Plugin.setState:
**setState** (self, name, value)
Sets one of the plugin's state variables, *name*, to *value*.
*value* must be a string. The change is permanent and will be recorded
to disk.
Note that a plugin cannot change any global BroControl state
variables.
.. _Plugin.broProcessDied:
**broProcessDied** (self, node)
Called when BroControl finds the Bro process for Node_ *node*
to have terminated unexpectedly. This method will be called just
before BroControl prepares the node's "crash report" and before it
cleans up the node's spool directory.
This method can be overridden by derived classes. The default
implementation does nothing.
.. _Plugin.cmd_attachgdb_post:
**cmd_attachgdb_post** (self, nodes)
Called just after the ``attachgdb`` command has finished. Arguments
are as with the ``pre`` method.
This method can be overridden by derived classes. The default
implementation does nothing.
.. _Plugin.cmd_attachgdb_pre:
**cmd_attachgdb_pre** (self, nodes)
Called just before the ``attachgdb`` command is run. It receives the
list of nodes, and returns the list of nodes that should proceed with
the command.
This method can be overridden by derived classes. The default
implementation does nothing.
.. _Plugin.cmd_capstats_post:
**cmd_capstats_post** (self, nodes, interval)
Called just after the ``capstats`` command has finished. Arguments
are as with the ``pre`` method.
This method can be overridden by derived classes. The default
implementation does nothing.
.. _Plugin.cmd_capstats_pre:
**cmd_capstats_pre** (self, nodes, interval)
Called just before the ``capstats`` command is run. It receives the
list of nodes, and returns the list of nodes that should proceed with
the command. *integer* is an integer with the measurement interval in
seconds.
This method can be overridden by derived classes. The default
implementation does nothing.
.. _Plugin.cmd_check_post:
**cmd_check_post** (self, results)
Called just after the ``check`` command has finished. It receives
the list of 2-tuples ``(node, bool)`` indicating the nodes the command
was executed for, along with their success status.
This method can be overridden by derived classes. The default
implementation does nothing.
.. _Plugin.cmd_check_pre:
**cmd_check_pre** (self, nodes)
Called just before the ``check`` command is run. It receives the
list of nodes, and returns the list of nodes that should proceed with
the command.
This method can be overridden by derived classes. The default
implementation does nothing.
.. _Plugin.cmd_cleanup_post:
**cmd_cleanup_post** (self, nodes, all)
Called just after the ``cleanup`` command has finished. Arguments
are as with the ``pre`` method.
This method can be overridden by derived classes. The default
implementation does nothing.
.. _Plugin.cmd_cleanup_pre:
**cmd_cleanup_pre** (self, nodes, all)
Called just before the ``cleanup`` command is run. It receives the
list of nodes, and returns the list of nodes that should proceed with
the command. *all* is boolean indicating whether the ``--all``
argument has been given.
This method can be overridden by derived classes. The default
implementation does nothing.
.. _Plugin.cmd_config_post:
**cmd_config_post** (self)
Called just after the ``config`` command has finished.
This method can be overridden by derived classes. The default
implementation does nothing.
.. _Plugin.cmd_config_pre:
**cmd_config_pre** (self)
Called just before the ``config`` command is run.
This method can be overridden by derived classes. The default
implementation does nothing.
.. _Plugin.cmd_cron_post:
**cmd_cron_post** (self, arg, watch)
Called just after the ``cron`` command has finished. Arguments are
as with the ``pre`` method.
This method can be overridden by derived classes. The default
implementation does nothing.
.. _Plugin.cmd_cron_pre:
**cmd_cron_pre** (self, arg, watch)
Called just before the ``cron`` command is run. *arg* is None if
the cron is executed without arguments. Otherwise, it is one of the
strings: ``enable``, ``disable``, ``?``. *watch* is a boolean
indicating whether ``cron`` should restart abnormally terminated Bro
processes; it's only valid if arg is empty.
This method can be overridden by derived classes. The default
implementation does nothing.
.. _Plugin.cmd_custom:
**cmd_custom** (self, cmd, args)
Called when command defined by the ``commands`` method is executed.
``cmd`` is the command (with the plugin's prefix), and ``args`` is a
single *string* with all arguments.
If the arguments are actually node names, ``parseNodes`` can
be used to get the `Node`_ objects.
This method can be overridden by derived classes. The default
implementation does nothing.
.. _Plugin.cmd_df_post:
**cmd_df_post** (self, nodes)
Called just after the ``df`` command has finished. Arguments are as
with the ``pre`` method.
This method can be overridden by derived classes. The default
implementation does nothing.
.. _Plugin.cmd_df_pre:
**cmd_df_pre** (self, nodes)
Called just before the ``df`` command is run. It receives the
list of nodes, and returns the list of nodes that should proceed with
the command.
This method can be overridden by derived classes. The default
implementation does nothing.
.. _Plugin.cmd_diag_post:
**cmd_diag_post** (self, nodes)
Called just after the ``diag`` command has finished. Arguments are
as with the ``pre`` method.
This method can be overridden by derived classes. The default
implementation does nothing.
.. _Plugin.cmd_diag_pre:
**cmd_diag_pre** (self, nodes)
Called just before the ``diag`` command is run. It receives the
list of nodes, and returns the list of nodes that should proceed with
the command.
This method can be overridden by derived classes. The default
implementation does nothing.
.. _Plugin.cmd_exec_post:
**cmd_exec_post** (self, cmdline)
Called just after the ``exec`` command has finished. Arguments are
as with the ``pre`` method.
This method can be overridden by derived classes. The default
implementation does nothing.
.. _Plugin.cmd_exec_pre:
**cmd_exec_pre** (self, cmdline)
Called just before the ``exec`` command is run. *cmdline* is a
string with the command line to execute.
This method can be overridden by derived classes. The default
implementation does nothing.
.. _Plugin.cmd_install_post:
**cmd_install_post** (self)
Called just after the ``install`` command has finished.
This method can be overridden by derived classes. The default
implementation does nothing.
.. _Plugin.cmd_install_pre:
**cmd_install_pre** (self)
Called just before the ``install`` command is run.
This method can be overridden by derived classes. The default
implementation does nothing.
.. _Plugin.cmd_netstats_post:
**cmd_netstats_post** (self, nodes)
Called just after the ``netstats`` command has finished. Arguments
are as with the ``pre`` method.
This method can be overridden by derived classes. The default
implementation does nothing.
.. _Plugin.cmd_netstats_pre:
**cmd_netstats_pre** (self, nodes)
Called just before the ``netstats`` command is run. It receives the
list of nodes, and returns the list of nodes that should proceed with
the command.
This method can be overridden by derived classes. The default
implementation does nothing.
.. _Plugin.cmd_nodes_post:
**cmd_nodes_post** (self)
Called just after the ``nodes`` command has finished.
This method can be overridden by derived classes. The default
implementation does nothing.
.. _Plugin.cmd_nodes_pre:
**cmd_nodes_pre** (self)
Called just before the ``nodes`` command is run.
This method can be overridden by derived classes. The default
implementation does nothing.
.. _Plugin.cmd_peerstatus_post:
**cmd_peerstatus_post** (self, nodes)
Called just after the ``peerstatus`` command has finished.
Arguments are as with the ``pre`` method.
This method can be overridden by derived classes. The default
implementation does nothing.
.. _Plugin.cmd_peerstatus_pre:
**cmd_peerstatus_pre** (self, nodes)
Called just before the ``peerstatus`` command is run. It receives the
list of nodes, and returns the list of nodes that should proceed with
the command.
This method can be overridden by derived classes. The default
implementation does nothing.
.. _Plugin.cmd_print_post:
**cmd_print_post** (self, nodes, id)
Called just after the ``print`` command has finished. Arguments are
as with the ``pre`` method.
This method can be overridden by derived classes. The default
implementation does nothing.
.. _Plugin.cmd_print_pre:
**cmd_print_pre** (self, nodes, id)
Called just before the ``print`` command is run. It receives the
list of nodes, and returns the list of nodes that should proceed with
the command. *id* is a string with the name of the ID to be printed.
This method can be overridden by derived classes. The default
implementation does nothing.
.. _Plugin.cmd_process_post:
**cmd_process_post** (self, trace, options, scripts, success)
Called just after the ``process`` command has finished. Arguments
are as with the ``pre`` method, plus an additional boolean *success*
indicating whether Bro terminated normally.
This method can be overridden by derived classes. The default
implementation does nothing.
.. _Plugin.cmd_process_pre:
**cmd_process_pre** (self, trace, options, scripts)
Called just before the ``process`` command is run. It receives the
*trace* to read from as a string, a list of additional Bro *options*,
and a list of additional Bro scripts.
This method can be overridden by derived classes. The default
implementation does nothing.
.. _Plugin.cmd_restart_post:
**cmd_restart_post** (self, results)
Called just after the ``restart`` command has finished. It receives
the list of 2-tuples ``(node, bool)`` indicating the nodes the command
was executed for, along with their success status. The remaining
arguments are as with the ``pre`` method.
This method can be overridden by derived classes. The default
implementation does nothing.
.. _Plugin.cmd_restart_pre:
**cmd_restart_pre** (self, nodes, clean)
Called just before the ``restart`` command is run. It receives the
list of nodes, and returns the list of nodes that should proceed with
the command. *clean* is boolean indicating whether the ``--clean``
argument has been given.
This method can be overridden by derived classes. The default
implementation does nothing.
.. _Plugin.cmd_scripts_post:
**cmd_scripts_post** (self, nodes, full_path, check)
Called just after the ``scripts`` command has finished. Arguments
are as with the ``pre`` method.
This method can be overridden by derived classes. The default
implementation does nothing.
.. _Plugin.cmd_scripts_pre:
**cmd_scripts_pre** (self, nodes, full_path, check)
Called just before the ``scripts`` command is run. It receives the
list of nodes, and returns the list of nodes that should proceed with
the command. ``full_path`` and ``check`` are boolean indicating
whether the ``-p`` and ``-c`` options were given, respectively.
This method can be overridden by derived classes. The default
implementation does nothing.
.. _Plugin.cmd_start_post:
**cmd_start_post** (self, results)
Called just after the ``start`` command has finished. It receives
the list of 2-tuples ``(node, bool)`` indicating the nodes the command
was executed for, along with their success status.
This method can be overridden by derived classes. The default
implementation does nothing.
.. _Plugin.cmd_start_pre:
**cmd_start_pre** (self, nodes)
Called just before the ``start`` command is run. It receives the
list of nodes, and returns the list of nodes that should proceed with
the command.
This method can be overridden by derived classes. The default
implementation does nothing.
.. _Plugin.cmd_status_post:
**cmd_status_post** (self, nodes)
Called just after the ``status`` command has finished. Arguments
are as with the ``pre`` method.
This method can be overridden by derived classes. The default
implementation does nothing.
.. _Plugin.cmd_status_pre:
**cmd_status_pre** (self, nodes)
Called just before the ``status`` command is run. It receives the
list of nodes, and returns the list of nodes that should proceed with
the command.
This method can be overridden by derived classes. The default
implementation does nothing.
.. _Plugin.cmd_stop_post:
**cmd_stop_post** (self, results)
Called just after the ``stop`` command has finished. It receives
the list of 2-tuples ``(node, bool)`` indicating the nodes the command
was executed for, along with their success status.
This method can be overridden by derived classes. The default
implementation does nothing.
.. _Plugin.cmd_stop_pre:
**cmd_stop_pre** (self, nodes)
Called just before the ``stop`` command is run. It receives the
list of nodes, and returns the list of nodes that should proceed with
the command.
This method can be overridden by derived classes. The default
implementation does nothing.
.. _Plugin.cmd_top_post:
**cmd_top_post** (self, nodes)
Called just after the ``top`` command has finished. Arguments are
as with the ``pre`` method. Note that when ``top`` is run
interactively to auto-refresh continuously, this method will be called
once after each update.
This method can be overridden by derived classes. The default
implementation does nothing.
.. _Plugin.cmd_top_pre:
**cmd_top_pre** (self, nodes)
Called just before the ``top`` command is run. It receives the list
of nodes, and returns the list of nodes that should proceed with the
command. Note that when ``top`` is run interactively to auto-refresh
continuously, this method will be called once before each update.
This method can be overridden by derived classes. The default
implementation does nothing.
.. _Plugin.cmd_update_post:
**cmd_update_post** (self, results)
Called just after the ``update`` command has finished. It receives
the list of 2-tuples ``(node, bool)`` indicating the nodes the command
was executed for, along with their success status.
This method can be overridden by derived classes. The default
implementation does nothing.
.. _Plugin.cmd_update_pre:
**cmd_update_pre** (self, nodes)
Called just before the ``update`` command is run. It receives the
list of nodes, and returns the list of nodes that should proceed with
the command.
This method can be overridden by derived classes. The default
implementation does nothing.
.. _Plugin.commands:
**commands** (self)
Returns a set of custom commands provided by the
plugin.
The return value is a list of 3-tuples each having the following
elements:
``command``
A string with the command's name. Note that the command name
exposed to the user will be prefixed with the plugin's prefix
as returned by *name()* (e.g., ``myplugin.mycommand``).
``arguments``
A string describing the command's arguments in a textual form
suitable for use in the ``help`` command summary (e.g.,
``[<nodes>]`` for command taking an optional list of nodes).
Empty if no arguments are expected.
``description``
A string with a description of the command's semantics.
This method can be overridden by derived classes. The implementation
must not call the parent class' implementation. The default
implementation returns an empty list.
.. _Plugin.done:
**done** (self)
Called once just before BroControl terminates. This method can do
any cleanup the plugin may require.
This method can be overridden by derived classes. The default
implementation does nothing.
.. _Plugin.hostStatusChanged:
**hostStatusChanged** (self, host, status)
Called when BroControl's ``cron`` command finds the availability of
a cluster system to have changed. Initially, all systems are assumed
to be up and running. Once BroControl notices that a system isn't
responding (defined as either it doesn't ping at all, or does not
accept SSH sessions), it calls this method, passing in a string with
the name of the *host* and a boolean *status* set to False. Once the
host becomes available again, the method will be called again for the
same host with *status* now set to True.
Note that BroControl's ``cron`` tracks a host's availability across
execution, so if the next time it's run the host is still down, this
method will not be called again.
This method can be overridden by derived classes. The default
implementation does nothing.
.. _Plugin.init:
**init** (self)
Called once just before BroControl starts executing any commands.
This method can do any initialization that the plugin may require.
Note that when this method executes, BroControl guarantees that all
internals are fully set up (e.g., user-defined options are available).
This may not be the case when the class ``__init__`` method runs.
Returns a boolean, indicating whether the plugin should be used. If it
returns ``False``, the plugin will be removed and no other methods
called.
This method can be overridden by derived classes. The default
implementation always returns True.
.. _Plugin.name:
**name** (self)
Returns a string with a descriptive *name* for the plugin (e.g.,
``"TestPlugin"``). The name must not contain any whitespace.
This method must be overridden by derived classes. The implementation
must not call the parent class' implementation.
.. _Plugin.nodeKeys:
**nodeKeys** (self)
Returns a list of custom keys for ``node.cfg``. The value for a
key will be available from the `Node`_ object as attribute
``<prefix>_<key>`` (e.g., ``node.test_mykw``). If not set, the
attribute will be set to None.
This method can be overridden by derived classes. The implementation
must not call the parent class' implementation. The default
implementation returns an empty list.
.. _Plugin.options:
**options** (self)
Returns a set of local configuration options provided by the
plugin.
The return value is a list of 4-tuples each having the following
elements:
``name``
A string with name of the option (e.g., ``Path``). Option
names are case-insensitive. Note that the option name exposed
to the user will be prefixed with your plugin's prefix as
returned by *name()* (e.g., ``myplugin.Path``).
``type``
A string with type of the option, which must be one of
``"bool"``, ``"string"``, or ``"int"``.
``default``
A string with the option's default value. Note that this must
always be a string, even for non-string types. For booleans,
use ``"0"`` for False and ``"1"`` for True. For integers, give
the value as a string ``"42"``.
``description``
A string with a description of the option semantics.
This method can be overridden by derived classes. The implementation
must not call the parent class' implementation. The default
implementation returns an empty list.
.. _Plugin.pluginVersion:
**pluginVersion** (self)
Returns an integer with a version number for the plugin. Plugins
should increase their version number with any significant change.
This method must be overridden by derived classes. The implementation
must not call the parent class' implementation.
.. _Plugin.prefix:
**prefix** (self)
Returns a string with a prefix for the plugin's options and
commands names (e.g., "myplugin").
This method can be overridden by derived classes. The implementation
must not call the parent class' implementation. The default
implementation returns a lower-cased version of *name()*.
.. _Node:
Class ``Node``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
class **Node**
Class representing one node of the BroControl maintained setup. In
standalone mode, there's always exactly one node of type ``standalone``. In
a cluster setup, there is exactly one of type ``manager``, one or
more of type ``proxy``, and zero or more of type ``worker``.
In addition to the methods described above, a ``Node`` object has a number
of keys with values that are set via ``node.cfg`` and can be accessed
directly via corresponding Python attributes (e.g., ``node.name``):
``name`` (string)
The name of the node, which corresponds to the ``[<name>]``
section in ``node.cfg``.
``type`` (string)
The type of the node, which will be one of ``standalone``,
``manager``, ``proxy``, and ``worker``.
``host`` (string)
The hostname of the system the node is running on.
``interface`` (string)
The network interface for Bro to use; empty if not set.
``lb_procs`` (integer)
The number of clustered Bro workers you'd like to start up.
``lb_method`` (string)
The load balancing method to distribute packets to all of the
processes (must be one of: ``pf_ring``, ``myricom``, or
``interfaces``).
``lb_interfaces`` (string)
If the load balancing method is ``interfaces``, then this is
a comma-separated list of network interface names to use.
``aux_scripts`` (string)
Any node-specific Bro script configured for this node.
``zone_id`` (string)
If BroControl is managing a cluster comprised of nodes
using non-global IPv6 addresses, then this configures the
RFC 4007 ``zone_id`` string that the node associates with
the common zone that all cluster nodes are a part of. This
identifier may differ between nodes.
Any attribute that is not defined in ``node.cfg`` will be empty.
In addition, plugins can override `Plugin.nodeKeys`_ to define their own
node keys, which can then be likewise set in ``node.cfg``. The key names
will be prepended with the plugin's `Plugin.prefix`_ (e.g., for the plugin
``test``, the node key ``foo`` is set by adding ``test.foo=value`` to
``node.cfg``).
.. _Node.cwd:
**cwd** (self)
Returns a string with the node's working directory.
.. _Node.describe:
**describe** (self)
Returns an extended string representation of the node including all
its keys with values.
.. _Node.getPID:
**getPID** (self)
Returns the process ID of the node's Bro process if running, and
None otherwise.
.. _Node.getPort:
**getPort** (self)
Returns an integer with the port that this node's communication
system is listening on for incoming connections, or -1 if no such port
has been set yet.
.. _Node.hasCrashed:
**hasCrashed** (self)
Returns True if the node's Bro process has exited abnormally.
Miscellaneous
-------------
Mails
~~~~~
*BroControl* sends four types of mails to the address given in
``MailTo``:
1. When logs are rotated (per default once a day), a list of all
alarms during the last rotation interval is sent. This can be
disabled by setting ``MailAlarms=0``.
2. When the ``cron`` command notices that a node has crashed, it
restarts it and sends a notification. It may also send a more
detailed crash report containing information about the crash.
3. NOTICES with a notice action ``EMAIL``.
4. If `trace-summary <http://www.bro.org/documentation/components/trace-summary/README.html>`_
is installed, a traffic summary is sent each rotation interval.
Performance Analysis
~~~~~~~~~~~~~~~~~~~~
*TODO*: ``broctl cron`` logs a number of statistics, which can be
analyzed/plotted for understanding the clusters run-time behavior.
Questions and Answers
---------------------
*Can I use an NFS-mounted partition as the cluster's base directory to avoid the ``rsync``'ing?*
Yes. BroBase_ can be on an NFS partition.
Configure and install the shell as usual with
``--prefix=<BroBase>``. Then add ``HaveNFS=1`` and
``SpoolDir=<spath>`` to ``broctl.cfg``, where ``<spath>`` is a
path on the local disks of the nodes; ``<spath>`` will be used for
all non-shared data (make sure that the parent directory exists
and is writable on all nodes!). Then run ``make install`` again.
Finally, you can remove ``<BroBase>/spool`` (or link it to <spath>).
In addition, you might want to keep the log files locally on the nodes
as well by setting LogDir_ to a non-NFS directory. (Only
the manager's logs will be kept permanently, the logs of
workers/proxies are discarded upon rotation.)
*When I'm using the stand-alone mode, do I still need to have ``ssh`` and ``rsync`` installed and configured?*
No. In stand-alone mode all operations are performed directly on the local
file system.
*What do I need to do when something in the Bro distribution changes?*
After pulling from the main Bro git repository, just re-run ``make
install`` inside your build directory. It will reinstall all the
files from the distribution that are not up-to-date. Then do
``broctl install`` to make sure everything gets pushed out.
*Can I change the naming scheme that BroControl uses for archived log files?*
Yes, set MakeArchiveName_ to a
script that outputs the desired destination file name for an
archived log file. The default script for that task is
``<BroBase>/share/broctl/scripts/make-archive-name``, which you
can use as a template for creating your own version. See
the beginning of that script for instructions.
*Can BroControl manage a cluster of nodes over non-global IPv6 scope (e.g. link-local)?*
Yes, set ``ZoneID`` in ``broctl.cfg`` to the zone identifier
that the BroControl node uses to identify the scope zone
(the ``ifconfig`` command output is usually helpful, if it doesn't
show the zone identifier appended to the address with a '%'
character, then it may just be the interface name). Then in
``node.cfg``, add a ``zone_id`` key to each node section
representing that particular node's zone identifier and set
the ``host`` key to the IPv6 address assigned to the node within
the scope zone. Most nodes probably have the same ``zone_id``, but
may not if their interface configuration differs. See RFC 4007 for
more information on IPv6 scoped addresses and zones.