292 lines · plain
1.. SPDX-License-Identifier: GPL-2.02 3================================4The UDP-Lite protocol (RFC 3828)5================================6 7 8 UDP-Lite is a Standards-Track IETF transport protocol whose characteristic9 is a variable-length checksum. This has advantages for transport of multimedia10 (video, VoIP) over wireless networks, as partly damaged packets can still be11 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 on22 http://web.archive.org/web/%2E/http://www.erg.abdn.ac.uk/users/gerrit/udp-lite/files/UDP-Lite-HOWTO.txt23 24 - The Wireshark UDP-Lite WiKi (with capture files):25 https://wiki.wireshark.org/Lightweight_User_Datagram_Protocol26 27 - The Protocol Spec, RFC 3828, http://www.ietf.org/rfc/rfc3828.txt28 29 301. Applications31===============32 33 Several applications have been ported successfully to UDP-Lite. Ethereal34 (now called wireshark) has UDP-Litev4/v6 support by default.35 36 Porting applications to UDP-Lite is straightforward: only socket level and37 IPPROTO need to be changed; senders additionally set the checksum coverage38 length (default = header length = 8). Details are in the next section.39 402. Programming API41==================42 43 UDP-Lite provides a connectionless, unreliable datagram service and hence44 uses the same socket type as UDP. In fact, porting from UDP to UDP-Lite is45 very easy: simply add ``IPPROTO_UDPLITE`` as the last argument of the46 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 connect57 to UDP-Lite servers. The kernel will assume that you are not interested in58 using partial checksum coverage and so emulate UDP mode (full coverage).59 60 To make use of the partial checksum coverage facilities requires setting a61 single socket option, which takes an integer specifying the coverage length:62 63 * Sender checksum coverage: UDPLITE_SEND_CSCOV64 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 be72 checksummed. This is useful for RTP applications which have a 12-byte73 base header.74 75 76 * Receiver checksum coverage: UDPLITE_RECV_CSCOV77 78 This option is the receiver-side analogue. It is truly optional, i.e. not79 required to enable traffic with partial checksum coverage. Its function is80 that of a traffic filter: when enabled, it instructs the kernel to drop81 all packets which have a coverage _less_ than this value. For example, if82 RTP and UDP headers are to be protected, a receiver can enforce that only83 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 the90 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 943. Header Files95===============96 97 The socket API requires support through header files in /usr/include:98 99 * /usr/include/netinet/in.h100 to define IPPROTO_UDPLITE101 102 * /usr/include/netinet/udplite.h103 for UDP-Lite header fields and protocol constants104 105 For testing purposes, the following can serve as a ``mini`` header file::106 107 #define IPPROTO_UDPLITE 136108 #define SOL_UDPLITE 136109 #define UDPLITE_SEND_CSCOV 10110 #define UDPLITE_RECV_CSCOV 11111 112 Ready-made header files for various distros are in the UDP-Lite tarball.113 1144. Kernel Behaviour with Regards to the Various Socket Options115==============================================================116 117 118 To enable debugging messages, the log level need to be set to 8, as most119 messages use the KERN_DEBUG level (7).120 121 1) Sender Socket Options122 123 If the sender specifies a value of 0 as coverage length, the module124 assumes full coverage, transmits a packet with coverage length of 0125 and according checksum. If the sender specifies a coverage < 8 and126 different from 0, the kernel assumes 8 as default value. Finally,127 if the specified coverage length exceeds the packet length, the packet128 length is used instead as coverage length.129 130 2) Receiver Socket Options131 132 The receiver specifies the minimum value of the coverage length it133 is willing to accept. A value of 0 here indicates that the receiver134 always wants the whole of the packet covered. In this case, all135 partially covered packets are dropped and an error is logged.136 137 It is not possible to specify illegal values (<0 and <8); in these138 cases the default of 8 is assumed.139 140 All packets arriving with a coverage value less than the specified141 threshold are discarded, these events are also logged.142 143 3) Disabling the Checksum Computation144 145 On both sender and receiver, checksumming will always be performed146 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 are155 illegal (cf. RFC 3828, sec. 3.1) and will be silently discarded.156 157 4) Fragmentation158 159 The checksum computation respects both buffersize and MTU. The size160 of UDP-Lite packets is determined by the size of the send buffer. The161 minimum size of the send buffer is 2048 (defined as SOCK_MIN_SNDBUF162 in include/net/sock.h), the default value is configurable as163 net.core.wmem_default or via setting the SO_SNDBUF socket(7)164 option. The maximum upper bound for the send buffer is determined165 by net.core.wmem_max.166 167 Given a payload size larger than the send buffer size, UDP-Lite will168 split the payload into several individual packets, filling up the169 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 generated173 UDP-Lite packet is split into several IP packets, of which only the174 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 bytes180 MTU: 1500 bytes Coverage Length: 856 bytes181 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 bytes185 Packet 2: 512 payload + 8 byte header + 20 byte IP header = 540 bytes186 187 The coverage packet covers the UDP-Lite header and 848 bytes of the188 payload in the first packet, the second packet is fully covered. Note189 that for the second packet, the coverage length exceeds the packet190 length. The kernel always re-adjusts the coverage length to the packet191 length in such cases.192 193 As an example of what happens when one UDP-Lite packet is split into194 several tiny fragments, consider the following example::195 196 Payload: 1024 bytes Send buffer size: 1024 bytes197 MTU: 300 bytes Coverage length: 575 bytes198 199 +-+-----------+--------------+--------------+--------------+200 |8| 272 | 280 | 280 | 280 |201 +-+-----------+--------------+--------------+--------------+202 280 560 840 1032203 ^204 *****checksum coverage*************205 206 The UDP-Lite module generates one 1032 byte packet (1024 + 8 byte207 header). According to the interface MTU, these are split into 4 IP208 packets (280 byte IP payload + 20 byte IP header). The kernel module209 sums the contents of the entire first two packets, plus 15 bytes of210 the last packet before releasing the fragments to the IP module.211 212 To see the analogous case for IPv6 fragmentation, consider a link213 MTU of 1280 bytes and a write buffer of 3356 bytes. If the checksum214 coverage is less than 1232 bytes (MTU minus IPv6/fragment header215 lengths), only the first fragment needs to be considered. When using216 larger checksum coverage lengths, each eligible fragment needs to be217 checksummed. Suppose we have a checksum coverage of 3062. The buffer218 of 3356 bytes will be split into the following fragments::219 220 Fragment 1: 1280 bytes carrying 1232 bytes of UDP-Lite data221 Fragment 2: 1280 bytes carrying 1232 bytes of UDP-Lite data222 Fragment 3: 948 bytes carrying 900 bytes of UDP-Lite data223 224 The first two fragments have to be checksummed in full, of the last225 fragment only 598 (= 3062 - 2*1232) bytes are checksummed.226 227 While it is important that such cases are dealt with correctly, they228 are (annoyingly) rare: UDP-Lite is designed for optimising multimedia229 performance over wireless (or generally noisy) links and thus smaller230 coverage lengths are likely to be expected.231 2325. UDP-Lite Runtime Statistics and their Meaning233================================================234 235 Exceptional and error conditions are logged to syslog at the KERN_DEBUG236 level. Live statistics about UDP-Lite are available in /proc/net/snmp237 and can (with newer versions of netstat) be viewed using::238 239 netstat -svu240 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 errors252 * packet too short (less than 8 bytes or stated253 coverage length exceeds received length)254 * xfrm4_policy_check() returned with error255 * application has specified larger min. coverage256 length than that of incoming packet257 * checksum coverage violated258 * bad checksum259 260 OutDatagrams Total number of sent datagrams.261 ============ =====================================================262 263 These statistics derive from the UDP MIB (RFC 2013).264 2656. IPtables266===========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 LOG276 277 will produce logging output to syslog. Dropping and rejecting packets also works.278 2797. Maintainer Address280=====================281 282 The UDP-Lite patch was developed at283 284 University of Aberdeen285 Electronics Research Group286 Department of Engineering287 Fraser Noble Building288 Aberdeen AB24 3UE; UK289 290 The current maintainer is Gerrit Renker, <gerrit@erg.abdn.ac.uk>. Initial291 code was developed by William Stanislaus, <william@erg.abdn.ac.uk>.292