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