# 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.
Raw data
{
"_id": null,
"home_page": "https://github.com/zeek/zeek-client",
"name": "zeek-client",
"maintainer": "The Zeek Project",
"docs_url": null,
"requires_python": ">=3.7.0",
"maintainer_email": "info@zeek.org",
"keywords": "zeek management client cluster",
"author": "",
"author_email": "",
"download_url": "https://files.pythonhosted.org/packages/44/85/85bff99040e2db31e2f59f0f6517cfff07054f920353275bb69c705c77dd/zeek-client-1.3.1.tar.gz",
"platform": null,
"description": "# The Zeek Cluster Management Client\n\n[](https://github.com/zeek/zeek-client/actions/workflows/test.yml)\n\nThis is the recommended command-line client for interacting with Zeek's\n[Management framework](https://docs.zeek.org/en/master/frameworks/management.html).\nBuilt in Python and using Broker's [WebSocket pub/sub interface](https://docs.zeek.org/projects/broker/en/v2.3.0/web-socket.html), it\nconnects to a cluster controller to execute management tasks. Here's what it looks like:\n\n```console\n$ zeek-client --help\nusage: zeek-client [-h] [-c FILE] [--controller HOST:PORT] [--set SECTION.KEY=VAL] [--quiet | --verbose]\n [--version]\n {deploy,deploy-config,get-config,get-id-value,get-instances,get-nodes,monitor,restart,stage-config,show-settings,test-timeout}\n ...\n\nA Zeek management client\n\noptions:\n -h, --help show this help message and exit\n -c FILE, --configfile FILE\n Path to zeek-client config file. (Default: /home/christian/inst/opt/zeek/etc/zeek-\n client.cfg)\n --controller HOST:PORT\n Address and port of the controller, either of which may be omitted (default:\n 127.0.0.1:2150)\n --set SECTION.KEY=VAL\n Adjust a configuration setting. Can use repeatedly. See show-settings.\n --quiet, -q Suppress informational output to stderr.\n --verbose, -v Increase informational output to stderr. Repeat for more output (e.g. -vvv).\n --version Show version number and exit.\n\ncommands:\n {deploy,deploy-config,get-config,get-id-value,get-instances,get-nodes,monitor,restart,stage-config,show-settings,test-timeout}\n See `zeek-client <command> -h` for per-command usage info.\n deploy Deploy a staged cluster configuration.\n deploy-config Upload a cluster configuration and deploy it.\n get-config Retrieve staged or deployed cluster configuration.\n get-id-value Show the value of a given identifier in Zeek cluster nodes.\n get-instances Show instances connected to the controller.\n get-nodes Show active Zeek nodes at each instance.\n monitor For troubleshooting: do nothing, just report events.\n restart Restart cluster nodes.\n stage-config Upload a cluster configuration for later deployment.\n show-settings Show zeek-client's own configuration.\n test-timeout Send timeout test event.\n\nenvironment variables:\n\n ZEEK_CLIENT_CONFIG_FILE: Same as `--configfile` argument, but lower precedence.\n ZEEK_CLIENT_CONFIG_SETTINGS: Same as a space-separated series of `--set` arguments, but lower precedence.\n```\n\n## Installation\n\nThe recommended way to run the client is to install it with Zeek, since the\nclient is part of the distribution. You may also run it directly from the\nofficial Zeek [Docker image](https://hub.docker.com/r/zeekurity/zeek).\n\nThe WebSocket-powered `zeek-client` currently requires Zeek built from\nthe master branch, or via our [development Docker image](https://hub.docker.com/r/zeekurity/zeek-dev).\n`zeek-client` will officially become available as a standalone package,\ninstallable via `pip`, with Zeek 5.2.\n\n## Quickstart\n\nRun the following (as root) to launch an all-in-one management instance on your\nsystem:\n\n```console\n# zeek -C -j policy/frameworks/management/controller policy/frameworks/management/agent\n```\n\nThe above will stay in the foreground. In a new shell, save the following\ncontent to a file ``cluster.cfg`` and adapt the worker's sniffing interfaces to\nyour system:\n\n```ini\n[manager]\nrole = manager\n\n[logger]\nrole = logger\n\n[worker-01]\nrole = worker\ninterface = lo\n\n[worker-02]\nrole = worker\ninterface = eth0\n```\n\nRun the following command (as any user) to deploy the configuration:\n\n```console\n$ zeek-client deploy-config cluster.cfg\n{\n \"errors\": [],\n \"results\": {\n \"id\": \"9befc56c-f7e8-11ec-8626-7c10c94416bb\",\n \"nodes\": {\n \"logger\": {\n \"instance\": \"agent-testbox\",\n \"success\": true\n },\n \"manager\": {\n \"instance\": \"agent-testbox\",\n \"success\": true\n },\n \"worker-01\": {\n \"instance\": \"agent-testbox\",\n \"success\": true\n },\n \"worker-02\": {\n \"instance\": \"agent-testbox\",\n \"success\": true\n }\n }\n }\n}\n```\n\nYou are now running a Zeek cluster on your system. Try ``zeek-client get-nodes``\nto see more details about the cluster's current status. (In the above, \"testbox\"\nis the system's hostname.)\n\n## Documentation\n\nThe [Zeek documentation](https://docs.zeek.org/en/master/frameworks/management.html)\ncovers both the Management framework and the client's commands.\n\n\n",
"bugtrack_url": null,
"license": "3-clause BSD License",
"summary": "A CLI for Zeek's Management Framework",
"version": "1.3.1",
"project_urls": {
"Homepage": "https://github.com/zeek/zeek-client"
},
"split_keywords": [
"zeek",
"management",
"client",
"cluster"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "448585bff99040e2db31e2f59f0f6517cfff07054f920353275bb69c705c77dd",
"md5": "67d9e11a61ccf0371be0316b842f18cb",
"sha256": "0443991570ce295b61ba25e57ada11bb285b06b70ce6cfd71d218e4b74b0bc87"
},
"downloads": -1,
"filename": "zeek-client-1.3.1.tar.gz",
"has_sig": false,
"md5_digest": "67d9e11a61ccf0371be0316b842f18cb",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7.0",
"size": 34829,
"upload_time": "2023-09-07T06:24:40",
"upload_time_iso_8601": "2023-09-07T06:24:40.283577Z",
"url": "https://files.pythonhosted.org/packages/44/85/85bff99040e2db31e2f59f0f6517cfff07054f920353275bb69c705c77dd/zeek-client-1.3.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-09-07 06:24:40",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "zeek",
"github_project": "zeek-client",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "zeek-client"
}
JSON
