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