1. Quickstart Guide

1.1. Dependencies

Note that following the suggested Installation process via pip will automatically install GitPython and semantic_version for you.

1.2. Installation

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 site scripts directory (e.g. <bro_install_prefix>/share/bro/site)
  • plugin_dir: set to the location of Bro’s default plugin directory (e.g. <bro_install_prefix>/lib/bro/plugins)
  • 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.

Note

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)

The final step is to edit your site/local.bro. If you want to have Bro 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 bro-pkg.

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 additional configuration.

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 PATH and run:

    $ `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.cfg based on the output you see. Similarly, run:

    $ bro-pkg config plugin_dir
    

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

1.5. Usage

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

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.

Note

The package manager currently lacks automatic dependency/version analysis, but in those cases the package author will likely document dependencies in their package’s README so that users can always install them manually.