Documentation/networking/udplite.rst

   1 .. SPDX-License-Identifier: GPL-2.0
   2
   3 ================================
   4 The UDP-Lite protocol (RFC 3828)
   5 ================================
   6
   7
   8   UDP-Lite is a Standards-Track IETF transport protocol whose characteristic
   9   is a variable-length checksum. This has advantages for transport of multimedia
  10   (video, VoIP) over wireless networks, as partly damaged packets can still be
  11   fed into the codec instead of being discarded due to a failed checksum test.
  12
  13   This file briefly describes the existing kernel support and the socket API.
  14   For in-depth information, you can consult:
  15
  16    - The UDP-Lite Homepage:
  17      http://web.archive.org/web/%2E/http://www.erg.abdn.ac.uk/users/gerrit/udp-lite/
  18
  19      From here you can also download some example application source code.
  20
  21    - The UDP-Lite HOWTO on
  22      http://web.archive.org/web/%2E/http://www.erg.abdn.ac.uk/users/gerrit/udp-lite/files/UDP-Lite-HOWTO.txt
  23
  24    - The Wireshark UDP-Lite WiKi (with capture files):
  25      https://wiki.wireshark.org/Lightweight_User_Datagram_Protocol
  26
  27    - The Protocol Spec, RFC 3828, http://www.ietf.org/rfc/rfc3828.txt
  28
  29
  30 1. Applications
  31 ===============
  32
  33   Several applications have been ported successfully to UDP-Lite. Ethereal
  34   (now called wireshark) has UDP-Litev4/v6 support by default.
  35
  36   Porting applications to UDP-Lite is straightforward: only socket level and
  37   IPPROTO need to be changed; senders additionally set the checksum coverage
  38   length (default = header length = 8). Details are in the next section.
  39
  40 2. Programming API
  41 ==================
  42
  43   UDP-Lite provides a connectionless, unreliable datagram service and hence
  44   uses the same socket type as UDP. In fact, porting from UDP to UDP-Lite is
  45   very easy: simply add ``IPPROTO_UDPLITE`` as the last argument of the
  46   socket(2) call so that the statement looks like::
  47
  48       s = socket(PF_INET, SOCK_DGRAM, IPPROTO_UDPLITE);
  49
  50   or, respectively,
  51
  52   ::
  53
  54       s = socket(PF_INET6, SOCK_DGRAM, IPPROTO_UDPLITE);
  55
  56   With just the above change you are able to run UDP-Lite services or connect
  57   to UDP-Lite servers. The kernel will assume that you are not interested in
  58   using partial checksum coverage and so emulate UDP mode (full coverage).
  59
  60   To make use of the partial checksum coverage facilities requires setting a
  61   single socket option, which takes an integer specifying the coverage length:
  62
  63     * Sender checksum coverage: UDPLITE_SEND_CSCOV
  64
  65       For example::
  66
  67         int val = 20;
  68         setsockopt(s, SOL_UDPLITE, UDPLITE_SEND_CSCOV, &val, sizeof(int));
  69
  70       sets the checksum coverage length to 20 bytes (12b data + 8b header).
  71       Of each packet only the first 20 bytes (plus the pseudo-header) will be
  72       checksummed. This is useful for RTP applications which have a 12-byte
  73       base header.
  74
  75
  76     * Receiver checksum coverage: UDPLITE_RECV_CSCOV
  77
  78       This option is the receiver-side analogue. It is truly optional, i.e. not
  79       required to enable traffic with partial checksum coverage. Its function is
  80       that of a traffic filter: when enabled, it instructs the kernel to drop
  81       all packets which have a coverage _less_ than this value. For example, if
  82       RTP and UDP headers are to be protected, a receiver can enforce that only
  83       packets with a minimum coverage of 20 are admitted::
  84
  85         int min = 20;
  86         setsockopt(s, SOL_UDPLITE, UDPLITE_RECV_CSCOV, &min, sizeof(int));
  87
  88   The calls to getsockopt(2) are analogous. Being an extension and not a stand-
  89   alone protocol, all socket options known from UDP can be used in exactly the
  90   same manner as before, e.g. UDP_CORK or UDP_ENCAP.
  91
  92   A detailed discussion of UDP-Lite checksum coverage options is in section IV.
  93
  94 3. Header Files
  95 ===============
  96
  97   The socket API requires support through header files in /usr/include:
  98
  99     * /usr/include/netinet/in.h
 100       to define IPPROTO_UDPLITE
 101
 102     * /usr/include/netinet/udplite.h
 103       for UDP-Lite header fields and protocol constants
 104
 105   For testing purposes, the following can serve as a ``mini`` header file::
 106
 107     #define IPPROTO_UDPLITE       136
 108     #define SOL_UDPLITE           136
 109     #define UDPLITE_SEND_CSCOV     10
 110     #define UDPLITE_RECV_CSCOV     11
 111
 112   Ready-made header files for various distros are in the UDP-Lite tarball.
 113
 114 4. Kernel Behaviour with Regards to the Various Socket Options
 115 ==============================================================
 116
 117
 118   To enable debugging messages, the log level need to be set to 8, as most
 119   messages use the KERN_DEBUG level (7).
 120
 121   1) Sender Socket Options
 122
 123   If the sender specifies a value of 0 as coverage length, the module
 124   assumes full coverage, transmits a packet with coverage length of 0
 125   and according checksum.  If the sender specifies a coverage < 8 and
 126   different from 0, the kernel assumes 8 as default value.  Finally,
 127   if the specified coverage length exceeds the packet length, the packet
 128   length is used instead as coverage length.
 129
 130   2) Receiver Socket Options
 131
 132   The receiver specifies the minimum value of the coverage length it
 133   is willing to accept.  A value of 0 here indicates that the receiver
 134   always wants the whole of the packet covered. In this case, all
 135   partially covered packets are dropped and an error is logged.
 136
 137   It is not possible to specify illegal values (<0 and <8); in these
 138   cases the default of 8 is assumed.
 139
 140   All packets arriving with a coverage value less than the specified
 141   threshold are discarded, these events are also logged.
 142
 143   3) Disabling the Checksum Computation
 144
 145   On both sender and receiver, checksumming will always be performed
 146   and cannot be disabled using SO_NO_CHECK. Thus::
 147
 148         setsockopt(sockfd, SOL_SOCKET, SO_NO_CHECK,  ... );
 149
 150   will always will be ignored, while the value of::
 151
 152         getsockopt(sockfd, SOL_SOCKET, SO_NO_CHECK, &value, ...);
 153
 154   is meaningless (as in TCP). Packets with a zero checksum field are
 155   illegal (cf. RFC 3828, sec. 3.1) and will be silently discarded.
 156
 157   4) Fragmentation
 158
 159   The checksum computation respects both buffersize and MTU. The size
 160   of UDP-Lite packets is determined by the size of the send buffer. The
 161   minimum size of the send buffer is 2048 (defined as SOCK_MIN_SNDBUF
 162   in include/net/sock.h), the default value is configurable as
 163   net.core.wmem_default or via setting the SO_SNDBUF socket(7)
 164   option. The maximum upper bound for the send buffer is determined
 165   by net.core.wmem_max.
 166
 167   Given a payload size larger than the send buffer size, UDP-Lite will
 168   split the payload into several individual packets, filling up the
 169   send buffer size in each case.
 170
 171   The precise value also depends on the interface MTU. The interface MTU,
 172   in turn, may trigger IP fragmentation. In this case, the generated
 173   UDP-Lite packet is split into several IP packets, of which only the
 174   first one contains the L4 header.
 175
 176   The send buffer size has implications on the checksum coverage length.
 177   Consider the following example::
 178
 179     Payload: 1536 bytes          Send Buffer:     1024 bytes
 180     MTU:     1500 bytes          Coverage Length:  856 bytes
 181
 182   UDP-Lite will ship the 1536 bytes in two separate packets::
 183
 184     Packet 1: 1024 payload + 8 byte header + 20 byte IP header = 1052 bytes
 185     Packet 2:  512 payload + 8 byte header + 20 byte IP header =  540 bytes
 186
 187   The coverage packet covers the UDP-Lite header and 848 bytes of the
 188   payload in the first packet, the second packet is fully covered. Note
 189   that for the second packet, the coverage length exceeds the packet
 190   length. The kernel always re-adjusts the coverage length to the packet
 191   length in such cases.
 192
 193   As an example of what happens when one UDP-Lite packet is split into
 194   several tiny fragments, consider the following example::
 195
 196     Payload: 1024 bytes            Send buffer size: 1024 bytes
 197     MTU:      300 bytes            Coverage length:   575 bytes
 198
 199     +-+-----------+--------------+--------------+--------------+
 200     |8|    272    |      280     |     280      |     280      |
 201     +-+-----------+--------------+--------------+--------------+
 202                 280            560            840           1032
 203                                         ^
 204     *****checksum coverage*************
 205
 206   The UDP-Lite module generates one 1032 byte packet (1024 + 8 byte
 207   header). According to the interface MTU, these are split into 4 IP
 208   packets (280 byte IP payload + 20 byte IP header). The kernel module
 209   sums the contents of the entire first two packets, plus 15 bytes of
 210   the last packet before releasing the fragments to the IP module.
 211
 212   To see the analogous case for IPv6 fragmentation, consider a link
 213   MTU of 1280 bytes and a write buffer of 3356 bytes. If the checksum
 214   coverage is less than 1232 bytes (MTU minus IPv6/fragment header
 215   lengths), only the first fragment needs to be considered. When using
 216   larger checksum coverage lengths, each eligible fragment needs to be
 217   checksummed. Suppose we have a checksum coverage of 3062. The buffer
 218   of 3356 bytes will be split into the following fragments::
 219
 220     Fragment 1: 1280 bytes carrying  1232 bytes of UDP-Lite data
 221     Fragment 2: 1280 bytes carrying  1232 bytes of UDP-Lite data
 222     Fragment 3:  948 bytes carrying   900 bytes of UDP-Lite data
 223
 224   The first two fragments have to be checksummed in full, of the last
 225   fragment only 598 (= 3062 - 2*1232) bytes are checksummed.
 226
 227   While it is important that such cases are dealt with correctly, they
 228   are (annoyingly) rare: UDP-Lite is designed for optimising multimedia
 229   performance over wireless (or generally noisy) links and thus smaller
 230   coverage lengths are likely to be expected.
 231
 232 5. UDP-Lite Runtime Statistics and their Meaning
 233 ================================================
 234
 235   Exceptional and error conditions are logged to syslog at the KERN_DEBUG
 236   level.  Live statistics about UDP-Lite are available in /proc/net/snmp
 237   and can (with newer versions of netstat) be viewed using::
 238
 239                             netstat -svu
 240
 241   This displays UDP-Lite statistics variables, whose meaning is as follows.
 242
 243    ============     =====================================================
 244    InDatagrams      The total number of datagrams delivered to users.
 245
 246    NoPorts          Number of packets received to an unknown port.
 247                     These cases are counted separately (not as InErrors).
 248
 249    InErrors         Number of erroneous UDP-Lite packets. Errors include:
 250
 251                       * internal socket queue receive errors
 252                       * packet too short (less than 8 bytes or stated
 253                         coverage length exceeds received length)
 254                       * xfrm4_policy_check() returned with error
 255                       * application has specified larger min. coverage
 256                         length than that of incoming packet
 257                       * checksum coverage violated
 258                       * bad checksum
 259
 260    OutDatagrams     Total number of sent datagrams.
 261    ============     =====================================================
 262
 263    These statistics derive from the UDP MIB (RFC 2013).
 264
 265 6. IPtables
 266 ===========
 267
 268   There is packet match support for UDP-Lite as well as support for the LOG target.
 269   If you copy and paste the following line into /etc/protocols::
 270
 271     udplite 136     UDP-Lite        # UDP-Lite [RFC 3828]
 272
 273   then::
 274
 275               iptables -A INPUT -p udplite -j LOG
 276
 277   will produce logging output to syslog. Dropping and rejecting packets also works.
 278
 279 7. Maintainer Address
 280 =====================
 281
 282   The UDP-Lite patch was developed at
 283
 284                     University of Aberdeen
 285                     Electronics Research Group
 286                     Department of Engineering
 287                     Fraser Noble Building
 288                     Aberdeen AB24 3UE; UK
 289
 290   The current maintainer is Gerrit Renker, <gerrit@erg.abdn.ac.uk>. Initial
 291   code was developed by William  Stanislaus, <william@erg.abdn.ac.uk>.