diff options
Diffstat (limited to 'man7/arp.7')
| -rw-r--r-- | man7/arp.7 | 306 |
1 files changed, 306 insertions, 0 deletions
diff --git a/man7/arp.7 b/man7/arp.7 new file mode 100644 index 0000000..a4ca6a6 --- /dev/null +++ b/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 2023-07-15 "Linux man-pages 6.05.01" +.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. +.PP +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. +.PP +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. +.PP +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. +.PP +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. +.PP +.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 +.PP +.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. +.PP +.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 +.PP +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. +.PP +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). +.PP +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). +.PP +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). +.PP +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) +.PP +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. |