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

Update documentation on xdp_tests #1403

Merged
merged 4 commits into from
Sep 20, 2022
Merged

Update documentation on xdp_tests #1403

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
73826ab
doc changes.
shankarseal Sep 19, 2022
5df44b8
PR Feedback.
shankarseal Sep 20, 2022
d8fa23d
PR Feedback.
shankarseal Sep 20, 2022
84e4530
Merge branch 'main' into fix_xdp_test_documentation
dthaler Sep 20, 2022
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
41 changes: 34 additions & 7 deletions docs/GettingStarted.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -252,12 +252,39 @@ Other useful options include:
4. `Test_name` to run a single test

### xdp_tests.exe
This application tests various XDP functionalities. It has the following tests:
1. Reflection Test: This tests the XDP_TX functionality. The following steps show how to run the test:
1. On the system under test, install eBPF binaries (`.\scripts\setup-ebpf.ps1`).
2. Load the test eBPF program by running the following commands: `netsh`, `ebpf`, `add program reflect_packet.o xdp` and note the ID.
3. From a remote host, run xdp_tests.exe and in `--remote-ip` parameter pass an IPv4 or IPv6 address of an Ethernet-like interface on the system under test in string format.
4. Unload the program from system under test by running `delete program <id>` on the netsh prompt, where <id> is the ID noted above.
This application tests various XDP functionalities. These tests require two hosts to run. There are three variations of the XDP tests.

#### Reflection Test
This tests the XDP_TX functionality.
1. On the first host:
1. [Install eBPF for Windows](https://github.com/microsoft/ebpf-for-windows/blob/main/docs/InstallEbpf.md).
2. Load the test eBPF program by running the following command: `netsh ebpf add program reflect_packet.o xdp` and note the ID. See **Note 3** below.
2. On the second host:
1. Allow inbound traffic for `xdp_tests.exe` through Windows Defender Firewall. See **Note 1** below.
2. Run `xdp_tests.exe xdp_reflect_test --remote_ip <IP on the first host>`. See **Note 2** below.

#### Encapsulation Test
This uses `bpf_xdp_adjust_head` helper function to encapsulate an outer IP header to a packet.
1. On the first host:
1. [Install eBPF for Windows](https://github.com/microsoft/ebpf-for-windows/blob/main/docs/InstallEbpf.md).
2. Load the test eBPF program by running the following command: `netsh ebpf add program encap_reflect_packet.o xdp` and note the ID. See **Note 3** below.
2. On the second host:
1. Allow inbound traffic for `xdp_tests.exe` through Windows Defender Firewall. See **Note 1** below.
2. Run `xdp_tests.exe xdp_encap_reflect_test --remote_ip <IP on the first host>`. See **Note 2** below.

#### Decapsulation Test
This uses `bpf_xdp_adjust_head` helper function to decapsulate an outer IP header from a packet.
1. On *both* the hosts, [install eBPF for Windows](https://github.com/microsoft/ebpf-for-windows/blob/main/docs/InstallEbpf.md).
2. On the first host load the first test eBPF program by running the following command: `netsh ebpf add program encap_reflect_packet.o xdp` and note the ID. See **Note 3** below.
3. On the second host:
1. Load the second test eBPF program by running the following command: `netsh ebpf add program decap_permit_packet.o xdp` and note the ID. See **Note 3** below.
2. Allow inbound traffic for `xdp_tests.exe` through Windows Defender Firewall. See **Note 1** below.
3. Run `xdp_tests.exe xdp_reflect_test --remote_ip <IP on the first host>`. See **Note 2** below.

**Note 1:** To allow inbound traffic to `xdp_tests.exe`, in a Windows Powershell with administrative privilege, run `New-NetFirewallRule -DisplayName "XDP_Test" -Program "<Full path to xdp_tests.exe>" -Direction Inbound -Action Allow`.<br>
**Note 2:** For the `--remote-ip` parameter to `xdp_tests.exe` program that is run on the second host, pass an IPv4 or IPv6 address of an Ethernet-like interface on the first host in string format.<br>
**Note 3:** After completion of each test variation, unload the eBPF programs from both host machines by running `delete program <id>` on the netsh prompt, where `<id>` is the ID noted when the eBPF programs were loaded.<br>
shankarseal marked this conversation as resolved.
Show resolved Hide resolved
***Advanced:*** The eBPF program can be attached to a specific interface by passing `interface=<IfIndex>` parameter either to the netsh `add program` or `set program` commands.

### socket_tests.exe
This application loads the `cgroup_sock_addr.o` eBPF program and attaches to hooks to handle various socket operations. Currently it tests authorizing ingress and egress connections based on entries in a map passed to the program.
Expand All @@ -275,7 +302,7 @@ To capture a trace in a file use the following commands:

### Viewing traces in real-time
To view traces in real-time, the `tracelog.exe` and `tracefmt.exe` commands from the WDK can be used.
If you are running eBPF for Windows in a VM, you can either install the full WDK in the VM (see the Prequisites
If you are running eBPF for Windows in a VM, you can either install the full WDK in the VM (see the Prerequisites
section above) or just copy the two executables into the VM.

To view all eBPF trace events that would be captured to a file, use the following commands:
Expand Down