1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
|
# Requirements
These tests are done for Ubuntu and Debian distros. Please use latest stable Debian or Ubuntu to run the tests.
The commands in this guide require CMake/CTest 3.20 or newer, including
`ctest --test-dir`. The standalone kernel-module installation script requires
CMake 3.15 or newer for `cmake --install`. These command requirements are
separate from the project's minimum CMake version of 3.10.
## Focused unit tests
The standalone unit tests compile production callbacks with small test fixtures
and run them with AddressSanitizer and UndefinedBehaviorSanitizer. Pass a configured
CMake build directory and optional test names:
```bash
sh tests/unit/run_safeguards.sh build log_line
```
These tests do not require installed kernel modules or root privileges. The
sanitizer runtime needs an environment that permits its process inspection.
The runner has six suites: `dhcpv6`, `radius`, `vrf`, `lcp`, `mempool`, and
`log_line`. With no names it runs all six:
```bash
sh tests/unit/run_safeguards.sh build
```
The DHCPv6 suite checks bounded DNS replies and failure propagation when
non-truncatable options exhaust reply space. The
[integration validation record](../docs/ng40-safeguards-review.md#validation)
describes results from the revision at which those safeguards were introduced.
## Kernel module installation test
The kernel module installation regression test is rootless and does not need
kernel headers. It uses a fake kernel build tree to verify that `ipoe`,
`vlan_mon`, and `ppposeq` are installed from their actual build directories,
honor `DESTDIR`, and make installation fail when `modules_install` fails.
It also verifies that Debian and CentOS packaging configurations include
`ppposeq.ko` with the standalone driver package name, and omit it when the
build flag is disabled.
Run it through CTest after configuring the project:
```bash
ctest --test-dir build --output-on-failure -R '^kernel-module-install$'
```
It can also be run directly from the repository root:
```bash
sh tests/kernel-module-install/test.sh cmake
```
## Preparations
Install pytest and its plugins from the distribution packages:
```bash
sudo apt install python3-pytest python3-pytest-dependency python3-pytest-order
```
pytest-dependency version must be >= 0.5 (with 'scope' support)
The network/session tests run under sudo, so the plugins must be available to
the system Python interpreter used by `sudo python3`.
Install additional tools required for tests:
```bash
sudo apt install iproute2 ppp pppoe isc-dhcp-client
```
Install the build dependencies described in the project README, including
kernel headers and Lua 5.1 development files (`liblua5.1-0-dev` on Debian and
Ubuntu) for `LUA=TRUE` below. Run these
commands from the repository root.
Install accel-pppd (make install or use distro package). Do not run accel-pppd using systemd or other supervisors
```bash
cmake -S . -B build \
-DBUILD_IPOE_DRIVER=TRUE -DBUILD_VLAN_MON_DRIVER=TRUE \
-DCMAKE_INSTALL_PREFIX=/usr -DCMAKE_INSTALL_SYSCONFDIR=/etc \
-DCMAKE_INSTALL_LOCALSTATEDIR=/var \
-DKDIR="/usr/src/linux-headers-$(uname -r)" \
-DLUA=TRUE -DSHAPER=TRUE -DRADIUS=TRUE
cmake --build build
sudo cmake --install build
```
For a package-based installation on Ubuntu 24.04, configure the matching
package dependencies before building the DEB:
```bash
cmake -S . -B build -DCPACK_TYPE=Ubuntu24
cpack --config build/CPackConfig.cmake -G DEB -B build
sudo dpkg -i build/accel-ppp.deb
```
Use `Ubuntu22`, `Debian12`, or `Debian13` when building for those releases.
Do not use `Ubuntu20` for a newer distribution: it declares dependencies on
older libraries, including `libssl1.1`.
Load the kernel modules from the repository root after either installation method:
```bash
sudo insmod build/drivers/vlan_mon/driver/vlan_mon.ko
sudo insmod build/drivers/ipoe/driver/ipoe.ko
```
## Run tests (without coverage)
```bash
# from this dir (tests)
sudo python3 -m pytest -Wall --order-dependencies -v
```
To skip tests related to ipoe and vlan_mon kernel modules:
```bash
# from this dir (tests)
sudo python3 -m pytest -Wall --order-dependencies -v -m "not ipoe_driver and not vlan_mon_driver"
```
## Preparations (for coverage report)
Perform preparation steps for running tests without coverage
Install gcovr
Using apt:
```bash
sudo apt install gcovr
```
```bash
# from root dir
cmake -S . -B build \
-DBUILD_IPOE_DRIVER=TRUE -DBUILD_VLAN_MON_DRIVER=TRUE \
-DCMAKE_INSTALL_PREFIX=/usr -DCMAKE_INSTALL_SYSCONFDIR=/etc \
-DCMAKE_INSTALL_LOCALSTATEDIR=/var \
-DKDIR="/usr/src/linux-headers-$(uname -r)" \
-DLUA=TRUE -DSHAPER=TRUE -DRADIUS=TRUE \
-DCMAKE_C_FLAGS="--coverage -O0"
cmake --build build
sudo cmake --install build
```
Then insert kernel modules (ipoe.ko and vlan-mon.ko)
## Run tests and generate coverage report
```bash
# from root dir (parent for this dir)
sudo python3 -m pytest -Wall --order-dependencies tests -v # execute tests to collect coverage data
mkdir tests/report
gcovr --config=tests/gcovr.conf # default report
gcovr --config=tests/gcovr.conf --csv # csv report
gcovr --config=tests/gcovr.conf --html --html-details --output=tests/report/accel-ppp.html # html reports (most useful)
```
(If `gcovr` command does not exist, use `python3 -m gcovr` instead)
## Remove coverage data
If you want to re-run tests 'from scratch', you may want to remove coverage data. To do this:
```bash
# from root dir (parent for this dir)
sudo gcovr -d # build report and delete
sudo gcovr -d # check that data is deleted (any coverage = 0%)
```
|
