132 lines
4.8 KiB
Markdown
132 lines
4.8 KiB
Markdown
# The Zeek Cluster Management Client
|
|
|
|
[](https://github.com/zeek/zeek-client/actions/workflows/test.yml)
|
|
|
|
This is the recommended command-line client for interacting with Zeek's
|
|
[Management framework](https://docs.zeek.org/en/master/frameworks/management.html).
|
|
Built in Python and using Broker's [WebSocket pub/sub interface](https://docs.zeek.org/projects/broker/en/v2.3.0/web-socket.html), it
|
|
connects to a cluster controller to execute management tasks. Here's what it looks like:
|
|
|
|
```console
|
|
$ zeek-client --help
|
|
usage: zeek-client [-h] [-c FILE] [--controller HOST:PORT] [--set SECTION.KEY=VAL] [--quiet | --verbose]
|
|
[--version]
|
|
{deploy,deploy-config,get-config,get-id-value,get-instances,get-nodes,monitor,restart,stage-config,show-settings,test-timeout}
|
|
...
|
|
|
|
A Zeek management client
|
|
|
|
options:
|
|
-h, --help show this help message and exit
|
|
-c FILE, --configfile FILE
|
|
Path to zeek-client config file. (Default: /home/christian/inst/opt/zeek/etc/zeek-
|
|
client.cfg)
|
|
--controller HOST:PORT
|
|
Address and port of the controller, either of which may be omitted (default:
|
|
127.0.0.1:2150)
|
|
--set SECTION.KEY=VAL
|
|
Adjust a configuration setting. Can use repeatedly. See show-settings.
|
|
--quiet, -q Suppress informational output to stderr.
|
|
--verbose, -v Increase informational output to stderr. Repeat for more output (e.g. -vvv).
|
|
--version Show version number and exit.
|
|
|
|
commands:
|
|
{deploy,deploy-config,get-config,get-id-value,get-instances,get-nodes,monitor,restart,stage-config,show-settings,test-timeout}
|
|
See `zeek-client <command> -h` for per-command usage info.
|
|
deploy Deploy a staged cluster configuration.
|
|
deploy-config Upload a cluster configuration and deploy it.
|
|
get-config Retrieve staged or deployed cluster configuration.
|
|
get-id-value Show the value of a given identifier in Zeek cluster nodes.
|
|
get-instances Show instances connected to the controller.
|
|
get-nodes Show active Zeek nodes at each instance.
|
|
monitor For troubleshooting: do nothing, just report events.
|
|
restart Restart cluster nodes.
|
|
stage-config Upload a cluster configuration for later deployment.
|
|
show-settings Show zeek-client's own configuration.
|
|
test-timeout Send timeout test event.
|
|
|
|
environment variables:
|
|
|
|
ZEEK_CLIENT_CONFIG_FILE: Same as `--configfile` argument, but lower precedence.
|
|
ZEEK_CLIENT_CONFIG_SETTINGS: Same as a space-separated series of `--set` arguments, but lower precedence.
|
|
```
|
|
|
|
## Installation
|
|
|
|
The recommended way to run the client is to install it with Zeek, since the
|
|
client is part of the distribution. You may also run it directly from the
|
|
official Zeek [Docker image](https://hub.docker.com/r/zeekurity/zeek).
|
|
|
|
The WebSocket-powered `zeek-client` currently requires Zeek built from
|
|
the master branch, or via our [development Docker image](https://hub.docker.com/r/zeekurity/zeek-dev).
|
|
`zeek-client` will officially become available as a standalone package,
|
|
installable via `pip`, with Zeek 5.2.
|
|
|
|
## Quickstart
|
|
|
|
Run the following (as root) to launch an all-in-one management instance on your
|
|
system:
|
|
|
|
```console
|
|
# zeek -C -j policy/frameworks/management/controller policy/frameworks/management/agent
|
|
```
|
|
|
|
The above will stay in the foreground. In a new shell, save the following
|
|
content to a file ``cluster.cfg`` and adapt the worker's sniffing interfaces to
|
|
your system:
|
|
|
|
```ini
|
|
[manager]
|
|
role = manager
|
|
|
|
[logger]
|
|
role = logger
|
|
|
|
[worker-01]
|
|
role = worker
|
|
interface = lo
|
|
|
|
[worker-02]
|
|
role = worker
|
|
interface = eth0
|
|
```
|
|
|
|
Run the following command (as any user) to deploy the configuration:
|
|
|
|
```console
|
|
$ zeek-client deploy-config cluster.cfg
|
|
{
|
|
"errors": [],
|
|
"results": {
|
|
"id": "9befc56c-f7e8-11ec-8626-7c10c94416bb",
|
|
"nodes": {
|
|
"logger": {
|
|
"instance": "agent-testbox",
|
|
"success": true
|
|
},
|
|
"manager": {
|
|
"instance": "agent-testbox",
|
|
"success": true
|
|
},
|
|
"worker-01": {
|
|
"instance": "agent-testbox",
|
|
"success": true
|
|
},
|
|
"worker-02": {
|
|
"instance": "agent-testbox",
|
|
"success": true
|
|
}
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
You are now running a Zeek cluster on your system. Try ``zeek-client get-nodes``
|
|
to see more details about the cluster's current status. (In the above, "testbox"
|
|
is the system's hostname.)
|
|
|
|
## Documentation
|
|
|
|
The [Zeek documentation](https://docs.zeek.org/en/master/frameworks/management.html)
|
|
covers both the Management framework and the client's commands.
|