STRLCPY/ebpfguard

Readme: extract prerequisites and development to separate doc files
Tomasz Jonak committed 1 year ago

2cad8332

1 parent 12ca746b

■ ■ ■ ■ ■ ■

README.md

		skipped 86 lines
87	87
88	88		## Prerequisites
89	89
90		-	### kernel capabilities
91		-
92		-	First, you need to have a Linux kernel:
93		-	* with BTF support
94		-	* with BPF LSM support (kernels >= 5.7)
95		-
96		-	You can check if your kernel has BTF support by checking whether file
97		-	`/sys/kernel/btf/vmlinux` exists. You can also check the kernel configuration:
98		-
99		-	```bash
100		-	$ zgrep CONFIG_DEBUG_INFO_BTF /proc/config.gz
101		-	CONFIG_DEBUG_INFO_BTF=y
102		-	```
103		-
104		-	Next, you need to check if your kernel has BPF LSM support:
105		-
106		-	```bash
107		-	$ cat /sys/kernel/security/lsm
108		-	lockdown,capability,selinux,bpf
109		-	```
110		-
111		-	If the output doesn't contain `bpf`, you need to enable BPF LSM by adding
112		-	`lsm=[...],bpf` to your kernel config parameters. That can be achieved by
113		-	executing the [enable-bpf-lsm.py](https://github.com/deepfence/ebpfguard/blob/main/enable-bpf-lsm.py.py) script.
114		-
115		-	This script will print modified contents of `/etc/default/grub` file to stdout.
116		-	Either pipe it back directly to `/etc/default/grub` or save it somewhere
117		-	and compare contents before swapping to a new version.
118		-
119		-	Whole command with direct pipe:
120		-
121		-	```bash
122		-	$ ./enable-bpf.lsm.py \| sudo tee /etc/default/grub 1>/dev/null
123		-	```
124		-
125		-	This file is used by grub2 to assemble final `grub.cfg`. To trigger reconfiguration
126		-	use grub's mkconfig command with `-o <path to grub.cfg>` switch.
127		-
128		-	Both command name and path to `grub.cfg` are distribution dependent.
129		-
130		-	On ubuntu:
131		-
132		-	```
133		-	$ sudo grub-mkconfig -o /boot/grub/grub.cfg
134		-	```
135		-
136		-	On fedora:
137		-
138		-	```
139		-	$ sudo grub2-mkconfig -o /boot/grub2/grub.cfg
140		-	```
141		-
142		-	After that's done reboot your system.
143		-
144		-	### rust toolchain and packages
145		-
146		-	You need the Rust stable and nightly toolchains installed on your system, bpf-linker and bpftool binary.
147		-
148		-	Install nightly toolchain:
149		-
150		-	```
151		-	$ rustup toolchain install nightly --component rust-src
152		-	```
153		-
154		-	Optionally add miri:
155		-
156		-	```
157		-	$ rustup component add miri --toolchain nightly
158		-	```
159		-
160		-	Finally install bpf-linker:
161		-
162		-	```
163		-	$ cargo install bpf-linker
164		-	```
165		-
166		-	This bpf-linker installation method works on linux x86_64 systems.
167		-	For others refer to [aya-rs documentation](https://aya-rs.dev/book/start/development/).
168		-
169		-	To install bpftool either use distro provided package or build it from [source](https://github.com/libbpf/bpftool).
170		-
171		-	On ubuntu it is a part of linux-tools:
172		-
173		-	```
174		-	$ sudo apt install linux-tools-$(uname -r)
175		-	```
	90	+	Check [PREREQUISISTES.md](doc/PREREQUISISTES.md) to set up your environment.
176	91
177	92		## Development
178	93
179		-	All commands should be executed from repository/workspace root folder unless noted otherwise.
180		-
181		-	### Compilation
182		-
183		-	First compile ebpf bytecode with the following command. It will be embedded
184		-	in userspace binary using aya.
185		-
186		-	```
187		-	$ cargo xtask build-ebpf
188		-	```
189		-
190		-	Then userspace code.
191		-
192		-	```
193		-	$ cargo build
194		-	```
195		-
196		-	### Tests
197		-
198		-	Commands in this subsection mirror state of CI pipeline.
199		-
200		-	Regular tests
201		-
202		-	```
203		-	$ cargo test
204		-	```
205		-
206		-	Formatting gateway. Drop check subflag to autoformat.
207		-
208		-	```
209		-	$ cargo fmt --all -- --check
210		-	```
211		-
212		-	Clippy lints.
213		-
214		-	```
215		-	$ cargo clippy --workspace -- --deny warnings
216		-	```
217		-
218		-	Miri verification.
219		-
220		-	```
221		-	$ cargo +nightly miri test --all-targets
222		-	```
223		-
224		-	Note that miri verification requires nightly toolchain as well as miri component. To add them execute:
225		-
226		-	```
227		-	$ rustup toolchain install nightly --component rust-src
228		-	$ rustup component add miri --toolchain nightly
229		-	```
	94	+	Check [Development.md](doc/DEVELOPMENT.md) for compillation and testing commands.
230	95
231	96		## Get in touch
232	97
		skipped 17 lines

■ ■ ■ ■ ■ ■

doc/DEVELOPMENT.md

1	+
2	+	# Development
3	+
4	+	All commands should be executed from repository/workspace root folder unless noted otherwise.
5	+
6	+	## Compilation
7	+
8	+	First compile ebpf bytecode with the following command. It will be embedded
9	+	in userspace binary using aya.
10	+
11	+	```
12	+	$ cargo xtask build-ebpf
13	+	```
14	+
15	+	Then userspace code.
16	+
17	+	```
18	+	$ cargo build
19	+	```
20	+
21	+	## Tests
22	+
23	+	Commands in this subsection mirror state of CI pipeline.
24	+
25	+	Regular tests
26	+
27	+	```
28	+	$ cargo test
29	+	```
30	+
31	+	Formatting gateway. Drop check subflag to autoformat.
32	+
33	+	```
34	+	$ cargo fmt --all -- --check
35	+	```
36	+
37	+	Clippy lints.
38	+
39	+	```
40	+	$ cargo clippy --workspace -- --deny warnings
41	+	```
42	+
43	+	Miri verification.
44	+
45	+	```
46	+	$ cargo +nightly miri test --all-targets
47	+	```
48	+
49	+	Note that miri verification requires nightly toolchain as well as miri component. To add them execute:
50	+
51	+	```
52	+	$ rustup toolchain install nightly --component rust-src
53	+	$ rustup component add miri --toolchain nightly
54	+	```
55	+

■ ■ ■ ■ ■ ■

doc/PREREQUISISTES.md

1	+	# Prerequisites
2	+
3	+	## kernel capabilities
4	+
5	+	First, you need to have a Linux kernel:
6	+	* with BTF support
7	+	* with BPF LSM support (kernels >= 5.7)
8	+
9	+	You can check if your kernel has BTF support by checking whether file
10	+	`/sys/kernel/btf/vmlinux` exists. You can also check the kernel configuration:
11	+
12	+	```bash
13	+	$ zgrep CONFIG_DEBUG_INFO_BTF /proc/config.gz
14	+	CONFIG_DEBUG_INFO_BTF=y
15	+	```
16	+
17	+	Next, you need to check if your kernel has BPF LSM support:
18	+
19	+	```bash
20	+	$ cat /sys/kernel/security/lsm
21	+	lockdown,capability,selinux,bpf
22	+	```
23	+
24	+	If the output doesn't contain `bpf`, you need to enable BPF LSM by adding
25	+	`lsm=[...],bpf` to your kernel config parameters. That can be achieved by
26	+	executing the [enable-bpf-lsm.py](https://github.com/deepfence/ebpfguard/blob/main/enable-bpf-lsm.py.py) script.
27	+
28	+	This script will print modified contents of `/etc/default/grub` file to stdout.
29	+	Either pipe it back directly to `/etc/default/grub` or save it somewhere
30	+	and compare contents before swapping to a new version.
31	+
32	+	Whole command with direct pipe:
33	+
34	+	```bash
35	+	$ ./enable-bpf.lsm.py \| sudo tee /etc/default/grub 1>/dev/null
36	+	```
37	+
38	+	This file is used by grub2 to assemble final `grub.cfg`. To trigger reconfiguration
39	+	use grub's mkconfig command with `-o <path to grub.cfg>` switch.
40	+
41	+	Both command name and path to `grub.cfg` are distribution dependent.
42	+
43	+	On ubuntu:
44	+
45	+	```
46	+	$ sudo grub-mkconfig -o /boot/grub/grub.cfg
47	+	```
48	+
49	+	On fedora:
50	+
51	+	```
52	+	$ sudo grub2-mkconfig -o /boot/grub2/grub.cfg
53	+	```
54	+
55	+	After that's done reboot your system.
56	+
57	+	## rust toolchain and packages
58	+
59	+	You need the Rust stable and nightly toolchains installed on your system, bpf-linker and bpftool binary.
60	+
61	+	Install nightly toolchain:
62	+
63	+	```
64	+	$ rustup toolchain install nightly --component rust-src
65	+	```
66	+
67	+	Optionally add miri:
68	+
69	+	```
70	+	$ rustup component add miri --toolchain nightly
71	+	```
72	+
73	+	Finally install bpf-linker:
74	+
75	+	```
76	+	$ cargo install bpf-linker
77	+	```
78	+
79	+	This bpf-linker installation method works on linux x86_64 systems.
80	+	For others refer to [aya-rs documentation](https://aya-rs.dev/book/start/development/).
81	+
82	+	To install bpftool either use distro provided package or build it from [source](https://github.com/libbpf/bpftool).
83	+
84	+	On ubuntu it is a part of linux-tools:
85	+
86	+	```
87	+	$ sudo apt install linux-tools-$(uname -r)
88	+	```
89	+

Readme: extract prerequisites and development to separate doc files