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