About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / networking / udplite.txt




Custom Search

Based on kernel version 3.16. Page generated on 2014-08-06 21:40 EST.

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	       http://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>.
Hide Line Numbers
About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Information is copyright its respective author. All material is available from the Linux Kernel Source distributed under a GPL License. This page is provided as a free service by mjmwired.net.