usr.sbin/arp/arp.8

   1 .\" Copyright (c) 1985, 1991, 1993
   2 .\"     The Regents of the University of California.  All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\" 3. Neither the name of the University nor the names of its contributors
  13 .\"    may be used to endorse or promote products derived from this software
  14 .\"    without specific prior written permission.
  15 .\"
  16 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  17 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  19 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  20 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  21 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  22 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  23 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  24 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  25 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  26 .\" SUCH DAMAGE.
  27 .\"
  28 .Dd July 13, 2020
  29 .Dt ARP 8
  30 .Os
  31 .Sh NAME
  32 .Nm arp
  33 .Nd address resolution display and control
  34 .Sh SYNOPSIS
  35 .Nm
  36 .Op Fl -libxo Ar options
  37 .Op Fl n
  38 .Op Fl i Ar interface
  39 .Ar hostname
  40 .Nm
  41 .Op Fl -libxo Ar options
  42 .Op Fl n
  43 .Op Fl i Ar interface
  44 .Fl a
  45 .Nm
  46 .Fl d Ar hostname
  47 .Op Cm pub
  48 .Nm
  49 .Fl d
  50 .Op Fl i Ar interface
  51 .Fl a
  52 .Nm
  53 .Fl s Ar hostname ether_addr
  54 .Op Cm temp
  55 .Op Cm blackhole No \&| Cm reject
  56 .Op Cm pub
  57 .Nm
  58 .Fl S Ar hostname ether_addr
  59 .Op Cm temp
  60 .Op Cm blackhole No \&| Cm reject
  61 .Op Cm pub
  62 .Nm
  63 .Fl f Ar filename
  64 .Sh DESCRIPTION
  65 The
  66 .Nm
  67 utility displays and modifies the Internet-to-Ethernet address translation
  68 tables used by the address resolution protocol
  69 .Pq Xr arp 4 .
  70 With no flags, the program displays the current
  71 .Tn ARP
  72 entry for
  73 .Ar hostname .
  74 The host may be specified by name or by number,
  75 using Internet dot notation.
  76 .Pp
  77 Available options:
  78 .Bl -tag -width indent
  79 .It Fl -libxo
  80 Generate output via
  81 .Xr libxo 3
  82 in a selection of different human and machine readable formats.
  83 See
  84 .Xr xo_parse_args 3
  85 for details on command line arguments.
  86 .It Fl a
  87 The program displays or, if it is used with the
  88 .Fl d
  89 flag, deletes all of the current
  90 .Tn ARP
  91 entries.
  92 .It Fl d
  93 A super-user may delete an entry for the host called
  94 .Ar hostname
  95 with the
  96 .Fl d
  97 flag.
  98 If the
  99 .Cm pub
 100 keyword is specified, only the
 101 .Dq published
 102 .Tn ARP
 103 entry
 104 for this host will be deleted.
 105 .Pp
 106 Alternatively, the
 107 .Fl d
 108 flag may be combined with the
 109 .Fl a
 110 flag to delete all entries.
 111 .It Fl i Ar interface
 112 Limit the operation scope to the
 113 .Tn ARP
 114 entries on
 115 .Ar interface .
 116 Applicable only to the following operations:
 117 display one, display all, delete all.
 118 .It Fl n
 119 Show network addresses as numbers (normally
 120 .Nm
 121 attempts to display addresses symbolically).
 122 .It Fl s Ar hostname ether_addr
 123 Create an
 124 .Tn ARP
 125 entry for the host called
 126 .Ar hostname
 127 with the Ethernet address
 128 .Ar ether_addr .
 129 The Ethernet address is given as six hex bytes separated by colons.
 130 The entry will be permanent unless the word
 131 .Cm temp
 132 is given in the command.
 133 If the word
 134 .Cm pub
 135 is given, the entry will be
 136 .Dq published ;
 137 i.e., this system will
 138 act as an
 139 .Tn ARP
 140 server,
 141 responding to requests for
 142 .Ar hostname
 143 even though the host address is not its own.
 144 In this case the
 145 .Ar ether_addr
 146 can be given as
 147 .Cm auto
 148 in which case the interfaces on this host will be examined,
 149 and if one of them is found to occupy the same subnet, its
 150 Ethernet address will be used.
 151 .Pp
 152 If the
 153 .Cm reject
 154 keyword is specified the entry will be marked so that traffic to
 155 the host will be discarded and the sender will be notified the
 156 host is unreachable.
 157 The
 158 .Cm blackhole
 159 keyword is similar in that traffic is discarded but the sender is
 160 not notified.
 161 These can be used to block external traffic to a host without
 162 using a firewall.
 163 .It Fl S Ar hostname ether_addr
 164 Is just like
 165 .Fl s
 166 except any existing
 167 .Tn ARP
 168 entry for this host will be deleted first.
 169 .It Fl f Ar filename
 170 Cause the file
 171 .Ar filename
 172 to be read and multiple entries to be set in the
 173 .Tn ARP
 174 tables.
 175 Entries
 176 in the file should be of the form
 177 .Pp
 178 .Bd -ragged -offset indent -compact
 179 .Ar hostname ether_addr
 180 .Op Cm temp
 181 .Op Cm blackhole No \&| Cm reject
 182 .Op Cm pub
 183 .Ed
 184 .Pp
 185 with argument meanings as given above.
 186 Leading whitespace and empty lines are ignored.
 187 A
 188 .Ql #
 189 character will mark the rest of the line as a comment.
 190 .El
 191 .Sh SEE ALSO
 192 .Xr inet 3 ,
 193 .Xr libxo 3 ,
 194 .Xr xo_parse_args 3 ,
 195 .Xr arp 4 ,
 196 .Xr ifconfig 8 ,
 197 .Xr ndp 8
 198 .Sh HISTORY
 199 The
 200 .Nm
 201 utility appeared in
 202 .Bx 4.3 .