Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

doc: update eBPF/compilation instructions v1 #10182

Closed
wants to merge 2 commits into from
Closed

doc: update eBPF/compilation instructions v1 #10182

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
93e1bea
doc: update eBPF compilation instructions
Jan 16, 2024
4954fa1
doc: port user install and build instruction from master-6.0.x
Jan 16, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
16 changes: 10 additions & 6 deletions doc/userguide/capture-hardware/ebpf-xdp.rst
View file
Open in desktop
Expand Up @@ -80,16 +80,15 @@ Make sure you have ``clang`` (>=3.9) installed on the system ::

sudo apt install clang

Some i386 headers will also be needed as eBPF is not x86_64 and some included headers
are architecture specific ::

sudo apt install libc6-dev-i386 --no-install-recommends

libbpf
~~~~~~

Suricata uses libbpf to interact with eBPF and XDP ::

sudo apt install libbpf-dev

If the libbpf package is unavailable, it can cloned from the repository ::

git clone https://github.com/libbpf/libbpf.git

Now, you can build and install the library ::
Expand All @@ -100,6 +99,11 @@ Now, you can build and install the library ::
sudo make install_headers
sudo ldconfig

You may miss some i386 headers (as eBPF is not x86_64 and some included headers
are architecture specific) ::

sudo apt install libc6-dev-i386 --no-install-recommends

In some cases your system will not find the libbpf library that is installed under
``/usr/lib64`` so you may need to modify your ldconfig configuration.

Expand All @@ -109,7 +113,7 @@ Compile and install Suricata
To get Suricata source, you can use the usual ::

git clone https://github.com/OISF/suricata.git
cd suricata && git clone https://github.com/OISF/libhtp.git -b 0.5.x
cd suricata && ./scripts/bundle.sh

./autogen.sh

Expand Down
110 changes: 54 additions & 56 deletions doc/userguide/install.rst
View file
Open in desktop
Expand Up @@ -61,31 +61,8 @@ Common configure options

Enables `DPDK <https://www.dpdk.org/>`_ packet capture method.

Dependencies
^^^^^^^^^^^^

For Suricata's compilation you'll need the following libraries and their development headers installed::

libjansson, libpcap, libpcre2, libyaml, zlib

The following tools are required::

make gcc (or clang) pkg-config rustc cargo

Rust support::

rustc, cargo

Some distros don't provide or provide outdated Rust packages.
Rust can also be installed directly from the Rust project itself::

1) Install Rust https://www.rust-lang.org/en-US/install.html
2) Install cbindgen - if the cbindgen is not found in the repository
or the cbindgen version is lower than required, it can be
alternatively installed as: cargo install --force cbindgen
3) Make sure the cargo path is within your PATH environment
e.g. echo 'export PATH=”${PATH}:~/.cargo/bin”' >> ~/.bashrc
e.g. export PATH="${PATH}:/root/.cargo/bin"
Dependencies and compilation
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Ubuntu/Debian
"""""""""""""
Expand All @@ -94,23 +71,19 @@ Ubuntu/Debian

Minimal::

# Installed Rust and cargo as indicated above
sudo apt-get install build-essential git libjansson-dev libpcap-dev \
libpcre2-dev libtool libyaml-dev make pkg-config zlib1g-dev
# On most distros installing cbindgen with package manager should be enough
sudo apt-get install cbindgen # alternative: cargo install --force cbindgen
sudo apt-get install build-essential cargo cbindgen git libjansson-dev \
libpcap-dev libpcre2-dev libtool libyaml-dev make \
pkg-config rustc zlib1g-dev

Recommended::

# Installed Rust and cargo as indicated above
sudo apt-get install autoconf automake build-essential ccache clang curl git \
gosu jq libbpf-dev libcap-ng0 libcap-ng-dev libelf-dev \
libevent-dev libgeoip-dev libhiredis-dev libjansson-dev \
liblua5.1-dev libmagic-dev libnet1-dev libpcap-dev \
libpcre2-dev libtool libyaml-0-2 libyaml-dev m4 make \
pkg-config python3 python3-dev python3-yaml sudo zlib1g \
zlib1g-dev
cargo install --force cbindgen
sudo apt-get install autoconf automake build-essential cargo cbindgen \
ccache clang curl git gosu jq libbpf-dev libcap-ng0 \
libcap-ng-dev libelf-dev libevent-dev libgeoip-dev \
libhiredis-dev libjansson-dev liblua5.1-dev libmagic-dev \
libnet1-dev libpcap-dev libpcre2-dev libtool libyaml-0-2 \
libyaml-dev m4 make pkg-config python3 python3-dev \
python3-yaml rustc sudo zlib1g zlib1g-dev

Extra for iptables/nftables IPS integration::

Expand All @@ -129,9 +102,9 @@ one of the following ways::

sudo dnf -y update
sudo dnf -y install dnf-plugins-core
# AlmaLinux 8
# AlmaLinux 8 / RockyLinux 8
sudo dnf config-manager --set-enabled powertools
# AlmaLinux 9
# AlmaLinux 9 / RockyLinux 9
sudo dnf config-manager --set-enable crb
# Oracle Linux 8
sudo dnf config-manager --set-enable ol8_codeready_builder
Expand All @@ -140,34 +113,59 @@ one of the following ways::

Minimal::

# Installed Rust and cargo as indicated above
sudo dnf install -y rustc cargo
cargo install --force cbindgen
# Make sure the cargo path is within your PATH environment e.g.:
echo 'export PATH=”${PATH}:~/.cargo/bin”' >> ~/.bashrc
export PATH="${PATH}:~/.cargo/bin"
sudo dnf install -y gcc gcc-c++ git jansson-devel libpcap-devel libtool \
libyaml-devel make pcre2-devel which zlib-devel
cargo install --force cbindgen

Recommended::

# Installed Rust and cargo as indicated above
sudo dnf install -y autoconf automake diffutils file-devel gcc gcc-c++ git \
jansson-devel jq libcap-ng-devel libevent-devel \
libmaxminddb-devel libnet-devel libnetfilter_queue-devel \
libnfnetlink-devel libpcap-devel libtool libyaml-devel \
lua-devel lz4-devel make nss-devel pcre2-devel pkgconfig \
python3-devel python3-sphinx python3-yaml sudo which \
zlib-devel
cargo install --force cbindgen
# Minimal dependencies installed and then
sudo dnf install -y epel-release
sudo dnf install -y autoconf automake clang diffutils file-devel \
hiredis-devel hyperscan-devel \
jansson-devel jq libbpf-devel libcap-ng-devel \
libevent-devel libmaxminddb-devel libnet-devel \
libnetfilter_queue-devel libnfnetlink-devel libpcap-devel \
libtool libyaml-devel llvm-toolset lua-devel \
lz4-devel make nspr-devel nss-devel pcre2-devel \
pkgconfig python3-devel python3-sphinx python3-yaml \
sudo which zlib-devel

Compilation
^^^^^^^^^^^
"""""""""""

Follow these steps from your Suricata directory::

./scripts/bundle.sh
./autogen.sh
./configure # you may want to add additional parameters here
# ./configure --help to get all available parameters
make -j8 # j is for paralleling, you may de/increase depending on your CPU
# Recommended parameters:
CC=clang ./configure --enable-ebpf --enable-ebpf-build --enable-nfqueue \
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't think we're generally recommending clang over gcc or recommending enabling ebpf and or pretty much any of the other "enable" options. They are disabled by default for a reason

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I derived these "enable" options from the packages installed in the previous Recommend dependencies section. As a user, I would be clueless as to why the recommended packages are recommended and what to configure as a next step. This configure step enables most of the "good stuff" that Suricata offers. If you disagree, what would you like me to do?

  1. remove altogether
  2. Reword "recommended parameters" to "possible configure parameters"

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@victorjulien do you have any preference? I would personally opt for the second option.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't think this section should really change.

What would likely be nice is a section on "build options" where these are covered, and what new dependencies they might bring in. A bigger job, but more useful.

Possible example, but a bit verbose: https://nginx.org/en/docs/configure.html

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Created a ticket: https://redmine.openinfosecfoundation.org/issues/6824

--enable-dpdk --enable-http2-decompression --enable-unix-socket \
--enable-af-packet --enable-libmagic --enable-lua --enable-geoip \
--enable-hiredis
make -j8 # j is for simultaneous compilation, number can be de/increased based on your CPU
make install # to install your Suricata compiled binary
# make install-full - installs configuration and rulesets as well

Rust support
""""""""""""

Rust packages can be found in package managers but some distros
don't provide or provide outdated Rust packages.
In case of insufficient version you can install Rust directly
from the Rust project itself::

1) Install Rust https://www.rust-lang.org/en-US/install.html
2) Install cbindgen - if the cbindgen is not found in the repository
or the cbindgen version is lower than required, it can be
alternatively installed as: cargo install --force cbindgen
3) Make sure the cargo path is within your PATH environment
e.g. echo 'export PATH=”${PATH}:~/.cargo/bin”' >> ~/.bashrc
e.g. export PATH="${PATH}:~/.cargo/bin"

Auto-Setup
^^^^^^^^^^
Expand Down