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