path: root/usr/src/man/man7p/arp.7p

'\" te
.\" Copyright (c) 2009, Sun Microsystems, Inc. All Rights Reserved.
.\" Copyright 2008 AT&T
.\" 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.
.\" 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.
.\" 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]
.TH ARP 7P "Sep 02, 2015"
.SH NAME
arp, ARP \- Address Resolution Protocol
.SH SYNOPSIS
.LP
.nf
\fB#include <sys/fcntl.h>\fR
\fB#include <sys/socket.h>\fR
\fB#include <net/if_arp.h>\fR
\fB#include <netinet/in.h>\fR
.fi
.LP
.nf
\fBs = socket(PF_INET, SOCK_DGRAM, 0);\fR
.fi
.LP
.nf
\fBd = open ("/dev/arp", \fIoflag\fR);\fR
.fi
.SH DESCRIPTION
.LP
ARP is a protocol used to map  dynamically between Internet Protocol (IP) and
Ethernet addresses. It is used by all Ethernet datalink providers (network
drivers) and can be used by other datalink providers that support broadcast,
including FDDI  and Token Ring. The  only network layer supported in this
implementation is the Internet Protocol, although ARP is not specific to that
protocol.
.sp
.LP
\fBARP\fR caches \fBIP-to-link-layer\fR address mappings. When an interface
requests a mapping for an address not in the cache, \fBARP\fR queues the
message that requires the mapping and broadcasts a message on the associated
network requesting the address mapping. If a response is provided, \fBARP\fR
caches the new mapping and transmits any pending message. \fBARP\fR will queue
a maximum of four packets while awaiting a response to a mapping  request. ARP
keeps only the first four transmitted packets.
.SH APPLICATION PROGRAMMING INTERFACE
.LP
The STREAMS device \fB/dev/arp\fR is not a Transport Level Interface
(\fBTLI\fR) transport provider and may not be used with the \fBTLI\fR
interface.
.sp
.LP
To facilitate  communications with  systems that do  not use ARP,  ioctl()
requests are  provided  to  enter and delete entries  in  the  IP-to-link
address tables. Ioctls  that change the table  contents require the
\fBPRIV_SYS_NET_CONFIG\fR privilege. See \fBprivileges\fR(5).
.sp
.in +2
.nf
#include <sys/sockio.h>
#include <sys/socket.h>
#include <net/if.h>
#include <net/if_arp.h>
struct arpreq arpreq;
ioctl(s, SIOCSARP, (caddr_t)&arpreq);
ioctl(s, SIOCGARP, (caddr_t)&arpreq);
ioctl(s, SIOCDARP, (caddr_t)&arpreq);
.fi
.in -2

.sp
.LP
\fBSIOCSARP\fR, \fBSIOCGARP\fR and \fBSIOCDARP\fR are BSD compatible ioctls.
These ioctls do not communicate the mac address length between the user and the
kernel (and thus only work for 6 byte wide Ethernet addresses). To manage the
ARP cache for media that has different sized mac addresses, use
\fBSIOCSXARP\fR, \fBSIOCGXARP\fR and \fBSIOCDXARP\fR ioctls.
.sp
.in +2
.nf
#include <sys/sockio.h>
#include <sys/socket.h>
#include <net/if.h>
#include <net/if_dl.h>
#include <net/if_arp.h>
struct xarpreq xarpreq;
ioctl(s, SIOCSXARP, (caddr_t)&xarpreq);
ioctl(s, SIOCGXARP, (caddr_t)&xarpreq);
ioctl(s, SIOCDXARP, (caddr_t)&xarpreq);
.fi
.in -2

.sp
.LP
Each \fBioctl()\fR request takes the same structure as an argument.
\fBSIOCS[X]ARP\fR sets an \fBARP\fR entry, \fBSIOCG[X]ARP\fR gets an \fBARP\fR
entry, and \fBSIOCD[X]ARP\fR deletes an \fBARP\fR entry. These \fBioctl()\fR
requests may be applied to any Internet family socket descriptor\fIs\fR, or to
a descriptor for the \fBARP\fR device. Note that \fBSIOCS[X]ARP\fR and
\fBSIOCD[X]ARP\fR require the user to have the \fBPRIV_SYS_NET_CONFIG\fR
privilege, while \fBSIOCG[X]ARP\fR does not.
.sp
.LP
The \fBarpreq\fR structure contains
.sp
.in +2
.nf
/*
* ARP ioctl request
*/
struct arpreq {
    struct sockaddr arp_pa;  /* protocol address */
    struct sockaddr arp_ha; /* hardware address */
    int  arp_flags;         /* flags */
};
.fi
.in -2

.sp
.LP
The \fBxarpreq\fR structure contains:
.sp
.in +2
.nf
/*
* Extended ARP ioctl request
*/
struct xarpreq {
    struct sockaddr_storage xarp_pa; /* protocol address */
    struct sockaddr_dl xarp_ha;     /* hardware address */
    int xarp_flags;                 /* arp_flags field values */
};
#define ATF_COM 0x2          /* completed entry (arp_ha valid) */
#define ATF_PERM 0x4         /* permanent (non-aging) entry */
#define ATF_PUBL 0x8         /* publish (respond for other host) */
#define ATF_USETRAILERS 0x10 /* send trailer pckts to host */
#define ATF_AUTHORITY 0x20   /* hardware address is authoritative */
.fi
.in -2

.sp
.LP
The address family for the [x]arp_pa sockaddr must be \fBAF_INET\fR. The
\fBATF_COM\fR flag bits  ([x]arp_flags) cannot be altered. \fBATF_USETRAILERS\fR
is not implemented by the operating system and is retained for
compatibility only. \fBATF_PERM\fR makes the entry permanent (disables aging)
if the \fBioctl()\fR request succeeds. \fBATF_PUBL\fR specifies that the system
should respond to ARP requests for the indicated protocol address coming from
other machines. This allows a host to act as an ARP server, which may be useful
in convincing an ARP-only machine to talk to a non-ARP  machine.
\fBATF_AUTHORITY\fR indicates that this machine owns the address. ARP does not
update the entry based on received packets.
.sp
.LP
The address family for the arp_ha sockaddr must be \fBAF_UNSPEC\fR.
.sp
.LP
Before invoking any of the \fBSIOC*XARP\fR ioctls, user code must fill in the
\fBxarp_pa\fR field with the protocol (IP) address information, similar to the
BSD variant. The \fBSIOC*XARP\fR ioctls come in two (legal) varieties,
depending on \fBxarp_ha.sdl_nlen\fR:
.RS +4
.TP
1.
if \fBsdl_nlen\fR = 0, it behaves as an extended BSD ioctl. The kernel uses
the IP address to determine the network interface.
.RE
.RS +4
.TP
2.
if (\fBsdl_nlen\fR > 0) and (\fBsdl_nlen\fR < \fBLIFNAMSIZ\fR), the kernel
uses the interface name in sdl_data[0] to determine the network interface;
\fBsdl_nlen\fR represents the length of the string (excluding terminating null
character).
.RE
.RS +4
.TP
3.
if (\fBsdl_nlen\fR >= \fBLIFNAMSIZ\fR), an error (\fBEINVAL\fR) is flagged
from the ioctl.
.RE
.sp
.LP
Other than the above, the \fBxarp_ha\fR structure should be 0-filled except for
\fBSIOCSXARP\fR, where the \fBsdl_alen\fR field must be set to the size of
hardware address length and the hardware address itself must be placed in the
\fB\fR\fBLLADDR/sdl_data[]\fR area. (\fBEINVAL\fR will be returned if user
specified \fBsdl_alen\fR does not match the address length of the identified
interface).
.sp
.LP
On return from the kernel on a \fBSIOCGXARP\fR ioctl, the kernel fills in the
name of the interface (excluding terminating NULL) and its hardware address,
one after another, in the \fBsdl_data/LLADDR\fR area; if the two are larger
than can be held in the 244 byte \fBsdl_data[\fR] area, an \fBEINVAL\fR error
is returned. Assuming it fits, the kernel will also set \fBsdl_alen\fR with the
length of the hardware address, \fBsdl_nlen\fR with the length of the name of the
interface (excluding terminating NULL), \fBsdl_type\fR with an IFT_* value to
indicate the type of the media, \fBsdl_slen\fR with 0, \fBsdl_family\fR with
\fBAF_LINK\fR and \fBsdl_index\fR (which if not 0) with system given index for
the interface. The information returned is very similar to that returned via
routing sockets on an \fBRTM_IFINFO\fR message.
.sp
.LP
The ARP   ioctls  have several additional restrictions and enhancements when
used in conjunction with IPMP:
.RS +4
.TP
.ie t \(bu
.el o
ARP  mappings for IPMP  data and test addresses are managed by  the kernel and
cannot be changed through ARP  ioctls, though they may be retrieved using
\fBSIOCGARP\fR or \fBSIOCGXARP\fR.
.RE
.RS +4
.TP
.ie t \(bu
.el o
ARP mappings for a given IPMP group must be consistent across the group.  As a
result, ARP  mappings cannot be associated with  individual underlying IP
interfaces in an IPMP group and  must instead be associated with the
corresponding IPMP IP interface.
.RE
.RS +4
.TP
.ie t \(bu
.el o
Proxy ARP mappings for an IPMP group are automatically managed by the kernel.
Specifically, if the  hardware address in a \fBSIOCSARP\fR or \fBSIOCSXARP\fR
request matches the hardware  address of  an IP interface in an  IPMP group and
the IP address is not  local to the system, the kernel regards this as a  IPMP
Proxy ARP entry. This  IPMP Proxy ARP entry  will have its hardware address
automatically adjusted in  order to keep the IP address reachable  (provided
the IPMP group has not entirely failed).
.RE
.sp
.LP
\fBARP\fR performs duplicate address detection for local addresses. When a
logical  interface is brought up (\fBIFF_UP\fR) or any time the hardware link
goes up  (\fBIFF_RUNNING\fR), ARP sends probes (ar$spa == 0) for the assigned
address.  If  a conflict is  found, the interface is torn down. See
\fBifconfig\fR(1M) for more details.
.sp
.LP
\fBARP\fR watches for hosts impersonating the local host, that is, any host
that responds to an ARP request for the local host's address, and any address
for which the local host is an authority. ARP defends local addresses and logs
those with \fBATF_AUTHORITY\fR set, and can tear down local addresses on an
excess of conflicts.
.sp
.LP
ARP also  handles UNARP messages received  from other nodes. It does not
generate these messages.
.SH PACKET EVENTS
.LP
The \fBarp\fR driver registers itself with the netinfo  interface. To gain
access to  these events, a handle from net_protocol_lookup must be acquired by
passing it the value \fBNHF_ARP\fR. Through this interface, two packet events
are supported:
.sp
.LP
Physical in - ARP packets received via a network  interface
.sp
.LP
Physical out - ARP packets to be sent out via a  network interface
.sp
.LP
For ARP packets, the hook_pkt_event structure is filled out as follows:
.sp
.ne 2
.na
\fBhpe_ifp\fR
.ad
.sp .6
.RS 4n
Identifier indicating the  inbound  interface for packets received with the
\fBphysical in\fR event.
.RE

.sp
.ne 2
.na
\fBhpe_ofp\fR
.ad
.sp .6
.RS 4n
Identifier indicating the outbound  interface  for packets received with the
\fBphysical out\fR event.
.RE

.sp
.ne 2
.na
\fBhpe_hdr\fR
.ad
.sp .6
.RS 4n
Pointer to the start of the ARP  header  (not  the Ethernet header).
.RE

.sp
.ne 2
.na
\fBhpe_mp\fR
.ad
.sp .6
.RS 4n
Pointer to the start of the mblk_t chain containing the ARP packet.
.RE

.sp
.ne 2
.na
\fBhpe_mb\fR
.ad
.sp .6
.RS 4n
Pointer to the mblk_t with the ARP header in it.
.RE

.SH NETWORK INTERFACE EVENTS
.LP
In addition  to events describing packets as they  move through the system, it
is also possible to receive notification of events relating to network
interfaces. These events are  all  reported back through the same callback. The
list of events is as follows:
.sp
.ne 2
.na
\fBplumb\fR
.ad
.sp .6
.RS 4n
A new network interface has been instantiated.
.RE

.sp
.ne 2
.na
\fBunplumb\fR
.ad
.sp .6
.RS 4n
A network interface is no longer  associated with ARP.
.RE

.SH SEE ALSO
.LP
\fBarp\fR(1M), \fBifconfig\fR(1M), \fBsockaddr\fR(3SOCKET), \fBprivileges\fR(5),
\fBif_tcp\fR(7P), \fBinet\fR(7P), \fBnetinfo\fR(9F)
.sp
.LP
Plummer, Dave, \fIAn Ethernet Address Resolution Protocol\fR or \fIConverting
Network  Protocol  Addresses to 48 .bit Ethernet Addresses for Transmission on
Ethernet  Hardware\fR, RFC  826, STD 0037, November 1982.
.sp
.LP
Malkin,  Gary, \fIARP  Extension  - UNARP, RFC 1868\fR, November, 1995
.SH DIAGNOSTICS
.LP
Several messages can be written to the system  logs (by the IP module) when
errors occur. In the following examples, the hardware address strings include
colon (:) separated ASCII  representations of the link layer addresses, whose
lengths depend on the underlying media (for example, 6 bytes for Ethernet).
.sp
.ne 2
.na
\fBNode %x:%x ... %x:%x is using our IP address %d.%d.%d.%d on %s.\fR
.ad
.sp .6
.RS 4n
Duplicate IP address warning. ARP has discovered another host on a local
network that responds to mapping requests for the Internet  address of this
system, and has defended the system against this node by re-announcing the ARP
entry.
.RE

.sp
.ne 2
.na
\fB%s has duplicate address %d.%d.%d.%d (in use by %x:%x ... %x:%x);
disabled.\fR
.ad
.sp .6
.RS 4n
Duplicate IP address detected while performing initial probing. The
newly-configured interface has been shut down.
.RE

.sp
.ne 2
.na
\fB%s has duplicate address %d.%d.%d.%d (claimed by %x:%x ... %x:%x);
disabled.\fR
.ad
.sp .6
.RS 4n
Duplicate IP address detected on a running IP interface. The conflict cannot be
resolved, and the interface has been disabled to protect the network.
.RE

.sp
.ne 2
.na
\fBRecovered address %d.%d.%d.%d on %s.\fR
.ad
.sp .6
.RS 4n
An interface with a previously-conflicting IP address has been recovered
automatically and reenabled. The conflict has been resolved.
.RE

.sp
.ne 2
.na
\fBProxy ARP problem?  Node '%x:%x ... %x:%x' is using %d.%d.%d.%d on %s\fR
.ad
.sp .6
.RS 4n
This  message appears if \fBarp\fR(1M) has been used to create a published
permanent (\fBATF_AUTHORITY\fR) entry, and some other host on the local network
responds to mapping requests for the published ARP entry.
.RE