Merging upstream version 6.8.

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

1 files changed, 306 insertions, 0 deletions

diff --git a/man/man7/arp.7 b/man/man7/arp.7
new file mode 100644
index 0000000..59f0813
--- /dev/null
+++ b/man/man7/arp.7
@@ -0,0 +1,306 @@
+'\" t
+.\" SPDX-License-Identifier: Linux-man-pages-1-para
+.\"
+.\" This man page is Copyright (C) 1999 Matthew Wilcox <willy@bofh.ai>.
+.\"
+.\" Modified June 1999 Andi Kleen
+.\" $Id: arp.7,v 1.10 2000/04/27 19:31:38 ak Exp $
+.\"
+.TH arp 7 2024-05-02 "Linux man-pages (unreleased)"
+.SH NAME
+arp \- Linux ARP kernel module.
+.SH DESCRIPTION
+This kernel protocol module implements the Address Resolution
+Protocol defined in RFC\ 826.
+It is used to convert between Layer2 hardware addresses
+and IPv4 protocol addresses on directly connected networks.
+The user normally doesn't interact directly with this module except to
+configure it;
+instead it provides a service for other protocols in the kernel.
+.P
+A user process can receive ARP packets by using
+.BR packet (7)
+sockets.
+There is also a mechanism for managing the ARP cache
+in user-space by using
+.BR netlink (7)
+sockets.
+The ARP table can also be controlled via
+.BR ioctl (2)
+on any
+.B AF_INET
+socket.
+.P
+The ARP module maintains a cache of mappings between hardware addresses
+and protocol addresses.
+The cache has a limited size so old and less
+frequently used entries are garbage-collected.
+Entries which are marked
+as permanent are never deleted by the garbage-collector.
+The cache can
+be directly manipulated by the use of ioctls and its behavior can be
+tuned by the
+.I /proc
+interfaces described below.
+.P
+When there is no positive feedback for an existing mapping after some
+time (see the
+.I /proc
+interfaces below), a neighbor cache entry is considered stale.
+Positive feedback can be gotten from a higher layer; for example from
+a successful TCP ACK.
+Other protocols can signal forward progress
+using the
+.B MSG_CONFIRM
+flag to
+.BR sendmsg (2).
+When there is no forward progress, ARP tries to reprobe.
+It first tries to ask a local arp daemon
+.B app_solicit
+times for an updated MAC address.
+If that fails and an old MAC address is known, a unicast probe is sent
+.B ucast_solicit
+times.
+If that fails too, it will broadcast a new ARP
+request to the network.
+Requests are sent only when there is data queued
+for sending.
+.P
+Linux will automatically add a nonpermanent proxy arp entry when it
+receives a request for an address it forwards to and proxy arp is
+enabled on the receiving interface.
+When there is a reject route for the target, no proxy arp entry is added.
+.SS Ioctls
+Three ioctls are available on all
+.B AF_INET
+sockets.
+They take a pointer to a
+.I struct arpreq
+as their argument.
+.P
+.in +4n
+.EX
+struct arpreq {
+    struct sockaddr arp_pa;      /* protocol address */
+    struct sockaddr arp_ha;      /* hardware address */
+    int             arp_flags;   /* flags */
+    struct sockaddr arp_netmask; /* netmask of protocol address */
+    char            arp_dev[16];
+};
+.EE
+.in
+.P
+.BR SIOCSARP ", " SIOCDARP " and " SIOCGARP
+respectively set, delete, and get an ARP mapping.
+Setting and deleting ARP maps are privileged operations and may
+be performed only by a process with the
+.B CAP_NET_ADMIN
+capability or an effective UID of 0.
+.P
+.I arp_pa
+must be an
+.B AF_INET
+address and
+.I arp_ha
+must have the same type as the device which is specified in
+.IR arp_dev .
+.I arp_dev
+is a zero-terminated string which names a device.
+.RS
+.TS
+tab(:) allbox;
+c s
+l l.
+\fIarp_flags\fR
+flag:meaning
+ATF_COM:Lookup complete
+ATF_PERM:Permanent entry
+ATF_PUBL:Publish entry
+ATF_USETRAILERS:Trailers requested
+ATF_NETMASK:Use a netmask
+ATF_DONTPUB:Don't answer
+.TE
+.RE
+.P
+If the
+.B ATF_NETMASK
+flag is set, then
+.I arp_netmask
+should be valid.
+Linux 2.2 does not support proxy network ARP entries, so this
+should be set to 0xffffffff, or 0 to remove an existing proxy arp entry.
+.B ATF_USETRAILERS
+is obsolete and should not be used.
+.SS /proc interfaces
+ARP supports a range of
+.I /proc
+interfaces to configure parameters on a global or per-interface basis.
+The interfaces can be accessed by reading or writing the
+.I /proc/sys/net/ipv4/neigh/*/*
+files.
+Each interface in the system has its own directory in
+.IR /proc/sys/net/ipv4/neigh/ .
+The setting in the "default" directory is used for all newly created
+devices.
+Unless otherwise specified, time-related interfaces are specified
+in seconds.
+.TP
+.IR anycast_delay " (since Linux 2.2)"
+.\" Precisely: 2.1.79
+The maximum number of jiffies to delay before replying to a
+IPv6 neighbor solicitation message.
+Anycast support is not yet implemented.
+Defaults to 1 second.
+.TP
+.IR app_solicit " (since Linux 2.2)"
+.\" Precisely: 2.1.79
+The maximum number of probes to send to the user space ARP daemon via
+netlink before dropping back to multicast probes (see
+.IR mcast_solicit ).
+Defaults to 0.
+.TP
+.IR base_reachable_time " (since Linux 2.2)"
+.\" Precisely: 2.1.79
+Once a neighbor has been found, the entry is considered to be valid
+for at least a random value between
+.IR base_reachable_time "/2 and 3*" base_reachable_time /2.
+An entry's validity will be extended if it receives positive feedback
+from higher level protocols.
+Defaults to 30 seconds.
+This file is now obsolete in favor of
+.IR base_reachable_time_ms .
+.TP
+.IR base_reachable_time_ms " (since Linux 2.6.12)"
+As for
+.IR base_reachable_time ,
+but measures time in milliseconds.
+Defaults to 30000 milliseconds.
+.TP
+.IR delay_first_probe_time " (since Linux 2.2)"
+.\" Precisely: 2.1.79
+Delay before first probe after it has been decided that a neighbor
+is stale.
+Defaults to 5 seconds.
+.TP
+.IR gc_interval " (since Linux 2.2)"
+.\" Precisely: 2.1.79
+How frequently the garbage collector for neighbor entries
+should attempt to run.
+Defaults to 30 seconds.
+.TP
+.IR gc_stale_time " (since Linux 2.2)"
+.\" Precisely: 2.1.79
+Determines how often to check for stale neighbor entries.
+When a neighbor entry is considered stale, it is resolved again before
+sending data to it.
+Defaults to 60 seconds.
+.TP
+.IR gc_thresh1 " (since Linux 2.2)"
+.\" Precisely: 2.1.79
+The minimum number of entries to keep in the ARP cache.
+The garbage collector will not run if there are fewer than
+this number of entries in the cache.
+Defaults to 128.
+.TP
+.IR gc_thresh2 " (since Linux 2.2)"
+.\" Precisely: 2.1.79
+The soft maximum number of entries to keep in the ARP cache.
+The garbage collector will allow the number of entries to exceed
+this for 5 seconds before collection will be performed.
+Defaults to 512.
+.TP
+.IR gc_thresh3 " (since Linux 2.2)"
+.\" Precisely: 2.1.79
+The hard maximum number of entries to keep in the ARP cache.
+The garbage collector will always run if there are more than
+this number of entries in the cache.
+Defaults to 1024.
+.TP
+.IR locktime " (since Linux 2.2)"
+.\" Precisely: 2.1.79
+The minimum number of jiffies to keep an ARP entry in the cache.
+This prevents ARP cache thrashing if there is more than one potential
+mapping (generally due to network misconfiguration).
+Defaults to 1 second.
+.TP
+.IR mcast_solicit " (since Linux 2.2)"
+.\" Precisely: 2.1.79
+The maximum number of attempts to resolve an address by
+multicast/broadcast before marking the entry as unreachable.
+Defaults to 3.
+.TP
+.IR proxy_delay " (since Linux 2.2)"
+.\" Precisely: 2.1.79
+When an ARP request for a known proxy-ARP address is received, delay up to
+.I proxy_delay
+jiffies before replying.
+This is used to prevent network flooding in some cases.
+Defaults to 0.8 seconds.
+.TP
+.IR proxy_qlen " (since Linux 2.2)"
+.\" Precisely: 2.1.79
+The maximum number of packets which may be queued to proxy-ARP addresses.
+Defaults to 64.
+.TP
+.IR retrans_time " (since Linux 2.2)"
+.\" Precisely: 2.1.79
+The number of jiffies to delay before retransmitting a request.
+Defaults to 1 second.
+This file is now obsolete in favor of
+.IR retrans_time_ms .
+.TP
+.IR retrans_time_ms " (since Linux 2.6.12)"
+The number of milliseconds to delay before retransmitting a request.
+Defaults to 1000 milliseconds.
+.TP
+.IR ucast_solicit " (since Linux 2.2)"
+.\" Precisely: 2.1.79
+The maximum number of attempts to send unicast probes before asking
+the ARP daemon (see
+.IR app_solicit ).
+Defaults to 3.
+.TP
+.IR unres_qlen " (since Linux 2.2)"
+.\" Precisely: 2.1.79
+The maximum number of packets which may be queued for each unresolved
+address by other network layers.
+Defaults to 3.
+.SH VERSIONS
+The
+.I struct arpreq
+changed in Linux 2.0 to include the
+.I arp_dev
+member and the ioctl numbers changed at the same time.
+Support for the old ioctls was dropped in Linux 2.2.
+.P
+Support for proxy arp entries for networks (netmask not equal 0xffffffff)
+was dropped in Linux 2.2.
+It is replaced by automatic proxy arp setup by
+the kernel for all reachable hosts on other interfaces (when
+forwarding and proxy arp is enabled for the interface).
+.P
+The
+.I neigh/*
+interfaces did not exist before Linux 2.2.
+.SH BUGS
+Some timer settings are specified in jiffies, which is architecture-
+and kernel version-dependent; see
+.BR time (7).
+.P
+There is no way to signal positive feedback from user space.
+This means connection-oriented protocols implemented in user space
+will generate excessive ARP traffic, because ndisc will regularly
+reprobe the MAC address.
+The same problem applies for some kernel protocols (e.g., NFS over UDP).
+.P
+This man page mashes together functionality that is IPv4-specific
+with functionality that is shared between IPv4 and IPv6.
+.SH SEE ALSO
+.BR capabilities (7),
+.BR ip (7),
+.BR arpd (8)
+.P
+RFC\ 826 for a description of ARP.
+RFC\ 2461 for a description of IPv6 neighbor discovery and the base
+algorithms used.
+Linux 2.2+ IPv4 ARP uses the IPv6 algorithms when applicable.