NAME¶

xdp-loader - an XDP program loader

SYNOPSIS¶

XDP-loader is a simple loader for XDP programs with support for attaching multiple programs to the same interface. To achieve this it exposes the same load and unload semantics exposed by the libxdp library. See the libxdp(3) man page for details of how this works, and what kernel features it relies on.

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


       clean       - clean up detached program links in XDP bpffs directory


       help        - show the list of available commands

The LOAD command¶

The load command loads one or more XDP programs onto an interface.

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 the <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)).

The supported options are:

The UNLOAD command¶

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

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.

The supported options are:

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.

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. 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.

The supported options are:

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.

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.

SEE ALSO¶

libxdp(3) for details on the XDP loading semantics and kernel compatibility requirements.

BUGS¶

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

AUTHOR¶

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