Runs the unit tests for the specified Bro packages. In most cases,
the "bro" and "bro-config" programs will need to be in
PATH before running this command.
usage: bro-pkg 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 "bro" that has a package named
"foo" located in "alice/bro-pkg.index" the following
names work: "foo", "alice/foo",
"bro/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 "master" branch.
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: bro-pkg install [-h] [--force] [--skiptests] [--nodeps]
[--nosuggestions] [--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 "bro" that has a package named
"foo" located in "alice/bro-pkg.index" the following
names work: "foo", "alice/foo",
"bro/alice/foo".
- Options:
- --force=False
- Skip the confirmation prompt.
- --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 "master" branch.
Unloads (see the unload command) and uninstalls a
previously installed package.
usage: bro-pkg remove [-h] [--force] 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 "bro" that has a package named
"foo" located in "alice/bro-pkg.index" the following
names work: "foo", "alice/foo",
"bro/alice/foo".
- Options:
Unloads (see the unload command) and uninstalls all
previously installed packages.
usage: bro-pkg purge [-h] [--force]
This command creates a bundle file containing a collection of Bro
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: bro-pkg bundle [-h] [--force] [--nodeps] [--nosuggestions]
[--manifest MANIFEST [MANIFEST ...] --]
bundle_filename
- Positional
arguments:
- bundle_filename
- 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.
This command unpacks a bundle file formerly created by the
bundle command and installs all the packages contained within.
usage: bro-pkg unbundle [-h] [--force] [--replace] bundle_filename
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: bro-pkg refresh [-h] [--aggregate] [--push]
[--sources SOURCES [SOURCES ...]]
- Options:
- --aggregate=False
- Crawls the urls listed in package source bro-pkg.index files and
aggregates the metadata found in their bro-pkg.meta files. The aggregated
metadata is stored in the local clone of the package source that bro-pkg
uses internally locating package metadata. For each package, the metadata
is taken from the highest available git version tag or the master branch
if no version tags exist
- --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.
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: bro-pkg upgrade [-h] [--force] [--skiptests] [--nodeps]
[--nosuggestions]
[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 "bro" that has a package named
"foo" located in "alice/bro-pkg.index" the following
names work: "foo", "alice/foo",
"bro/alice/foo".
- Options:
- --force=False
- Skip the confirmation prompt.
- --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.
The Bro Package Manager keeps track of all packages that are
marked as "loaded" and maintains a single Bro script that, when
loaded by Bro (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: bro-pkg load [-h] package [package ...]
The Bro Package Manager keeps track of all packages that are
marked as "loaded" and maintains a single Bro script that, when
loaded by Bro, will load the scripts from all "loaded" packages at
once. This command removes a set of packages from the "loaded
packages" list.
usage: bro-pkg unload [-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 "bro" that has a package named
"foo" located in "alice/bro-pkg.index" the following
names work: "foo", "alice/foo",
"bro/alice/foo".
Pinned packages are ignored by the upgrade command.
usage: bro-pkg 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 "bro" that has a package named
"foo" located in "alice/bro-pkg.index" the following
names work: "foo", "alice/foo",
"bro/alice/foo".
Packages that are not pinned are automatically upgraded by the
upgrade command
usage: bro-pkg 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 "bro" that has a package named
"foo" located in "alice/bro-pkg.index" the following
names work: "foo", "alice/foo",
"bro/alice/foo".
Outputs a list of packages that match a given category.
usage: bro-pkg list [-h] [--nodesc]
[{all,installed,not_installed,loaded,unloaded,outdated}]
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: bro-pkg search [-h] search_text [search_text ...]
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: bro-pkg info [-h] [--version VERSION] [--nolocal] [--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 "bro" that has a package named
"foo" located in "alice/bro-pkg.index" the following
names work: "foo", "alice/foo",
"bro/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 "master" branch
is used.
- --nolocal=False
- Do not read information from locally installed packages. Instead read info
from remote GitHub.
- --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.
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: bro-pkg config [-h]
[{all,sources,user_vars,state_dir,script_dir,plugin_dir,bro_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, bro_dist
The output of this command is a valid package manager config file
that is generated by using the bro-config script that is installed
along with Bro. It is the suggested configuration to use for most Bro
installations. For this command to work, the bro-config script must
be in PATH.
usage: bro-pkg autoconfig [-h]
This command returns shell commands that, when executed, will
correctly set BROPATH and BRO_PLUGIN_PATH to utilize the
scripts and plugins from packages installed by the package manager. For this
command to function properly, either have the bro-config script
(installed by bro) in PATH, or have the BROPATH and
BRO_PLUGIN_PATH environment variables already set so this command can
append package-specific paths to them.
The bro-pkg command-line tool uses an INI-format config
file to allow users to customize their Package Sources, Package installation
paths, Bro executable/source paths, and other bro-pkg 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 bro-pkg to explain what
# settings are possible as well as their default values.
# The order of precedence for how bro-pkg finds/reads config files:
#
# (1) bro-pkg --configfile=/path/to/custom/config
# (2) the BRO_PKG_CONFIG_FILE environment variable
# (3) a config file located at $HOME/.bro-pkg/config
# (4) if none of the above exist, then bro-pkg uses builtin/default
# values for all settings shown below
[sources]
# The default package source repository from which bro-pkg 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.
bro = https://github.com/bro/packages
[paths]
# Directory where source repositories are cloned, packages are
# installed, and other package manager state information is
# maintained. If left blank, this defaults to $HOME/.bro-pkg
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 bro-pkg.meta
# file there.
# If left blank, this defaults to <state_dir>/script_dir
# A typical path to set here is <bro_install_prefix>/share/bro/site
# If you decide to change this location after having already
# installed packages, bro-pkg will automatically relocate them
# the next time you run any bro-pkg 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 bro-pkg.meta
# file there.
# If left blank, this defaults to <state_dir>/plugin_dir
# A typical path to set here is <bro_install_prefix>/lib/bro/plugins
# If you decide to change this location after having already
# installed packages, bro-pkg will automatically relocate them
# the next time you run any bro-pkg command.
plugin_dir =
# The directory containing Bro distribution source code. This is only
# needed when installing packages that contain Bro plugins that are
# not pre-built.
bro_dist =
[user_vars]
# For any key in this section that is matched for value interpolation
# in a package's 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.