Installation

Retis can be installed from a container image, using pre-built packages on supported Linux distributions or from sources.

Container image

We provide a script to run Retis in a container for x86_64 and aarch64 targets, retis_in_container.sh. The current directory is mounted with read-write permissions to the container working directory. This allows Retis to read and write files (eg. events, pcap). Both the Podman and Docker runtimes are supported (which is auto-detected).

$ curl -O https://raw.githubusercontent.com/retis-org/retis/main/tools/retis_in_container.sh
$ chmod +x retis_in_container.sh
$ ./retis_in_container.sh --help

By default the above script uses the latest stable version of Retis. An environment variable, RETIS_TAG, can be used to set a specific version. Available tags can be seen on quay.io.

In addition a special tag, next, points to the latest daily build of the main branch. Using this tag comes with a tradeoff: it allows access to the latest features but might not be fully functional.

$ RETIS_TAG=next ./retis_in_container.sh --help

For those operating in a disconnected environment, an environment variable RETIS_IMAGE can be used to point to an alternate image location.

$ RETIS_IMAGE=my-registry.example.com/retis ./retis_in_container.sh --help

PAGER and NOPAGER environment variables work the same way as with the Retis binary. OVS_RUNDIR environment variable can also be specified if the default one (/var/run/openvswitch) does not point to OVS's runtime directory.

Pre-built packages on Linux distributions

Fedora (>= 43)

$ dnf -y install retis

Fedora (<= 42), RHEL (>= 8.6), CentOS Stream (>= 8.6), EPEL (>= 8.6)

$ dnf -y copr enable @retis/retis
$ dnf -y install retis

Use yum instead of dnf on older distributions (e.g. CentOS Stream 8).

From sources

Retis depends on the following (in addition to Git and Cargo):

• rust >= 2021
• clang
• jq
• libelf
• libpcap
• llvm
• make
• pkg-config

If the python feature is used (which is by default), the Python3 shared libraries and headers must be available.

To download Retis' sources:

$ git clone https://github.com/retis-org/retis    # Consider using --depth 1.
$ cd retis

To build Retis:

$ make -j$(nproc) release       # Release build.
$ ./target/release/retis -V

$ make -j$(nproc)               # Debug build.
$ ./target/debug/retis -V

Finally, profiles should be installed in either /usr/share/retis/profiles or $HOME/.config/retis/profiles.

$ mkdir -p /usr/share/retis/profiles
$ cp retis/profiles/* /usr/share/retis/profiles

Fedora

$ dnf -y install git cargo clang elfutils-libelf-devel python3-devel \
        jq libpcap-devel llvm make pkgconf-pkg-config
$ make -j$(nproc) release

Debian based

$ apt update
$ apt -y install git cargo clang jq libelf-dev libpcap-dev python3-dev \
        llvm make pkg-config

On Debian based systems asm/errno.h does not live in a path known to the compiler, in turn an additional header location must be configured. For example:

$ CPATH=/usr/include/x86_64-linux-gnu make -j$(nproc) release

Cross-compilation

Retis can be cross-compiled and is currently supported on x86, x86-64 and aarch64. The target is defined using the CARGO_BUILD_TARGET environment variable, which is documented in the Rust reference.

When python support is built (it is enabled by default), PYO3_CROSS_LIB_DIR= needs to be set to the directory containing the target's libpython dynamic shared object. To disable Python support, use CARGO_CMD_OPTS=--no-default-features.

$ CARGO_BUILD_TARGET=aarch64-unknown-linux-gnu \
      PYO3_CROSS_LIB_DIR=sysroot/usr/lib/python3.14 \
      make release
$ file ./target/aarch64-unknown-linux-gnu/release/retis
[...] ARM aarch64, [...]

Shell auto-completion

Retis can generate completion files for shells (Bash, Zsh, Fish...). For example to enable auto-completion of Retis command in Bash, you can add line source <(retis sh-complete --shell bash) in .bashrc, then the command parameter could be auto-completed when pressing .