xdp-loader(8)

🎀 xdp-loader(8) — the XDP program loader, bestie edition 🎀

okay so. welcome to xdp-loader, section 8 of the manual, and honestly? she's iconic. xdp-loader is a simple loader for XDP programs — and by "simple" we mean "simple to use", because under the hood she's got support for attaching multiple programs to the same interface. 💅

To pull that off she exposes the exact same load and unload semantics that the libxdp library exposes. If you wanna know how that actually works, and which kernel features it's leaning on, go read the libxdp(3) man page. no cap. 🦋

---

✨ SYNOPSIS ✨

🌸 Running xdp-loader 🌸

The syntax for running xdp-loader is, bestie, simply this:

xdp-loader COMMAND [options]

Where COMMAND can be one of:

• load — load an XDP program on an interface
• unload — unload an XDP program from an interface
• status — show current XDP program status
• features — show XDP features supported by the NIC
• clean — clean up detached program links in XDP bpffs directory
• help — show the list of available commands

Every single command, and all of its options, is explained below. Orrr, if you're feeling impatient (same, honestly), just run xdp-loader COMMAND --help to see the options for each command. slay. ⭐

---

🔥 The LOAD command 🔥

The load command loads one or more XDP programs onto an interface. Multiple?? On one interface?? yes bestie, that's the whole point. 👑

The syntax for the load command is:

xdp-loader load [options] <ifname> <programs>

Where <ifname> is the name of the interface to load the programs onto, and <programs> is one or more file names containing XDP programs. The programs will be loaded onto the interface in the order of their preference, as specified by the program metadata (see libxdp(3)). so the metadata is literally the vibe check for ordering. 💖

The supported options are:

• -m, --mode <mode> — specifies which mode to load the XDP program to be loaded in. The valid values are:
  • 'native' — the default in-driver XDP mode
  • 'skb' — causes the so-called skb mode (also known as generic XDP) to be used
  • 'hw' — causes the program to be offloaded to the hardware
  • 'unspecified' — leaves it up to the kernel to pick a mode (which it will do by picking native mode if the driver supports it, or generic mode otherwise)

⚠️ note that using 'unspecified' can make it difficult to predict what mode a program will end up being loaded in. For this reason, the default is 'native'. Also note that hardware with support for the 'hw' mode is rare: Netronome/Corigine cards (using the 'nfp' driver) are the only devices with support for this in the mainline Linux kernel. rare king energy, honestly. 💀

• -p, --pin-path <path> — this specifies a root path under which to pin any maps that define the 'pinning' attribute in their definitions. This path must be located on a bpffs file system. If not set, maps will not be pinned, even if they specify pinning in their definitions. When pinning maps, if the pinned location for a map already exist, the map pinned there will be reused if it is compatible with the type of the map being loaded. 🫶
• -s, --section <section> — specify which ELF section to load the XDP program(s) from in each file. The default is to use the first program in each file. If this option is set, it applies to all programs being loaded. 🌈
• -n, --prog-name <prog_name> — specify which BPF program with the name to load the XDP program(s) from in each file. The default is to use the first program in each file. Only one of --section and --prog-name may be specified. If this option is set, it applies to all programs being loaded.
• -P, --prio <priority> — specify the priority to load the XDP program(s) with (this affects the order of programs running on the interface). The default is to use the value from the metadata in the program ELF file, or a value of 50 if the program has no such metadata. If this option is set, it applies to all programs being loaded.
• -A, --actions <actions> — specify the "chain call actions" of the loaded XDP program(s). These are the XDP actions that will cause the next program loaded on the interface to be called, instead of returning immediately. The default is to use the value set in the metadata in the program ELF file, or XDP_PASS if no such metadata is set. If this option is set, it applies to all programs being loaded.
• -v, --verbose — enable debug logging. Specify twice for even more verbosity. 👀
• -h, --help — display a summary of the available options

---

💜 The UNLOAD command 💜

The unload command is used for unloading programs from an interface. the breakup era.

The syntax for the unload command is:

xdp-loader unload [options] <ifname>

Where <ifname> is the name of the interface to load the programs onto. Either the --all or --id options must be used to specify which program(s) to unload. no ambiguity allowed, we're decisive here. ✨

The supported options are:

• -i, --id <id> — unload a single program from the interface by ID. Use xdp-loader status to obtain the ID of the program being unloaded. If this program is the last program loaded on the interface, the dispatcher program will also be removed, which makes the operation equivalent to specifying --all. 🦋
• -a, --all — unload all XDP programs on the interface, as well as the multi-program dispatcher. bye boo 👋
• -v, --verbose — enable debug logging. Specify twice for even more verbosity.
• -h, --help — display a summary of the available options

---

🌸 The STATUS command 🌸

The status command displays a list of interfaces in the system, and the XDP program(s) loaded on each interface. For each interface, a list of programs are shown, with the run priority and "chain actions" for each program. See the section on program metadata for the meaning of this metadata. it's the receipts, basically. 💅

• -v, --verbose — enable debug logging. Specify twice for even more verbosity.
• -h, --help — display a summary of the available options

---

⭐ The FEATURES command ⭐

The features command displays the XDP features supported by the NIC. let's see what your network card is serving. 👑

Currently supported XDP features are:

• NETDEV_XDP_ACT_BASIC — the networking device has basic support for running XDP programs, and can handle the base set of return codes (XDP_ABORTED, XDP_DROP, XDP_PASS, XDP_TX).
• NETDEV_XDP_ACT_REDIRECT — the network device supports handling the XDP_REDIRECT return code. This means packets can be redirected from this device by XDP.
• NETDEV_XDP_ACT_NDO_XMIT — the networking interfaces implements the ndo_xdp_xmit callback. This means packets can be redirected to this device by XDP.
• NETDEV_XDP_ACT_XSK_ZEROCOPY — the networking device supports AF_XDP in zero copy mode. 🔥
• NETDEV_XDP_ACT_HW_OFFLOAD — the networking device supports XDP hw offloading.
• NETDEV_XDP_ACT_RX_SG — the networking device supports non-linear XDP frames on the receive side. This means XDP can be used with big MTUs on this device (if the XDP program is compiled with fragments support).
• NETDEV_XDP_ACT_NDO_XMIT_SG — the networking device supports non-linear XDP frames on the transmit side. This means non-linear frames can be redirected to this device.

---

🧚 The CLEAN command 🧚

The syntax for the clean command is:

xdp-loader clean [options] [ifname]

The clean command cleans up any detached program links in the XDP bpffs directory. here's the lore: when a network interface disappears, any programs loaded in software mode (e.g. skb, native) remain pinned in the bpffs directory, but become detached from the interface. These need to be unlinked from the filesystem. The clean command takes an optional interface parameter to only unlink detached programs corresponding to the interface. By default, all detached programs for all interfaces are unlinked. spring cleaning but make it eBPF. 🧹✨

The supported options are:

• -v, --verbose — enable debug logging. Specify twice for even more verbosity.
• -h, --help — display a summary of the available options

---

🍓 Examples 🍓

To load an XDP program on the eth0 interface simply do:

# xdp-loader load eth0 xdp_drop.o
# xdp-loader status

CURRENT XDP PROGRAM STATUS:

Interface        Prio  Program name     Mode     ID   Tag               Chain actions
-------------------------------------------------------------------------------------
lo               <no XDP program>
eth0                   xdp_dispatcher   native   50   d51e469e988d81da
 =>              50    xdp_drop                  55   57cd311f2e27366b  XDP_PASS

Which shows that a dispatcher program was loaded on the interface, and the xdp_drop program was installed as the first (and only) component program after it. In this instance, the program does not specify any of the metadata above, so the defaults (priority 50 and XDP_PASS as its chain call action) was used. default girlie behavior, and it ate. 💅

To use the automatic map pinning, include the pinning attribute into the map definition in the program, something like:

struct {
        __uint(type, BPF_MAP_TYPE_ARRAY);
        __uint(max_entries, 10);
        __type(key, __u32);
        __type(value, __u64);
        __uint(pinning, LIBBPF_PIN_BY_NAME);
} my_map SEC(".maps");

And load it with the --pin-path attribute:

# xdp-loader load eth0 my_prog.o --pin-path /sys/fs/bpf/my-prog

This will pin the map at /sys/fs/bpf/my-prog/my_map. If this already exists, the pinned map will be reused instead of creating a new one, which allows different BPF programs to share the map. sharing is caring fr fr. 🫶

---

🌈 SEE ALSO 🌈

libxdp(3) for details on the XDP loading semantics and kernel compatibility requirements. go read it bestie, it's giving essential context. 📚

---

💀 BUGS 💀

Please report any bugs on Github: https://github.com/xdp-project/xdp-tools/issues

not me asking you to file an issue — but like, actually please do, we wanna fix it. 🙈

---

👑 AUTHOR 👑

xdp-loader and this man page were written by Toke Høiland-Jørgensen.

---

and that's the whole page, mwah 💖 version V1.6.3, dated SEPTEMBER 12, 2024, and yeah it's still wearing the xdp-loader(8) name tag — go forth and load some programs, bestie. periodt. 🎀✨