1. Quickstart Guide

1.1. Dependencies

Note that following the zkg Installation process via pip3 will automatically install its dependencies for you.

1.2. Installation

  • Zeek 4.0.0 or greater comes with a bundled zkg that is included as part of its installation. This is often the easiest choice since it comes pre-configured to work correctly for that particular Zeek installation and some Basic Configuration steps can be skipped. The directions to build and install Zeek from source are here: https://docs.zeek.org/en/current/install/install.html

    Note that this method does require independent installation of zkg's dependencies, which is usually easiest to do via pip3:

    $ pip3 install gitpython semantic-version

  • To install the latest release of zkg on PyPI:

    $ pip3 install zkg

  • To install the latest Git development version of zkg:

    $ pip3 install git+git://github.com/zeek/package-manager@master

Note

If not using something like virtualenv to manage Python environments, the default user script directory is ~/.local/bin and you may have to modify your PATH to search there for zkg.

1.3. Basic Configuration

zkg supports four broad approaches to managing Zeek packages:

  • Keep package metadata in $HOME/.zkg/ and maintain Zeek-relevant package content (such as scripts and plugins) in the Zeek installation tree. This is zkg's "traditional" approach.

  • Keep all state and package content within the Zeek installation tree. Zeek 4's bundled zkg installation provides this by default. If you use multiple Zeek installations in parallel, this approach allows you to install different sets of Zeek packages with each Zeek version.

  • Keep all state and package content in $HOME/.zkg/. This is the preferred approach when you're running zkg and zeek as different users. zkg's --user mode enables this approach.

  • Custom configurations where you select your own state and content locations.

After installing via pip3, but not when using the zkg that comes pre-bundled with a Zeek installation, additional configuration is still required in the form of running a zkg autoconfig command, but in either case, do read onward to get a better understanding of how the package manager is configured, what directories it uses, etc.

To configure zkg for use with a given Zeek installation, make sure that the zeek-config script that gets installed with zeek is in your PATH. Then, as the user you want to run zkg with, do:

$ zkg autoconfig

This automatically generates a config file with the following suggested settings that should work for most Zeek deployments:

  • script_dir: set to the location of Zeek's site scripts directory (e.g. <zeek_install_prefix>/share/zeek/site)

  • plugin_dir: set to the location of Zeek's default plugin directory (e.g. <zeek_install_prefix>/lib/zeek/plugins)

  • bin_dir: set to the location where zkg installs executables that packages provide (e.g., <zeek_install_prefix>/bin).

  • zeek_dist: set to the location of Zeek's source code. If you didn't build/install Zeek from source code, this field will not be set, but it's only needed if you plan on installing packages that have uncompiled Zeek plugins.

With those settings, the package manager will install Zeek scripts, Zeek plugins, and ZeekControl plugins into directories where zeek and zeekctl will, by default, look for them. ZeekControl clusters will also automatically distribute installed package scripts/plugins to all nodes.

Note

If your Zeek installation is owned by "root" and you intend to run zkg as a different user, you have two options.

First, you can use zkg's user mode (zkg --user). In user mode, zkg consults $HOME/.zkg/config for configuration settings. Creating this config file in user mode (zkg --user autoconfig) ensures that all state and content directories reside within $HOME/.zkg/. zkg reports according environment variables in the output of zkg --user env.

Second, you can grant "write" access to the directories specified by script_dir, plugin_dir, and bin_dir; perhaps using something like:

$ sudo chgrp $USER $(zeek-config --site_dir) $(zeek-config
--plugin_dir) $(zeek-config --prefix)/bin
$ sudo chmod g+rwX $(zeek-config --site_dir) $(zeek-config --plugin_dir) $(zeek-config --prefix)/bin

The final step is to edit your site/local.zeek. If you want to have Zeek automatically load the scripts from all installed packages that are also marked as "loaded" add:

@load packages

If you prefer to manually pick the package scripts to load, you may instead add lines like @load <package_name>, where <package_name> is the shorthand name of the desired package.

If you want to further customize your configuration, see the Advanced Configuration section and also check here for a full explanation of config file options. Otherwise you're ready to use zkg.

1.4. Advanced Configuration

If you prefer to not use the suggested Basic Configuration settings for script_dir and plugin_dir, the default configuration will install all package scripts/plugins within ~/.zkg or you may change them to whatever location you prefer. These will be referred to as "non-standard" locations in the sense that vanilla configurations of either zeek or zeekctl will not detect scripts/plugins in those locations without additional configuration.

When using non-standard location, follow these steps to integrate with zeek and zeekctl:

  • To get command-line zeek to be aware of Zeek scripts/plugins in a non-standard location, make sure the zeek-config script (that gets installed along with zeek) is in your PATH and run:

    $ `zkg env`

    Note that this sets up the environment only for the current shell session.

  • To get zeekctl to be aware of scripts/plugins in a non-standard location, run:

    $ zkg config script_dir

    And set the SitePolicyPath option in zeekctl.cfg based on the output you see. Similarly, run:

    $ zkg config plugin_dir

    And set the SitePluginPath option in zeekctl.cfg based on the output you see.

  • To have your shell find executables that packages provide, update your PATH:

    $ export PATH=$(zkg config bin_dir):$PATH

    (Executing `zkg env`, as described above, includes this already.)

1.5. Usage

Check the output of zkg --help for an explanation of all available functionality of the command-line tool.

1.5.1. Package Upgrades/Versioning

When installing packages, note that the install command, has a --version flag that may be used to install specific package versions which may either be git release tags or branch names. The way that zkg receives updates for a package depends on whether the package is first installed to track stable releases or a specific git branch. See the package upgrade process documentation to learn how zkg treats each situation.

1.5.2. Offline Usage

It's common to have limited network/internet access on the systems where Zeek is deployed. To accomodate those scenarios, zkg can be used as normally on a system that does have network access to create bundles of its package installation environment. Those bundles can then be transferred to the deployment systems via whatever means are appropriate (SSH, USB flash drive, etc).

For example, on the package management system you can do typical package management tasks, like install and update packages:

$ zkg install <package name>

Then, via the bundle command, create a bundle file which contains a snapshot of all currently installed packages:

$ zkg bundle zeek-packages.bundle

Then transfer zeek-packages.bundle to the Zeek deployment management host. For Zeek clusters using ZeekControl, this will be the system acting as the "manager" node. Then on that system (assuming it already as zkg installed and configured):

$ zkg unbundle zeek-packages.bundle

Finally, if you're using ZeekControl, and the unbundling process was successful, you need to deploy the changes to worker nodes:

$ zeekctl deploy