man7/arp.7

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