0001 .. SPDX-License-Identifier: GPL-2.0
0002
0003 ================================
0004 The UDP-Lite protocol (RFC 3828)
0005 ================================
0006
0007
0008 UDP-Lite is a Standards-Track IETF transport protocol whose characteristic
0009 is a variable-length checksum. This has advantages for transport of multimedia
0010 (video, VoIP) over wireless networks, as partly damaged packets can still be
0011 fed into the codec instead of being discarded due to a failed checksum test.
0012
0013 This file briefly describes the existing kernel support and the socket API.
0014 For in-depth information, you can consult:
0015
0016 - The UDP-Lite Homepage:
0017 http://web.archive.org/web/%2E/http://www.erg.abdn.ac.uk/users/gerrit/udp-lite/
0018
0019 From here you can also download some example application source code.
0020
0021 - The UDP-Lite HOWTO on
0022 http://web.archive.org/web/%2E/http://www.erg.abdn.ac.uk/users/gerrit/udp-lite/files/UDP-Lite-HOWTO.txt
0023
0024 - The Wireshark UDP-Lite WiKi (with capture files):
0025 https://wiki.wireshark.org/Lightweight_User_Datagram_Protocol
0026
0027 - The Protocol Spec, RFC 3828, http://www.ietf.org/rfc/rfc3828.txt
0028
0029
0030 1. Applications
0031 ===============
0032
0033 Several applications have been ported successfully to UDP-Lite. Ethereal
0034 (now called wireshark) has UDP-Litev4/v6 support by default.
0035
0036 Porting applications to UDP-Lite is straightforward: only socket level and
0037 IPPROTO need to be changed; senders additionally set the checksum coverage
0038 length (default = header length = 8). Details are in the next section.
0039
0040 2. Programming API
0041 ==================
0042
0043 UDP-Lite provides a connectionless, unreliable datagram service and hence
0044 uses the same socket type as UDP. In fact, porting from UDP to UDP-Lite is
0045 very easy: simply add ``IPPROTO_UDPLITE`` as the last argument of the
0046 socket(2) call so that the statement looks like::
0047
0048 s = socket(PF_INET, SOCK_DGRAM, IPPROTO_UDPLITE);
0049
0050 or, respectively,
0051
0052 ::
0053
0054 s = socket(PF_INET6, SOCK_DGRAM, IPPROTO_UDPLITE);
0055
0056 With just the above change you are able to run UDP-Lite services or connect
0057 to UDP-Lite servers. The kernel will assume that you are not interested in
0058 using partial checksum coverage and so emulate UDP mode (full coverage).
0059
0060 To make use of the partial checksum coverage facilities requires setting a
0061 single socket option, which takes an integer specifying the coverage length:
0062
0063 * Sender checksum coverage: UDPLITE_SEND_CSCOV
0064
0065 For example::
0066
0067 int val = 20;
0068 setsockopt(s, SOL_UDPLITE, UDPLITE_SEND_CSCOV, &val, sizeof(int));
0069
0070 sets the checksum coverage length to 20 bytes (12b data + 8b header).
0071 Of each packet only the first 20 bytes (plus the pseudo-header) will be
0072 checksummed. This is useful for RTP applications which have a 12-byte
0073 base header.
0074
0075
0076 * Receiver checksum coverage: UDPLITE_RECV_CSCOV
0077
0078 This option is the receiver-side analogue. It is truly optional, i.e. not
0079 required to enable traffic with partial checksum coverage. Its function is
0080 that of a traffic filter: when enabled, it instructs the kernel to drop
0081 all packets which have a coverage _less_ than this value. For example, if
0082 RTP and UDP headers are to be protected, a receiver can enforce that only
0083 packets with a minimum coverage of 20 are admitted::
0084
0085 int min = 20;
0086 setsockopt(s, SOL_UDPLITE, UDPLITE_RECV_CSCOV, &min, sizeof(int));
0087
0088 The calls to getsockopt(2) are analogous. Being an extension and not a stand-
0089 alone protocol, all socket options known from UDP can be used in exactly the
0090 same manner as before, e.g. UDP_CORK or UDP_ENCAP.
0091
0092 A detailed discussion of UDP-Lite checksum coverage options is in section IV.
0093
0094 3. Header Files
0095 ===============
0096
0097 The socket API requires support through header files in /usr/include:
0098
0099 * /usr/include/netinet/in.h
0100 to define IPPROTO_UDPLITE
0101
0102 * /usr/include/netinet/udplite.h
0103 for UDP-Lite header fields and protocol constants
0104
0105 For testing purposes, the following can serve as a ``mini`` header file::
0106
0107 #define IPPROTO_UDPLITE 136
0108 #define SOL_UDPLITE 136
0109 #define UDPLITE_SEND_CSCOV 10
0110 #define UDPLITE_RECV_CSCOV 11
0111
0112 Ready-made header files for various distros are in the UDP-Lite tarball.
0113
0114 4. Kernel Behaviour with Regards to the Various Socket Options
0115 ==============================================================
0116
0117
0118 To enable debugging messages, the log level need to be set to 8, as most
0119 messages use the KERN_DEBUG level (7).
0120
0121 1) Sender Socket Options
0122
0123 If the sender specifies a value of 0 as coverage length, the module
0124 assumes full coverage, transmits a packet with coverage length of 0
0125 and according checksum. If the sender specifies a coverage < 8 and
0126 different from 0, the kernel assumes 8 as default value. Finally,
0127 if the specified coverage length exceeds the packet length, the packet
0128 length is used instead as coverage length.
0129
0130 2) Receiver Socket Options
0131
0132 The receiver specifies the minimum value of the coverage length it
0133 is willing to accept. A value of 0 here indicates that the receiver
0134 always wants the whole of the packet covered. In this case, all
0135 partially covered packets are dropped and an error is logged.
0136
0137 It is not possible to specify illegal values (<0 and <8); in these
0138 cases the default of 8 is assumed.
0139
0140 All packets arriving with a coverage value less than the specified
0141 threshold are discarded, these events are also logged.
0142
0143 3) Disabling the Checksum Computation
0144
0145 On both sender and receiver, checksumming will always be performed
0146 and cannot be disabled using SO_NO_CHECK. Thus::
0147
0148 setsockopt(sockfd, SOL_SOCKET, SO_NO_CHECK, ... );
0149
0150 will always will be ignored, while the value of::
0151
0152 getsockopt(sockfd, SOL_SOCKET, SO_NO_CHECK, &value, ...);
0153
0154 is meaningless (as in TCP). Packets with a zero checksum field are
0155 illegal (cf. RFC 3828, sec. 3.1) and will be silently discarded.
0156
0157 4) Fragmentation
0158
0159 The checksum computation respects both buffersize and MTU. The size
0160 of UDP-Lite packets is determined by the size of the send buffer. The
0161 minimum size of the send buffer is 2048 (defined as SOCK_MIN_SNDBUF
0162 in include/net/sock.h), the default value is configurable as
0163 net.core.wmem_default or via setting the SO_SNDBUF socket(7)
0164 option. The maximum upper bound for the send buffer is determined
0165 by net.core.wmem_max.
0166
0167 Given a payload size larger than the send buffer size, UDP-Lite will
0168 split the payload into several individual packets, filling up the
0169 send buffer size in each case.
0170
0171 The precise value also depends on the interface MTU. The interface MTU,
0172 in turn, may trigger IP fragmentation. In this case, the generated
0173 UDP-Lite packet is split into several IP packets, of which only the
0174 first one contains the L4 header.
0175
0176 The send buffer size has implications on the checksum coverage length.
0177 Consider the following example::
0178
0179 Payload: 1536 bytes Send Buffer: 1024 bytes
0180 MTU: 1500 bytes Coverage Length: 856 bytes
0181
0182 UDP-Lite will ship the 1536 bytes in two separate packets::
0183
0184 Packet 1: 1024 payload + 8 byte header + 20 byte IP header = 1052 bytes
0185 Packet 2: 512 payload + 8 byte header + 20 byte IP header = 540 bytes
0186
0187 The coverage packet covers the UDP-Lite header and 848 bytes of the
0188 payload in the first packet, the second packet is fully covered. Note
0189 that for the second packet, the coverage length exceeds the packet
0190 length. The kernel always re-adjusts the coverage length to the packet
0191 length in such cases.
0192
0193 As an example of what happens when one UDP-Lite packet is split into
0194 several tiny fragments, consider the following example::
0195
0196 Payload: 1024 bytes Send buffer size: 1024 bytes
0197 MTU: 300 bytes Coverage length: 575 bytes
0198
0199 +-+-----------+--------------+--------------+--------------+
0200 |8| 272 | 280 | 280 | 280 |
0201 +-+-----------+--------------+--------------+--------------+
0202 280 560 840 1032
0203 ^
0204 *****checksum coverage*************
0205
0206 The UDP-Lite module generates one 1032 byte packet (1024 + 8 byte
0207 header). According to the interface MTU, these are split into 4 IP
0208 packets (280 byte IP payload + 20 byte IP header). The kernel module
0209 sums the contents of the entire first two packets, plus 15 bytes of
0210 the last packet before releasing the fragments to the IP module.
0211
0212 To see the analogous case for IPv6 fragmentation, consider a link
0213 MTU of 1280 bytes and a write buffer of 3356 bytes. If the checksum
0214 coverage is less than 1232 bytes (MTU minus IPv6/fragment header
0215 lengths), only the first fragment needs to be considered. When using
0216 larger checksum coverage lengths, each eligible fragment needs to be
0217 checksummed. Suppose we have a checksum coverage of 3062. The buffer
0218 of 3356 bytes will be split into the following fragments::
0219
0220 Fragment 1: 1280 bytes carrying 1232 bytes of UDP-Lite data
0221 Fragment 2: 1280 bytes carrying 1232 bytes of UDP-Lite data
0222 Fragment 3: 948 bytes carrying 900 bytes of UDP-Lite data
0223
0224 The first two fragments have to be checksummed in full, of the last
0225 fragment only 598 (= 3062 - 2*1232) bytes are checksummed.
0226
0227 While it is important that such cases are dealt with correctly, they
0228 are (annoyingly) rare: UDP-Lite is designed for optimising multimedia
0229 performance over wireless (or generally noisy) links and thus smaller
0230 coverage lengths are likely to be expected.
0231
0232 5. UDP-Lite Runtime Statistics and their Meaning
0233 ================================================
0234
0235 Exceptional and error conditions are logged to syslog at the KERN_DEBUG
0236 level. Live statistics about UDP-Lite are available in /proc/net/snmp
0237 and can (with newer versions of netstat) be viewed using::
0238
0239 netstat -svu
0240
0241 This displays UDP-Lite statistics variables, whose meaning is as follows.
0242
0243 ============ =====================================================
0244 InDatagrams The total number of datagrams delivered to users.
0245
0246 NoPorts Number of packets received to an unknown port.
0247 These cases are counted separately (not as InErrors).
0248
0249 InErrors Number of erroneous UDP-Lite packets. Errors include:
0250
0251 * internal socket queue receive errors
0252 * packet too short (less than 8 bytes or stated
0253 coverage length exceeds received length)
0254 * xfrm4_policy_check() returned with error
0255 * application has specified larger min. coverage
0256 length than that of incoming packet
0257 * checksum coverage violated
0258 * bad checksum
0259
0260 OutDatagrams Total number of sent datagrams.
0261 ============ =====================================================
0262
0263 These statistics derive from the UDP MIB (RFC 2013).
0264
0265 6. IPtables
0266 ===========
0267
0268 There is packet match support for UDP-Lite as well as support for the LOG target.
0269 If you copy and paste the following line into /etc/protocols::
0270
0271 udplite 136 UDP-Lite # UDP-Lite [RFC 3828]
0272
0273 then::
0274
0275 iptables -A INPUT -p udplite -j LOG
0276
0277 will produce logging output to syslog. Dropping and rejecting packets also works.
0278
0279 7. Maintainer Address
0280 =====================
0281
0282 The UDP-Lite patch was developed at
0283
0284 University of Aberdeen
0285 Electronics Research Group
0286 Department of Engineering
0287 Fraser Noble Building
0288 Aberdeen AB24 3UE; UK
0289
0290 The current maintainer is Gerrit Renker, <gerrit@erg.abdn.ac.uk>. Initial
0291 code was developed by William Stanislaus, <william@erg.abdn.ac.uk>.
