1 Using XDP/AF_XDP sockets 2 ======================== 3 4 .. 5 TODO: set version 6 Since version xxx, NSD has support for AF_XDP sockets. 7 8 AF_XDP sockets introduce a fast-path for network packets from the device driver 9 directly to user-space memory, bypassing the rest of the Linux network stack and 10 facilitating high packet-rate and bandwidth processing of network packetsDNS 11 queries (only via UDP) in our case. 12 13 Compiling NSD with XDP 14 ---------------------- 15 16 As this feature is experimental and introduces new dependencies to NSD, it needs 17 to be compiled in with ``--enable-xdp``. 18 19 The additional dependencies are: ``libxdp libbpf libcap clang llvm`` (and 20 ``gcc-multilib`` to fix a missing ``asm/types.h`` file, if you're on Ubuntu). 21 22 For Debian/Ubuntu based systems, you would install the dependencies as follows: 23 24 .. code-block:: bash 25 26 sudo apt install -y libxdp-dev libbpf-dev libcap-dev clang llvm gcc-multilib 27 28 When using the git source repository, make sure to also initialize the 29 submodules and auxilary files: 30 31 .. code-block:: bash 32 33 git clone https://github.com/NLnetLabs/nsd --branch features/af-xdp 34 cd nsd 35 git submodule update --init 36 autoreconf -fi 37 38 After installing the dependencies, you can build NSD: 39 40 .. code-block:: bash 41 42 ./configure --enable-xdp 43 make -j4 44 sudo make install 45 46 47 Configuring XDP 48 --------------- 49 50 The configuration options are described in `nsd.conf(5) <manpages/nsd.conf.html#xdp>`_. 51 52 By default, you can enable XDP for a single interface that supports it, with 53 the ``xdp-interface`` option: 54 55 .. code-block:: text 56 57 server: 58 xdp-interface: enp1s0 59 60 In this configuration, NSD will load and (after stopping NSD) unload its 61 bundled XDP program that redirects UDP traffic to port 53 directly to NSD 62 user-space. You usually don't have to do anything else. If it doesn't work, 63 check out the :ref:`its-not-working` section. 64 65 .. Note:: 66 67 Even though NSD uses libxdp, NSD skips the xdp-dispatcher. This is done so 68 that NSD can unload the XDP program itself when finished without requiring 69 the SYS_ADMIN capability (see `xdp-project/xdp-tools#432 70 <https://github.com/xdp-project/xdp-tools/pull/432>`_ and 71 `xdp-project/xdp-tools#434 72 <https://github.com/xdp-project/xdp-tools/issues/434>`_ on GitHub). 73 If you use multiple XDP programs on your system, please refer to 74 :ref:`load-bundled-xdp`, until we turn this into a config option. 75 76 Configuring XDP in special cases 77 -------------------------------- 78 79 If you have custom requirements for the use of XDP, e.g. because you want to 80 integrate NSD into you existing XDP setup, you have two options: 81 82 1. :ref:`load-bundled-xdp`, or 83 2. :ref:`custom-xdp`. 84 85 .. _load-bundled-xdp: 86 87 Loading the bundled XDP program yourself 88 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 89 90 NSD includes two XDP programs (in ``/usr/share/nsd/``, by default). You'll need 91 the file named ``xdp-dns-redirect_kern_pinned.o``. The two programs are 92 functionally identical, the ``_pinned`` variant just defines the pinning option 93 for the ``xsks_map``. 94 95 When loading the program, make sure to instruct your xdp program loader of 96 choice to pin the map and adjust the file permissions so that NSD can modify the 97 pinned map. For example with the ``xdp-loader`` from xdp-tools: 98 99 .. code-block:: bash 100 101 sudo xdp-loader load -p /sys/fs/bpf <iface> /usr/share/nsd/xdp-dns-redirect_kern_pinned.o 102 sudo chown nsd /sys/fs/bpf/xsks_map 103 sudo chmod o+x /sys/fs/bpf 104 105 You'll need to instruct NSD to not load any XDP programs, and inform NSD about 106 which XDP program you loaded and the bpffs path used, if that differs from the 107 default of ``/sys/fs/bpf``. For example: 108 109 .. code-block:: text 110 111 server: 112 xdp-interface: enp1s0 113 114 xdp-program-load: no 115 xdp-program-path: "/usr/share/nsd/xdp-dns-redirect_kern_pinned.o" 116 xdp-bpffs-path: "/sys/fs/bpf" 117 118 .. _custom-xdp: 119 120 Writing/Extending your own custom XDP program 121 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 122 123 If you want to write or extend your own XDP program, you'll need to define 124 a ``BPF_MAP_TYPE_XSKMAP`` BPF MAP with the name ``xsks_map``: 125 126 .. code-block:: c 127 128 struct { 129 __uint(type, BPF_MAP_TYPE_XSKMAP); 130 __type(key, __u32); 131 __type(value, __u32); 132 __uint(max_entries, 64); // max_entries must be >= number of network queues 133 __uint(pinning, LIBBPF_PIN_BY_NAME); 134 } xsks_map SEC(".maps"); 135 136 Like with :ref:`load-bundled-xdp` (see above), you'll need to pin the map to 137 a bpffs and configure NSD appropriately. 138 139 NSD (the XDP code path) internally checks whether incoming traffic is destined 140 for port 53. If you want to redirect UDP traffic incoming at a port other than 141 53, you'll currently have to adjust ``DNS_PORT`` in ``xdp-server.c`` 142 accordingly. 143 144 .. _its-not-working: 145 146 It's not working 147 ---------------- 148 149 Some drivers don't support AF_XDP sockets fully. For those you can try out the 150 ``xdp-force-copy`` option: 151 152 .. code-block:: text 153 154 server: 155 xdp-force-copy: yes 156
Indexes created Tue Feb 24 08:35:24 UTC 2026