udplite.txt 11 KB

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