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