zkg(1) Zeek Package Manager zkg(1)
NAME
zkg - Zeek Package Manager
A command-line package manager for Zeek.
usage: zkg [-h] [--version] [--configfile FILE | --user] [--verbose] [--extra-source NAME=URL]
{test,install,bundle,unbundle,remove,uninstall,purge,refresh,upgrade,load,unload,pin,unpin,list,search,info,config,autoconfig,env,create,template}
...
Options:
--version
show program's version number and exit
--configfile
Path to Zeek Package Manager config file. Precludes
--user.
See Config File.
--user=False
Store all state in user's home directory. Precludes
--configfile.
--verbose=0, -v=0
Increase program output for debugging. Use multiple times
for more output (e.g. -vv).
--extra-source
Add an extra source.
Environment Variables:
ZKG_CONFIG_FILE: Same as --configfile option, but has less
precedence. ZKG_DEFAULT_SOURCE: The default package source to use
(normally https://github.com/zeek/packages). ZKG_DEFAULT_TEMPLATE:
The default package template to use (normally
https://github.com/zeek/package-template).
COMMANDS
test
Runs the unit tests for the specified Zeek packages. In most cases, the
"zeek" and "zeek-config" programs will need to be in PATH before
running this command.
usage: zkg test [-h] [--version VERSION] package [package ...]
Positional arguments:
package
The name(s) of package(s) to operate on. The package may
be named in several ways. If the package is part of a
package source, it may be referred to by the base name of
the package (last component of git URL) or its path
within the package source. If two packages in different
package sources have conflicting paths, then the package
source name may be prepended to the package path to
resolve the ambiguity. A full git URL may also be used to
refer to a package that does not belong to a source. E.g.
for a package source called "zeek" that has a package
named "foo" located in "alice/zkg.index", the following
names work: "foo", "alice/foo", "zeek/alice/foo".
Options:
--version
The version of the package to test. Only one package may
be specified at a time when using this flag. A version
tag, branch name, or commit hash may be specified here.
If the package name refers to a local git repo with a
working tree, then its currently active branch is used.
The default for other cases is to use the latest version
tag, or if a package has none, the default branch, like
"main" or "master".
install
Installs packages from a configured package source or directly from a
git URL. After installing, the package is marked as being "loaded"
(see the load command).
usage: zkg install [-h] [--skiptests] [--nodeps] [--nosuggestions] [--version VERSION] [--force]
[--user-var NAME=VAL]
package [package ...]
Positional arguments:
package
The name(s) of package(s) to operate on. The package may
be named in several ways. If the package is part of a
package source, it may be referred to by the base name of
the package (last component of git URL) or its path
within the package source. If two packages in different
package sources have conflicting paths, then the package
source name may be prepended to the package path to
resolve the ambiguity. A full git URL may also be used to
refer to a package that does not belong to a source. E.g.
for a package source called "zeek" that has a package
named "foo" located in "alice/zkg.index", the following
names work: "foo", "alice/foo", "zeek/alice/foo".
Options:
--skiptests=False
Skip running unit tests for packages before installation.
--nodeps=False
Skip all dependency resolution/checks. Note that using
this option risks putting your installed package
collection into a broken or unusable state.
--nosuggestions=False
Skip automatically installing suggested packages.
--version
The version of the package to install. Only one package
may be specified at a time when using this flag. A
version tag, branch name, or commit hash may be specified
here. If the package name refers to a local git repo with
a working tree, then its currently active branch is used.
The default for other cases is to use the latest version
tag, or if a package has none, the default branch, like
"main" or "master".
--force=False
Don't prompt for confirmation or user variables.
--user-var
A user variable assignment. This avoids prompting for
input and lets you provide a value when using --force.
Use repeatedly as needed for multiple values.
remove
Unloads (see the unload command) and uninstalls a previously installed
package.
usage: zkg remove [-h] [--force] [--nodeps] package [package ...]
Positional arguments:
package
The name(s) of package(s) to operate on. The package may
be named in several ways. If the package is part of a
package source, it may be referred to by the base name of
the package (last component of git URL) or its path
within the package source. If two packages in different
package sources have conflicting paths, then the package
source name may be prepended to the package path to
resolve the ambiguity. A full git URL may also be used to
refer to a package that does not belong to a source. E.g.
for a package source called "zeek" that has a package
named "foo" located in "alice/zkg.index", the following
names work: "foo", "alice/foo", "zeek/alice/foo".
Options:
--force=False
Skip the confirmation prompt.
--nodeps=False
Skip all dependency resolution/checks. Note that using
this option risks putting your installed package
collection into a broken or unusable state.
NOTE:
You may also say uninstall.
purge
Unloads (see the unload command) and uninstalls all previously
installed packages.
usage: zkg purge [-h] [--force]
Options:
--force=False
Skip the confirmation prompt.
bundle
This command creates a bundle file containing a collection of Zeek
packages. If --manifest is used, the user supplies the list of
packages to put in the bundle, else all currently installed packages
are put in the bundle. A bundle file can be unpacked on any target
system, resulting in a repeatable/specific set of packages being
installed on that target system (see the unbundle command). This
command may be useful for those that want to manage packages on a
system that otherwise has limited network connectivity. E.g. one can
use a system with an internet connection to create a bundle, transport
that bundle to the target machine using whatever means are appropriate,
and finally unbundle/install it on the target machine.
usage: zkg bundle [-h] [--force] [--nodeps] [--nosuggestions] [--manifest MANIFEST [MANIFEST ...] --]
filename.bundle
Positional arguments:
filename.bundle
The path of the bundle file to create. It will be
overwritten if it already exists. Note that if
--manifest is used before this filename is specified, you
should use a double-dash, --, to first terminate that
argument list.
Options:
--force=False
Skip the confirmation prompt.
--nodeps=False
Skip all dependency resolution/checks. Note that using
this option risks creating a bundle of packages that is
in a broken or unusable state.
--nosuggestions=False
Skip automatically bundling suggested packages.
--manifest
This may either be a file name or a list of packages to
include in the bundle. If a file name is supplied, it
should be in INI format with a single ``[bundle]``
section. The keys in that section correspond to package
names and their values correspond to git version tags,
branch names, or commit hashes. The values may be left
blank to indicate that the latest available version
should be used.
unbundle
This command unpacks a bundle file formerly created by the bundle
command and installs all the packages contained within.
usage: zkg unbundle [-h] [--replace] [--force] [--user-var NAME=VAL] filename.bundle
Positional arguments:
filename.bundle
The path of the bundle file to install.
Options:
--replace=False
Using this flag first removes all installed packages
before then installing the packages from the bundle.
--force=False
Don't prompt for confirmation or user variables.
--user-var
A user variable assignment. This avoids prompting for
input and lets you provide a value when using --force.
Use repeatedly as needed for multiple values.
refresh
Retrieve latest package metadata from sources and checks whether any
installed packages have available upgrades. Note that this does not
actually upgrade any packages (see the upgrade command for that).
usage: zkg refresh [-h] [--aggregate] [--fail-on-aggregate-problems] [--push]
[--sources SOURCES [SOURCES ...]]
Options:
--aggregate=False
Crawls the urls listed in package source zkg.index files
and aggregates the metadata found in their zkg.meta (or
legacy bro-pkg.meta) files. The aggregated metadata is
stored in the local clone of the package source that zkg
uses internally for locating package metadata. For each
package, the metadata is taken from the highest available
git version tag or the default branch, like "main" or
"master", if no version tags exist
--fail-on-aggregate-problems=False
When using --aggregate, exit with error when any packages
trigger metadata problems. Normally such problems only
cause a warning.
--push=False
Push all local changes to package sources to upstream
repos
--sources
A list of package source names to operate on. If this
argument is not used, then the command will operate on
all configured sources.
upgrade
Uprades the specified package(s) to latest available version. If no
specific packages are specified, then all installed packages that are
outdated and not pinned are upgraded. For packages that are installed
with --version using a git branch name, the package is updated to the
latest commit on that branch, else the package is updated to the
highest available git version tag.
usage: zkg upgrade [-h] [--skiptests] [--nodeps] [--nosuggestions] [--force] [--user-var NAME=VAL]
[package ...]
Positional arguments:
package
The name(s) of package(s) to operate on. The package may
be named in several ways. If the package is part of a
package source, it may be referred to by the base name of
the package (last component of git URL) or its path
within the package source. If two packages in different
package sources have conflicting paths, then the package
source name may be prepended to the package path to
resolve the ambiguity. A full git URL may also be used to
refer to a package that does not belong to a source. E.g.
for a package source called "zeek" that has a package
named "foo" located in "alice/zkg.index", the following
names work: "foo", "alice/foo", "zeek/alice/foo".
Options:
--skiptests=False
Skip running unit tests for packages before installation.
--nodeps=False
Skip all dependency resolution/checks. Note that using
this option risks putting your installed package
collection into a broken or unusable state.
--nosuggestions=False
Skip automatically installing suggested packages.
--force=False
Don't prompt for confirmation or user variables.
--user-var
A user variable assignment. This avoids prompting for
input and lets you provide a value when using --force.
Use repeatedly as needed for multiple values.
load
The Zeek Package Manager keeps track of all packages that are marked as
"loaded" and maintains a single Zeek script that, when loaded by Zeek
(e.g. via @load packages), will load the scripts from all "loaded"
packages at once. This command adds a set of packages to the "loaded
packages" list.
usage: zkg load [-h] [--nodeps] package [package ...]
Positional arguments:
package
Name(s) of package(s) to load.
Options:
--nodeps=False
Skip all dependency resolution/checks. Note that using
this option risks putting your installed package
collection into a broken or unusable state.
unload
The Zeek Package Manager keeps track of all packages that are marked as
"loaded" and maintains a single Zeek script that, when loaded by Zeek,
will load the scripts from all "loaded" packages at once. This command
removes a set of packages from the "loaded packages" list.
usage: zkg unload [-h] [--force] [--nodeps] package [package ...]
Positional arguments:
package
The name(s) of package(s) to operate on. The package may
be named in several ways. If the package is part of a
package source, it may be referred to by the base name of
the package (last component of git URL) or its path
within the package source. If two packages in different
package sources have conflicting paths, then the package
source name may be prepended to the package path to
resolve the ambiguity. A full git URL may also be used to
refer to a package that does not belong to a source. E.g.
for a package source called "zeek" that has a package
named "foo" located in "alice/zkg.index", the following
names work: "foo", "alice/foo", "zeek/alice/foo".
Options:
--force=False
Skip the confirmation prompt.
--nodeps=False
Skip all dependency resolution/checks. Note that using
this option risks putting your installed package
collection into a broken or unusable state.
pin
Pinned packages are ignored by the upgrade command.
usage: zkg pin [-h] package [package ...]
Positional arguments:
package
The name(s) of package(s) to operate on. The package may
be named in several ways. If the package is part of a
package source, it may be referred to by the base name of
the package (last component of git URL) or its path
within the package source. If two packages in different
package sources have conflicting paths, then the package
source name may be prepended to the package path to
resolve the ambiguity. A full git URL may also be used to
refer to a package that does not belong to a source. E.g.
for a package source called "zeek" that has a package
named "foo" located in "alice/zkg.index", the following
names work: "foo", "alice/foo", "zeek/alice/foo".
unpin
Packages that are not pinned are automatically upgraded by the upgrade
command
usage: zkg unpin [-h] package [package ...]
Positional arguments:
package
The name(s) of package(s) to operate on. The package may
be named in several ways. If the package is part of a
package source, it may be referred to by the base name of
the package (last component of git URL) or its path
within the package source. If two packages in different
package sources have conflicting paths, then the package
source name may be prepended to the package path to
resolve the ambiguity. A full git URL may also be used to
refer to a package that does not belong to a source. E.g.
for a package source called "zeek" that has a package
named "foo" located in "alice/zkg.index", the following
names work: "foo", "alice/foo", "zeek/alice/foo".
list
Outputs a list of packages that match a given category.
usage: zkg list [-h] [--nodesc] [--include-builtin] [{all,installed,not_installed,loaded,unloaded,outdated}]
Positional arguments:
category
Package category used to filter listing.
Possible choices: all, installed, not_installed, loaded,
unloaded, outdated
Options:
--nodesc=False
Do not display description text, just the package
name(s).
--include-builtin=False
Also output packages that Zeek has built-in. By default
these are not shown.
search
Perform a substring search on package names and metadata tags.
Surround search text with slashes to indicate it is a regular
expression (e.g. /text/).
usage: zkg search [-h] search_text [search_text ...]
Positional arguments:
search_text
The text(s) or pattern(s) to look for.
info
Shows detailed information/metadata for given packages. If the package
is currently installed, additional information about the status of it
is displayed. E.g. the installed version or whether it is currently
marked as "pinned" or "loaded."
usage: zkg info [-h] [--version VERSION] [--nolocal] [--include-builtin] [--json] [--jsonpretty SPACES]
[--allvers]
package [package ...]
Positional arguments:
package
The name(s) of package(s) to operate on. The package may
be named in several ways. If the package is part of a
package source, it may be referred to by the base name of
the package (last component of git URL) or its path
within the package source. If two packages in different
package sources have conflicting paths, then the package
source name may be prepended to the package path to
resolve the ambiguity. A full git URL may also be used to
refer to a package that does not belong to a source. E.g.
for a package source called "zeek" that has a package
named "foo" located in "alice/zkg.index", the following
names work: "foo", "alice/foo", "zeek/alice/foo". If a
single name is given and matches one of the same
categories as the "list" command, then it is
automatically expanded to be the names of all packages
which match the given category.
Options:
--version
The version of the package metadata to inspect. A
version tag, branch name, or commit hash and only one
package at a time may be given when using this flag. If
unspecified, the behavior depends on whether the package
is currently installed. If installed, the metadata will
be pulled from the installed version. If not installed,
the latest version tag is used, or if a package has no
version tags, the default branch, like "main" or
"master", is used.
--nolocal=False
Do not read information from locally installed packages.
Instead read info from remote GitHub.
--include-builtin=False
Also output packages that Zeek has built-in. By default
these are not shown.
--json=False
Output package information as JSON.
--jsonpretty
Optional number of spaces to indent for pretty-printed
JSON output.
--allvers=False
When outputting package information as JSON, show
metadata for all versions. This option can be slow since
remote repositories may be cloned multiple times. Also,
installed packages will show metadata only for the
installed version unless the --nolocal option is given.
config
The default output of this command is a valid package manager config
file that corresponds to the one currently being used, but also with
any defaulted field values filled in. This command also allows for
only the value of a specific field to be output if the name of that
field is given as an argument to the command.
usage: zkg config [-h] [{all,sources,user_vars,state_dir,script_dir,plugin_dir,bin_dir,zeek_dist}]
Positional arguments:
config_param
Name of a specific config file field to output.
Possible choices: all, sources, user_vars, state_dir,
script_dir, plugin_dir, bin_dir, zeek_dist
autoconfig
The output of this command is a valid package manager config file that
is generated by using the zeek-config script that is installed along
with Zeek. It is the suggested configuration to use for most Zeek
installations. For this command to work, the zeek-config script must
be in PATH, unless the --user option is given, in which case this
creates a config that does not touch the Zeek installation.
usage: zkg autoconfig [-h] [--force]
Options:
--force=False
Skip any confirmation prompt.
env
This command returns shell commands that, when executed, will correctly
set ZEEKPATH and ZEEK_PLUGIN_PATH to use scripts and plugins from
packages installed by the package manager. For this command to function
properly, either have the zeek-config script (installed by zeek) in
PATH, or have the ZEEKPATH and ZEEK_PLUGIN_PATH environment variables
already set so this command can append package-specific paths to them.
usage: zkg env [-h]
create
This command creates a new Zeek package in the directory provided via
--packagedir. If this directory exists, zkg will not modify it unless
you provide --force.
usage: zkg create [-h] --packagedir DIR [--version VERSION] [--features FEATURE [FEATURE ...]]
[--template URL] [--force] [--user-var NAME=VAL]
Options:
--packagedir
Output directory into which to produce the new package.
Required.
--version
The template version to use. A version tag, branch name,
or commit hash may be specified here. If --template
refers to a local git repo with a working tree, then zkg
uses it as-is and the version is ignored. The default
for other cases is to use the latest version tag, or if a
template has none, the default branch, like "main" or
"master".
--features
Additional features to include in your package. Use the
``template info`` command for information about available
features.
--template
By default, zkg uses its own package template. This makes
it select an alternative.
--force=False
Don't prompt for confirmation or user variables.
--user-var
A user variable assignment. This avoids prompting for
input and lets you provide a value when using --force.
Use repeatedly as needed for multiple values.
template info
This command shows versions and supported features for a given package.
usage: zkg template info [-h] [--json] [--jsonpretty SPACES] [--version VERSION] [URL]
Positional arguments:
URL URL of a package template repository, or local path to
one. When not provided, the configured default template
is used.
Options:
--json=False
Output template information as JSON.
--jsonpretty
Optional number of spaces to indent for pretty-printed
JSON output.
--version
The template version to report on. A version tag, branch
name, or commit hash may be specified here. If the
selected template refers to a local git repo, the version
is ignored. The default for other cases is to use the
latest version tag, or if a template has none, the
default branch, like "main" or "master".
CONFIG FILE
The zkg command-line tool uses an INI-format config file to allow users
to customize their Package Sources, Package installation paths, Zeek
executable/source paths, and other zkg options.
See the default/example config file below for explanations of the
available options and how to customize them:
# This is an example config file for zkg to explain what
# settings are possible as well as their default values.
# The order of precedence for how zkg finds/reads config files:
#
# (1) zkg --configfile=/path/to/custom/config
# (2) the ZKG_CONFIG_FILE environment variable
# (3) a config file located at $HOME/.zkg/config
# (4) if none of the above exist, then zkg uses builtin/default
# values for all settings shown below
[sources]
# The default package source repository from which zkg fetches
# packages. The default source may be removed, changed, or
# additional sources may be added as long as they use a unique key
# and a value that is a valid git URL. The git URL may also use a
# suffix like "@branch-name" where "branch-name" is the name of a real
# branch to checkout (as opposed to the default branch, which is typically
# "main" or "master"). You can override the package source zkg puts
# in new config files (e.g. "zkg autoconfig") by setting the
# ZKG_DEFAULT_SOURCE environment variable.
zeek = https://github.com/zeek/packages
[paths]
# Directory where source repositories are cloned, packages are
# installed, and other package manager state information is
# maintained. If left blank or with --user this defaults to
# $HOME/.zkg. In Zeek-bundled installations, it defaults to
# <zeek_install_prefix>/var/lib/zkg/.
state_dir =
# The directory where package scripts are copied upon installation.
# A subdirectory named "packages" is always created within the
# specified path and the package manager will copy the directory
# specified by the "script_dir" option of each package's zkg.meta
# (or legacy bro-pkg.meta) file there.
# If left blank or with --user this defaults to <state_dir>/script_dir.
# In Zeek-bundled installations, it defaults to
# <zeek_install_prefix>/share/zeek/site.
# If you decide to change this location after having already
# installed packages, zkg will automatically relocate them
# the next time you run any zkg command.
script_dir =
# The directory where package plugins are copied upon installation.
# A subdirectory named "packages" is always created within the
# specified path and the package manager will copy the directory
# specified by the "plugin_dir" option of each package's zkg.meta
# (or legacy bro-pkg.meta) file there.
# If left blank or with --user this defaults to <state_dir>/plugin_dir.
# In Zeek-bundled installations, it defaults to
# <zeek_install_prefix>/lib/zeek/plugins.
# If you decide to change this location after having already
# installed packages, zkg will automatically relocate them
# the next time you run any zkg command.
plugin_dir =
# The directory where executables from packages are linked into upon
# installation. If left blank or with --user this defaults to <state_dir>/bin.
# In Zeek-bundled installations, it defaults to <zeek_install_prefix>/bin.
# If you decide to change this location after having already
# installed packages, zkg will automatically relocate them
# the next time you run any zkg command.
bin_dir =
# The directory containing Zeek distribution source code. This is only
# needed when installing packages that contain Zeek plugins that are
# not pre-built. This value is generally not needed by most users other
# than plugin developers anymore.
zeek_dist =
[templates]
# The URL of the package template repository that the "zkg create" command
# will instantiate by default.
default = https://github.com/zeek/package-template
[user_vars]
# For any key in this section that is matched for value interpolation
# in a package's zkg.meta (or legacy bro-pkg.meta) file, the corresponding
# value is substituted during execution of the package's `build_command`.
# This section is typically automatically populated with the
# the answers supplied during package installation prompts
# and, as a convenience feature, used to recall the last-used settings
# during subsequent operations (e.g. upgrades) on the same package.
AUTHOR
The Zeek Project
COPYRIGHT
2019, The Zeek Project
3.0.1-33 May 13, 2024 zkg(1)
zeek 7.0.5 - Generated Tue Jan 7 18:54:38 CST 2025