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