1ARP(7)                     Linux Programmer's Manual                    ARP(7)
2
3
4

NAME

6       arp - Linux ARP kernel module.
7

DESCRIPTION

9       This  kernel protocol module implements the Address Resolution Protocol
10       defined in RFC 826.  It is used  to  convert  between  Layer2  hardware
11       addresses  and  IPv4 protocol addresses on directly connected networks.
12       The user normally doesn't interact directly with this module except  to
13       configure  it; instead it provides a service for other protocols in the
14       kernel.
15
16       A user process can receive ARP  packets  by  using  packet(7)  sockets.
17       There  is  also a mechanism for managing the ARP cache in user-space by
18       using netlink(7) sockets.  The ARP table can  also  be  controlled  via
19       ioctl(2) on any AF_INET socket.
20
21       The ARP module maintains a cache of mappings between hardware addresses
22       and protocol addresses.  The cache has a limited size so old  and  less
23       frequently  used  entries  are  garbage-collected.   Entries  which are
24       marked as permanent are never deleted by  the  garbage-collector.   The
25       cache can be directly manipulated by the use of ioctls and its behavior
26       can be tuned by the /proc interfaces described below.
27
28       When there is no positive feedback for an existing mapping  after  some
29       time  (see  the /proc interfaces below), a neighbor cache entry is con‐
30       sidered stale.  Positive feedback can be gotten from  a  higher  layer;
31       for example from a successful TCP ACK.  Other protocols can signal for‐
32       ward progress using the MSG_CONFIRM flag to sendmsg(2).  When there  is
33       no  forward  progress,  ARP  tries to reprobe.  It first tries to ask a
34       local arp daemon app_solicit times for an updated MAC address.  If that
35       fails  and  an  old  MAC  address  is  known,  a  unicast probe is sent
36       ucast_solicit times.  If that fails too, it will broadcast  a  new  ARP
37       request  to  the  network.   Requests  are sent only when there is data
38       queued for sending.
39
40       Linux will automatically add a nonpermanent proxy  arp  entry  when  it
41       receives  a  request  for  an  address  it forwards to and proxy arp is
42       enabled on the receiving interface.  When there is a reject  route  for
43       the target, no proxy arp entry is added.
44
45   Ioctls
46       Three ioctls are available on all AF_INET sockets.  They take a pointer
47       to a struct arpreq as their argument.
48
49           struct arpreq {
50               struct sockaddr arp_pa;      /* protocol address */
51               struct sockaddr arp_ha;      /* hardware address */
52               int             arp_flags;   /* flags */
53               struct sockaddr arp_netmask; /* netmask of protocol address */
54               char            arp_dev[16];
55           };
56
57       SIOCSARP, SIOCDARP and SIOCGARP respectively set, delete and get an ARP
58       mapping.   Setting  and deleting ARP maps are privileged operations and
59       may be performed only by a process with the CAP_NET_ADMIN capability or
60       an effective UID of 0.
61
62       arp_pa must be an AF_INET address and arp_ha must have the same type as
63       the device which is specified in arp_dev.  arp_dev is a zero-terminated
64       string which names a device.
65
66              ┌─────────────────────────────────────┐
67arp_flags
68              ├────────────────┬────────────────────┤
69              │flag            │ meaning            │
70              ├────────────────┼────────────────────┤
71              │ATF_COM         │ Lookup complete    │
72              ├────────────────┼────────────────────┤
73              │ATF_PERM        │ Permanent entry    │
74              ├────────────────┼────────────────────┤
75              │ATF_PUBL        │ Publish entry      │
76              ├────────────────┼────────────────────┤
77              │ATF_USETRAILERS │ Trailers requested │
78              ├────────────────┼────────────────────┤
79              │ATF_NETMASK     │ Use a netmask      │
80              ├────────────────┼────────────────────┤
81              │ATF_DONTPUB     │ Don't answer       │
82              └────────────────┴────────────────────┘
83       If  the  ATF_NETMASK  flag  is  set,  then arp_netmask should be valid.
84       Linux 2.2 does not support proxy network ARP entries, so this should be
85       set  to  0xffffffff,  or  0  to  remove  an  existing  proxy arp entry.
86       ATF_USETRAILERS is obsolete and should not be used.
87
88   /proc interfaces
89       ARP supports a range of /proc interfaces to configure parameters  on  a
90       global or per-interface basis.  The interfaces can be accessed by read‐
91       ing or writing the /proc/sys/net/ipv4/neigh/*/* files.  Each  interface
92       in  the system has its own directory in /proc/sys/net/ipv4/neigh/.  The
93       setting in the "default"  directory  is  used  for  all  newly  created
94       devices.  Unless otherwise specified, time-related interfaces are spec‐
95       ified in seconds.
96
97       anycast_delay (since Linux 2.2)
98              The maximum number of jiffies to delay before replying to a IPv6
99              neighbor  solicitation  message.   Anycast  support  is  not yet
100              implemented.  Defaults to 1 second.
101
102       app_solicit (since Linux 2.2)
103              The maximum number of probes to send to the user space ARP  dae‐
104              mon  via  netlink  before dropping back to multicast probes (see
105              mcast_solicit).  Defaults to 0.
106
107       base_reachable_time (since Linux 2.2)
108              Once a neighbor has been found, the entry is  considered  to  be
109              valid  for at least a random value between base_reachable_time/2
110              and  3*base_reachable_time/2.   An  entry's  validity  will   be
111              extended if it receives positive feedback from higher level pro‐
112              tocols.  Defaults to 30 seconds.  This file is now  obsolete  in
113              favor of base_reachable_time_ms.
114
115       base_reachable_time_ms (since Linux 2.6.12)
116              As  for  base_reachable_time, but measures time in milliseconds.
117              Defaults to 30000 milliseconds.
118
119       delay_first_probe_time (since Linux 2.2)
120              Delay before first probe after it has been decided that a neigh‐
121              bor is stale.  Defaults to 5 seconds.
122
123       gc_interval (since Linux 2.2)
124              How frequently the garbage collector for neighbor entries should
125              attempt to run.  Defaults to 30 seconds.
126
127       gc_stale_time (since Linux 2.2)
128              Determines how often to check for stale neighbor entries.   When
129              a  neighbor  entry  is  considered  stale,  it is resolved again
130              before sending data to it.  Defaults to 60 seconds.
131
132       gc_thresh1 (since Linux 2.2)
133              The minimum number of entries to keep in  the  ARP  cache.   The
134              garbage collector will not run if there are fewer than this num‐
135              ber of entries in the cache.  Defaults to 128.
136
137       gc_thresh2 (since Linux 2.2)
138              The soft maximum number of entries to keep  in  the  ARP  cache.
139              The garbage collector will allow the number of entries to exceed
140              this  for  5  seconds  before  collection  will  be   performed.
141              Defaults to 512.
142
143       gc_thresh3 (since Linux 2.2)
144              The  hard  maximum  number  of entries to keep in the ARP cache.
145              The garbage collector will always run if  there  are  more  than
146              this number of entries in the cache.  Defaults to 1024.
147
148       locktime (since Linux 2.2)
149              The minimum number of jiffies to keep an ARP entry in the cache.
150              This prevents ARP cache thrashing if  there  is  more  than  one
151              potential  mapping  (generally due to network misconfiguration).
152              Defaults to 1 second.
153
154       mcast_solicit (since Linux 2.2)
155              The maximum number of attempts to resolve an address  by  multi‐
156              cast/broadcast   before   marking   the  entry  as  unreachable.
157              Defaults to 3.
158
159       proxy_delay (since Linux 2.2)
160              When an ARP request for a known proxy-ARP address  is  received,
161              delay  up  to proxy_delay jiffies before replying.  This is used
162              to prevent network flooding in some cases.  Defaults to 0.8 sec‐
163              onds.
164
165       proxy_qlen (since Linux 2.2)
166              The  maximum  number of packets which may be queued to proxy-ARP
167              addresses.  Defaults to 64.
168
169       retrans_time (since Linux 2.2)
170              The number of jiffies to delay before retransmitting a  request.
171              Defaults  to  1  second.   This file is now obsolete in favor of
172              retrans_time_ms.
173
174       retrans_time_ms (since Linux 2.6.12)
175              The number of milliseconds  to  delay  before  retransmitting  a
176              request.  Defaults to 1000 milliseconds.
177
178       ucast_solicit (since Linux 2.2)
179              The  maximum  number  of  attempts to send unicast probes before
180              asking the ARP daemon (see app_solicit).  Defaults to 3.
181
182       unres_qlen (since Linux 2.2)
183              The maximum number of packets which may be queued for each unre‐
184              solved address by other network layers.  Defaults to 3.
185

VERSIONS

187       The  struct  arpreq  changed in Linux 2.0 to include the arp_dev member
188       and the ioctl numbers changed at the same time.  Support  for  the  old
189       ioctls was dropped in Linux 2.2.
190
191       Support   for  proxy  arp  entries  for  networks  (netmask  not  equal
192       0xffffffff) was dropped in Linux 2.2.   It  is  replaced  by  automatic
193       proxy  arp  setup by the kernel for all reachable hosts on other inter‐
194       faces (when forwarding and proxy arp is enabled for the interface).
195
196       The neigh/* interfaces did not exist before Linux 2.2.
197

BUGS

199       Some timer settings are specified in jiffies,  which  is  architecture-
200       and kernel version-dependent; see time(7).
201
202       There  is  no  way  to  signal positive feedback from user space.  This
203       means connection-oriented protocols implemented in user space will gen‐
204       erate  excessive  ARP traffic, because ndisc will regularly reprobe the
205       MAC address.  The same problem applies for some kernel protocols (e.g.,
206       NFS over UDP).
207
208       This  man page mashes together functionality that is IPv4-specific with
209       functionality that is shared between IPv4 and IPv6.
210

SEE ALSO

212       capabilities(7), ip(7), arpd(8)
213
214       RFC 826 for a description of ARP.  RFC 2461 for a description  of  IPv6
215       neighbor  discovery  and the base algorithms used.  Linux 2.2+ IPv4 ARP
216       uses the IPv6 algorithms when applicable.
217

COLOPHON

219       This page is part of release 4.15 of the Linux  man-pages  project.   A
220       description  of  the project, information about reporting bugs, and the
221       latest    version    of    this    page,    can     be     found     at
222       https://www.kernel.org/doc/man-pages/.
223
224
225
226Linux                             2017-09-15                            ARP(7)
Impressum