- ===========================================================================
- The UDP-Lite protocol (RFC 3828)
- ===========================================================================
+.. SPDX-License-Identifier: GPL-2.0
+
+================================
+The UDP-Lite protocol (RFC 3828)
+================================
UDP-Lite is a Standards-Track IETF transport protocol whose characteristic
This file briefly describes the existing kernel support and the socket API.
For in-depth information, you can consult:
- o The UDP-Lite Homepage:
- http://web.archive.org/web/*/http://www.erg.abdn.ac.uk/users/gerrit/udp-lite/
- From here you can also download some example application source code.
+ - The UDP-Lite Homepage:
+ http://web.archive.org/web/%2E/http://www.erg.abdn.ac.uk/users/gerrit/udp-lite/
+
+ From here you can also download some example application source code.
- o The UDP-Lite HOWTO on
- http://web.archive.org/web/*/http://www.erg.abdn.ac.uk/users/gerrit/udp-lite/
- files/UDP-Lite-HOWTO.txt
+ - The UDP-Lite HOWTO on
+ http://web.archive.org/web/%2E/http://www.erg.abdn.ac.uk/users/gerrit/udp-lite/files/UDP-Lite-HOWTO.txt
- o The Wireshark UDP-Lite WiKi (with capture files):
- https://wiki.wireshark.org/Lightweight_User_Datagram_Protocol
+ - The Wireshark UDP-Lite WiKi (with capture files):
+ https://wiki.wireshark.org/Lightweight_User_Datagram_Protocol
- o The Protocol Spec, RFC 3828, http://www.ietf.org/rfc/rfc3828.txt
+ - The Protocol Spec, RFC 3828, http://www.ietf.org/rfc/rfc3828.txt
- I) APPLICATIONS
+1. Applications
+===============
Several applications have been ported successfully to UDP-Lite. Ethereal
- (now called wireshark) has UDP-Litev4/v6 support by default.
+ (now called wireshark) has UDP-Litev4/v6 support by default.
+
Porting applications to UDP-Lite is straightforward: only socket level and
IPPROTO need to be changed; senders additionally set the checksum coverage
length (default = header length = 8). Details are in the next section.
-
- II) PROGRAMMING API
+2. Programming API
+==================
UDP-Lite provides a connectionless, unreliable datagram service and hence
uses the same socket type as UDP. In fact, porting from UDP to UDP-Lite is
- very easy: simply add `IPPROTO_UDPLITE' as the last argument of the socket(2)
- call so that the statement looks like:
+ very easy: simply add ``IPPROTO_UDPLITE`` as the last argument of the
+ socket(2) call so that the statement looks like::
s = socket(PF_INET, SOCK_DGRAM, IPPROTO_UDPLITE);
- or, respectively,
+ or, respectively,
+
+ ::
s = socket(PF_INET6, SOCK_DGRAM, IPPROTO_UDPLITE);
* Sender checksum coverage: UDPLITE_SEND_CSCOV
- For example,
+ For example::
- int val = 20;
- setsockopt(s, SOL_UDPLITE, UDPLITE_SEND_CSCOV, &val, sizeof(int));
+ int val = 20;
+ setsockopt(s, SOL_UDPLITE, UDPLITE_SEND_CSCOV, &val, sizeof(int));
sets the checksum coverage length to 20 bytes (12b data + 8b header).
Of each packet only the first 20 bytes (plus the pseudo-header) will be
that of a traffic filter: when enabled, it instructs the kernel to drop
all packets which have a coverage _less_ than this value. For example, if
RTP and UDP headers are to be protected, a receiver can enforce that only
- packets with a minimum coverage of 20 are admitted:
+ packets with a minimum coverage of 20 are admitted::
- int min = 20;
- setsockopt(s, SOL_UDPLITE, UDPLITE_RECV_CSCOV, &min, sizeof(int));
+ int min = 20;
+ setsockopt(s, SOL_UDPLITE, UDPLITE_RECV_CSCOV, &min, sizeof(int));
The calls to getsockopt(2) are analogous. Being an extension and not a stand-
alone protocol, all socket options known from UDP can be used in exactly the
A detailed discussion of UDP-Lite checksum coverage options is in section IV.
-
- III) HEADER FILES
+3. Header Files
+===============
The socket API requires support through header files in /usr/include:
* /usr/include/netinet/in.h
- to define IPPROTO_UDPLITE
+ to define IPPROTO_UDPLITE
* /usr/include/netinet/udplite.h
- for UDP-Lite header fields and protocol constants
+ for UDP-Lite header fields and protocol constants
- For testing purposes, the following can serve as a `mini' header file:
+ For testing purposes, the following can serve as a ``mini`` header file::
#define IPPROTO_UDPLITE 136
#define SOL_UDPLITE 136
Ready-made header files for various distros are in the UDP-Lite tarball.
+4. Kernel Behaviour with Regards to the Various Socket Options
+==============================================================
- IV) KERNEL BEHAVIOUR WITH REGARD TO THE VARIOUS SOCKET OPTIONS
To enable debugging messages, the log level need to be set to 8, as most
messages use the KERN_DEBUG level (7).
3) Disabling the Checksum Computation
On both sender and receiver, checksumming will always be performed
- and cannot be disabled using SO_NO_CHECK. Thus
+ and cannot be disabled using SO_NO_CHECK. Thus::
- setsockopt(sockfd, SOL_SOCKET, SO_NO_CHECK, ... );
+ setsockopt(sockfd, SOL_SOCKET, SO_NO_CHECK, ... );
- will always will be ignored, while the value of
+ will always will be ignored, while the value of::
- getsockopt(sockfd, SOL_SOCKET, SO_NO_CHECK, &value, ...);
+ getsockopt(sockfd, SOL_SOCKET, SO_NO_CHECK, &value, ...);
is meaningless (as in TCP). Packets with a zero checksum field are
illegal (cf. RFC 3828, sec. 3.1) and will be silently discarded.
first one contains the L4 header.
The send buffer size has implications on the checksum coverage length.
- Consider the following example:
+ Consider the following example::
- Payload: 1536 bytes Send Buffer: 1024 bytes
- MTU: 1500 bytes Coverage Length: 856 bytes
+ Payload: 1536 bytes Send Buffer: 1024 bytes
+ MTU: 1500 bytes Coverage Length: 856 bytes
- UDP-Lite will ship the 1536 bytes in two separate packets:
+ UDP-Lite will ship the 1536 bytes in two separate packets::
- Packet 1: 1024 payload + 8 byte header + 20 byte IP header = 1052 bytes
- Packet 2: 512 payload + 8 byte header + 20 byte IP header = 540 bytes
+ Packet 1: 1024 payload + 8 byte header + 20 byte IP header = 1052 bytes
+ Packet 2: 512 payload + 8 byte header + 20 byte IP header = 540 bytes
The coverage packet covers the UDP-Lite header and 848 bytes of the
payload in the first packet, the second packet is fully covered. Note
length in such cases.
As an example of what happens when one UDP-Lite packet is split into
- several tiny fragments, consider the following example.
+ several tiny fragments, consider the following example::
- Payload: 1024 bytes Send buffer size: 1024 bytes
- MTU: 300 bytes Coverage length: 575 bytes
+ Payload: 1024 bytes Send buffer size: 1024 bytes
+ MTU: 300 bytes Coverage length: 575 bytes
- +-+-----------+--------------+--------------+--------------+
- |8| 272 | 280 | 280 | 280 |
- +-+-----------+--------------+--------------+--------------+
- 280 560 840 1032
- ^
- *****checksum coverage*************
+ +-+-----------+--------------+--------------+--------------+
+ |8| 272 | 280 | 280 | 280 |
+ +-+-----------+--------------+--------------+--------------+
+ 280 560 840 1032
+ ^
+ *****checksum coverage*************
The UDP-Lite module generates one 1032 byte packet (1024 + 8 byte
header). According to the interface MTU, these are split into 4 IP
lengths), only the first fragment needs to be considered. When using
larger checksum coverage lengths, each eligible fragment needs to be
checksummed. Suppose we have a checksum coverage of 3062. The buffer
- of 3356 bytes will be split into the following fragments:
+ of 3356 bytes will be split into the following fragments::
Fragment 1: 1280 bytes carrying 1232 bytes of UDP-Lite data
Fragment 2: 1280 bytes carrying 1232 bytes of UDP-Lite data
performance over wireless (or generally noisy) links and thus smaller
coverage lengths are likely to be expected.
-
- V) UDP-LITE RUNTIME STATISTICS AND THEIR MEANING
+5. UDP-Lite Runtime Statistics and their Meaning
+================================================
Exceptional and error conditions are logged to syslog at the KERN_DEBUG
level. Live statistics about UDP-Lite are available in /proc/net/snmp
- and can (with newer versions of netstat) be viewed using
+ and can (with newer versions of netstat) be viewed using::
- netstat -svu
+ netstat -svu
This displays UDP-Lite statistics variables, whose meaning is as follows.
- InDatagrams: The total number of datagrams delivered to users.
+ ============ =====================================================
+ InDatagrams The total number of datagrams delivered to users.
- NoPorts: Number of packets received to an unknown port.
- These cases are counted separately (not as InErrors).
+ NoPorts Number of packets received to an unknown port.
+ These cases are counted separately (not as InErrors).
- InErrors: Number of erroneous UDP-Lite packets. Errors include:
- * internal socket queue receive errors
- * packet too short (less than 8 bytes or stated
- coverage length exceeds received length)
- * xfrm4_policy_check() returned with error
- * application has specified larger min. coverage
- length than that of incoming packet
- * checksum coverage violated
- * bad checksum
+ InErrors Number of erroneous UDP-Lite packets. Errors include:
- OutDatagrams: Total number of sent datagrams.
+ * internal socket queue receive errors
+ * packet too short (less than 8 bytes or stated
+ coverage length exceeds received length)
+ * xfrm4_policy_check() returned with error
+ * application has specified larger min. coverage
+ length than that of incoming packet
+ * checksum coverage violated
+ * bad checksum
- These statistics derive from the UDP MIB (RFC 2013).
+ OutDatagrams Total number of sent datagrams.
+ ============ =====================================================
+ These statistics derive from the UDP MIB (RFC 2013).
- VI) IPTABLES
+6. IPtables
+===========
There is packet match support for UDP-Lite as well as support for the LOG target.
- If you copy and paste the following line into /etc/protocols,
+ If you copy and paste the following line into /etc/protocols::
- udplite 136 UDP-Lite # UDP-Lite [RFC 3828]
+ udplite 136 UDP-Lite # UDP-Lite [RFC 3828]
- then
- iptables -A INPUT -p udplite -j LOG
+ then::
- will produce logging output to syslog. Dropping and rejecting packets also works.
+ iptables -A INPUT -p udplite -j LOG
+ will produce logging output to syslog. Dropping and rejecting packets also works.
- VII) MAINTAINER ADDRESS
+7. Maintainer Address
+=====================
The UDP-Lite patch was developed at
- University of Aberdeen
- Electronics Research Group
- Department of Engineering
- Fraser Noble Building
- Aberdeen AB24 3UE; UK
+
+ University of Aberdeen
+ Electronics Research Group
+ Department of Engineering
+ Fraser Noble Building
+ Aberdeen AB24 3UE; UK
+
The current maintainer is Gerrit Renker, <gerrit@erg.abdn.ac.uk>. Initial
code was developed by William Stanislaus, <william@erg.abdn.ac.uk>.
OSDN Git Service
