| blob | 5489ce3aca76f5b5355549210a835c42a1f039b7 |
1 '\" te
2 .\" Copyright (c) 2009, Sun Microsystems, Inc. All Rights Reserved.
3 .\" Copyright 2008 AT&T
4 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
5 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
6 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
7 .TH ARP 7P "Feb 5, 2009"
8 .SH NAME
9 arp, ARP \- Address Resolution Protocol
10 .SH SYNOPSIS
11 .LP
12 .nf
13 \fB#include <sys/fcntl.h>\fR
14 .fi
16 .LP
17 .nf
18 \fB#include <sys/socket.h>\fR
19 .fi
21 .LP
22 .nf
23 \fB#include <net/if_arp.h>\fR
24 .fi
26 .LP
27 .nf
28 \fB#include <netinet/in.h>\fR
29 .fi
31 .LP
32 .nf
33 \fBs = socket(AF_INET, SOCK_DGRAM, 0);\fR
34 .fi
36 .LP
37 .nf
38 \fBd = open ("/dev/arp", \fIoflag\fR);\fR
39 .fi
41 .SH DESCRIPTION
42 .LP
43 ARP is a protocol used to map dynamically between Internet Protocol (IP) and
44 Ethernet addresses. It is used by all Ethernet datalink providers (network
45 drivers) and can be used by other datalink providers that support broadcast,
46 including FDDI and Token Ring. The only network layer supported in this
47 implementation is the Internet Protocol, although ARP is not specific to that
48 protocol.
49 .sp
50 .LP
51 \fBARP\fR caches \fBIP-to-link-layer\fR address mappings. When an interface
52 requests a mapping for an address not in the cache, \fBARP\fR queues the
53 message that requires the mapping and broadcasts a message on the associated
54 network requesting the address mapping. If a response is provided, \fBARP\fR
55 caches the new mapping and transmits any pending message. \fBARP\fR will queue
56 a maximum of four packets while awaiting a response to a mapping request. ARP
57 keeps only the first four transmitted packets.
58 .SH APPLICATION PROGRAMMING INTERFACE
59 .LP
60 The STREAMS device \fB/dev/arp\fR is not a Transport Level Interface
61 (\fBTLI\fR) transport provider and may not be used with the \fBTLI\fR
62 interface.
63 .sp
64 .LP
65 To facilitate communications with systems that do not use ARP, ioctl()
66 requests are provided to enter and delete entries in the IP-to-link
67 address tables. Ioctls that change the table contents require sys_net_config
68 privilege. See \fBprivileges\fR(5).
69 .sp
70 .in +2
71 .nf
72 #include <sys/sockio.h>
73 #include <sys/socket.h>
74 #include <net/if.h>
75 #include <net/if_arp.h>
76 struct arpreq arpreq;
77 ioctl(s, SIOCSARP, (caddr_t)&arpreq);
78 ioctl(s, SIOCGARP, (caddr_t)&arpreq);
79 ioctl(s, SIOCDARP, (caddr_t)&arpreq);
80 .fi
81 .in -2
83 .sp
84 .LP
85 \fBSIOCSARP\fR, \fBSIOCGARP\fR and \fBSIOCDARP\fR are BSD compatible ioctls.
86 These ioctls do not communicate the mac address length between the user and the
87 kernel (and thus only work for 6 byte wide Ethernet addresses). To manage the
88 ARP cache for media that has different sized mac addresses, use
89 \fBSIOCSXARP\fR, \fBSIOCGXARP\fR and \fBSIOCDXARP\fR ioctls.
90 .sp
91 .in +2
92 .nf
93 #include <sys/sockio.h>
94 #include <sys/socket.h>
95 #include <net/if.h>
96 #include <net/if_dl.h>
97 #include <net/if_arp.h>
98 struct xarpreq xarpreq;
99 ioctl(s, SIOCSXARP, (caddr_t)&xarpreq);
100 ioctl(s, SIOCGXARP, (caddr_t)&xarpreq);
101 ioctl(s, SIOCDXARP, (caddr_t)&xarpreq);
102 .fi
103 .in -2
105 .sp
106 .LP
107 Each \fBioctl()\fR request takes the same structure as an argument.
108 \fBSIOCS[X]ARP\fR sets an \fBARP\fR entry, \fBSIOCG[X]ARP\fR gets an \fBARP\fR
109 entry, and \fBSIOCD[X]ARP\fR deletes an \fBARP\fR entry. These \fBioctl()\fR
110 requests may be applied to any Internet family socket descriptor\fIs\fR, or to
111 a descriptor for the \fBARP\fR device. Note that \fBSIOCS[X]ARP\fR and
112 \fBSIOCD[X]ARP\fR require a privileged user, while \fBSIOCG[X]ARP\fR
113 .sp
114 .LP
115 does not.
116 .sp
117 .LP
118 The \fBarpreq\fR structure contains
119 .sp
120 .in +2
121 .nf
122 /*
123 * ARP ioctl request
124 */
125 struct arpreq {
126 struct sockaddr arp_pa; /* protocol address */
127 struct sockaddr arp_ha; /* hardware address */
128 int arp_flags; /* flags */
129 };
130 .fi
131 .in -2
133 .sp
134 .LP
135 The \fBxarpreq\fR structure contains:
136 .sp
137 .in +2
138 .nf
139 /*
140 * Extended ARP ioctl request
141 */
142 struct xarpreq {
143 struct sockaddr_storage xarp_pa; /* protocol address */
144 struct sockaddr_dl xarp_ha; /* hardware address */
145 int xarp_flags; /* arp_flags field values */
146 };
147 #define ATF_COM 0x2 /* completed entry (arp_ha valid) */
148 #define ATF_PERM 0x4 /* permanent (non-aging) entry */
149 #define ATF_PUBL 0x8 /* publish (respond for other host) */
150 #define ATF_USETRAILERS 0x10 /* send trailer pckts to host */
151 #define ATF_AUTHORITY 0x20 /* hardware address is authoritative */
152 .fi
153 .in -2
155 .sp
156 .LP
157 The address family for the [x]arp_pa sockaddr must be \fBAF_INET\fR. The
158 \fBATF_COM\fR flag bits ([x]arp_flags) cannot be altered.
159 \fBATF_USETRAILERS\fR is not implemented on Solaris and is retained for
160 compatibility only. \fBATF_PERM\fR makes the entry permanent (disables aging)
161 if the \fBioctl()\fR request succeeds. \fBATF_PUBL\fR specifies that the system
162 should respond to ARP requests for the indicated protocol address coming from
163 other machines. This allows a host to act as an ARP server, which may be useful
164 in convincing an ARP-only machine to talk to a non-ARP machine.
165 \fBATF_AUTHORITY\fR indicates that this machine owns the address. ARP does not
166 update the entry based on received packets.
167 .sp
168 .LP
169 The address family for the arp_ha sockaddr must be \fBAF_UNSPEC\fR.
170 .sp
171 .LP
172 Before invoking any of the \fBSIOC*XARP\fR ioctls, user code must fill in the
173 \fBxarp_pa\fR field with the protocol (IP) address information, similar to the
174 BSD variant. The \fBSIOC*XARP\fR ioctls come in two (legal) varieties,
175 depending on \fBxarp_ha.sdl_nlen\fR:
176 .RS +4
177 .TP
178 1.
179 if \fBsdl_nlen\fR = 0, it behaves as an extended BSD ioctl. The kernel uses
180 the IP address to determine the network interface.
181 .RE
182 .RS +4
183 .TP
184 2.
185 if (\fBsdl_nlen\fR > 0) and (\fBsdl_nlen\fR < \fBLIFNAMSIZ\fR), the kernel
186 uses the interface name in sdl_data[0] to determine the network interface;
187 \fBsdl_nlen\fR represents the length of the string (excluding terminating null
188 character).
189 .RE
190 .RS +4
191 .TP
192 3.
193 if (\fBsdl_nlen\fR >= \fBLIFNAMSIZ\fR), an error (\fBEINVAL\fR) is flagged
194 from the ioctl.
195 .RE
196 .sp
197 .LP
198 Other than the above, the \fBxarp_ha\fR structure should be 0-filled except for
199 \fBSIOCSXARP\fR, where the \fBsdl_alen\fR field must be set to the size of
200 hardware address length and the hardware address itself must be placed in the
201 \fB\fR\fBLLADDR/sdl_data[]\fR area. (\fBEINVAL\fR will be returned if user
202 specified \fBsdl_alen\fR does not match the address length of the identified
203 interface).
204 .sp
205 .LP
206 On return from the kernel on a \fBSIOCGXARP\fR ioctl, the kernel fills in the
207 name of the interface (excluding terminating NULL) and its hardware address,
208 one after another, in the \fBsdl_data/LLADDR\fR area; if the two are larger
209 than can be held in the 244 byte \fBsdl_data[\fR] area, an \fBENOSPC\fR error
210 is returned. Assuming it fits, the kernel will also set \fBsdl_alen\fR with the
211 length of hardware address, \fBsdl_nlen\fR with the length of name of the
212 interface (excluding terminating NULL), \fBsdl_type\fR with an IFT_* value to
213 indicate the type of the media, \fBsdl_slen\fR with 0, sdl_family with
214 \fBAF_LINK\fR and \fBsdl_index\fR (which if not 0) with system given index for
215 the interface. The information returned is very similar to that returned via
216 routing sockets on an \fBRTM_IFINFO\fR message.
217 .sp
218 .LP
219 The ARP ioctls have several additional restrictions and enhancements when
220 used in conjunction with IPMP:
221 .RS +4
222 .TP
223 .ie t \(bu
224 .el o
225 ARP mappings for IPMP data and test addresses are managed by the kernel and
226 cannot be changed through ARP ioctls, though they may be retrieved using
227 \fBSIOCGARP\fR or \fBSIOCGXARP\fR.
228 .RE
229 .RS +4
230 .TP
231 .ie t \(bu
232 .el o
233 ARP mappings for a given IPMP group must be consistent across the group. As a
234 result, ARP mappings cannot be associated with individual underlying IP
235 interfaces in an IPMP group and must instead be associated with the
236 corresponding IPMP IP interface.
237 .RE
238 .RS +4
239 .TP
240 .ie t \(bu
241 .el o
242 roxy ARP mappings for an IPMP group are automatically managed by the kernel.
243 Specifically, if the hardware address in a \fBSIOCSARP\fR or \fBSIOCSXARP\fR
244 request matches the hardware address of an IP interface in an IPMP group and
245 the IP address is not local to the system, the kernel regards this as a IPMP
246 Proxy ARP entry. This IPMP Proxy ARP entry will have its hardware address
247 automatically adjusted in order to keep the IP address reachable (provided
248 the IPMP group has not entirely failed).
249 .RE
250 .br
251 .in +2
252 \(em
253 .in -2
254 .br
255 .in +2
256 \(em
257 .in -2
258 .br
259 .in +2
260 \(emP
261 .in -2
262 .sp
263 .LP
264 \fBARP\fR performs duplicate address detection for local addresses. When a
265 logical interface is brought up (\fBIFF_UP\fR) or any time the hardware link
266 goes up (\fBIFF_RUNNING\fR), ARP sends probes (ar$spa == 0) for the assigned
267 address. If a conflict is found, the interface is torn down. See
268 \fBifconfig\fR(1M) for more details.
269 .sp
270 .LP
271 \fBARP\fR watches for hosts impersonating the local host, that is, any host
272 that responds to an ARP request for the local host's address, and any address
273 for which the local host is an authority. ARP defends local addresses and logs
274 those with \fBATF_AUTHORITY\fR set, and can tear down local addresses on an
275 excess of conflicts.
276 .sp
277 .LP
278 ARP also handles UNARP messages received from other nodes. It does not
279 generate these messages.
280 .SH PACKET EVENTS
281 .LP
282 The \fBarp\fR driver registers itself with the netinfo interface. To gain
283 access to these events, a handle from net_protocol_lookup must be acquired by
284 passing it the value \fBNHF_ARP\fR. Through this interface, two packet events
285 are supported:
286 .sp
287 .LP
288 Physical in - ARP packets received via a network inter face
289 .sp
290 .LP
291 Physical out - ARP packets to be sent out via a network interface
292 .sp
293 .LP
294 For ARP packets, the hook_pkt_event structure is filled out as follows:
295 .sp
296 .ne 2
297 .na
298 \fBhpe_ifp\fR
299 .ad
300 .sp .6
301 .RS 4n
302 Identifier indicating the inbound interface for packets received with the
303 \fBphysical in\fR event.
304 .RE
306 .sp
307 .ne 2
308 .na
309 \fBhpe_ofp\fR
310 .ad
311 .sp .6
312 .RS 4n
313 Identifier indicating the outbound interface for packets received with the
314 \fBphysical out\fR event.
315 .RE
317 .sp
318 .ne 2
319 .na
320 \fBhpe_hdr\fR
321 .ad
322 .sp .6
323 .RS 4n
324 Pointer to the start of the ARP header (not the ethernet header).
325 .RE
327 .sp
328 .ne 2
329 .na
330 \fBhpe_mp\fR
331 .ad
332 .sp .6
333 .RS 4n
334 Pointer to the start of the mblk_t chain containing the ARP packet.
335 .RE
337 .sp
338 .ne 2
339 .na
340 \fBhpe_mb\fR
341 .ad
342 .sp .6
343 .RS 4n
344 Pointer to the mblk_t with the ARP header in it.
345 .RE
347 .SH NETWORK INTERFACE EVENTS
348 .LP
349 In addition to events describing packets as they move through the system, it
350 is also possible to receive notification of events relating to network
351 interfaces. These events are all reported back through the same callback. The
352 list of events is as follows:
353 .sp
354 .ne 2
355 .na
356 \fBplumb\fR
357 .ad
358 .sp .6
359 .RS 4n
360 A new network interface has been instantiated.
361 .RE
363 .sp
364 .ne 2
365 .na
366 \fBunplumb\fR
367 .ad
368 .sp .6
369 .RS 4n
370 A network interface is no longer associated with ARP.
371 .RE
373 .SH SEE ALSO
374 .LP
375 \fBarp\fR(1M), \fBifconfig\fR(1M), \fBsockaddr\fR(3SOCKET), \fBprivileges\fR(5),
376 \fBif_tcp\fR(7P), \fBinet\fR(7P), \fBnetinfo\fR(9F)
377 .sp
378 .LP
379 Plummer, Dave, \fIAn Ethernet Address Resolution Protocol\fR or \fIConverting
380 Network Protocol Addresses to 48 .bit Ethernet Addresses for Transmission on
381 Ethernet Hardware\fR, RFC 826, STD 0037, November 1982.
382 .sp
383 .LP
384 Malkin, Gary, \fIARP Extension - UNARP, RFC 1868\fR, November, 1995
385 .SH DIAGNOSTICS
386 .LP
387 Several messages can be written to the system logs (by the IP module) when
388 errors occur. In the following examples, the hardware address strings include
389 colon (:) separated ASCII representations of the link layer addresses, whose
390 lengths depend on the underlying media (for example, 6 bytes for Ethernet).
391 .sp
392 .ne 2
393 .na
394 \fBNode %x:%x ... %x:%x is using our IP address %d.%d.%d.%d on %s.\fR
395 .ad
396 .sp .6
397 .RS 4n
398 Duplicate IP address warning. ARP has discovered another host on a local
399 network that responds to mapping requests for the Internet address of this
400 system, and has defended the system against this node by re-announcing the ARP
401 entry.
402 .RE
404 .sp
405 .ne 2
406 .na
407 \fB%s has duplicate address %d.%d.%d.%d (in use by %x:%x ... %x:%x);
408 disabled.\fR
409 .ad
410 .sp .6
411 .RS 4n
412 Duplicate IP address detected while performing initial probing. The
413 newly-configured interface has been shut down.
414 .RE
416 .sp
417 .ne 2
418 .na
419 \fB%s has duplicate address %d.%d.%d.%d (claimed by %x:%x ... %x:%x);
420 disabled.\fR
421 .ad
422 .sp .6
423 .RS 4n
424 Duplicate IP address detected on a running IP interface. The conflict cannot be
425 resolved, and the interface has been disabled to protect the network.
426 .RE
428 .sp
429 .ne 2
430 .na
431 \fBRecovered address %d.%d.%d.%d on %s.\fR
432 .ad
433 .sp .6
434 .RS 4n
435 An interface with a previously-conflicting IP address has been recovered
436 automatically and reenabled. The conflict has been resolved.
437 .RE
439 .sp
440 .ne 2
441 .na
442 \fBProxy ARP problem? Node '%x:%x ... %x:%x' is using %d.%d.%d.%d on %s\fR
443 .ad
444 .sp .6
445 .RS 4n
446 This message appears if \fBarp\fR(1M) has been used to create a published
447 permanent (\fBATF_AUTHORITY\fR) entry, and some other host on the local network
448 responds to mapping requests for the published ARP entry.
449 .RE