1. Installation¶

Spicy can be installed from pre-built binaries (Linux, macOS) or with Homebrew (macOS), executed via Docker containers (Linux), or built from source (Linux, macOS, FreeBSD):

Pre-built binaries
- Linux
- macOS
  - Homebrew
  - Pre-built binaries
Using Docker
Building from source
- Prerequisites
  - Linux
  - macOS
  - FreeBSD
- Building Spicy
Parser development setup

We generally aim to follow Zeek’s platform policy on which platforms to support and test.

Note

Most of the installation options discussed in this chapter do not include the Zeek plugin for Spicy. We recommend installing the plugin through Zeek’s package manager; see its installation instructions.

1.1. Pre-built binaries ¶

1.1.1. Linux ¶

We provide pre-built Spicy binaries for a range of Linux distributions, both for the current release version and for development builds made from the Git main branch.

These binary artifacts are distributed as either DEB or RPM packages for the corresponding distribution; or, in a couple cases, as TAR archives. To install the binaries, download the corresponding package and execute one of the following:

DEB packages

# dpkg --install spicy.deb

RPM packages

# rpm -i spicy.rpm

TAR archives

The TAR archives need to be unpacked into /opt/spicy. Any previous installation must be removed first:

# rm -rf /opt/spicy && mkdir /opt/spicy
# tar xf spicy.tar.gz -C /opt/spicy --strip-components=1

The binaries may require installation of additional dependencies; see the Dockerfile for the respective platform for what’s needed.

Platform	Release Version	Development Version	Dockerfile
Alpine 3.12	TAR	TAR	Dockerfile
CentOS Stream 8		RPM	Dockerfile
Debian 9	DEB	DEB	Dockerfile
Debian 10	DEB	DEB	Dockerfile
Debian 11	DEB	DEB	Dockerfile
Fedora 33	RPM	RPM	Dockerfile
Fedora 34	RPM	RPM	Dockerfile
Ubuntu 16	DEB	DEB	Dockerfile
Ubuntu 18	DEB	DEB	Dockerfile
Ubuntu 20	DEB	DEB	Dockerfile

1.1.2. macOS ¶

1.1.2.1. Homebrew ¶

We provide a Homebrew formula for installation of Spicy. After installing Homebrew add the Zeek tap:

# brew tap zeek/zeek

To install the most recent Spicy release version, execute:

# brew install spicy

To instead install the current development version, execute:

# brew install --HEAD spicy

1.1.2.2. Pre-built binaries ¶

We provide TAR archives with pre-built binaries for the following macOS versions:

macOS	Release Version	Development Version
Catalina (10.15)	TAR	TAR
Big Sur (11)	TAR	TAR

The TAR archives need to be unpacked into /opt/spicy. Any previous installation must be removed first. To prevent macOS from quarantining the files, you should download and unpack via the command line:

# curl -L <link-per-above> -o spicy.tar.gz
# rm -rf /opt/spicy && mkdir /opt/spicy
# tar xf spicy.tar.gz -C /opt/spicy --strip-components 1

For JIT support, these binaries require an Xcode installation.

1.2. Using Docker ¶

We provide pre-built Docker images on Docker Hub. The Spicy distribution also comes with a set of Docker files to create base images for all the supported Linux distributions that put all of Spicy’s dependencies in place. We’ll walk through using either of these in the following.

1.2.1. Pre-requisites ¶

You first need to install Docker on your host system, if you haven’t yet.

1.2.1.1. Linux ¶

All major Linux distributions provide Docker. Install it using your package manager. Alternatively, follow the official instructions.

1.2.1.2. macOS ¶

Install Docker Desktop for Mac following the official instructions.

Note

Docker Desktop for Mac uses a VM behind the scenes to host the Docker runtime environment. By default it allocates 2 GB of RAM to the VM. This is not enough to compile Spicy or Zeek and will cause an error that looks something like this:

c++: internal compiler error: Killed (program cc1plus)
Please submit a full bug report,
with preprocessed source if appropriate.
See <file:///usr/share/doc/gcc-7/README.Bugs> for instructions.

This is due to the VM hitting an out-of-memory condition. To avoid this you will need to allocate more RAM to the VM. Click on the Docker Icon in your menubar and select “Preferences”. Click on the “Advanced” tab and then use the slider to select 8 GB of RAM. Docker Desktop will restart and then you will be ready to go.

1.2.2. Using pre-built Docker images ¶

We provide the following Docker images:

Spicy Version	Image name/tag	Source
Release	zeekurity/spicy	Dockerfile
Development	zeekurity/spicy-dev	Dockerfile

These images include Zeek, the Spicy plugin for Zeek, and the Zeek analyzer collection as well, so you can use them to try out the full setup end-to-end.

To run the release image, execute the following command:

# docker run -it zeekurity/spicy:latest

Spicy is installed in /opt/spicy on these images. The development image is updated nightly.

1.2.3. Build your own Spicy container ¶

You can build base images for your own Spicy setups through the Docker files coming with the distribution. These images do not include Spicy itself, just the dependencies that it needs on each platform, both for a source build and for the using the corresponding binary packages. (The images do include Zeek, but not the Zeek plugin.)

To build an image, go into Spicy’s docker directory and run make to see the container platforms available:

# cd docker
# make

Run "make build-<platform>", then "make run-<platform>".

Available platforms:

    alpine-3.12
    centos-8-stream
    debian-10
    [...]

To build and run a container image based on, for example, Debian 10, execute:

# make build-debian-10
# make run-debian-10

Note

The primary purpose of these Docker files is creating the foundation for our CI pipelines. However, they also double as verified installation instructions for setting up Spicy’s dependencies on the various platforms, which is why we are describing them here.

1.3. Building from source ¶

1.3.1. Prerequisites ¶

To build Spicy from source, you will need:

For compiling the toolchain:

A C++ compiler that supports C++17 (known to work are Clang >= 9 and GCC >= 9)

CMake >= 3.15

Bison >= 3.0

Flex >= 2.6

Python >= 3.4

Zlib (no particular version)

For testing:

BTest >= 0.66 (pip install btest)

Bash (for BTest)

For building the documentation:

Sphinx >= 1.8

Pygments >= 2.5

Read the Docs Sphinx Theme (pip install sphinx_rtd_theme)

In the following we record how to get these dependencies in place on some popular platforms. Please file an issue if you have instructions for platforms not yet listed here.

1.3.1.1. Linux ¶

See the corresponding Dockerfiles.

1.3.1.2. macOS ¶

Make sure you have Xcode installed, including its command-line tools (xcode-select --install).

If you are using Homebrew:

# brew install bison flex cmake ninja python@3.8 sphinx-doc
# pip3 install btest sphinx_rtd_theme

If you are using MacPorts:

# port install flex bison cmake ninja python38 py38-pip py38-sphinx py38-sphinx_rtd_theme
# pip install btest

1.3.1.3. FreeBSD ¶

See the prepare script coming with the Spicy distribution.

1.3.2. Building Spicy ¶

Get the code:

# git clone --recursive https://github.com/zeek/spicy

The short version to build Spicy is the usual process then:

# ./configure && make && make install

However, you may want to customize the build a bit, see the output ./configure --help for the available options. In particular, you can use --prefix=/other/path to install into something else than /usr/local.

The final configure output will summarize your build’s configuration.

Note

For developers, the following configure options may be particular useful:

--enable-ccache: use the ccache compiler cache to speed up compilation

--enable-debug: compile a non-optimized debug version

--enable-sanitizer: enable address & leak sanitizers

--generator=Ninja: use the faster ninja build system instead of make

Using Ninja and ccache will speed up compile times. On Linux, compiling will also be quite a bit faster if you have the “Gold linker” available. To check if you do, see if which ld.gold returns anything. If yes, configure will automatically pick it up.

Once you have configured Spicy, running make will change into the newly created build directory and start the compilation there. Once finished, make test will execute the test suite. It will take a bit, but all tests should be passing (unless explicitly reported as expected to fail). Finally, make install will install Spicy system-wide into the configured prefix. If you are installing into a non-standard location, make sure that <prefix>/bin is in your PATH.

Note

You can also use the Spicy tools directly out of the build directory without installing; the binaries land in build/bin.

To build Spicy’s documentation, run make inside the docs/ directory. Documentation will then be located in build/doc/html.

1.4. Parser development setup ¶

In order to speed up compilation of Spicy parsers, users can create a cache of precompiled files. This cache is tied to a specific Spicy version, and needs to be recreated each time Spicy is updated.

To precompile the files execute the following command:

# spicy-precompile-headers

Note

By default the cache is located in the folder .cache/spicy/<VERSION> inside the user’s home directory. This location can be overridden by setting the environment variable SPICY_CACHE to a different folder path, both when executing spicy-precompile-headers and Spicy toolchain commands.