Merging upstream version 6.8.

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 281 insertions, 0 deletions

diff --git a/man/man7/raw.7 b/man/man7/raw.7
new file mode 100644
index 0000000..44b1aff
--- /dev/null
+++ b/man/man7/raw.7
@@ -0,0 +1,281 @@
+'\" t
+.\" SPDX-License-Identifier: Linux-man-pages-1-para
+.\"
+.\" This man page is Copyright (C) 1999 Andi Kleen <ak@muc.de>.
+.\"
+.\" $Id: raw.7,v 1.6 1999/06/05 10:32:08 freitag Exp $
+.\"
+.TH raw 7 2024-05-02 "Linux man-pages (unreleased)"
+.SH NAME
+raw \- Linux IPv4 raw sockets
+.SH SYNOPSIS
+.nf
+.B #include <sys/socket.h>
+.B #include <netinet/in.h>
+.BI "raw_socket = socket(AF_INET, SOCK_RAW, int " protocol );
+.fi
+.SH DESCRIPTION
+Raw sockets allow new IPv4 protocols to be implemented in user space.
+A raw socket receives or sends the raw datagram not
+including link level headers.
+.P
+The IPv4 layer generates an IP header when sending a packet unless the
+.B IP_HDRINCL
+socket option is enabled on the socket.
+When it is enabled, the packet must contain an IP header.
+For receiving, the IP header is always included in the packet.
+.P
+In order to create a raw socket, a process must have the
+.B CAP_NET_RAW
+capability in the user namespace that governs its network namespace.
+.P
+All packets or errors matching the
+.I protocol
+number specified
+for the raw socket are passed to this socket.
+For a list of the allowed protocols,
+see the IANA list of assigned protocol numbers at
+.UR http://www.iana.org/assignments/protocol\-numbers/
+.UE
+and
+.BR getprotobyname (3).
+.P
+A protocol of
+.B IPPROTO_RAW
+implies enabled
+.B IP_HDRINCL
+and is able to send any IP protocol that is specified in the passed
+header.
+Receiving of all IP protocols via
+.B IPPROTO_RAW
+is not possible using raw sockets.
+.RS
+.TS
+tab(:) allbox;
+c s
+l l.
+IP Header fields modified on sending by \fBIP_HDRINCL\fP
+IP Checksum:Always filled in
+Source Address:Filled in when zero
+Packet ID:Filled in when zero
+Total Length:Always filled in
+.TE
+.RE
+.P
+If
+.B IP_HDRINCL
+is specified and the IP header has a nonzero destination address, then
+the destination address of the socket is used to route the packet.
+When
+.B MSG_DONTROUTE
+is specified, the destination address should refer to a local interface,
+otherwise a routing table lookup is done anyway but gatewayed routes
+are ignored.
+.P
+If
+.B IP_HDRINCL
+isn't set, then IP header options can be set on raw sockets with
+.BR setsockopt (2);
+see
+.BR ip (7)
+for more information.
+.P
+Starting with Linux 2.2, all IP header fields and options can be set using
+IP socket options.
+This means raw sockets are usually needed only for new
+protocols or protocols with no user interface (like ICMP).
+.P
+When a packet is received, it is passed to any raw sockets which have
+been bound to its protocol before it is passed to other protocol handlers
+(e.g., kernel protocol modules).
+.SS Address format
+For sending and receiving datagrams
+.RB ( sendto (2),
+.BR recvfrom (2),
+and similar),
+raw sockets use the standard
+.I sockaddr_in
+address structure defined in
+.BR ip (7).
+The
+.I sin_port
+field could be used to specify the IP protocol number,
+but it is ignored for sending in Linux 2.2 and later, and should be always
+set to 0 (see BUGS).
+For incoming packets,
+.I sin_port
+.\" commit f59fc7f30b710d45aadf715460b3e60dbe9d3418
+is set to zero.
+.SS Socket options
+Raw socket options can be set with
+.BR setsockopt (2)
+and read with
+.BR getsockopt (2)
+by passing the
+.B IPPROTO_RAW
+.\" Or SOL_RAW on Linux
+family flag.
+.TP
+.B ICMP_FILTER
+Enable a special filter for raw sockets bound to the
+.B IPPROTO_ICMP
+protocol.
+The value has a bit set for each ICMP message type which
+should be filtered out.
+The default is to filter no ICMP messages.
+.P
+In addition, all
+.BR ip (7)
+.B IPPROTO_IP
+socket options valid for datagram sockets are supported.
+.SS Error handling
+Errors originating from the network are passed to the user only when the
+socket is connected or the
+.B IP_RECVERR
+flag is enabled.
+For connected sockets, only
+.B EMSGSIZE
+and
+.B EPROTO
+are passed for compatibility.
+With
+.BR IP_RECVERR ,
+all network errors are saved in the error queue.
+.SH ERRORS
+.TP
+.B EACCES
+User tried to send to a broadcast address without having the
+broadcast flag set on the socket.
+.TP
+.B EFAULT
+An invalid memory address was supplied.
+.TP
+.B EINVAL
+Invalid argument.
+.TP
+.B EMSGSIZE
+Packet too big.
+Either Path MTU Discovery is enabled (the
+.B IP_MTU_DISCOVER
+socket flag) or the packet size exceeds the maximum allowed IPv4
+packet size of 64\ kB.
+.TP
+.B EOPNOTSUPP
+Invalid flag has been passed to a socket call (like
+.BR MSG_OOB ).
+.TP
+.B EPERM
+The user doesn't have permission to open raw sockets.
+Only processes with an effective user ID of 0 or the
+.B CAP_NET_RAW
+attribute may do that.
+.TP
+.B EPROTO
+An ICMP error has arrived reporting a parameter problem.
+.SH VERSIONS
+.B IP_RECVERR
+and
+.B ICMP_FILTER
+are new in Linux 2.2.
+They are Linux extensions and should not be used in portable programs.
+.P
+Linux 2.0 enabled some bug-to-bug compatibility with BSD in the
+raw socket code when the
+.B SO_BSDCOMPAT
+socket option was set; since Linux 2.2,
+this option no longer has that effect.
+.SH NOTES
+By default, raw sockets do path MTU (Maximum Transmission Unit) discovery.
+This means the kernel
+will keep track of the MTU to a specific target IP address and return
+.B EMSGSIZE
+when a raw packet write exceeds it.
+When this happens, the application should decrease the packet size.
+Path MTU discovery can be also turned off using the
+.B IP_MTU_DISCOVER
+socket option or the
+.I /proc/sys/net/ipv4/ip_no_pmtu_disc
+file, see
+.BR ip (7)
+for details.
+When turned off, raw sockets will fragment outgoing packets
+that exceed the interface MTU.
+However, disabling it is not recommended
+for performance and reliability reasons.
+.P
+A raw socket can be bound to a specific local address using the
+.BR bind (2)
+call.
+If it isn't bound, all packets with the specified IP protocol are received.
+In addition, a raw socket can be bound to a specific network device using
+.BR SO_BINDTODEVICE ;
+see
+.BR socket (7).
+.P
+An
+.B IPPROTO_RAW
+socket is send only.
+If you really want to receive all IP packets, use a
+.BR packet (7)
+socket with the
+.B ETH_P_IP
+protocol.
+Note that packet sockets don't reassemble IP fragments,
+unlike raw sockets.
+.P
+If you want to receive all ICMP packets for a datagram socket,
+it is often better to use
+.B IP_RECVERR
+on that particular socket; see
+.BR ip (7).
+.P
+Raw sockets may tap all IP protocols in Linux, even
+protocols like ICMP or TCP which have a protocol module in the kernel.
+In this case, the packets are passed to both the kernel module and the raw
+socket(s).
+This should not be relied upon in portable programs, many other BSD
+socket implementation have limitations here.
+.P
+Linux never changes headers passed from the user (except for filling
+in some zeroed fields as described for
+.BR IP_HDRINCL ).
+This differs from many other implementations of raw sockets.
+.P
+Raw sockets are generally rather unportable and should be avoided in
+programs intended to be portable.
+.P
+Sending on raw sockets should take the IP protocol from
+.IR sin_port ;
+this ability was lost in Linux 2.2.
+The workaround is to use
+.BR IP_HDRINCL .
+.SH BUGS
+Transparent proxy extensions are not described.
+.P
+When the
+.B IP_HDRINCL
+option is set, datagrams will not be fragmented and are limited to
+the interface MTU.
+.P
+Setting the IP protocol for sending in
+.I sin_port
+got lost in Linux 2.2.
+The protocol that the socket was bound to or that
+was specified in the initial
+.BR socket (2)
+call is always used.
+.\" .SH AUTHORS
+.\" This man page was written by Andi Kleen.
+.SH SEE ALSO
+.BR recvmsg (2),
+.BR sendmsg (2),
+.BR capabilities (7),
+.BR ip (7),
+.BR socket (7)
+.P
+.B RFC\ 1191
+for path MTU discovery.
+.B RFC\ 791
+and the
+.I <linux/ip.h>
+header file for the IP protocol.