xref: /openbsd/usr.sbin/arp/arp.8 (revision cecf84d4) 
1.\"	$OpenBSD: arp.8,v 1.35 2014/09/03 10:39:41 mpi Exp $
2.\"	$NetBSD: arp.8,v 1.7 1995/03/01 11:50:59 chopps Exp $
3.\"
4.\" Copyright (c) 1985, 1991, 1993
5.\"	The Regents of the University of California.  All rights reserved.
6.\"
7.\" Redistribution and use in source and binary forms, with or without
8.\" modification, are permitted provided that the following conditions
9.\" are met:
10.\" 1. Redistributions of source code must retain the above copyright
11.\"    notice, this list of conditions and the following disclaimer.
12.\" 2. Redistributions in binary form must reproduce the above copyright
13.\"    notice, this list of conditions and the following disclaimer in the
14.\"    documentation and/or other materials provided with the distribution.
15.\" 3. Neither the name of the University nor the names of its contributors
16.\"    may be used to endorse or promote products derived from this software
17.\"    without specific prior written permission.
18.\"
19.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
20.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
21.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
22.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
23.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
24.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
25.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
26.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
27.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
28.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
29.\" SUCH DAMAGE.
30.\"
31.\"	from: @(#)arp.8	8.1 (Berkeley) 6/6/93
32.\"
33.Dd $Mdocdate: September 3 2014 $
34.Dt ARP 8
35.Os
36.Sh NAME
37.Nm arp
38.Nd address resolution display and control
39.Sh SYNOPSIS
40.Nm arp
41.Op Fl adn
42.Op Fl V Ar rdomain
43.Ar hostname
44.Nm arp
45.Op Fl F
46.Op Fl f Ar file
47.Op Fl V Ar rdomain
48.Fl s Ar hostname ether_addr
49.Op Cm temp | permanent
50.Op Cm pub
51.Nm
52.Fl W Ar ether_addr Op Ar iface
53.Sh DESCRIPTION
54The
55.Nm
56program displays and modifies the Internet-to-Ethernet address translation
57tables used by the address resolution protocol (ARP).
58.Pp
59.Nm
60displays the current ARP entry for
61.Ar hostname
62when no optional parameters are supplied.
63.Ar hostname
64may be specified by name or by number,
65using Internet dot notation.
66.Pp
67.Nm
68can also be used to send Wake on LAN (WoL) frames over a local
69Ethernet network to one or more hosts using their link layer (hardware)
70addresses.
71WoL functionality is generally enabled in a machine's BIOS
72and can be used to power on machines from a remote system without
73having physical access to them.
74.Pp
75The options are as follows:
76.Bl -tag -width Ds
77.It Fl a
78Display all of the current ARP entries.
79See also the
80.Fl d
81option below.
82The following information will be printed:
83.Bl -tag -width Ds -offset 3n
84.It Host
85The network address of the host.
86.It Ethernet Address
87The Ethernet address of the host.
88If the address is not available,
89it will be displayed as
90.Dq (incomplete) .
91.It Netif
92The network interface associated with the ARP entry.
93.It Expire
94The time until expiry of the entry.
95If the entry is marked
96.Dq permanent
97or
98.Dq static ,
99it will never expire.
100.It Flags
101Flags on the ARP entry, in a single letter.
102They are: local
103.Pq Sq l ,
104proxy
105.Pq Sq P
106and published
107.Pq Sq p .
108.El
109.It Fl d
110Delete an entry for the host called
111.Ar hostname .
112Alternatively, the
113.Fl d
114flag may be combined with the
115.Fl a
116flag to delete all entries, with hostname lookups automatically
117disabled.
118Only the superuser may delete entries.
119.It Fl F
120Force existing entries for the given host to be overwritten
121(only relevant to the
122.Fl f
123and
124.Fl s
125options).
126.It Fl f Ar file
127Process entries from
128.Ar file
129to be set in the ARP tables.
130Any entries in the file that already exist for a given host
131will not be overwritten unless
132.Fl F
133is given.
134Entries in the file should be of the form:
135.Bd -filled -offset indent
136.Ar hostname ether_addr
137.Op Cm temp | permanent
138.Op Cm pub
139.Ed
140.Pp
141The entry will be static (will not time out) unless the word
142.Cm temp
143is given in the command.
144A static ARP entry can be overwritten by network traffic, unless the word
145.Cm permanent
146is given.
147If the word
148.Cm pub
149is given, the entry will be
150.Dq published ;
151that is, this system will act as an ARP server,
152responding to requests for
153.Ar hostname
154even though the host address is not its own.
155This behavior has traditionally been called
156.Em proxy ARP .
157.It Fl n
158Show network addresses as numbers (normally
159.Nm
160attempts to display addresses symbolically).
161.It Xo
162.Fl s Ar hostname ether_addr
163.Op Cm temp | permanent
164.Op Cm pub
165.Xc
166Create an ARP entry for the host called
167.Ar hostname
168with the Ethernet address
169.Ar ether_addr .
170The Ethernet address is given as six hexadecimal bytes separated by
171colons.
172.Pp
173The
174.Cm permanent , pub ,
175or
176.Cm temp
177modifiers may be specified with meanings as given above.
178.Pp
179If the entry already exists for the given host, it will not
180be replaced unless
181.Fl F
182is given.
183.It Fl V Ar rdomain
184Select the routing domain.
185.It Fl W Ar ether_addr Op Ar iface
186Send the Wake on LAN frame from all interfaces on the local machine
187that are up, if
188.Ar iface
189has not been specified.
190Otherwise the frame will be sent from
191.Ar iface .
192.Ar ether_addr
193is the Ethernet address of the remote machine or a hostname entry in
194.Pa /etc/ethers .
195This option cannot be used in combination with any other option.
196.El
197.Sh FILES
198.Bl -tag -width "/etc/ethers" -compact
199.It /etc/ethers
200Ethernet host name database.
201.El
202.Sh EXAMPLES
203View the current
204.Xr arp 4
205table,
206showing network addresses symbolically:
207.Pp
208.Dl $ arp -a
209.Pp
210Create a permanent
211entry (one that cannot be overwritten by other network traffic):
212.Pp
213.Dl # arp -s 10.0.0.2 00:90:27:bb:cc:dd permanent
214.Pp
215Create proxy ARP
216entries on interface fxp0
217(MAC address 00:90:27:bb:cc:dd),
218for IP addresses 204.1.2.3 and 204.1.2.4:
219.Bd -literal -offset indent
220# arp -s 204.1.2.3 00:90:27:bb:cc:dd pub
221# arp -s 204.1.2.4 00:90:27:bb:cc:dd pub
222.Ed
223.Sh SEE ALSO
224.Xr inet_addr 3 ,
225.Xr arp 4 ,
226.Xr ethers 5 ,
227.Xr ifconfig 8 ,
228.Xr ndp 8
229.Sh HISTORY
230The
231.Nm
232command appeared in
233.Bx 4.3 .
234Wake on LAN functionality was added in
235.Ox 4.9 .
236