Commit | Line | Data |
---|---|---|
961fb1ff MCC |
1 | .. SPDX-License-Identifier: GPL-2.0 |
2 | ||
3 | ================================ | |
4 | The UDP-Lite protocol (RFC 3828) | |
5 | ================================ | |
ba4e58ec GR |
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 | ||
961fb1ff MCC |
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. | |
ba4e58ec | 20 | |
961fb1ff MCC |
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 | |
ba4e58ec | 23 | |
961fb1ff MCC |
24 | - The Wireshark UDP-Lite WiKi (with capture files): |
25 | https://wiki.wireshark.org/Lightweight_User_Datagram_Protocol | |
ba4e58ec | 26 | |
961fb1ff | 27 | - The Protocol Spec, RFC 3828, http://www.ietf.org/rfc/rfc3828.txt |
ba4e58ec GR |
28 | |
29 | ||
961fb1ff MCC |
30 | 1. Applications |
31 | =============== | |
ba4e58ec GR |
32 | |
33 | Several applications have been ported successfully to UDP-Lite. Ethereal | |
961fb1ff MCC |
34 | (now called wireshark) has UDP-Litev4/v6 support by default. |
35 | ||
ba4e58ec GR |
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 | ||
961fb1ff MCC |
40 | 2. Programming API |
41 | ================== | |
ba4e58ec GR |
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 | |
961fb1ff MCC |
45 | very easy: simply add ``IPPROTO_UDPLITE`` as the last argument of the |
46 | socket(2) call so that the statement looks like:: | |
ba4e58ec GR |
47 | |
48 | s = socket(PF_INET, SOCK_DGRAM, IPPROTO_UDPLITE); | |
49 | ||
961fb1ff MCC |
50 | or, respectively, |
51 | ||
52 | :: | |
ba4e58ec GR |
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 | ||
961fb1ff | 65 | For example:: |
ba4e58ec | 66 | |
961fb1ff MCC |
67 | int val = 20; |
68 | setsockopt(s, SOL_UDPLITE, UDPLITE_SEND_CSCOV, &val, sizeof(int)); | |
ba4e58ec GR |
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 | |
961fb1ff | 83 | packets with a minimum coverage of 20 are admitted:: |
ba4e58ec | 84 | |
961fb1ff MCC |
85 | int min = 20; |
86 | setsockopt(s, SOL_UDPLITE, UDPLITE_RECV_CSCOV, &min, sizeof(int)); | |
ba4e58ec GR |
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 | ||
961fb1ff MCC |
94 | 3. Header Files |
95 | =============== | |
ba4e58ec GR |
96 | |
97 | The socket API requires support through header files in /usr/include: | |
98 | ||
99 | * /usr/include/netinet/in.h | |
961fb1ff | 100 | to define IPPROTO_UDPLITE |
ba4e58ec GR |
101 | |
102 | * /usr/include/netinet/udplite.h | |
961fb1ff | 103 | for UDP-Lite header fields and protocol constants |
ba4e58ec | 104 | |
961fb1ff | 105 | For testing purposes, the following can serve as a ``mini`` header file:: |
ba4e58ec GR |
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 | ||
961fb1ff MCC |
114 | 4. Kernel Behaviour with Regards to the Various Socket Options |
115 | ============================================================== | |
ba4e58ec | 116 | |
ba4e58ec GR |
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 | |
961fb1ff | 146 | and cannot be disabled using SO_NO_CHECK. Thus:: |
ba4e58ec | 147 | |
961fb1ff | 148 | setsockopt(sockfd, SOL_SOCKET, SO_NO_CHECK, ... ); |
ba4e58ec | 149 | |
961fb1ff | 150 | will always will be ignored, while the value of:: |
ba4e58ec | 151 | |
961fb1ff | 152 | getsockopt(sockfd, SOL_SOCKET, SO_NO_CHECK, &value, ...); |
ba4e58ec GR |
153 | |
154 | is meaningless (as in TCP). Packets with a zero checksum field are | |
47112e25 | 155 | illegal (cf. RFC 3828, sec. 3.1) and will be silently discarded. |
ba4e58ec GR |
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. | |
961fb1ff | 177 | Consider the following example:: |
ba4e58ec | 178 | |
961fb1ff MCC |
179 | Payload: 1536 bytes Send Buffer: 1024 bytes |
180 | MTU: 1500 bytes Coverage Length: 856 bytes | |
ba4e58ec | 181 | |
961fb1ff | 182 | UDP-Lite will ship the 1536 bytes in two separate packets:: |
ba4e58ec | 183 | |
961fb1ff MCC |
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 | |
ba4e58ec GR |
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 | |
961fb1ff | 194 | several tiny fragments, consider the following example:: |
ba4e58ec | 195 | |
961fb1ff MCC |
196 | Payload: 1024 bytes Send buffer size: 1024 bytes |
197 | MTU: 300 bytes Coverage length: 575 bytes | |
ba4e58ec | 198 | |
961fb1ff MCC |
199 | +-+-----------+--------------+--------------+--------------+ |
200 | |8| 272 | 280 | 280 | 280 | | |
201 | +-+-----------+--------------+--------------+--------------+ | |
202 | 280 560 840 1032 | |
203 | ^ | |
204 | *****checksum coverage************* | |
ba4e58ec GR |
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 | |
961fb1ff | 218 | of 3356 bytes will be split into the following fragments:: |
ba4e58ec GR |
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 | |
01dd2fbf | 230 | coverage lengths are likely to be expected. |
ba4e58ec | 231 | |
961fb1ff MCC |
232 | 5. UDP-Lite Runtime Statistics and their Meaning |
233 | ================================================ | |
ba4e58ec GR |
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 | |
961fb1ff | 237 | and can (with newer versions of netstat) be viewed using:: |
ba4e58ec | 238 | |
961fb1ff | 239 | netstat -svu |
ba4e58ec GR |
240 | |
241 | This displays UDP-Lite statistics variables, whose meaning is as follows. | |
242 | ||
961fb1ff MCC |
243 | ============ ===================================================== |
244 | InDatagrams The total number of datagrams delivered to users. | |
ba4e58ec | 245 | |
961fb1ff MCC |
246 | NoPorts Number of packets received to an unknown port. |
247 | These cases are counted separately (not as InErrors). | |
ba4e58ec | 248 | |
961fb1ff | 249 | InErrors Number of erroneous UDP-Lite packets. Errors include: |
ba4e58ec | 250 | |
961fb1ff MCC |
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 | |
ba4e58ec | 259 | |
961fb1ff MCC |
260 | OutDatagrams Total number of sent datagrams. |
261 | ============ ===================================================== | |
ba4e58ec | 262 | |
961fb1ff | 263 | These statistics derive from the UDP MIB (RFC 2013). |
ba4e58ec | 264 | |
961fb1ff MCC |
265 | 6. IPtables |
266 | =========== | |
ba4e58ec GR |
267 | |
268 | There is packet match support for UDP-Lite as well as support for the LOG target. | |
961fb1ff | 269 | If you copy and paste the following line into /etc/protocols:: |
ba4e58ec | 270 | |
961fb1ff | 271 | udplite 136 UDP-Lite # UDP-Lite [RFC 3828] |
ba4e58ec | 272 | |
961fb1ff | 273 | then:: |
ba4e58ec | 274 | |
961fb1ff | 275 | iptables -A INPUT -p udplite -j LOG |
ba4e58ec | 276 | |
961fb1ff | 277 | will produce logging output to syslog. Dropping and rejecting packets also works. |
ba4e58ec | 278 | |
961fb1ff MCC |
279 | 7. Maintainer Address |
280 | ===================== | |
ba4e58ec GR |
281 | |
282 | The UDP-Lite patch was developed at | |
961fb1ff MCC |
283 | |
284 | University of Aberdeen | |
285 | Electronics Research Group | |
286 | Department of Engineering | |
287 | Fraser Noble Building | |
288 | Aberdeen AB24 3UE; UK | |
289 | ||
ba4e58ec GR |
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>. |