265 lines
9.5 KiB
ReStructuredText
265 lines
9.5 KiB
ReStructuredText
.. _PyPI: https://pypi.python.org/pypi
|
|
.. _ZeekControl: https://github.com/zeek/zeekctl
|
|
|
|
Quickstart Guide
|
|
================
|
|
|
|
Dependencies
|
|
------------
|
|
|
|
* Python 3.6+
|
|
* 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
|
|
|
|
Note that following the :program:`zkg` `Installation`_ process via
|
|
:program:`pip3` will automatically install its dependencies for you.
|
|
|
|
Installation
|
|
------------
|
|
|
|
* Zeek 4.0.0 or greater comes with a bundled :program:`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
|
|
:program:`zkg`'s dependencies, which is usually easiest to do via
|
|
:program:`pip3`:
|
|
|
|
.. code-block:: console
|
|
|
|
$ pip3 install gitpython semantic-version
|
|
|
|
* To install the latest release of :program:`zkg` on PyPI_:
|
|
|
|
.. code-block:: console
|
|
|
|
$ pip3 install zkg
|
|
|
|
* To install the latest Git development version of :program:`zkg`:
|
|
|
|
.. code-block:: console
|
|
|
|
$ pip3 install git+git://github.com/zeek/package-manager@master
|
|
|
|
.. note::
|
|
|
|
If not using something like :program:`virtualenv` to manage Python
|
|
environments, the default user script directory is :file:`~/.local/bin` and
|
|
you may have to modify your :envvar:`PATH` to search there for
|
|
:program:`zkg`.
|
|
|
|
Basic Configuration
|
|
-------------------
|
|
|
|
:program:`zkg` supports four broad approaches to managing Zeek packages:
|
|
|
|
- Keep package metadata in :file:`$HOME/.zkg/` and maintain
|
|
Zeek-relevant package content (such as scripts and plugins) in the
|
|
Zeek installation tree. This is :program:`zkg`'s "traditional"
|
|
approach.
|
|
|
|
- Keep all state and package content within the Zeek installation
|
|
tree. Zeek 4's bundled :program:`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 :file:`$HOME/.zkg/`. This is
|
|
the preferred approach when you're running :program:`zkg` and
|
|
:program:`zeek` as different users. :program:`zkg`'s ``--user`` mode
|
|
enables this approach.
|
|
|
|
- Custom configurations where you select your own state and content
|
|
locations.
|
|
|
|
After installing via :program:`pip3`, but not when using the :program:`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 :program:`zkg` for use with a given Zeek installation, make
|
|
sure that the :program:`zeek-config` script that gets installed with
|
|
:program:`zeek` is in your :envvar:`PATH`. Then, as the user you want to run
|
|
:program:`zkg` with, do:
|
|
|
|
.. code-block:: console
|
|
|
|
$ 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 :file:`site` scripts directory
|
|
(e.g. :file:`{<zeek_install_prefix>}/share/zeek/site`)
|
|
|
|
- `plugin_dir`: set to the location of Zeek's default plugin directory (e.g.
|
|
:file:`{<zeek_install_prefix>}/lib/zeek/plugins`)
|
|
|
|
- `bin_dir`: set to the location where :program:`zkg` installs
|
|
executables that packages provide (e.g.,
|
|
:file:`{<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 :program:`zeek` and
|
|
:program:`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
|
|
:program:`zkg` as a different user, you have two options.
|
|
|
|
First, you can use :program:`zkg`'s user mode (``zkg --user``). In
|
|
user mode, :program:`zkg` consults :file:`$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 :file:`$HOME/.zkg/`. :program:`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:
|
|
|
|
.. code-block:: console
|
|
|
|
$ 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 :file:`site/local.zeek`. If you want to
|
|
have Zeek automatically load the scripts from all
|
|
:ref:`installed <install-command>` packages that are also marked as
|
|
":ref:`loaded <load-command>`" add:
|
|
|
|
.. code-block:: zeek
|
|
|
|
@load packages
|
|
|
|
If you prefer to manually pick the package scripts to load, you may instead add
|
|
lines like :samp:`@load {<package_name>}`, where :samp:`{<package_name>}`
|
|
is the :ref:`shorthand name <package-shorthand-name>` of the desired package.
|
|
|
|
If you want to further customize your configuration, see the `Advanced
|
|
Configuration`_ section and also check :ref:`here <zkg-config-file>` for a
|
|
full explanation of config file options. Otherwise you're ready to use
|
|
:ref:`zkg <zkg>`.
|
|
|
|
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 :file:`~/.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 :program:`zeek` or
|
|
:program:`zeekctl` will not detect scripts/plugins in those locations without
|
|
additional configuration.
|
|
|
|
When using non-standard location, follow these steps to integrate with
|
|
:program:`zeek` and :program:`zeekctl`:
|
|
|
|
- To get command-line :program:`zeek` to be aware of Zeek scripts/plugins in a
|
|
non-standard location, make sure the :program:`zeek-config` script (that gets
|
|
installed along with :program:`zeek`) is in your :envvar:`PATH` and run:
|
|
|
|
.. code-block:: console
|
|
|
|
$ `zkg env`
|
|
|
|
Note that this sets up the environment only for the current shell session.
|
|
|
|
- To get :program:`zeekctl` to be aware of scripts/plugins in a non-standard
|
|
location, run:
|
|
|
|
.. code-block:: console
|
|
|
|
$ zkg config script_dir
|
|
|
|
And set the `SitePolicyPath` option in :file:`zeekctl.cfg` based on the output
|
|
you see. Similarly, run:
|
|
|
|
.. code-block:: console
|
|
|
|
$ zkg config plugin_dir
|
|
|
|
And set the `SitePluginPath` option in :file:`zeekctl.cfg` based on the output
|
|
you see.
|
|
|
|
- To have your shell find executables that packages provide, update
|
|
your :envvar:`PATH`:
|
|
|
|
.. code-block:: console
|
|
|
|
$ export PATH=$(zkg config bin_dir):$PATH
|
|
|
|
(Executing ```zkg env```, as described above, includes this
|
|
already.)
|
|
|
|
Usage
|
|
-----
|
|
|
|
Check the output of :ref:`zkg --help <zkg>` for an explanation of all
|
|
available functionality of the command-line tool.
|
|
|
|
Package Upgrades/Versioning
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
When installing packages, note that the :ref:`install command
|
|
<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 :program:`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 :ref:`package upgrade
|
|
process <package-upgrade-process>` documentation to learn how
|
|
:program:`zkg` treats each situation.
|
|
|
|
Offline Usage
|
|
~~~~~~~~~~~~~
|
|
|
|
It's common to have limited network/internet access on the systems where
|
|
Zeek is deployed. To accomodate those scenarios, :program:`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:
|
|
|
|
.. code-block:: console
|
|
|
|
$ zkg install <package name>
|
|
|
|
Then, via the :ref:`bundle command <bundle-command>`, create a bundle
|
|
file which contains a snapshot of all currently installed packages:
|
|
|
|
.. code-block:: console
|
|
|
|
$ zkg bundle zeek-packages.bundle
|
|
|
|
Then transfer :file:`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 :program:`zkg` installed and configured):
|
|
|
|
.. code-block:: console
|
|
|
|
$ 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:
|
|
|
|
.. code-block:: console
|
|
|
|
$ zeekctl deploy
|