zeek-client 1.2.0

A CLI for Zeek's Management Framework

The Zeek Cluster Management Client

This is the recommended command-line client for interacting with Zeek's Management framework. Built in Python and using Broker's WebSocket pub/sub interface, it connects to a cluster controller to execute management tasks. Here's what it looks like:

$ 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.

The WebSocket-powered zeek-client currently requires Zeek built from the master branch, or via our development Docker image. 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:

# 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:

[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:

$ 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 covers both the Management framework and the client's commands.