Skip to content

L
linux
Commit 961fb1ff authored by Mauro Carvalho Chehab's avatar Mauro Carvalho Chehab Committed by David S. Miller
Browse files
Options

docs: networking: convert udplite.txt to ReST 

- add SPDX header;
- adjust titles and chapters, adding proper markups;
- mark lists as such;
- mark tables as such;
- mark code blocks and literals as such;
- adjust identation, whitespaces and blank lines where needed;
- add to networking/index.rst.
Signed-off-by: default avatarMauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: default avatarDavid S. Miller <davem@davemloft.net>
parent 973d55e5
Hide whitespace changes
Inline Side-by-side
Showing with 95 additions and 81 deletions
Documentation/networking/index.rst
View file @ 961fb1ff
......@@ -112,6 +112,7 @@ Contents:
timestamping
tproxy
tuntap
udplite
.. only:: subproject and html
......
Documentation/networking/udplite.txt → Documentation/networking/udplite.rst
View file @ 961fb1ff
===========================================================================
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
......@@ -11,39 +13,43 @@
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);
......@@ -56,10 +62,10 @@
* 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
......@@ -74,10 +80,10 @@
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
......@@ -85,18 +91,18 @@
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
......@@ -105,8 +111,9 @@
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).
......@@ -136,13 +143,13 @@
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.
......@@ -167,15 +174,15 @@
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
......@@ -184,17 +191,17 @@
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
......@@ -208,7 +215,7 @@
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
......@@ -222,57 +229,63 @@
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>.
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment
GitLab Nexedi Edition | About GitLab | About Nexedi | 沪ICP备2021021310号-2 | 沪ICP备2021021310号-7