original/man7/arp.7

   1 '\" t
   2 .\" This man page is Copyright (C) 1999 Matthew Wilcox <willy@bofh.ai>.
   3 .\" Permission is granted to distribute possibly modified copies
   4 .\" of this page provided the header is included verbatim,
   5 .\" and in case of nontrivial modification author and date
   6 .\" of the modification is added to the header.
   7 .\" Modified June 1999 Andi Kleen
   8 .\" $Id: arp.7,v 1.10 2000/04/27 19:31:38 ak Exp $
   9 .TH ARP 7 2008-11-25 "Linux" "Linux Programmer's Manual"
  10 .SH NAME
  11 arp \- Linux ARP kernel module.
  12 .SH DESCRIPTION
  13 This kernel protocol module implements the Address Resolution
  14 Protocol defined in RFC\ 826.
  15 It is used to convert between Layer2 hardware addresses
  16 and IPv4 protocol addresses on directly connected networks.
  17 The user normally doesn't interact directly with this module except to
  18 configure it;
  19 instead it provides a service for other protocols in the kernel.
  20
  21 A user process can receive ARP packets by using
  22 .BR packet (7)
  23 sockets.
  24 There is also a mechanism for managing the ARP cache
  25 in user-space by using
  26 .BR netlink (7)
  27 sockets.
  28 The ARP table can also be controlled via
  29 .BR ioctl (2)
  30 on any
  31 .B AF_INET
  32 socket.
  33
  34 The ARP module maintains a cache of mappings between hardware addresses
  35 and protocol addresses.
  36 The cache has a limited size so old and less
  37 frequently used entries are garbage-collected.
  38 Entries which are marked
  39 as permanent are never deleted by the garbage-collector.
  40 The cache can
  41 be directly manipulated by the use of ioctls and its behavior can be
  42 tuned by the
  43 .I /proc
  44 interfaces described below.
  45
  46 When there is no positive feedback for an existing mapping after some
  47 time (see the
  48 .I /proc
  49 interfaces below), a neighbor cache entry is considered stale.
  50 Positive feedback can be gotten from a higher layer; for example from
  51 a successful TCP ACK.
  52 Other protocols can signal forward progress
  53 using the
  54 .B MSG_CONFIRM
  55 flag to
  56 .BR sendmsg (2).
  57 When there is no forward progress, ARP tries to reprobe.
  58 It first tries to ask a local arp daemon
  59 .B app_solicit
  60 times for an updated MAC address.
  61 If that fails and an old MAC address is known, a unicast probe is sent
  62 .B ucast_solicit
  63 times.
  64 If that fails too, it will broadcast a new ARP
  65 request to the network.
  66 Requests are only sent when there is data queued
  67 for sending.
  68
  69 Linux will automatically add a nonpermanent proxy arp entry when it
  70 receives a request for an address it forwards to and proxy arp is
  71 enabled on the receiving interface.
  72 When there is a reject route for the target, no proxy arp entry is added.
  73 .SS Ioctls
  74 Three ioctls are available on all
  75 .B AF_INET
  76 sockets.
  77 They take a pointer to a
  78 .I struct arpreq
  79 as their argument.
  80
  81 .in +4n
  82 .nf
  83 struct arpreq {
  84     struct sockaddr arp_pa;      /* protocol address */
  85     struct sockaddr arp_ha;      /* hardware address */
  86     int             arp_flags;   /* flags */
  87     struct sockaddr arp_netmask; /* netmask of protocol address */
  88     char            arp_dev[16];
  89 };
  90 .fi
  91 .in
  92
  93 .BR SIOCSARP ", " SIOCDARP " and " SIOCGARP
  94 respectively set, delete and get an ARP mapping.
  95 Setting and deleting ARP maps are privileged operations and may
  96 only be performed by a process with the
  97 .B CAP_NET_ADMIN
  98 capability or an effective UID of 0.
  99
 100 .I arp_pa
 101 must be an
 102 .B AF_INET
 103 socket and
 104 .I arp_ha
 105 must have the same type as the device which is specified in
 106 .IR arp_dev .
 107 .I arp_dev
 108 is a zero-terminated string which names a device.
 109 .RS
 110 .TS
 111 tab(:) allbox;
 112 c s
 113 l l.
 114 \fIarp_flags\fR
 115 flag:meaning
 116 ATF_COM:Lookup complete
 117 ATF_PERM:Permanent entry
 118 ATF_PUBL:Publish entry
 119 ATF_USETRAILERS:Trailers requested
 120 ATF_NETMASK:Use a netmask
 121 ATF_DONTPUB:Don't answer
 122 .TE
 123 .RE
 124
 125 .PP
 126 If the
 127 .B ATF_NETMASK
 128 flag is set, then
 129 .I arp_netmask
 130 should be valid.
 131 Linux 2.2 does not support proxy network ARP entries, so this
 132 should be set to 0xffffffff, or 0 to remove an existing proxy arp entry.
 133 .B ATF_USETRAILERS
 134 is obsolete and should not be used.
 135 .SS /proc interfaces
 136 ARP supports a range of
 137 .I /proc
 138 interfaces to configure parameters on a global or per-interface basis.
 139 The interfaces can be accessed by reading or writing the
 140 .I /proc/sys/net/ipv4/neigh/*/*
 141 files.
 142 Each interface in the system has its own directory in
 143 .IR /proc/sys/net/ipv4/neigh/ .
 144 The setting in the "default" directory is used for all newly created
 145 devices.
 146 Unless otherwise specified, time-related interfaces are specified
 147 in seconds.
 148 .TP
 149 .IR anycast_delay " (since Linux 2.2)"
 150 .\" Precisely: 2.1.79
 151 The maximum number of jiffies to delay before replying to a
 152 IPv6 neighbor solicitation message.
 153 Anycast support is not yet implemented.
 154 Defaults to 1 second.
 155 .TP
 156 .IR app_solicit " (since Linux 2.2)"
 157 .\" Precisely: 2.1.79
 158 The maximum number of probes to send to the user space ARP daemon via
 159 netlink before dropping back to multicast probes (see
 160 .IR mcast_solicit ).
 161 Defaults to 0.
 162 .TP
 163 .IR base_reachable_time " (since Linux 2.2)"
 164 .\" Precisely: 2.1.79
 165 Once a neighbor has been found, the entry is considered to be valid
 166 for at least a random value between
 167 .IR base_reachable_time "/2 and 3*" base_reachable_time /2.
 168 An entry's validity will be extended if it receives positive feedback
 169 from higher level protocols.
 170 Defaults to 30 seconds.
 171 This file is now obsolete in favor of
 172 .IR base_reachable_time_ms .
 173 .TP
 174 .IR base_reachable_time_ms " (since Linux 2.6.12)"
 175 As for
 176 .IR base_reachable_time ,
 177 but measures time in milliseconds.
 178 Defaults to 30000 milliseconds.
 179 .TP
 180 .IR delay_first_probe_time " (since Linux 2.2)"
 181 .\" Precisely: 2.1.79
 182 Delay before first probe after it has been decided that a neighbor
 183 is stale.
 184 Defaults to 5 seconds.
 185 .TP
 186 .IR gc_interval " (since Linux 2.2)"
 187 .\" Precisely: 2.1.79
 188 How frequently the garbage collector for neighbor entries
 189 should attempt to run.
 190 Defaults to 30 seconds.
 191 .TP
 192 .IR gc_stale_time " (since Linux 2.2)"
 193 .\" Precisely: 2.1.79
 194 Determines how often to check for stale neighbor entries.
 195 When a neighbor entry is considered stale, it is resolved again before
 196 sending data to it.
 197 Defaults to 60 seconds.
 198 .TP
 199 .IR gc_thresh1 " (since Linux 2.2)"
 200 .\" Precisely: 2.1.79
 201 The minimum number of entries to keep in the ARP cache.
 202 The garbage collector will not run if there are fewer than
 203 this number of entries in the cache.
 204 Defaults to 128.
 205 .TP
 206 .IR gc_thresh2 " (since Linux 2.2)"
 207 .\" Precisely: 2.1.79
 208 The soft maximum number of entries to keep in the ARP cache.
 209 The garbage collector will allow the number of entries to exceed
 210 this for 5 seconds before collection will be performed.
 211 Defaults to 512.
 212 .TP
 213 .IR gc_thresh3 " (since Linux 2.2)"
 214 .\" Precisely: 2.1.79
 215 The hard maximum number of entries to keep in the ARP cache.
 216 The garbage collector will always run if there are more than
 217 this number of entries in the cache.
 218 Defaults to 1024.
 219 .TP
 220 .IR locktime " (since Linux 2.2)"
 221 .\" Precisely: 2.1.79
 222 The minimum number of jiffies to keep an ARP entry in the cache.
 223 This prevents ARP cache thrashing if there is more than one potential
 224 mapping (generally due to network misconfiguration).
 225 Defaults to 1 second.
 226 .TP
 227 .IR mcast_solicit " (since Linux 2.2)"
 228 .\" Precisely: 2.1.79
 229 The maximum number of attempts to resolve an address by
 230 multicast/broadcast before marking the entry as unreachable.
 231 Defaults to 3.
 232 .TP
 233 .IR proxy_delay " (since Linux 2.2)"
 234 .\" Precisely: 2.1.79
 235 When an ARP request for a known proxy-ARP address is received, delay up to
 236 .I proxy_delay
 237 jiffies before replying.
 238 This is used to prevent network flooding in some cases.
 239 Defaults to 0.8 seconds.
 240 .TP
 241 .IR proxy_qlen " (since Linux 2.2)"
 242 .\" Precisely: 2.1.79
 243 The maximum number of packets which may be queued to proxy-ARP addresses.
 244 Defaults to 64.
 245 .TP
 246 .IR retrans_time " (since Linux 2.2)"
 247 .\" Precisely: 2.1.79
 248 The number of jiffies to delay before retransmitting a request.
 249 Defaults to 1 second.
 250 This file is now obsolete in favor of
 251 .IR retrans_time_ms .
 252 .TP
 253 .IR retrans_time_ms " (since Linux 2.6.12)"
 254 The number of milliseconds to delay before retransmitting a request.
 255 Defaults to 1000 milliseconds.
 256 .TP
 257 .IR ucast_solicit " (since Linux 2.2)"
 258 .\" Precisely: 2.1.79
 259 The maximum number of attempts to send unicast probes before asking
 260 the ARP daemon (see
 261 .IR app_solicit ).
 262 Defaults to 3.
 263 .TP
 264 .IR unres_qlen " (since Linux 2.2)"
 265 .\" Precisely: 2.1.79
 266 The maximum number of packets which may be queued for each unresolved
 267 address by other network layers.
 268 Defaults to 3.
 269 .SH VERSIONS
 270 The
 271 .I struct arpreq
 272 changed in Linux 2.0 to include the
 273 .I arp_dev
 274 member and the ioctl numbers changed at the same time.
 275 Support for the old ioctls was dropped in Linux 2.2.
 276
 277 Support for proxy arp entries for networks (netmask not equal 0xffffffff)
 278 was dropped in Linux 2.2.
 279 It is replaced by automatic proxy arp setup by
 280 the kernel for all reachable hosts on other interfaces (when
 281 forwarding and proxy arp is enabled for the interface).
 282
 283 The
 284 .I neigh/*
 285 interfaces did not exist before Linux 2.2.
 286 .SH BUGS
 287 Some timer settings are specified in jiffies, which is architecture-
 288 and kernel version-dependent; see
 289 .BR time (7).
 290
 291 There is no way to signal positive feedback from user space.
 292 This means connection-oriented protocols implemented in user space
 293 will generate excessive ARP traffic, because ndisc will regularly
 294 reprobe the MAC address.
 295 The same problem applies for some kernel protocols (e.g., NFS over UDP).
 296
 297 This man page mashes IPv4 specific and shared between IPv4 and IPv6
 298 functionality together.
 299 .SH "SEE ALSO"
 300 .BR capabilities (7),
 301 .BR ip (7)
 302 .PP
 303 RFC\ 826 for a description of ARP.
 304 .br
 305 RFC\ 2461 for a description of IPv6 neighbor discovery and the base
 306 algorithms used.
 307 .LP
 308 Linux 2.2+ IPv4 ARP uses the IPv6 algorithms when applicable.