Reference docker containers with all dependencies needed to develop ebpfguard.
4
+
5
+
This instruction assumes that docker is installed. For convenience you can add your user to docker group.
6
+
The following script checks whether current user is in docker group.
7
+
8
+
``` bash
9
+
$ groups | grep docker 1>/dev/null 2>&1 || echo "$USER is not in docker group. docker command will require sudo"
10
+
```
11
+
12
+
## Ubuntu
13
+
14
+
To build ubuntu based development docker image run the following `docker build` command.
15
+
16
+
```bash
17
+
$ pwd
18
+
<path to ebpfguard repo>/docker
19
+
$ cd ubuntu
20
+
$ docker build . -t ebpfguard-dev:local
21
+
```
22
+
23
+
After building you can start a container with this repository mounted into it and run compilation steps. Proposed `docker run` invocation doesn't copy repository contents. Changes made within container will be present on host machine.
24
+
25
+
```bash
26
+
# privileged flag is needed to run ebpfguard applications from within container
27
+
$ docker run -it --privileged -v <path to this repository on local filesystem>:/app ebpfguard-dev:local bash
28
+
# Previous command drops user into bash shell within container
29
+
$ cd app
30
+
$ cargo xtask build-ebpf && cargo build && cargo test
31
+
```
32
+
33
+
Lets assume that ebpfguard repository was cloned to `/home/user/ebpfguard`.
34
+
35
+
Docker run command would be:
36
+
```bash
37
+
$ docker run -it --privileged -v /home/user/ebpfguard:/app ebpfguard-dev:local bash
This doc describes characteristics that your system needs to run ebpfguard based applications.
4
+
5
+
[Kernel capabilites](#kernel-capabilities) section is required both for compilation and execution. Other sections are needed only for development.
6
+
7
+
For development purposes you can either install dependencies from [tools/packages](#toolspackages) and [rust toolchain](#rust-toolchain) sections or use [docker based development environment](docker_devel_env.md).
8
+
3
9
## kernel capabilities
10
+
11
+
Kernel capabilities outlined in this section are required for both execution and development.
4
12
5
13
First, you need to have a Linux kernel:
6
14
* with BTF support
skipped 25 lines
32
40
```
33
41
34
42
If the output doesn't contain `bpf`, you need to enable BPF LSM by adding
35
-
`lsm=[...],bpf` to your kernel config parameters.Thatcanbeachievedby
36
-
executing the [enable-bpf-lsm.py](https://github.com/deepfence/ebpfguard/blob/main/enable-bpf-lsm.py) script.
43
+
`lsm=[...],bpf` to your kernel config parameters.
37
44
38
-
This script will print modified contents of `/etc/default/grub` file to stdout.
39
-
Either pipe it back directly to `/etc/default/grub` or save it somewhere
40
-
and compare contents before swapping to a new version.
45
+
Be warned that changes to grub and/or kernel config parameters may result
46
+
in kernel panic at startup. It is strongly encouraged to make backups of
47
+
all files altered in this section.
48
+
49
+
Kernel parameter modification can be achieved using [enable-bpf-lsm.py](https://github.com/deepfence/ebpfguard/blob/main/enable-bpf-lsm.py) script.
50
+
This script will read contents of `/etc/default/grub`, add lsm section of kernel
51
+
parameters with `bpf` option appended to `GRUB_CMDLINE_LINUX_DEFAULT` and print
52
+
modified contents to its stdout.
53
+
54
+
Either pipe it back directly to `/etc/default/grub` or save it as a separate file
55
+
and compare contents before swapping to a modified version.
56
+
57
+
Note that script solution is not bulletproof. If your grub configuration is customized it is encouraged to inspect script contents/output and do changes manually.
41
58
42
59
Whole command with direct pipe:
43
60
44
61
```bash
45
-
$ ./enable-bpf.lsm.py | sudo tee /etc/default/grub 1>/dev/null
62
+
$ sudo cp /etc/default/grub{,.bak} && \
63
+
./enable-bpf.lsm.py | sudo tee /etc/default/grub 1>/dev/null
46
64
```
47
65
48
-
This file is used by grub2 to assemble final `grub.cfg`. To trigger reconfiguration
49
-
use grub's mkconfig command with `-o <path to grub.cfg>` switch.
50
-
51
-
Both command name and path to `grub.cfg` are distribution dependent.
66
+
`/etc/default/grub` file is not used directly by grub2. It is used as a parameter source to assemble final configuration file. Path of a final configuration file as well as command which assembles it are distribution dependent.
You need the Rust stable and nightly toolchains installed on your system, bpf-linker and bpftool binary.
80
129
81
-
```
82
-
$ rustup component add miri --toolchain nightly
130
+
Install rust from https://rustup.rs. Further commands assume availability of rustup command.
131
+
132
+
Install bindgen-cli:
133
+
134
+
```bash
135
+
$ cargo install bindgen-cli
83
136
```
84
137
85
-
Finallyinstall bpf-linker:
138
+
Install bpf-linker:
86
139
87
140
```
88
141
$ cargo install bpf-linker
89
142
```
90
143
91
-
This bpf-linker installation method works on linux x86_64 systems.
92
-
For others refer to [aya-rs documentation](https://aya-rs.dev/book/start/development/).
144
+
bpf-linker installation on architectures other than x86_64 may be more involved. Refer to [aya-rs documentation](https://aya-rs.dev/book/start/development/) for instructions.
93
145
94
-
To install bpftool either use distro provided package or build it from [source](https://github.com/libbpf/bpftool).
146
+
### miri
147
+
148
+
As a part of ebpfguard CI pipeline we test for undefined behaviors using [miri](https://github.com/rust-lang/miri).
149
+
To run such tests rust nightly toolchain with miri component is needed.
95
150
96
-
On ubuntu it is a part of linux-tools:
151
+
To install nightly toolchain and miri in it run the following command:
Tomasz Jonak
committed
with
GitHub
1 year ago