2209 lines
83 KiB
ReStructuredText
2209 lines
83 KiB
ReStructuredText
.. Autogenerated. Do not edit.
|
|
|
|
.. -*- mode: rst-mode -*-
|
|
..
|
|
.. Note: This file includes further autogenerated ones.
|
|
..
|
|
.. Version number is filled in automatically.
|
|
.. |version| replace:: 2.6.0-2
|
|
|
|
===========
|
|
ZeekControl
|
|
===========
|
|
|
|
.. rst-class:: opening
|
|
|
|
This document summarizes installation and use of *ZeekControl*,
|
|
a tool for operating Zeek installations. *ZeekControl*
|
|
has two modes of operation: a *stand-alone* mode for
|
|
managing a traditional, single-system Zeek setup; and a *cluster*
|
|
mode for maintaining a multi-system setup of coordinated Zeek
|
|
instances load-balancing the work across a set of independent
|
|
machines. 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 ZeekControl release for download at
|
|
https://www.zeek.org/download.
|
|
|
|
ZeekControl's git repository is located at https://github.com/zeek/zeekctl.
|
|
|
|
This document describes ZeekControl |version|. See the ``CHANGES``
|
|
file for version history.
|
|
|
|
Prerequisites
|
|
-------------
|
|
|
|
Running ZeekControl requires the following prerequisites:
|
|
|
|
- A Unix system. FreeBSD, Linux, and Mac OS X are supported and
|
|
should work out of the box. Other Unix systems will quite likely
|
|
require some tweaking.
|
|
|
|
- A version of *Python* >= 3.9 (on FreeBSD, the package "pyXY-sqlite3" must
|
|
also be installed for whatever your Python X.Y version is).
|
|
|
|
- A *bash* (note that on FreeBSD, *bash* is not installed by default).
|
|
|
|
- If *sendmail* is installed, then ZeekControl can send mail (for a cluster
|
|
setup, it would be needed on the manager only). Otherwise, ZeekControl
|
|
will not attempt to send mail.
|
|
|
|
- If *gdb* (*lldb* on Mac OS X, which is included with Xcode) is installed
|
|
and if Zeek crashes with a core dump, then ZeekControl can include
|
|
a backtrace in its crash report (that can be helpful for debugging
|
|
problems with Zeek). Otherwise, crash reports will not include a backtrace.
|
|
|
|
For a cluster setup that spans more than one machine, there are
|
|
additional requirements:
|
|
|
|
- All machines in the cluster must be running exactly the *same* operating
|
|
system (even the version must be the same).
|
|
|
|
- Every host in the cluster must have *rsync* installed.
|
|
|
|
- The manager host must have *ssh* installed, and every other host in the
|
|
cluster must have *sshd* installed and running.
|
|
|
|
- Decide which user account will be running ZeekControl, and then make sure
|
|
this user account is set up on all hosts in your cluster.
|
|
Note that if you plan to run zeekctl using sudo (i.e., "sudo zeekctl"), then
|
|
the user running zeekctl will be "root" (and in that case the user running
|
|
sudo does not need to exist on the other hosts in your cluster).
|
|
|
|
- Make sure the user running ZeekControl can ``ssh`` from the manager host
|
|
to each of the other hosts in your cluster, and this must work without
|
|
being prompted for anything (one way to accomplish this is to use ssh
|
|
public key authentication). You will need to try this manually before
|
|
attempting to run zeekctl, because zeekctl uses ssh to connect to other
|
|
hosts in your cluster.
|
|
|
|
If you're using a load-balancing method (such as PF_RING), then there is
|
|
additional software to install (for details, see the
|
|
:doc:`Cluster Configuration <../../configuration/index>` documentation).
|
|
|
|
|
|
Installation
|
|
------------
|
|
|
|
Follow the directions to install Zeek and ZeekControl
|
|
in the :doc:`Installing Zeek <../../install/install>`
|
|
documentation. Note that if you are planning to run Zeek in a cluster
|
|
configuration, then you need to install Zeek and ZeekControl only on the
|
|
manager host (the ZeekControl install_ or deploy_ commands will install Zeek
|
|
and all required scripts to the other hosts in your cluster).
|
|
|
|
|
|
Configuration
|
|
-------------
|
|
|
|
Before attempting to run ZeekControl, you first need to edit the ``zeekctl.cfg``,
|
|
``node.cfg``, and ``networks.cfg`` files. All three of these configuration
|
|
files contain a valid configuration by default, but you might need to
|
|
customize a few things.
|
|
|
|
First, edit the ``node.cfg`` file and specify the nodes that you will be
|
|
running. You need to decide whether you will be running Zeek standalone or
|
|
in a cluster. For a standalone configuration, there must be only one Zeek node
|
|
defined in this file. For a cluster configuration, at a minimum there
|
|
must be a manager node, a proxy node, and one or more worker nodes.
|
|
There is a :doc:`Cluster Configuration <../../configuration/index>`
|
|
guide that provides examples and additional information.
|
|
|
|
Each node defined in the ``node.cfg`` file has a set of options. A few options
|
|
are required to be specified on every node, and some options are allowed only
|
|
on certain node types (zeekctl will issue an error if you make a mistake).
|
|
By default, the ``node.cfg`` file contains a valid configuration for
|
|
a standalone setup and has a valid cluster configuration commented-out.
|
|
If you want to use the default configuration, then at least check if
|
|
the "interface" option is set correctly for your system. For a
|
|
description of every option available for nodes, see the `Node`_ section below.
|
|
|
|
In the ``zeekctl.cfg`` file, you should review the ZeekControl options and
|
|
check if any are not set correctly for your environment. The options have
|
|
default values that are reasonable for most users (the MailTo_ option is
|
|
probably the one that you will most likely want to change), but for a
|
|
description of every ZeekControl option, see the `Option Reference`_ section
|
|
below.
|
|
|
|
ZeekControl options are used in three different ways: some options
|
|
override the value of a Zeek script constant (these are noted in the
|
|
documentation), some affect only ZeekControl itself, and others affect Zeek.
|
|
|
|
Finally, edit the ``networks.cfg`` file and add each network (using standard
|
|
CIDR notation) that is considered local to the monitored environment (by
|
|
default, the ``networks.cfg`` file just lists the private IPv4 address spaces).
|
|
|
|
The information in the ``networks.cfg`` file is used when creating connection
|
|
summary reports. Also, ZeekControl takes the information in the
|
|
``networks.cfg`` file and puts it in the global Zeek script constant
|
|
``Site::local_nets``, and this global constant is used by several
|
|
standard Zeek scripts.
|
|
|
|
|
|
Basic Usage
|
|
-----------
|
|
|
|
There are two ways to run ZeekControl commands: by specifying a ZeekControl
|
|
command on the command-line (e.g. "zeekctl deploy"), or by entering
|
|
ZeekControl's interactive shell by running the zeekctl script without
|
|
any arguments (e.g. "zeekctl"). The interactive shell expects
|
|
commands on its command-line::
|
|
|
|
> zeekctl
|
|
Welcome to ZeekControl x.y
|
|
|
|
Type "help" for help.
|
|
|
|
[ZeekControl] >
|
|
|
|
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`_.
|
|
|
|
If this is the first time you are running ZeekControl, then the first command
|
|
you must run is the ZeekControl deploy_ command. The "deploy" command
|
|
will make sure all of the files needed by ZeekControl and Zeek are brought
|
|
up-to-date based on the configuration specified in the ``zeekctl.cfg``,
|
|
``node.cfg``, and ``networks.cfg`` files. It will also check if there
|
|
are any syntax errors in your Zeek policy scripts. For a cluster setup it will
|
|
copy all of the required scripts and executables to all the other hosts
|
|
in your cluster. Then it will successively start the logger, manager,
|
|
proxies, and workers (for a standalone configuration, only one Zeek instance
|
|
will be started).
|
|
|
|
The status_ command can be used to check that all nodes are "running".
|
|
If any nodes have a status of "crashed", then use the diag_ command to
|
|
see diagnostic information (you can specify the name of a crashed node
|
|
as an argument to the diag command to show diagnostics for only that one
|
|
node).
|
|
|
|
If you want to stop the monitoring, issue the stop_ command. After all
|
|
nodes have stopped, the status_ command should show all nodes as "stopped".
|
|
|
|
The exit_ command leaves the shell (you can exit ZeekControl while Zeek
|
|
is running).
|
|
|
|
Whenever the ZeekControl or Zeek configuration is modified in any way,
|
|
including changes to configuration files and site-specific policy
|
|
scripts or upgrading to a new version of Zeek, deploy_ must
|
|
be run (deploy will check all policy scripts, install all needed files, and
|
|
restart Zeek). No changes will take effect until deploy_ is run.
|
|
|
|
|
|
ZeekControl cron command
|
|
-----------------------
|
|
|
|
The main purpose of the ZeekControl cron_ command is to check for Zeek nodes
|
|
that have crashed, and to restart them. The command also performs other
|
|
housekeeping tasks, such as removing expired log files, checking if there is
|
|
sufficient free disk space, etc. Although this command can be run directly
|
|
by a user, it is intended to be run from a cron job so that crashed nodes
|
|
will be restarted automatically.
|
|
|
|
For example, to setup a cron job that runs once every
|
|
five minutes, insert the following entry into the crontab of the
|
|
user running ZeekControl (change the path to the actual location of zeekctl
|
|
on your system) by running the ``crontab -e`` command::
|
|
|
|
*/5 * * * * /usr/local/zeek/bin/zeekctl cron
|
|
|
|
It is important to make sure that the cron job runs as the same user that
|
|
normally runs zeekctl on your system. For a cluster configuration, this
|
|
should be run only on the manager host.
|
|
|
|
Note that on some systems, the default PATH for cron jobs might not include
|
|
the directory where python or bash are installed (the symptoms of this
|
|
problem would be that "zeekctl cron" works when run directly by the user,
|
|
but does not work from a cron job). The simplest fix for this problem
|
|
would be to redefine PATH on a line immediately before the line that
|
|
runs zeekctl in your crontab.
|
|
|
|
If the ``"zeekctl cron disable"`` command is run, then zeekctl cron will be
|
|
disabled (i.e., zeekctl cron won't do anything) until the
|
|
``"zeekctl cron enable"`` command is run. To check the status at any
|
|
time, run ``"zeekctl cron ?"``.
|
|
|
|
|
|
Log Files
|
|
---------
|
|
|
|
Log rotation and archival
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
While Zeek is running you can find the current set of (aggregated) logs
|
|
in ``logs/current`` (which is a symlink to the corresponding spool directory).
|
|
In a cluster setup, logs are written on the logger host (however, if there
|
|
is no logger defined in your node.cfg, then the manager writes logs).
|
|
|
|
Zeek logs are automatically rotated once per hour by default, or whenever Zeek
|
|
is stopped. A rotated log is renamed to contain a timestamp in the filename.
|
|
For example, the ``conn.log`` might be renamed to
|
|
``conn.2015-01-20-15-23-42.log``.
|
|
|
|
Immediately after a log is rotated, it is archived automatically. When a log
|
|
is archived, it is moved to a subdirectory of ``logs/`` named by date (such
|
|
as ``logs/2015-01-20``), then it is renamed again, and gzipped. For example,
|
|
a rotated log file named ``conn.2015-01-20-15-23-42.log`` might be archived
|
|
to ``logs/2015-01-20/conn.15:48:23-16:00:00.log.gz``. If the archival was
|
|
successful, then the original (rotated) log file is removed.
|
|
|
|
If, for some reason, a rotated log file cannot be archived then it will be
|
|
left in the node's working directory. Next time when ZeekControl either stops
|
|
Zeek or tries to restart a crashed Zeek, it will try to archive such log files
|
|
again. If this attempt fails, then an email is sent which contains the
|
|
name of a directory where any such unarchived logs can be found.
|
|
|
|
Log files created only when using ZeekControl
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
There are several log files that are not created by Zeek, but rather are
|
|
created only when using ZeekControl to run Zeek.
|
|
|
|
When ZeekControl starts Zeek it creates two files "stdout.log" and "stderr.log",
|
|
which just capture stdout and stderr from Zeek. Although these are not
|
|
actually Zeek logs, they might contain useful error or diagnostic information.
|
|
The contents of these files are included in crash reports and also
|
|
in the output of the "zeekctl diag" command.
|
|
|
|
Also, whenever logs are rotated, a connection summary report is generated if the
|
|
`trace-summary <https://github.com/zeek/trace-summary>`_ tool, included in the
|
|
Zeek distribution by default, is available. Although these are not actually
|
|
Zeek logs, they follow the same filename convention as other Zeek logs and they
|
|
have the filename prefix "conn-summary". If you don't want these connection
|
|
summary files to be created, then you can set the value of the TraceSummary_
|
|
option to an empty string.
|
|
|
|
|
|
Zeek Scripts
|
|
-----------
|
|
|
|
Site-specific Customization
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
If you want to adapt the Zeek policy to the local environment, then
|
|
you will most likely need to write local policy scripts.
|
|
|
|
Sample local policy scripts (which you can edit)
|
|
are located in ``share/zeek/site``. The file called ``local.zeek`` gets
|
|
loaded automatically.
|
|
|
|
The recommended way to modify the policy is to use only "@load" directives
|
|
in the ``local.zeek`` script. For example, you can add a "@load" directive
|
|
to load a Zeek policy script that is included with Zeek but is not loaded
|
|
by default. You can also create custom site-specific
|
|
policy scripts in the same directory as the ``local.zeek`` script, and "@load"
|
|
them from the ``local.zeek`` script. For example, you could create
|
|
your own Zeek script ``mypolicy.zeek`` in the ``share/zeek/site`` directory,
|
|
and then add a line "@load mypolicy" (without the quotes) to the ``local.zeek``
|
|
script.
|
|
|
|
After creating or modifying your local policy scripts, you must install them
|
|
by using the ZeekControl "install" or "deploy" command. Next, you can use the
|
|
ZeekControl "scripts" command to verify that your new scripts will be loaded
|
|
when you start Zeek.
|
|
|
|
|
|
Load Order of Scripts
|
|
~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
When writing custom site-specific policy scripts, it can be useful
|
|
to know in which order the scripts are loaded. For example, if more than
|
|
one script sets a value for the same global variable, then the value that
|
|
takes effect is the one set by the last such script loaded. The
|
|
ZeekControl "scripts" command shows the load order of every script
|
|
loaded by Zeek.
|
|
|
|
When Zeek starts up, the first script it loads is init-bare.zeek, followed
|
|
by init-default.zeek (keep in mind that each of these scripts loads many
|
|
other scripts). Note that these are the only scripts that are automatically
|
|
loaded when running Zeek directly (instead of using ZeekControl to run Zeek).
|
|
|
|
The next script loaded is the local.zeek script. By default, this script
|
|
loads a variety of other scripts. You can edit local.zeek and comment-out
|
|
anything that your site doesn't need (or add new "@load" directives).
|
|
|
|
Next, the "zeekctl" script package is loaded. This consists of some standard
|
|
settings that ZeekControl needs.
|
|
|
|
The next scripts loaded are ``local-networks.zeek`` and ``zeekctl-config.zeek``.
|
|
These scripts are automatically generated by ZeekControl based on the
|
|
contents of the ``networks.cfg`` and ``zeekctl.cfg`` files. Also, some
|
|
ZeekControl plugins might generate script code that will be automatically
|
|
inserted into the ``zeekctl-config.zeek`` script.
|
|
|
|
The last scripts loaded are any node-specific scripts specified with the
|
|
option ``aux_scripts`` in ``node.cfg``. This option is seldom ever
|
|
needed, but can be used to load additional scripts to individual nodes only.
|
|
For example, one could add a script ``experimental.zeek`` to a single worker
|
|
for trying out new experimental code.
|
|
|
|
|
|
Mails
|
|
-----
|
|
|
|
There are several situations when ZeekControl sends mail to the address given in
|
|
MailTo_ (note that ZeekControl will not be able to send any mail when the
|
|
value of the SendMail_ option is an empty string):
|
|
|
|
1. When the "zeekctl cron" command runs it performs various tasks (such as
|
|
checking available disk space, expiring old log files, etc.). If
|
|
any problems occur, a mail will be sent containing a list of those issues.
|
|
In order to reduce the amount of mail, the value of the following options
|
|
can be changed (see documentation of each option): MailHostUpDown_,
|
|
MinDiskSpace_, StatsLogEnable_, MailReceivingPackets_.
|
|
|
|
2. When ZeekControl tries to start or stop (via any of these commands:
|
|
start, stop, restart, deploy, or cron) a node that has crashed,
|
|
a crash report is mailed (one for each crashed node). The crash report
|
|
is essentially just the output of the "zeekctl diag" command.
|
|
|
|
3. When ZeekControl stops Zeek or restarts a crashed Zeek, if any log files
|
|
could not be archived, then mail will be sent to warn about this problem.
|
|
This mail can be disabled by setting ``MailArchiveLogFail=0``.
|
|
|
|
4. If `trace-summary <https://github.com/zeek/trace-summary>`_
|
|
is installed, a traffic summary is mailed each rotation interval. To
|
|
disable this mail, set ``MailConnectionSummary=0`` (however, the
|
|
connection summary file will still be created and archived along with
|
|
all other log files).
|
|
|
|
|
|
Using ZeekControl as an unprivileged user
|
|
----------------------------------------
|
|
|
|
If you decide to run ZeekControl as an unprivileged user, there are a
|
|
few issues that you may encounter.
|
|
|
|
If you installed Zeek and ZeekControl as the "root" user, then you will need
|
|
to adjust the ownership or permissions of the "logs" and "spool" directories
|
|
(and everything in those directories) so that the user running ZeekControl
|
|
has write permission.
|
|
|
|
If you're using a cluster setup that spans multiple machines, and if
|
|
your ZeekControl ``install`` or ``deploy`` commands fail with a permission
|
|
denied error, then it's most likely due to the user running ZeekControl
|
|
not having permission to create the install prefix directory
|
|
(by default, this is ``/usr/local/zeek``) on each remote machine.
|
|
A simple workaround is to login to each machine in your cluster and
|
|
manually create the install prefix directory and then set ownership
|
|
or permissions of this directory so that the user who will run ZeekControl
|
|
has write access to it.
|
|
|
|
Finally, on the worker nodes (or the standalone node), Zeek must have access
|
|
to the target network interface in promiscuous mode. If Zeek doesn't have
|
|
the necessary permissions, then it will fail almost immediately upon
|
|
startup.
|
|
|
|
|
|
Zeek communication
|
|
-----------------
|
|
|
|
This section summarizes the network communication between Zeek and ZeekControl,
|
|
which is useful to understand if you need to reconfigure your firewall. If
|
|
your firewall is preventing Zeek communication, then either the "deploy"
|
|
command or the "peerstatus" command will fail.
|
|
|
|
For a cluster setup, ZeekControl uses ssh to run commands on other hosts in
|
|
the cluster, so the manager host needs to connect to TCP port 22 on each
|
|
of the other hosts in the cluster. Note that ZeekControl never attempts
|
|
to ssh to the localhost, so in a standalone setup ZeekControl does not use ssh.
|
|
|
|
Each instance of Zeek in a cluster needs to communicate directly with other
|
|
instances of Zeek regardless of whether these instances are running on the same
|
|
host or not. Each proxy and worker needs to connect to the manager, and each
|
|
worker needs to connect to each proxy. If one or more logger nodes are
|
|
defined, then each of the other nodes needs to connect to each of the loggers.
|
|
|
|
Note that you can change the port that Zeek listens on by changing the value
|
|
of the "ZeekPort" option in your ``zeekctl.cfg`` file (this should be needed
|
|
only if your system has another process that listens on the same port). By
|
|
default, a standalone Zeek listens on TCP port 27760. For a cluster setup,
|
|
the logger listens on TCP port 27761, and the manager listens on TCP port 27762
|
|
(or 27761 if no logger is defined). Each proxy is assigned its own port
|
|
number, starting with one number greater than the manager's port. Likewise,
|
|
each worker is assigned its own port starting one number greater than the
|
|
highest port number assigned to a proxy.
|
|
|
|
Finally, a few ZeekControl commands (such as "print" and "peerstatus") rely
|
|
on Broker to communicate with Zeek. This means that for those commands to
|
|
function, ZeekControl needs to connect to each Zeek instance.
|
|
|
|
Command Reference
|
|
-----------------
|
|
|
|
The following summary lists all commands supported by ZeekControl.
|
|
If not specified otherwise, commands taking
|
|
*[<nodes>]* as arguments apply their action either to the given set of
|
|
nodes, to the manager node if "manager" is given, to all proxy nodes if
|
|
"proxies" is given, to all worker nodes if "workers" is given, or to all
|
|
nodes if none are given.
|
|
|
|
|
|
.. _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 :doc:`capstats<../../components/capstats/README>`
|
|
tool, which is installed along with ``zeekctl``.
|
|
|
|
|
|
.. _check:
|
|
|
|
*check* *[<nodes>]*
|
|
Verifies a modified configuration in terms of syntactical correctness
|
|
(most importantly correct syntax in policy scripts).
|
|
|
|
Note that this command checks the site-specific policy files as found
|
|
in SitePolicyPath_ rather than the ones installed by the install_
|
|
command. Therefore, new errors in a policy script can be detected
|
|
before affecting currently running nodes, even when they need to be
|
|
restarted.
|
|
|
|
This command should be executed for each configuration change *before*
|
|
using install_ to put the change into place. However, when using the
|
|
deploy command there is no need to first run check, because deploy
|
|
automatically runs check before installing the policy scripts.
|
|
|
|
|
|
.. _cleanup:
|
|
|
|
*cleanup* *[--all] [<nodes>]*
|
|
Clears the nodes' spool directories, but only for nodes that are not
|
|
running. This implies that their persistent state is flushed. Nodes
|
|
that were crashed are reset into the "stopped" state.
|
|
|
|
If ``--all`` is specified, this command also removes the content of
|
|
the node's TmpDir_, in particular deleting 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``, then install_, 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 ``zeekctl cron`` is executed. In other
|
|
words, even with ``zeekctl cron`` in your crontab, you can still
|
|
temporarily disable it by running ``cron disable``, and
|
|
then later reenable with ``cron enable``. This can be helpful while
|
|
working, e.g., on the ZeekControl configuration and ``cron`` would
|
|
interfere with that. ``cron ?`` can be used to query the current state.
|
|
|
|
|
|
.. _deploy:
|
|
|
|
*deploy*
|
|
Checks for errors in Zeek policy scripts, then does an install followed
|
|
by a restart on all nodes. This command should be run after any
|
|
changes to Zeek policy scripts or the zeekctl configuration, and after
|
|
Zeek is upgraded or even just recompiled.
|
|
|
|
This command is equivalent to running the check_, install_, and
|
|
restart_ commands, in that order.
|
|
|
|
|
|
.. _df:
|
|
|
|
*df* *[<nodes>]*
|
|
Reports the amount of disk space available on the nodes. Shows only
|
|
paths relevant to the zeekctl 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 hosts configured to
|
|
run at least one Zeek 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* *[--local]*
|
|
Reinstalls on all nodes, including all configuration files and
|
|
local policy scripts.
|
|
|
|
The ``--local`` option is intended for testing or debugging. It
|
|
causes only the local host to be installed (i.e., no changes pushed
|
|
out to any other hosts in the Zeek cluster). Normally all nodes
|
|
should be reinstalled at the same time, as any inconsistencies between
|
|
them will lead to strange effects.
|
|
|
|
This command must be executed after *all* changes to any part of
|
|
the ZeekControl configuration or after upgrading to a new version
|
|
of Zeek or ZeekControl, otherwise the modifications will not take effect.
|
|
Before executing ``install``, it is recommended to verify the
|
|
configuration with check_. Note that when using the deploy command
|
|
there is no need to first use the install command, because deploy
|
|
automatically runs install before restarting the nodes.
|
|
|
|
|
|
.. _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.
|
|
|
|
Note that the env_vars attribute includes the set of environment
|
|
variables from the 'env_vars' option in both 'node.cfg' and
|
|
'zeekctl.cfg' and also those set by any plugins.
|
|
|
|
|
|
.. _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 Zeek 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 Zeek namespace must be
|
|
prefixed with ``<namespace>::`` (e.g.,
|
|
``print Log::enable_remote_logging``).
|
|
|
|
|
|
.. _process:
|
|
|
|
*process* *<trace> [options] [-- <scripts>]*
|
|
Runs Zeek 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 Zeek 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, Zeek 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.
|
|
|
|
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_, check_, install_, and
|
|
start_.
|
|
|
|
|
|
.. _scripts:
|
|
|
|
*scripts* *[-c] [<nodes>]*
|
|
Primarily for debugging Zeek configurations, the ``scripts``
|
|
command lists all the Zeek scripts loaded by each of the nodes in the
|
|
order they will be parsed by the node at startup. The pathnames
|
|
of each script are indented such that it is possible to determine
|
|
from where a script was loaded based on the amount of indentation.
|
|
|
|
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.
|
|
|
|
For each node, the information shown includes the node's name and type,
|
|
the host where the node will run, the status, the PID, and the
|
|
date/time when the node was started. The status column will usually
|
|
show a status of either "stopped" or "running". A status of
|
|
"crashed" means that ZeekControl verified that Zeek is no longer
|
|
running, but was expected to be running.
|
|
|
|
|
|
.. _stop:
|
|
|
|
*stop* *[<nodes>]*
|
|
Stops the given nodes, or all nodes if none are specified. Nodes that
|
|
are in the "crashed" state are reset to the "stopped" state, and
|
|
nodes that are "stopped" are left untouched.
|
|
|
|
|
|
.. _top:
|
|
|
|
*top* *[<nodes>]*
|
|
For each of the nodes, prints the status of the Zeek 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.
|
|
|
|
|
|
Option Reference
|
|
----------------
|
|
|
|
This section summarizes the options that can be set in ``zeekctl.cfg``
|
|
for customizing the behavior of ZeekControl (the option names are not
|
|
case-sensitive). 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.
|
|
|
|
User Options
|
|
~~~~~~~~~~~~
|
|
.. _CommTimeout:
|
|
|
|
*CommTimeout* (int, default 10)
|
|
The number of seconds to wait before assuming Broker communication events have timed out.
|
|
|
|
.. _CommandTimeout:
|
|
|
|
*CommandTimeout* (int, default 60)
|
|
The number of seconds to wait for a command to return results.
|
|
|
|
.. _CompressCmd:
|
|
|
|
*CompressCmd* (string, default "gzip")
|
|
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.
|
|
|
|
.. _CompressLogsInFlight:
|
|
|
|
*CompressLogsInFlight* (int, default 0)
|
|
Set to greater than zero to compress archived log files as they're created instead of during rotation. The value indicates the compression level to use between 1 and 9 (values of 6 or 7 are a typical choice to bias slightly more towards better compression at cost of performance). If this is enabled, the CompressLogs, and CompressCmd arguments will be ignored as the files are compressed automatically by Zeek.
|
|
|
|
.. _ControlTopic:
|
|
|
|
*ControlTopic* (string, default "zeek/control")
|
|
The Broker topic name used for sending and receiving control messages to Zeek processes.
|
|
|
|
.. _CrashExpireInterval:
|
|
|
|
*CrashExpireInterval* (int, default 0)
|
|
Number of days that crash directories are kept (zero means never expire).
|
|
|
|
.. _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.
|
|
|
|
.. _Env_Vars:
|
|
|
|
*Env_Vars* (string, default _empty_)
|
|
A comma-separated list of environment variables (e.g. env_vars=VAR1=123, VAR2=456) to set on all nodes immediately before starting Zeek. Node-specific values (specified in the node configuration file) override these global values.
|
|
|
|
.. _HaveNFS:
|
|
|
|
*HaveNFS* (bool, default 0)
|
|
True if shared files are mounted across all nodes via NFS (see the FAQ_).
|
|
|
|
.. _KeepLogs:
|
|
|
|
*KeepLogs* (string, default _empty_)
|
|
A space-separated list of filename shell patterns of expired log files to keep (empty string means don't keep any expired log files). The filename shell patterns are not regular expressions and do not include any directories. For example, specifying 'conn.* dns*' will prevent any expired log files with filenames starting with 'conn.' or 'dns' from being removed. Finally, note that this option is ignored if log files never expire.
|
|
|
|
.. _LogDir:
|
|
|
|
*LogDir* (string, default "$\{ZeekBase}/logs")
|
|
Directory for archived log files.
|
|
|
|
.. _LogExpireInterval:
|
|
|
|
*LogExpireInterval* (string, default "0")
|
|
Time interval that archived log files are kept (a value of 0 means log files never expire). The time interval is expressed as an integer followed by one of the following time units: day, hr, min.
|
|
|
|
.. _LogRotationInterval:
|
|
|
|
*LogRotationInterval* (int, default 3600)
|
|
The frequency of log rotation in seconds for the manager/standalone node (zero to disable rotation). This overrides the Zeek script variable Log::default_rotation_interval.
|
|
|
|
.. _MailAlarmsInterval:
|
|
|
|
*MailAlarmsInterval* (int, default 86400)
|
|
The frequency (in seconds) of sending alarm summary mails (zero to disable). This overrides the Zeek script variable Log::default_mail_alarms_interval.
|
|
|
|
.. _MailAlarmsTo:
|
|
|
|
*MailAlarmsTo* (string, default "$\{MailTo}")
|
|
Destination address for alarm summary mails. Default is to use the same address as MailTo. This overrides the Zeek script variable Notice::mail_dest_pretty_printed.
|
|
|
|
.. _MailArchiveLogFail:
|
|
|
|
*MailArchiveLogFail* (bool, default 1)
|
|
True to enable sending mail when log files fail to be archived.
|
|
|
|
.. _MailConnectionSummary:
|
|
|
|
*MailConnectionSummary* (bool, default 1)
|
|
True to mail connection summary reports each log rotation interval (if false, then connection summary reports will still be generated and archived, but they will not be mailed). However, this option has no effect if the trace-summary script is not available.
|
|
|
|
.. _MailFrom:
|
|
|
|
*MailFrom* (string, default "Zeek <zeek@localhost>")
|
|
Originator address for mails. This overrides the Zeek script variable Notice::mail_from.
|
|
|
|
.. _MailHostUpDown:
|
|
|
|
*MailHostUpDown* (bool, default 1)
|
|
True to enable sending mail when zeekctl cron notices the availability of a host in the cluster to have changed.
|
|
|
|
.. _MailReceivingPackets:
|
|
|
|
*MailReceivingPackets* (bool, default 1)
|
|
True to enable sending mail when zeekctl cron notices that an interface is not receiving any packets (note that such mail is not sent when StatsLogEnable is 0).
|
|
|
|
.. _MailReplyTo:
|
|
|
|
*MailReplyTo* (string, default _empty_)
|
|
Reply-to address for zeekctl-generated mails.
|
|
|
|
.. _MailSubjectPrefix:
|
|
|
|
*MailSubjectPrefix* (string, default "[Zeek]")
|
|
General Subject prefix for mails. This overrides the Zeek script variable Notice::mail_subject_prefix.
|
|
|
|
.. _MailTo:
|
|
|
|
*MailTo* (string, default "<user>")
|
|
Destination address for non-alarm mails. This overrides the Zeek script variable Notice::mail_dest.
|
|
|
|
.. _MakeArchiveName:
|
|
|
|
*MakeArchiveName* (string, default "$\{ZeekBase}/share/zeekctl/scripts/make-archive-name")
|
|
Script to generate filenames for archived log files.
|
|
|
|
.. _MemLimit:
|
|
|
|
*MemLimit* (string, default "unlimited")
|
|
Maximum amount of memory for Zeek processes to use (in KB, or the string 'unlimited').
|
|
|
|
.. _MetricsPort:
|
|
|
|
*MetricsPort* (int, default 9991)
|
|
The TCP port number that Zeek will listen on for Prometheus telemetry. For a cluster configuration, each node in the cluster will automatically be assigned a subsequent port to listen on. Setting this to 0 will disable telemetry on all nodes.
|
|
|
|
.. _MinDiskSpace:
|
|
|
|
*MinDiskSpace* (int, default 5)
|
|
Minimum percentage of disk space available before zeekctl cron mails a warning. If this value is 0, then no warning will be sent.
|
|
|
|
.. _PFRINGClusterID:
|
|
|
|
*PFRINGClusterID* (int, default 21)
|
|
If PF_RING flow-based load balancing is desired, this is where the PF_RING cluster id is defined. In order to use PF_RING, the value of this option must be non-zero.
|
|
|
|
.. _PFRINGClusterType:
|
|
|
|
*PFRINGClusterType* (string, default "4-tuple")
|
|
If PF_RING flow-based load balancing is desired, this is where the PF_RING cluster type is defined. Allowed values are: 2-tuple, 4-tuple, 5-tuple, tcp-5-tuple, 6-tuple, inner-2-tuple, inner-4-tuple, inner-5-tuple, inner-tcp-5-tuple, or inner-6-tuple. Zeek must be linked with PF_RING's libpcap wrapper and PFRINGClusterID must be non-zero for this option to work.
|
|
|
|
.. _PFRINGFirstAppInstance:
|
|
|
|
*PFRINGFirstAppInstance* (int, default 0)
|
|
The first application instance for a PF_RING dnacluster interface to use. Zeekctl will start at this application instance number and increment for each new process running on that DNA cluster. Zeek must be linked with PF_RING's libpcap wrapper, PFRINGClusterID must be non-zero, and you must be using PF_RING+DNA and libzero for this option to work.
|
|
|
|
.. _Prefixes:
|
|
|
|
*Prefixes* (string, default "local")
|
|
Additional script prefixes for Zeek, separated by colons. Use this instead of @prefix.
|
|
|
|
.. _PrivateAddressSpaceIsLocal:
|
|
|
|
*PrivateAddressSpaceIsLocal* (bool, default 1)
|
|
This flag, enabled by default, controls whether Zeek should automatically consider private address space as local to your site. This is the zeekctl equivalent of Zeek's 'Site::private_address_space_is_local' setting. Setting this to 0 separates local and private address spaces, and you need to list any private address space explicitly in your 'network.cfg' for it to be considered local.
|
|
|
|
.. _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. This overrides the Zeek script variable Notice::sendmail.
|
|
|
|
.. _SitePluginPath:
|
|
|
|
*SitePluginPath* (string, default _empty_)
|
|
Directories to search for custom plugins (i.e., plugins that are not included with zeekctl), separated by colons.
|
|
|
|
.. _SitePolicyPath:
|
|
|
|
*SitePolicyPath* (string, default "$\{PolicyDir}/site")
|
|
Directories to search for local (i.e., site-specific) policy files, separated by colons. For each such directory, all files and subdirectories are copied to PolicyDirSiteInstall during zeekctl 'install' or 'deploy' (however, if the same file or subdirectory is found in more than one such directory, then only the first one encountered will be used).
|
|
|
|
.. _SitePolicyScripts:
|
|
|
|
*SitePolicyScripts* (string, default "local.zeek")
|
|
Space-separated list of local policy files that will be automatically loaded for all Zeek instances. Scripts listed here do not need to be explicitly loaded from any other policy scripts.
|
|
|
|
.. _StatsLogEnable:
|
|
|
|
*StatsLogEnable* (bool, default 1)
|
|
True to enable ZeekControl to write statistics to the stats.log file.
|
|
|
|
.. _StatsLogExpireInterval:
|
|
|
|
*StatsLogExpireInterval* (int, default 0)
|
|
Number of days entries in the stats.log file are kept (zero means never expire).
|
|
|
|
.. _StatusCmdShowAll:
|
|
|
|
*StatusCmdShowAll* (bool, default 0)
|
|
True to have the status command show all output, or False to show only some of the output (peer information will not be collected or shown, so the command will run faster).
|
|
|
|
.. _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.
|
|
|
|
.. _StopWait:
|
|
|
|
*StopWait* (bool, default 0)
|
|
True to force the stop command to wait for the post-terminate script to finish, or False to let post-terminate finish in the background.
|
|
|
|
.. _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 Zeek syntax, e.g., 47757/tcp).
|
|
|
|
.. _ZeekArgs:
|
|
|
|
*ZeekArgs* (string, default _empty_)
|
|
Additional arguments to pass to Zeek on the command-line (e.g. zeekargs=-f "tcp port 80").
|
|
|
|
.. _ZeekPort:
|
|
|
|
*ZeekPort* (int, default 27760)
|
|
The TCP port number that Zeek will listen on. For a cluster configuration, each node in the cluster will automatically be assigned a subsequent port to listen on.
|
|
|
|
|
|
Internal Options
|
|
~~~~~~~~~~~~~~~~
|
|
|
|
.. _BinDir:
|
|
|
|
*BinDir* (string, default "$\{ZeekBase}/bin")
|
|
Directory for executable files.
|
|
|
|
.. _BrokerDBDir:
|
|
|
|
*BrokerDBDir* (string, default "$\{ZeekBase}/spool/brokerstore")
|
|
Directory for data stores of persistent Broker-backed tables.
|
|
|
|
.. _CapstatsPath:
|
|
|
|
*CapstatsPath* (string, default "$\{bindir}/capstats")
|
|
Path to capstats binary; empty if not available.
|
|
|
|
.. _CfgDir:
|
|
|
|
*CfgDir* (string, default "$\{ZeekBase}/etc")
|
|
Directory for configuration files.
|
|
|
|
.. _DebugLog:
|
|
|
|
*DebugLog* (string, default "$\{SpoolDir}/debug.log")
|
|
Log file for debugging information.
|
|
|
|
.. _DefaultStoreDir:
|
|
|
|
*DefaultStoreDir* (string, default "$\{SpoolDir}/stores")
|
|
Default directory where Broker data stores will be written if user has not provided further customizations on a per-store basis.
|
|
|
|
.. _FileExtractDir:
|
|
|
|
*FileExtractDir* (string, default "$\{SpoolDir}/extract_files")
|
|
Default base directory for file extraction. The FileExtract module's prefix will be set to this value with Cluster::node appended.
|
|
|
|
.. _HelperDir:
|
|
|
|
*HelperDir* (string, default "$\{ZeekBase}/share/zeekctl/scripts/helpers")
|
|
Directory for zeekctl helper scripts.
|
|
|
|
.. _LibDir:
|
|
|
|
*LibDir* (string, default _empty_)
|
|
Directory for library files.
|
|
|
|
.. _LibDir64:
|
|
|
|
*LibDir64* (string, default "$\{ZeekBase}/lib64")
|
|
Directory for 64-bit architecture library files.
|
|
|
|
.. _LibDirInternal:
|
|
|
|
*LibDirInternal* (string, default _empty_)
|
|
Directory for ZeekControl's Python module.
|
|
|
|
.. _LocalNetsCfg:
|
|
|
|
*LocalNetsCfg* (string, default "$\{CfgDir}/networks.cfg")
|
|
File defining the local networks.
|
|
|
|
.. _LockFile:
|
|
|
|
*LockFile* (string, default "$\{SpoolDir}/lock")
|
|
Lock file preventing concurrent shell operations.
|
|
|
|
.. _LogExpireMinutes:
|
|
|
|
*LogExpireMinutes* (int, default 0)
|
|
Time interval (in minutes) that archived log files are kept (0 means they never expire). Users should never modify this value (see the LogExpireInterval option).
|
|
|
|
.. _NodeCfg:
|
|
|
|
*NodeCfg* (string, default "$\{CfgDir}/node.cfg")
|
|
Node configuration file.
|
|
|
|
.. _OS:
|
|
|
|
*OS* (string, default _empty_)
|
|
Name of operating system as reported by uname.
|
|
|
|
.. _PcapBufsize:
|
|
|
|
*PcapBufsize* (int, default 128)
|
|
Number of Mbytes to provide as buffer space when capturing from live interfaces via libpcap.
|
|
|
|
.. _PcapSnaplen:
|
|
|
|
*PcapSnaplen* (int, default 9216)
|
|
Number of bytes per packet to capture from live interfaces via libpcap.
|
|
|
|
.. _PluginDir:
|
|
|
|
*PluginDir* (string, default "$\{LibDirInternal}/zeekctl/plugins")
|
|
Directory where standard zeekctl plugins are located.
|
|
|
|
.. _PluginZeekDir:
|
|
|
|
*PluginZeekDir* (string, default "$\{LibDir}/zeek/plugins")
|
|
Directory where Zeek plugins are located. ZeekControl will search this directory tree for zeekctl plugins that are provided by any Zeek plugin.
|
|
|
|
.. _PolicyDir:
|
|
|
|
*PolicyDir* (string, default "$\{ZeekScriptDir}")
|
|
Directory for standard policy files.
|
|
|
|
.. _PolicyDirSiteInstall:
|
|
|
|
*PolicyDirSiteInstall* (string, default "$\{SpoolDir}/installed-scripts-do-not-touch/site")
|
|
Directory where the shell copies local (i.e., site-specific) 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 "$\{ZeekBase}/share/zeekctl/scripts/postprocessors")
|
|
Directory for log postprocessors.
|
|
|
|
.. _ScriptsDir:
|
|
|
|
*ScriptsDir* (string, default "$\{ZeekBase}/share/zeekctl/scripts")
|
|
Directory for executable scripts shipping as part of zeekctl.
|
|
|
|
.. _SpoolDir:
|
|
|
|
*SpoolDir* (string, default "$\{ZeekBase}/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}/state.db")
|
|
File storing the current zeekctl state.
|
|
|
|
.. _StaticDir:
|
|
|
|
*StaticDir* (string, default "$\{ZeekBase}/share/zeekctl")
|
|
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. This option is ignored if HaveNFS is 0.
|
|
|
|
.. _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 reports.
|
|
|
|
.. _Version:
|
|
|
|
*Version* (string, default _empty_)
|
|
Version of the zeekctl.
|
|
|
|
.. _Zeek:
|
|
|
|
*Zeek* (string, default "$\{BinDir}/zeek")
|
|
Path to Zeek binary.
|
|
|
|
.. _ZeekBase:
|
|
|
|
*ZeekBase* (string, default _empty_)
|
|
Base path of zeekctl installation on all nodes.
|
|
|
|
|
|
Plugins
|
|
-------
|
|
|
|
ZeekControl 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 ZeekControl
|
|
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 status on a per-node basis (where applicable).
|
|
|
|
* Add custom commands to ZeekControl.
|
|
|
|
* Add custom options to ZeekControl defined in ``zeekctl.cfg``.
|
|
|
|
* Add custom keys to nodes defined in ``node.cfg``.
|
|
|
|
A plugin is written by deriving a new class from ZeekControl class
|
|
`Plugin`_. The Python script with the new plugin is then copied into a
|
|
plugin directory searched by ZeekControl at startup. By default,
|
|
ZeekControl searches ``<prefix>/lib/zeek/python/zeekctl/plugins``; additional directories
|
|
may be configured by setting the SitePluginPath_ option. Note that any plugin
|
|
script must end in ``*.py`` to be found. ZeekControl comes with some
|
|
example plugins that can be used as a starting point; see
|
|
the ``<prefix>/lib/zeek/python/zeekctl/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 ZeekControl plugins.
|
|
|
|
The class has a number of methods for plugins to override, and every
|
|
plugin must at least override ``name()`` and ``pluginVersion()``.
|
|
|
|
For each ZeekControl 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).
|
|
|
|
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 is just a combination of other
|
|
commands and thus their callbacks are run in addition to the callbacks
|
|
for ``restart``.
|
|
|
|
.. _Plugin.debug:
|
|
|
|
**debug** (self, msg)
|
|
|
|
Logs a debug message in ZeekControl'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 a string
|
|
which contains 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
|
|
a string containing the combined stdout/stderr output for the
|
|
corresponding ``node``.
|
|
|
|
.. _Plugin.getGlobalOption:
|
|
|
|
**getGlobalOption** (self, name)
|
|
|
|
Returns the value of the global ZeekControl option *name*.
|
|
|
|
See the output of ``zeekctl config`` for a complete list.
|
|
|
|
.. _Plugin.getOption:
|
|
|
|
**getOption** (self, name)
|
|
|
|
Returns the value of one of the plugin's options, *name*.
|
|
|
|
An option has a default value (see *options()*), which can be
|
|
overridden by a user in ``zeekctl.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*. If it has not yet been set, an empty string will be returned.
|
|
|
|
Different from options, state variables can be set by the plugin.
|
|
They are persistent across restarts.
|
|
|
|
Note that a plugin cannot query any global ZeekControl state variables.
|
|
|
|
.. _Plugin.hosts:
|
|
|
|
**hosts** (self, nodes)
|
|
|
|
Returns a list of Node_ objects which is a subset of the list in
|
|
*nodes*, such that only one node per host will be chosen. If *nodes*
|
|
is empty, then the returned list will be a subset of the entire list
|
|
of configured nodes.
|
|
|
|
.. _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 a tuple which contains two lists. The first list is a list
|
|
of `Node`_ objects for a string of space-separated node names. If a
|
|
name does not correspond to a known node, then the name is added
|
|
to the second list in the returned tuple.
|
|
|
|
.. _Plugin.setState:
|
|
|
|
**setState** (self, name, value)
|
|
|
|
Sets one of the plugin's state variables, *name*, to *value*.
|
|
The change is permanent and will be recorded to disk.
|
|
|
|
Note that a plugin cannot change any global ZeekControl state
|
|
variables.
|
|
|
|
.. _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. *interval* 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. Returns a boolean
|
|
indicating whether or not the command should 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 an empty
|
|
string if the command is executed without arguments. Otherwise, it is
|
|
one of the strings: ``enable``, ``disable``, ``?``. *watch* is a
|
|
boolean indicating whether the ``cron`` command should restart
|
|
abnormally terminated Zeek processes; it's only valid if *arg* is empty.
|
|
|
|
Returns a boolean indicating whether or not the ``cron`` command should
|
|
run.
|
|
|
|
This method can be overridden by derived classes. The default
|
|
implementation does nothing.
|
|
|
|
.. _Plugin.cmd_custom:
|
|
|
|
**cmd_custom** (self, cmd, args, cmdout)
|
|
|
|
Called when a command defined by the ``commands`` method is executed.
|
|
*cmd* is the command (without the plugin's prefix), and *args* is a
|
|
single string with all arguments. It returns a CmdResult object
|
|
containing the command results.
|
|
|
|
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_deploy_post:
|
|
|
|
**cmd_deploy_post** (self)
|
|
|
|
Called just after the ``deploy`` command has finished.
|
|
|
|
This method can be overridden by derived classes. The default
|
|
implementation does nothing.
|
|
|
|
.. _Plugin.cmd_deploy_pre:
|
|
|
|
**cmd_deploy_pre** (self)
|
|
|
|
Called just before the ``deploy`` command is run. Returns a
|
|
boolean indicating whether or not the command should run.
|
|
|
|
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.
|
|
|
|
Returns a boolean indicating whether or not the ``exec`` command
|
|
should run.
|
|
|
|
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. Returns a
|
|
boolean indicating whether or not the command should 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. Returns a
|
|
boolean indicating whether or not the command should 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 Zeek 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 Zeek *options*,
|
|
and a list of additional Zeek *scripts*.
|
|
|
|
Returns a boolean indicating whether or not the ``process`` command
|
|
should run.
|
|
|
|
This method can be overridden by derived classes. The default
|
|
implementation does nothing.
|
|
|
|
.. _Plugin.cmd_restart_post:
|
|
|
|
**cmd_restart_post** (self, nodes)
|
|
|
|
Called just after the ``restart`` command has finished. It receives
|
|
a list of *nodes* indicating the nodes on which the command was
|
|
executed.
|
|
|
|
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, 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, 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. *check* is boolean indicating whether the ``-c``
|
|
option was given.
|
|
|
|
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 *prefix()* (e.g., ``myplugin.mycommand``, or
|
|
just ``myplugin`` if the command name is an empty string).
|
|
|
|
``arguments``
|
|
A string describing the command's arguments in a textual form
|
|
suitable for use in the ``help`` command summary (e.g.,
|
|
``[<nodes>]`` for a command taking an optional list of nodes).
|
|
Empty if no arguments are expected.
|
|
|
|
``description``
|
|
A string with a description of the command's semantics suitable
|
|
for use in the ``help`` command summary.
|
|
|
|
|
|
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 ZeekControl 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 ZeekControl's ``cron`` command finds the availability of
|
|
a cluster system to have changed. Initially, all systems are assumed
|
|
to be up and running. Once ZeekControl notices that a system isn't
|
|
responding (defined as not accepting 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 ZeekControl'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 ZeekControl starts executing any commands.
|
|
This method can do any initialization that the plugin may require.
|
|
|
|
Note that when this method executes, ZeekControl 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 names of custom keys for nodes (the value of a
|
|
key can be specified in ``node.cfg`` for any node defined there).
|
|
Node key names are not case-sensitive.
|
|
|
|
The value for a key will be available from the `Node`_ object as
|
|
attribute ``<prefix>_<key>`` (e.g., ``node.myplugin_mykey``). If not
|
|
set, the attribute will be set to an empty string.
|
|
|
|
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 not case-sensitive. Note that the option name exposed
|
|
to the user will be prefixed with your plugin's prefix as
|
|
returned by *prefix()* (e.g., ``myplugin.Path``).
|
|
|
|
``type``
|
|
A string with type of the option, which must be one of
|
|
``"bool"``, ``"string"``, or ``"int"``.
|
|
|
|
``default``
|
|
The option's default value. Note that this value must be
|
|
enclosed in quotes if the type is "string", and must not be
|
|
enclosed in quotes if the type is not "string".
|
|
|
|
``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"). The prefix cannot contain
|
|
any whitespace or dots (because dots are used as separators when
|
|
forming the plugin's option names, state variable names, and
|
|
command names).
|
|
|
|
Note that ZeekControl will refuse to load a plugin if its prefix
|
|
matches the prefix of another loaded plugin (this comparison is not
|
|
case-sensitive).
|
|
|
|
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()*.
|
|
|
|
.. _Plugin.zeekProcessDied:
|
|
|
|
**zeekProcessDied** (self, node)
|
|
|
|
Called when ZeekControl finds the Zeek process for Node_ *node*
|
|
to have terminated unexpectedly. This method will be called just
|
|
before ZeekControl 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.zeekctl_config:
|
|
|
|
**zeekctl_config** (self)
|
|
|
|
Returns a string containing Zeek script code that should be written
|
|
to the dynamically generated Zeek script named "zeekctl-config.zeek".
|
|
This provides a way for plugins to easily add Zeek script code that
|
|
depends on zeekctl settings.
|
|
|
|
This method can be overridden by derived classes. The default
|
|
implementation does nothing.
|
|
|
|
.. _Node:
|
|
|
|
Class ``Node``
|
|
~~~~~~~~~~~~~~
|
|
|
|
class **Node**
|
|
Class representing one node of the ZeekControl maintained setup. In
|
|
standalone mode, there's always exactly one node of type ``standalone``. In
|
|
a cluster setup, there is zero or more of type ``logger``, exactly one of
|
|
type ``manager``, one or more of type ``proxy``, and zero or more of type
|
|
``worker``. The manager will handle writing logs if there are no loggers
|
|
defined in a cluster.
|
|
|
|
A ``Node`` object has a number of keys with values that are set via the
|
|
``node.cfg`` file and can be accessed directly (from a plugin) 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. In a standalone configuration, the only
|
|
allowed type is ``standalone``. In a cluster configuration, the
|
|
type must be one of: ``logger``, ``manager``, ``proxy``,
|
|
or ``worker``.
|
|
|
|
``host`` (string)
|
|
The hostname or IP address of the system the node is
|
|
running on. Every node must specify a host.
|
|
|
|
``interface`` (string)
|
|
The network interface for the Zeek worker (or standalone node) to
|
|
use; empty if not set.
|
|
|
|
``lb_procs`` (integer)
|
|
The number of clustered Zeek workers you'd like to start up. If
|
|
specified, this number must be greater than zero and a load
|
|
balancing method must also be specified. This option is valid only
|
|
for worker nodes.
|
|
|
|
``lb_method`` (string)
|
|
The load balancing method to distribute packets to all of the
|
|
Zeek workers. This must be one of: ``af_packet``, ``pf_ring``,
|
|
``myricom``, ``custom``, or ``interfaces``. This option can have
|
|
a value only if the ``lb_procs`` option has a value.
|
|
|
|
``lb_interfaces`` (string)
|
|
A comma-separated list of network interface names for the Zeek
|
|
worker to use. The number of interfaces in this list must
|
|
equal the value of the ``lb_procs`` option.
|
|
|
|
This option can be specified only when the load balancing method
|
|
is ``interfaces``.
|
|
|
|
``pin_cpus`` (string)
|
|
A comma-separated list of CPU numbers to which the node's Zeek
|
|
processes will be pinned. If not specified, then CPU pinning will
|
|
not be used for this node. This option is supported only on
|
|
Linux and FreeBSD, and is ignored on all other platforms.
|
|
|
|
CPU numbering starts at zero (e.g.,
|
|
the only valid CPU numbers for a machine with one dual-core
|
|
processor would be 0 and 1). If the length of this list does not
|
|
match the number of Zeek processes for this node, then some CPUs
|
|
could have zero (if too many CPU numbers are specified) or more
|
|
than one (if not enough CPU numbers are specified) Zeek processes
|
|
pinned to them. Only the specified CPU numbers will be used,
|
|
regardless of whether additional CPU cores exist.
|
|
|
|
``env_vars`` (string)
|
|
A comma-separated list of environment variables to set when
|
|
running Zeek (e.g., ``env_vars=VAR1=1,VAR2=2``). These
|
|
node-specific values override any global values specified in
|
|
the ``zeekctl.cfg`` file.
|
|
|
|
``aux_scripts`` (string)
|
|
Any node-specific Zeek script configured for this node.
|
|
|
|
``zone_id`` (string)
|
|
If ZeekControl 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``).
|
|
|
|
Finally, a Node object has the following methods that can be called
|
|
from a plugin:
|
|
|
|
.. _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 (sorted by key).
|
|
|
|
.. _Node.getPID:
|
|
|
|
**getPID** (self)
|
|
|
|
Returns the process ID of the node's Zeek process if running, and
|
|
None otherwise.
|
|
|
|
.. _Node.getPort:
|
|
|
|
**getPort** (self)
|
|
|
|
Returns an integer with the port number 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 Zeek process has exited abnormally.
|
|
|
|
|
|
.. _FAQ:
|
|
|
|
Questions and Answers
|
|
---------------------
|
|
|
|
*Can I use an NFS-mounted partition as the cluster's base directory to avoid the ``rsync``'ing?*
|
|
Yes. ZeekBase_ can be on an NFS partition.
|
|
Configure and install the shell as usual with
|
|
``--prefix=<ZeekBase>``. Then add ``HaveNFS=1`` and
|
|
``SpoolDir=<spath>`` to ``zeekctl.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 ``<ZeekBase>/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.)
|
|
|
|
*What do I need to do when something in the Zeek distribution changes?*
|
|
After pulling from the main Zeek 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
|
|
``zeekctl deploy`` to make sure everything gets pushed out.
|
|
|
|
*Can I change the naming scheme that ZeekControl 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
|
|
``<ZeekBase>/share/zeekctl/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 ZeekControl manage a cluster of nodes over non-global IPv6 scope (e.g. link-local)?*
|
|
This used to be supported through a ``ZoneID`` option in
|
|
``zeekctl.cfg``, but no longer works in later versions
|
|
of Zeek which use Broker as the communication framework. Please
|
|
file a feature request if this is important to you.
|