docs: networking: convert udplite.txt to ReST

   timestamping

   tproxy

   tuntap

   udplite

.. only::  subproject and html

  ===========================================================================

.. 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/ 

   - 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):

   - 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.

  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,

  ::

      s = socket(PF_INET6, SOCK_DGRAM, IPPROTO_UDPLITE);

  With just the above change you are able to run UDP-Lite services or connect

    * Sender checksum coverage: UDPLITE_SEND_CSCOV

      For example,

      For example::

	int val = 20;

	setsockopt(s, SOL_UDPLITE, UDPLITE_SEND_CSCOV, &val, sizeof(int));

      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));

  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/udplite.h

      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,  ... );

  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, ...);

  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

  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

  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

  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

  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).

   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)

		      * checksum coverage violated

		      * bad checksum

   OutDatagrams:    Total number of sent datagrams.

   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]

  then

  then::

	      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

  The current maintainer is Gerrit Renker, <gerrit@erg.abdn.ac.uk>. Initial

  code was developed by William  Stanislaus, <william@erg.abdn.ac.uk>.