| blob | a7915e4940927ebcc8babf53b27f00cc26a940cd |
1 '\" t
2 .\" SPDX-License-Identifier: Linux-man-pages-1-para
3 .\"
4 .\" This man page is Copyright (C) 1999 Matthew Wilcox <willy@bofh.ai>.
5 .\"
6 .\" Modified June 1999 Andi Kleen
7 .\" $Id: arp.7,v 1.10 2000/04/27 19:31:38 ak Exp $
8 .\"
9 .TH arp 7 (date) "Linux man-pages (unreleased)"
10 .SH NAME
11 arp \- Linux ARP kernel module.
12 .SH DESCRIPTION
13 This kernel protocol module implements the Address Resolution
14 Protocol defined in RFC\ 826.
15 It is used to convert between Layer2 hardware addresses
16 and IPv4 protocol addresses on directly connected networks.
17 The user normally doesn't interact directly with this module except to
18 configure it;
19 instead it provides a service for other protocols in the kernel.
20 .PP
21 A user process can receive ARP packets by using
22 .BR packet (7)
23 sockets.
24 There is also a mechanism for managing the ARP cache
25 in user-space by using
26 .BR netlink (7)
27 sockets.
28 The ARP table can also be controlled via
29 .BR ioctl (2)
30 on any
31 .B AF_INET
32 socket.
33 .PP
34 The ARP module maintains a cache of mappings between hardware addresses
35 and protocol addresses.
36 The cache has a limited size so old and less
37 frequently used entries are garbage-collected.
38 Entries which are marked
39 as permanent are never deleted by the garbage-collector.
40 The cache can
41 be directly manipulated by the use of ioctls and its behavior can be
42 tuned by the
43 .I /proc
44 interfaces described below.
45 .PP
46 When there is no positive feedback for an existing mapping after some
47 time (see the
48 .I /proc
49 interfaces below), a neighbor cache entry is considered stale.
50 Positive feedback can be gotten from a higher layer; for example from
51 a successful TCP ACK.
52 Other protocols can signal forward progress
53 using the
54 .B MSG_CONFIRM
55 flag to
56 .BR sendmsg (2).
57 When there is no forward progress, ARP tries to reprobe.
58 It first tries to ask a local arp daemon
59 .B app_solicit
60 times for an updated MAC address.
61 If that fails and an old MAC address is known, a unicast probe is sent
62 .B ucast_solicit
63 times.
64 If that fails too, it will broadcast a new ARP
65 request to the network.
66 Requests are sent only when there is data queued
67 for sending.
68 .PP
69 Linux will automatically add a nonpermanent proxy arp entry when it
70 receives a request for an address it forwards to and proxy arp is
71 enabled on the receiving interface.
72 When there is a reject route for the target, no proxy arp entry is added.
73 .SS Ioctls
74 Three ioctls are available on all
75 .B AF_INET
76 sockets.
77 They take a pointer to a
78 .I struct arpreq
79 as their argument.
80 .PP
81 .in +4n
82 .EX
83 struct arpreq {
84 struct sockaddr arp_pa; /* protocol address */
85 struct sockaddr arp_ha; /* hardware address */
86 int arp_flags; /* flags */
87 struct sockaddr arp_netmask; /* netmask of protocol address */
88 char arp_dev[16];
89 };
90 .EE
91 .in
92 .PP
93 .BR SIOCSARP ", " SIOCDARP " and " SIOCGARP
94 respectively set, delete, and get an ARP mapping.
95 Setting and deleting ARP maps are privileged operations and may
96 be performed only by a process with the
97 .B CAP_NET_ADMIN
98 capability or an effective UID of 0.
99 .PP
100 .I arp_pa
101 must be an
102 .B AF_INET
103 address and
104 .I arp_ha
105 must have the same type as the device which is specified in
106 .IR arp_dev .
107 .I arp_dev
108 is a zero-terminated string which names a device.
109 .RS
110 .TS
111 tab(:) allbox;
112 c s
113 l l.
114 \fIarp_flags\fR
115 flag:meaning
116 ATF_COM:Lookup complete
117 ATF_PERM:Permanent entry
118 ATF_PUBL:Publish entry
119 ATF_USETRAILERS:Trailers requested
120 ATF_NETMASK:Use a netmask
121 ATF_DONTPUB:Don't answer
122 .TE
123 .RE
124 .PP
125 If the
126 .B ATF_NETMASK
127 flag is set, then
128 .I arp_netmask
129 should be valid.
130 Linux 2.2 does not support proxy network ARP entries, so this
131 should be set to 0xffffffff, or 0 to remove an existing proxy arp entry.
132 .B ATF_USETRAILERS
133 is obsolete and should not be used.
134 .SS /proc interfaces
135 ARP supports a range of
136 .I /proc
137 interfaces to configure parameters on a global or per-interface basis.
138 The interfaces can be accessed by reading or writing the
139 .I /proc/sys/net/ipv4/neigh/*/*
140 files.
141 Each interface in the system has its own directory in
142 .IR /proc/sys/net/ipv4/neigh/ .
143 The setting in the "default" directory is used for all newly created
144 devices.
145 Unless otherwise specified, time-related interfaces are specified
146 in seconds.
147 .TP
148 .IR anycast_delay " (since Linux 2.2)"
149 .\" Precisely: 2.1.79
150 The maximum number of jiffies to delay before replying to a
151 IPv6 neighbor solicitation message.
152 Anycast support is not yet implemented.
153 Defaults to 1 second.
154 .TP
155 .IR app_solicit " (since Linux 2.2)"
156 .\" Precisely: 2.1.79
157 The maximum number of probes to send to the user space ARP daemon via
158 netlink before dropping back to multicast probes (see
159 .IR mcast_solicit ).
160 Defaults to 0.
161 .TP
162 .IR base_reachable_time " (since Linux 2.2)"
163 .\" Precisely: 2.1.79
164 Once a neighbor has been found, the entry is considered to be valid
165 for at least a random value between
166 .IR base_reachable_time "/2 and 3*" base_reachable_time /2.
167 An entry's validity will be extended if it receives positive feedback
168 from higher level protocols.
169 Defaults to 30 seconds.
170 This file is now obsolete in favor of
171 .IR base_reachable_time_ms .
172 .TP
173 .IR base_reachable_time_ms " (since Linux 2.6.12)"
174 As for
175 .IR base_reachable_time ,
176 but measures time in milliseconds.
177 Defaults to 30000 milliseconds.
178 .TP
179 .IR delay_first_probe_time " (since Linux 2.2)"
180 .\" Precisely: 2.1.79
181 Delay before first probe after it has been decided that a neighbor
182 is stale.
183 Defaults to 5 seconds.
184 .TP
185 .IR gc_interval " (since Linux 2.2)"
186 .\" Precisely: 2.1.79
187 How frequently the garbage collector for neighbor entries
188 should attempt to run.
189 Defaults to 30 seconds.
190 .TP
191 .IR gc_stale_time " (since Linux 2.2)"
192 .\" Precisely: 2.1.79
193 Determines how often to check for stale neighbor entries.
194 When a neighbor entry is considered stale, it is resolved again before
195 sending data to it.
196 Defaults to 60 seconds.
197 .TP
198 .IR gc_thresh1 " (since Linux 2.2)"
199 .\" Precisely: 2.1.79
200 The minimum number of entries to keep in the ARP cache.
201 The garbage collector will not run if there are fewer than
202 this number of entries in the cache.
203 Defaults to 128.
204 .TP
205 .IR gc_thresh2 " (since Linux 2.2)"
206 .\" Precisely: 2.1.79
207 The soft maximum number of entries to keep in the ARP cache.
208 The garbage collector will allow the number of entries to exceed
209 this for 5 seconds before collection will be performed.
210 Defaults to 512.
211 .TP
212 .IR gc_thresh3 " (since Linux 2.2)"
213 .\" Precisely: 2.1.79
214 The hard maximum number of entries to keep in the ARP cache.
215 The garbage collector will always run if there are more than
216 this number of entries in the cache.
217 Defaults to 1024.
218 .TP
219 .IR locktime " (since Linux 2.2)"
220 .\" Precisely: 2.1.79
221 The minimum number of jiffies to keep an ARP entry in the cache.
222 This prevents ARP cache thrashing if there is more than one potential
223 mapping (generally due to network misconfiguration).
224 Defaults to 1 second.
225 .TP
226 .IR mcast_solicit " (since Linux 2.2)"
227 .\" Precisely: 2.1.79
228 The maximum number of attempts to resolve an address by
229 multicast/broadcast before marking the entry as unreachable.
230 Defaults to 3.
231 .TP
232 .IR proxy_delay " (since Linux 2.2)"
233 .\" Precisely: 2.1.79
234 When an ARP request for a known proxy-ARP address is received, delay up to
235 .I proxy_delay
236 jiffies before replying.
237 This is used to prevent network flooding in some cases.
238 Defaults to 0.8 seconds.
239 .TP
240 .IR proxy_qlen " (since Linux 2.2)"
241 .\" Precisely: 2.1.79
242 The maximum number of packets which may be queued to proxy-ARP addresses.
243 Defaults to 64.
244 .TP
245 .IR retrans_time " (since Linux 2.2)"
246 .\" Precisely: 2.1.79
247 The number of jiffies to delay before retransmitting a request.
248 Defaults to 1 second.
249 This file is now obsolete in favor of
250 .IR retrans_time_ms .
251 .TP
252 .IR retrans_time_ms " (since Linux 2.6.12)"
253 The number of milliseconds to delay before retransmitting a request.
254 Defaults to 1000 milliseconds.
255 .TP
256 .IR ucast_solicit " (since Linux 2.2)"
257 .\" Precisely: 2.1.79
258 The maximum number of attempts to send unicast probes before asking
259 the ARP daemon (see
260 .IR app_solicit ).
261 Defaults to 3.
262 .TP
263 .IR unres_qlen " (since Linux 2.2)"
264 .\" Precisely: 2.1.79
265 The maximum number of packets which may be queued for each unresolved
266 address by other network layers.
267 Defaults to 3.
268 .SH VERSIONS
269 The
270 .I struct arpreq
271 changed in Linux 2.0 to include the
272 .I arp_dev
273 member and the ioctl numbers changed at the same time.
274 Support for the old ioctls was dropped in Linux 2.2.
275 .PP
276 Support for proxy arp entries for networks (netmask not equal 0xffffffff)
277 was dropped in Linux 2.2.
278 It is replaced by automatic proxy arp setup by
279 the kernel for all reachable hosts on other interfaces (when
280 forwarding and proxy arp is enabled for the interface).
281 .PP
282 The
283 .I neigh/*
284 interfaces did not exist before Linux 2.2.
285 .SH BUGS
286 Some timer settings are specified in jiffies, which is architecture-
287 and kernel version-dependent; see
288 .BR time (7).
289 .PP
290 There is no way to signal positive feedback from user space.
291 This means connection-oriented protocols implemented in user space
292 will generate excessive ARP traffic, because ndisc will regularly
293 reprobe the MAC address.
294 The same problem applies for some kernel protocols (e.g., NFS over UDP).
295 .PP
296 This man page mashes together functionality that is IPv4-specific
297 with functionality that is shared between IPv4 and IPv6.
298 .SH SEE ALSO
299 .BR capabilities (7),
300 .BR ip (7),
301 .BR arpd (8)
302 .PP
303 RFC\ 826 for a description of ARP.
304 RFC\ 2461 for a description of IPv6 neighbor discovery and the base
305 algorithms used.
306 Linux 2.2+ IPv4 ARP uses the IPv6 algorithms when applicable.