]>
Commit | Line | Data |
---|---|---|
a1eaacb1 | 1 | '\" t |
7c4ddad1 AC |
2 | .\" SPDX-License-Identifier: Linux-man-pages-1-para |
3 | .\" | |
77117f4f | 4 | .\" This man page is Copyright (C) 1999 Matthew Wilcox <willy@bofh.ai>. |
6a717e5e | 5 | .\" |
77117f4f MK |
6 | .\" Modified June 1999 Andi Kleen |
7 | .\" $Id: arp.7,v 1.10 2000/04/27 19:31:38 ak Exp $ | |
6a717e5e | 8 | .\" |
4c1c5274 | 9 | .TH arp 7 (date) "Linux man-pages (unreleased)" |
77117f4f MK |
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. | |
c6d039a3 | 20 | .P |
77117f4f MK |
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 | |
d4c8c97c | 31 | .B AF_INET |
77117f4f | 32 | socket. |
c6d039a3 | 33 | .P |
77117f4f MK |
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 | |
5a2ff571 MK |
42 | tuned by the |
43 | .I /proc | |
44 | interfaces described below. | |
c6d039a3 | 45 | .P |
77117f4f | 46 | When there is no positive feedback for an existing mapping after some |
a113945f | 47 | time (see the |
5a2ff571 | 48 | .I /proc |
caf5129c | 49 | interfaces below), a neighbor cache entry is considered stale. |
77117f4f MK |
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). | |
caf5129c | 57 | When there is no forward progress, ARP tries to reprobe. |
77117f4f MK |
58 | It first tries to ask a local arp daemon |
59 | .B app_solicit | |
60 | times for an updated MAC address. | |
caf5129c | 61 | If that fails and an old MAC address is known, a unicast probe is sent |
77117f4f MK |
62 | .B ucast_solicit |
63 | times. | |
caf5129c | 64 | If that fails too, it will broadcast a new ARP |
77117f4f | 65 | request to the network. |
33a0ccb2 | 66 | Requests are sent only when there is data queued |
77117f4f | 67 | for sending. |
c6d039a3 | 68 | .P |
24b74457 | 69 | Linux will automatically add a nonpermanent proxy arp entry when it |
77117f4f MK |
70 | receives a request for an address it forwards to and proxy arp is |
71 | enabled on the receiving interface. | |
caf5129c | 72 | When there is a reject route for the target, no proxy arp entry is added. |
77117f4f MK |
73 | .SS Ioctls |
74 | Three ioctls are available on all | |
d4c8c97c | 75 | .B AF_INET |
77117f4f MK |
76 | sockets. |
77 | They take a pointer to a | |
78 | .I struct arpreq | |
79 | as their argument. | |
c6d039a3 | 80 | .P |
77117f4f | 81 | .in +4n |
b8302363 | 82 | .EX |
77117f4f MK |
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 | }; | |
b8302363 | 90 | .EE |
77117f4f | 91 | .in |
c6d039a3 | 92 | .P |
77117f4f | 93 | .BR SIOCSARP ", " SIOCDARP " and " SIOCGARP |
735334d4 | 94 | respectively set, delete, and get an ARP mapping. |
caf5129c | 95 | Setting and deleting ARP maps are privileged operations and may |
33a0ccb2 | 96 | be performed only by a process with the |
77117f4f MK |
97 | .B CAP_NET_ADMIN |
98 | capability or an effective UID of 0. | |
c6d039a3 | 99 | .P |
77117f4f MK |
100 | .I arp_pa |
101 | must be an | |
102 | .B AF_INET | |
d3bd4b52 | 103 | address and |
77117f4f MK |
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 | |
c6d039a3 | 124 | .P |
77117f4f MK |
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. | |
5a2ff571 MK |
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 | |
77117f4f | 139 | .I /proc/sys/net/ipv4/neigh/*/* |
5a2ff571 | 140 | files. |
77117f4f | 141 | Each interface in the system has its own directory in |
5a2ff571 | 142 | .IR /proc/sys/net/ipv4/neigh/ . |
77117f4f MK |
143 | The setting in the "default" directory is used for all newly created |
144 | devices. | |
caf5129c | 145 | Unless otherwise specified, time-related interfaces are specified |
77117f4f MK |
146 | in seconds. |
147 | .TP | |
665baea5 MK |
148 | .IR anycast_delay " (since Linux 2.2)" |
149 | .\" Precisely: 2.1.79 | |
77117f4f MK |
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 | |
665baea5 MK |
155 | .IR app_solicit " (since Linux 2.2)" |
156 | .\" Precisely: 2.1.79 | |
77117f4f MK |
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 | |
665baea5 MK |
162 | .IR base_reachable_time " (since Linux 2.2)" |
163 | .\" Precisely: 2.1.79 | |
77117f4f MK |
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. | |
f35067be | 170 | This file is now obsolete in favor of |
5adbf2d4 MK |
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 , | |
f35067be | 176 | but measures time in milliseconds. |
5adbf2d4 | 177 | Defaults to 30000 milliseconds. |
77117f4f | 178 | .TP |
665baea5 MK |
179 | .IR delay_first_probe_time " (since Linux 2.2)" |
180 | .\" Precisely: 2.1.79 | |
77117f4f MK |
181 | Delay before first probe after it has been decided that a neighbor |
182 | is stale. | |
183 | Defaults to 5 seconds. | |
184 | .TP | |
665baea5 MK |
185 | .IR gc_interval " (since Linux 2.2)" |
186 | .\" Precisely: 2.1.79 | |
77117f4f MK |
187 | How frequently the garbage collector for neighbor entries |
188 | should attempt to run. | |
189 | Defaults to 30 seconds. | |
190 | .TP | |
665baea5 MK |
191 | .IR gc_stale_time " (since Linux 2.2)" |
192 | .\" Precisely: 2.1.79 | |
77117f4f | 193 | Determines how often to check for stale neighbor entries. |
caf5129c | 194 | When a neighbor entry is considered stale, it is resolved again before |
77117f4f MK |
195 | sending data to it. |
196 | Defaults to 60 seconds. | |
197 | .TP | |
665baea5 MK |
198 | .IR gc_thresh1 " (since Linux 2.2)" |
199 | .\" Precisely: 2.1.79 | |
77117f4f MK |
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 | |
665baea5 MK |
205 | .IR gc_thresh2 " (since Linux 2.2)" |
206 | .\" Precisely: 2.1.79 | |
77117f4f MK |
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 | |
665baea5 MK |
212 | .IR gc_thresh3 " (since Linux 2.2)" |
213 | .\" Precisely: 2.1.79 | |
77117f4f MK |
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 | |
665baea5 MK |
219 | .IR locktime " (since Linux 2.2)" |
220 | .\" Precisely: 2.1.79 | |
77117f4f MK |
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 | |
665baea5 MK |
226 | .IR mcast_solicit " (since Linux 2.2)" |
227 | .\" Precisely: 2.1.79 | |
77117f4f MK |
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 | |
665baea5 MK |
232 | .IR proxy_delay " (since Linux 2.2)" |
233 | .\" Precisely: 2.1.79 | |
77117f4f MK |
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 | |
665baea5 MK |
240 | .IR proxy_qlen " (since Linux 2.2)" |
241 | .\" Precisely: 2.1.79 | |
77117f4f MK |
242 | The maximum number of packets which may be queued to proxy-ARP addresses. |
243 | Defaults to 64. | |
244 | .TP | |
665baea5 MK |
245 | .IR retrans_time " (since Linux 2.2)" |
246 | .\" Precisely: 2.1.79 | |
77117f4f MK |
247 | The number of jiffies to delay before retransmitting a request. |
248 | Defaults to 1 second. | |
f35067be | 249 | This file is now obsolete in favor of |
32fb5652 MK |
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. | |
77117f4f | 255 | .TP |
665baea5 MK |
256 | .IR ucast_solicit " (since Linux 2.2)" |
257 | .\" Precisely: 2.1.79 | |
77117f4f MK |
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 | |
665baea5 MK |
263 | .IR unres_qlen " (since Linux 2.2)" |
264 | .\" Precisely: 2.1.79 | |
77117f4f MK |
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. | |
c6d039a3 | 275 | .P |
77117f4f MK |
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). | |
c6d039a3 | 281 | .P |
77117f4f MK |
282 | The |
283 | .I neigh/* | |
5a2ff571 | 284 | interfaces did not exist before Linux 2.2. |
77117f4f MK |
285 | .SH BUGS |
286 | Some timer settings are specified in jiffies, which is architecture- | |
287 | and kernel version-dependent; see | |
288 | .BR time (7). | |
c6d039a3 | 289 | .P |
77117f4f | 290 | There is no way to signal positive feedback from user space. |
caf5129c | 291 | This means connection-oriented protocols implemented in user space |
77117f4f MK |
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). | |
c6d039a3 | 295 | .P |
d840e4fa MK |
296 | This man page mashes together functionality that is IPv4-specific |
297 | with functionality that is shared between IPv4 and IPv6. | |
47297adb | 298 | .SH SEE ALSO |
77117f4f | 299 | .BR capabilities (7), |
2222ef9b MK |
300 | .BR ip (7), |
301 | .BR arpd (8) | |
c6d039a3 | 302 | .P |
77117f4f | 303 | RFC\ 826 for a description of ARP. |
77117f4f MK |
304 | RFC\ 2461 for a description of IPv6 neighbor discovery and the base |
305 | algorithms used. | |
77117f4f | 306 | Linux 2.2+ IPv4 ARP uses the IPv6 algorithms when applicable. |