1. Quickstart Guide¶
- Python 2.7+ or 3.0+
- git: https://git-scm.com
- GitPython: https://pypi.python.org/pypi/GitPython
- semantic_version: https://pypi.python.org/pypi/semantic_version
- btest: https://pypi.python.org/pypi/btest
- configparser backport (not needed when using Python 3.5+): https://pypi.python.org/pypi/configparser
Note that following the suggested Installation process via pip will automatically install dependencies for you.
Using the latest stable release on PyPI:
$ pip install bro-pkg
Using the latest git development version:
$ pip install git+git://github.com/bro/package-manager@master
1.3. Basic Configuration¶
After installing via pip, additional configuration is required.
First, make sure that the bro-config script that gets installed with
bro is in your
PATH. Then, as the user you want to run
bro-pkg with, do:
$ bro-pkg autoconfig
This automatically generates a config file with the following suggested settings that should work for most Bro deployments:
- script_dir: set to the location of Bro's
sitescripts directory (e.g.
- plugin_dir: set to the location of Bro's default plugin directory (e.g.
- bro_dist: set to the location of Bro's source code. If you didn't build/install Bro from source code, this field will not be set, but it's only needed if you plan on installing packages that have uncompiled Bro plugins.
With those settings, the package manager will install Bro scripts, Bro plugins, and BroControl plugins into directories where bro and broctl will, by default, look for them. BroControl clusters will also automatically distribute installed package scripts/plugins to all nodes.
If your Bro installation is owned by "root" and you intend to run bro-pkg as a different user, then you should grant "write" access to the directories specified by script_dir and plugin_dir. E.g. you could do something like:
$ sudo chgrp $USER $(bro-config --site_dir) $(bro-config --plugin_dir) $ sudo chmod g+rwX $(bro-config --site_dir) $(bro-config --plugin_dir)
If you prefer to manually pick the package scripts to load, you may instead add
@load <package_name>, where
is the shorthand name of the desired package.
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
~/.bro-pkg 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 bro or
broctl will not detect scripts/plugins in those locations without
When using non-standard location, follow these steps to integrate with bro and broctl:
To get command-line bro to be aware of Bro scripts/plugins in a non-standard location, make sure the bro-config script (that gets installed along with bro) is in your
$ `bro-pkg env`
Note that this sets up the environment only for the current shell session.
To get broctl to be aware of scripts/plugins in a non-standard location, run:
$ bro-pkg config script_dir
And set the SitePolicyPath option in
broctl.cfgbased on the output you see. Similarly, run:
$ bro-pkg config plugin_dir
And set the SitePluginPath option in
broctl.cfgbased on the output you see.
Check the output of bro-pkg --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 bro-pkg 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
bro-pkg treats each situation.
1.5.2. Offline Usage¶
It's common to have limited network/internet access on the systems where Bro is deployed. To accomodate those scenarios, bro-pkg 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:
$ bro-pkg install <package name>
Then, via the bundle command, create a bundle file which contains a snapshot of all currently installed packages:
$ bro-pkg bundle bro-packages.bundle
bro-packages.bundle to the Bro deployment
management host. For Bro clusters using BroControl, this will
be the system acting as the "manager" node. Then on that system
(assuming it already as bro-pkg installed and configured):
$ bro-pkg unbundle bro-packages.bundle
Finally, if you're using BroControl, and the unbundling process was successful, you need to deploy the changes to worker nodes:
$ broctl deploy