mirror of
https://git.kernel.org/pub/scm/linux/kernel/git/next/linux-next.git
synced 2024-12-29 17:22:07 +00:00
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: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: David S. Miller <davem@davemloft.net>
This commit is contained in:
Mauro Carvalho Chehab
David S. Miller
parent
973d55e590
commit
961fb1ff41
@ -112,6 +112,7 @@ Contents:
|
|||||||
timestamping
|
timestamping
|
||||||
tproxy
|
tproxy
|
||||||
tuntap
|
tuntap
|
||||||
|
udplite
|
||||||
|
|
||||||
.. only:: subproject and html
|
.. only:: subproject and html
|
||||||
|
|
||||||
|
|||||||
@ -1,6 +1,8 @@
|
|||||||
===========================================================================
|
.. SPDX-License-Identifier: GPL-2.0
|
||||||
The UDP-Lite protocol (RFC 3828)
|
|
||||||
===========================================================================
|
================================
|
||||||
|
The UDP-Lite protocol (RFC 3828)
|
||||||
|
================================
|
||||||
|
|
||||||
|
|
||||||
UDP-Lite is a Standards-Track IETF transport protocol whose characteristic
|
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.
|
This file briefly describes the existing kernel support and the socket API.
|
||||||
For in-depth information, you can consult:
|
For in-depth information, you can consult:
|
||||||
|
|
||||||
o The UDP-Lite Homepage:
|
- The UDP-Lite Homepage:
|
||||||
http://web.archive.org/web/*/http://www.erg.abdn.ac.uk/users/gerrit/udp-lite/
|
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
|
From here you can also download some example application source code.
|
||||||
http://web.archive.org/web/*/http://www.erg.abdn.ac.uk/users/gerrit/udp-lite/
|
|
||||||
files/UDP-Lite-HOWTO.txt
|
|
||||||
|
|
||||||
o The Wireshark UDP-Lite WiKi (with capture files):
|
- The UDP-Lite HOWTO on
|
||||||
https://wiki.wireshark.org/Lightweight_User_Datagram_Protocol
|
http://web.archive.org/web/%2E/http://www.erg.abdn.ac.uk/users/gerrit/udp-lite/files/UDP-Lite-HOWTO.txt
|
||||||
|
|
||||||
o The Protocol Spec, RFC 3828, http://www.ietf.org/rfc/rfc3828.txt
|
- The Wireshark UDP-Lite WiKi (with capture files):
|
||||||
|
https://wiki.wireshark.org/Lightweight_User_Datagram_Protocol
|
||||||
|
|
||||||
|
- 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
|
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
|
Porting applications to UDP-Lite is straightforward: only socket level and
|
||||||
IPPROTO need to be changed; senders additionally set the checksum coverage
|
IPPROTO need to be changed; senders additionally set the checksum coverage
|
||||||
length (default = header length = 8). Details are in the next section.
|
length (default = header length = 8). Details are in the next section.
|
||||||
|
|
||||||
|
2. Programming API
|
||||||
II) PROGRAMMING API
|
==================
|
||||||
|
|
||||||
UDP-Lite provides a connectionless, unreliable datagram service and hence
|
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
|
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)
|
very easy: simply add ``IPPROTO_UDPLITE`` as the last argument of the
|
||||||
call so that the statement looks like:
|
socket(2) call so that the statement looks like::
|
||||||
|
|
||||||
s = socket(PF_INET, SOCK_DGRAM, IPPROTO_UDPLITE);
|
s = socket(PF_INET, SOCK_DGRAM, IPPROTO_UDPLITE);
|
||||||
|
|
||||||
or, respectively,
|
or, respectively,
|
||||||
|
|
||||||
|
::
|
||||||
|
|
||||||
s = socket(PF_INET6, SOCK_DGRAM, IPPROTO_UDPLITE);
|
s = socket(PF_INET6, SOCK_DGRAM, IPPROTO_UDPLITE);
|
||||||
|
|
||||||
@ -56,10 +62,10 @@
|
|||||||
|
|
||||||
* Sender checksum coverage: UDPLITE_SEND_CSCOV
|
* Sender checksum coverage: UDPLITE_SEND_CSCOV
|
||||||
|
|
||||||
For example,
|
For example::
|
||||||
|
|
||||||
int val = 20;
|
int val = 20;
|
||||||
setsockopt(s, SOL_UDPLITE, UDPLITE_SEND_CSCOV, &val, sizeof(int));
|
setsockopt(s, SOL_UDPLITE, UDPLITE_SEND_CSCOV, &val, sizeof(int));
|
||||||
|
|
||||||
sets the checksum coverage length to 20 bytes (12b data + 8b header).
|
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
|
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
|
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
|
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
|
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;
|
int min = 20;
|
||||||
setsockopt(s, SOL_UDPLITE, UDPLITE_RECV_CSCOV, &min, sizeof(int));
|
setsockopt(s, SOL_UDPLITE, UDPLITE_RECV_CSCOV, &min, sizeof(int));
|
||||||
|
|
||||||
The calls to getsockopt(2) are analogous. Being an extension and not a stand-
|
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
|
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.
|
A detailed discussion of UDP-Lite checksum coverage options is in section IV.
|
||||||
|
|
||||||
|
3. Header Files
|
||||||
III) HEADER FILES
|
===============
|
||||||
|
|
||||||
The socket API requires support through header files in /usr/include:
|
The socket API requires support through header files in /usr/include:
|
||||||
|
|
||||||
* /usr/include/netinet/in.h
|
* /usr/include/netinet/in.h
|
||||||
to define IPPROTO_UDPLITE
|
to define IPPROTO_UDPLITE
|
||||||
|
|
||||||
* /usr/include/netinet/udplite.h
|
* /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 IPPROTO_UDPLITE 136
|
||||||
#define SOL_UDPLITE 136
|
#define SOL_UDPLITE 136
|
||||||
@ -105,8 +111,9 @@
|
|||||||
|
|
||||||
Ready-made header files for various distros are in the UDP-Lite tarball.
|
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
|
To enable debugging messages, the log level need to be set to 8, as most
|
||||||
messages use the KERN_DEBUG level (7).
|
messages use the KERN_DEBUG level (7).
|
||||||
@ -136,13 +143,13 @@
|
|||||||
3) Disabling the Checksum Computation
|
3) Disabling the Checksum Computation
|
||||||
|
|
||||||
On both sender and receiver, checksumming will always be performed
|
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
|
is meaningless (as in TCP). Packets with a zero checksum field are
|
||||||
illegal (cf. RFC 3828, sec. 3.1) and will be silently discarded.
|
illegal (cf. RFC 3828, sec. 3.1) and will be silently discarded.
|
||||||
@ -167,15 +174,15 @@
|
|||||||
first one contains the L4 header.
|
first one contains the L4 header.
|
||||||
|
|
||||||
The send buffer size has implications on the checksum coverage length.
|
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
|
Payload: 1536 bytes Send Buffer: 1024 bytes
|
||||||
MTU: 1500 bytes Coverage Length: 856 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 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 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
|
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
|
payload in the first packet, the second packet is fully covered. Note
|
||||||
@ -184,17 +191,17 @@
|
|||||||
length in such cases.
|
length in such cases.
|
||||||
|
|
||||||
As an example of what happens when one UDP-Lite packet is split into
|
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
|
Payload: 1024 bytes Send buffer size: 1024 bytes
|
||||||
MTU: 300 bytes Coverage length: 575 bytes
|
MTU: 300 bytes Coverage length: 575 bytes
|
||||||
|
|
||||||
+-+-----------+--------------+--------------+--------------+
|
+-+-----------+--------------+--------------+--------------+
|
||||||
|8| 272 | 280 | 280 | 280 |
|
|8| 272 | 280 | 280 | 280 |
|
||||||
+-+-----------+--------------+--------------+--------------+
|
+-+-----------+--------------+--------------+--------------+
|
||||||
280 560 840 1032
|
280 560 840 1032
|
||||||
^
|
^
|
||||||
*****checksum coverage*************
|
*****checksum coverage*************
|
||||||
|
|
||||||
The UDP-Lite module generates one 1032 byte packet (1024 + 8 byte
|
The UDP-Lite module generates one 1032 byte packet (1024 + 8 byte
|
||||||
header). According to the interface MTU, these are split into 4 IP
|
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
|
lengths), only the first fragment needs to be considered. When using
|
||||||
larger checksum coverage lengths, each eligible fragment needs to be
|
larger checksum coverage lengths, each eligible fragment needs to be
|
||||||
checksummed. Suppose we have a checksum coverage of 3062. The buffer
|
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 1: 1280 bytes carrying 1232 bytes of UDP-Lite data
|
||||||
Fragment 2: 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
|
performance over wireless (or generally noisy) links and thus smaller
|
||||||
coverage lengths are likely to be expected.
|
coverage lengths are likely to be expected.
|
||||||
|
|
||||||
|
5. UDP-Lite Runtime Statistics and their Meaning
|
||||||
V) UDP-LITE RUNTIME STATISTICS AND THEIR MEANING
|
================================================
|
||||||
|
|
||||||
Exceptional and error conditions are logged to syslog at the KERN_DEBUG
|
Exceptional and error conditions are logged to syslog at the KERN_DEBUG
|
||||||
level. Live statistics about UDP-Lite are available in /proc/net/snmp
|
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.
|
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.
|
NoPorts Number of packets received to an unknown port.
|
||||||
These cases are counted separately (not as InErrors).
|
These cases are counted separately (not as InErrors).
|
||||||
|
|
||||||
InErrors: Number of erroneous UDP-Lite packets. Errors include:
|
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
|
|
||||||
|
|
||||||
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
|
||||||
|
|
||||||
|
OutDatagrams Total number of sent datagrams.
|
||||||
|
============ =====================================================
|
||||||
|
|
||||||
These statistics derive from the UDP MIB (RFC 2013).
|
These statistics derive from the UDP MIB (RFC 2013).
|
||||||
|
|
||||||
|
6. IPtables
|
||||||
VI) IPTABLES
|
===========
|
||||||
|
|
||||||
There is packet match support for UDP-Lite as well as support for the LOG target.
|
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
|
then::
|
||||||
iptables -A INPUT -p udplite -j LOG
|
|
||||||
|
iptables -A INPUT -p udplite -j LOG
|
||||||
|
|
||||||
will produce logging output to syslog. Dropping and rejecting packets also works.
|
will produce logging output to syslog. Dropping and rejecting packets also works.
|
||||||
|
|
||||||
|
7. Maintainer Address
|
||||||
VII) MAINTAINER ADDRESS
|
=====================
|
||||||
|
|
||||||
The UDP-Lite patch was developed at
|
The UDP-Lite patch was developed at
|
||||||
University of Aberdeen
|
|
||||||
Electronics Research Group
|
University of Aberdeen
|
||||||
Department of Engineering
|
Electronics Research Group
|
||||||
Fraser Noble Building
|
Department of Engineering
|
||||||
Aberdeen AB24 3UE; UK
|
Fraser Noble Building
|
||||||
|
Aberdeen AB24 3UE; UK
|
||||||
|
|
||||||
The current maintainer is Gerrit Renker, <gerrit@erg.abdn.ac.uk>. Initial
|
The current maintainer is Gerrit Renker, <gerrit@erg.abdn.ac.uk>. Initial
|
||||||
code was developed by William Stanislaus, <william@erg.abdn.ac.uk>.
|
code was developed by William Stanislaus, <william@erg.abdn.ac.uk>.
|
||||||
Loading…
Reference in New Issue
Block a user