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

doc: update eBPF/compilation instructions v2 #10560

Closed
wants to merge 2 commits into from
Closed

doc: update eBPF/compilation instructions v2 #10560

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
d8d784a
doc: update eBPF compilation instructions
Jan 16, 2024
5c13ec7
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.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 10 additions & 6 deletions doc/userguide/capture-hardware/ebpf-xdp.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
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
Copy link
Contributor

Choose a reason for hiding this comment

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

I'm not sure what you're saying here ... may miss some i386 headers (as eBPF is not x86_64).

Does may miss mean will miss or may or may not?

Suggest "If your platform is x86_64, install architecture specific headers``

Copy link
Contributor Author

@lukashino lukashino Mar 2, 2024 •
edited
Loading

Choose a reason for hiding this comment

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

I derived this from the original doc. The original docs also mention Some i386 headers will also be needed as eBPF is not x86_64 and some included headers are architecture specific. In your suggested version, by architecure-specific headers I would assume that I need to install x86_64 headers and not i386.

With that may miss I wanted to say that it might be possible that the compilation will complain about missing i386 headers - I actually didn't need any of that but left it there just to be sure...

Copy link
Contributor

@jufajardini jufajardini Mar 6, 2024 •
edited
Loading

Choose a reason for hiding this comment

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

Would:
"As eBPF is not x86_64, your installation might miss some i386 headers that are architecture-specific.::"
Work?

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 honestly think we don't need this here at all unless you can think of some scenario where we might.
Do you have any opinion on this @victorjulien @jasonish

Copy link
Member

Choose a reason for hiding this comment

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

I'm not familiar enough with this to comment. I do know I just have to install the ebpf-devel packages on RHEL based systems to build with ebpf support, but that might not cover the individual ebpf programs.

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
105 changes: 49 additions & 56 deletions doc/userguide/install.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
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
Comment on lines +74 to +76
Copy link
Contributor

Choose a reason for hiding this comment

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

I noticed that this doesn't list either gcc or clang, which are indicated as required in a paragraph that was removed. Is that alright?

Copy link
Member

Choose a reason for hiding this comment

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

I think its a bit of an Ubuntu'ism to just install build-essential to get all that stuff rather than breaking it out.


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,54 @@ one of the following ways::

Minimal::

# Installed Rust and cargo as indicated above
Copy link
Contributor

Choose a reason for hiding this comment

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

Why remove this part?

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Because there is no guide for Rust and Cargo install above this. It has been moved to the bottom of the guide in case rustc and cargo is not part of the package manager.

Copy link
Member

Choose a reason for hiding this comment

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

Do we know if this is the case for any distros or OSs? And could it be reduced to a single line, a link to Rust install page? This would most likely be a rare type install that we probably shouldn't try to cover.

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 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
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
Loading