ARP(7)              Linux Programmer's Manual              ARP(7)



NAME

       arp - Linux ARP kernel module.


DESCRIPTION

       This kernel protocol module implements the Address Resolu-
       tion Protocol defined in RFC 826.  It is used  to  convert
       between   Layer2  hardware  addresses  and  IPv4  protocol
       addresses on directly connected networks.  The  user  nor-
       mally doesn't interact directly with this module except to
       configure it; instead it provides a service for other pro-
       tocols in the kernel.

       A  user process can receive ARP packets by using packet(7)
       sockets.  There is also a mechanism for managing  the  ARP
       cache  in  user-space by using netlink(7) sockets. The ARP
       table can also be controlled via ioctl (2) on any  PF_INET
       socket.

       The ARP module maintains a cache of mappings between hard-
       ware addresses and protocol addresses.  The  cache  has  a
       limited  size  so old and less frequently used entries are
       garbage-collected.  Entries which are marked as  permanent
       are never deleted by the garbage-collector.  The cache can
       be directly manipulated by  the  use  of  ioctls  and  its
       behaviour can be tuned by the sysctls defined below.

       When there is no positive feedback for an existing mapping
       after some time (see the sysctls below) a neighbour  cache
       entry  is considered stale.  Positive feedback can be got-
       ten from a higher layer; for example from a successful TCP
       ACK. Other protocols can signal forward progress using the
       MSG_CONFIRM flag to sendmsg(2).  When there is no  forward
       progress  ARP  tries  to reprobe.  It first tries to ask a
       local arp daemon app_solicit  times  for  an  updated  MAC
       address.  If that fails and an old MAC address is known an
       unicast probe is send ucast_solicit times. If  that  fails
       too  it  will  broadcast a new ARP request to the network.
       Requests are only send when there is data queued for send-
       ing.

       Linux  will  automatically  add  a non-permanent proxy arp
       entry when it receives a request for an  address  it  for-
       wards  to and proxy arp is enabled on the receiving inter-
       face. When there is a reject route for the target no proxy
       arp entry is added.



IOCTLS

       Three  ioctls  are available on all PF_INET sockets.  They
       take a pointer to a struct arpreq as their parameter.

       struct arpreq
       {
           struct sockaddr arp_pa;      /* protocol address */



Linux Man Page              3 Jun 1999                          1





ARP(7)              Linux Programmer's Manual              ARP(7)


           struct sockaddr arp_ha;      /* hardware address */
           int             arp_flags;   /* flags */
           struct sockaddr arp_netmask; /* netmask of protocol address */
           char            arp_dev[16];
       };

       SIOCSARP, SIOCDARP and SIOCGARP respectively  set,  delete
       and  get  an ARP mapping.  Setting & deleting ARP maps are
       privileged operations and may only be performed by a  pro-
       cess with the CAP_NET_ADMIN capability or an effective UID
       of 0.

       arp_pa must be an AF_INET socket and arp_ha must have  the
       same  type  as  the  device which is specified in arp_dev.
       arp_dev is a zero-terminated string which names a  device.

       tab(:)   allbox;   c   s   l  l.   arp_flags  flag:meaning
       ATF_COM:Lookup    complete    ATF_PERM:Permanent     entry
       ATF_PUBL:Publish  entry ATF_USETRAILERS:Trailers requested
       ATF_NETMASK:Use a netmask ATF_DONTPUB:Don't answer



       If the ATF_NETMASK flag is set, then arp_netmask should be
       valid.   Linux  2.2  does  not  support  proxy network ARP
       entries, so this should be set  to  0xffffffff,  or  0  to
       remove  an  existing  proxy arp entry.  ATF_USETRAILERS is
       obsolete and should not be used.



SYSCTLS

       ARP supports a sysctl interface to configure parameters on
       a  global  or  per-interface  basis.   The  sysctls can be
       accessed     by      reading      or      writing      the
       /proc/sys/net/ipv4/neigh/*/*  files  or with the sysctl(2)
       interface.  Each interface  in  the  system  has  its  own
       directory  in  /proc/sys/net/ipv4/neigh/.   The setting in
       the `default' directory is  used  for  all  newly  created
       devices.   Unless otherwise specified time related sysctls
       are specified in seconds.

       anycast_delay
              The maximum  number  of  jiffies  to  delay  before
              replying  to a IPv6 neighbour solicitation message.
              Anycast support is not yet  implemented.   Defaults
              to 1 second.

       app_solicit
              The  maximum  number  of probes to send to the user
              space ARP daemon via netlink before  dropping  back
              to  multicast probes (see mcast_solicit).  Defaults
              to 0.





Linux Man Page              3 Jun 1999                          2





ARP(7)              Linux Programmer's Manual              ARP(7)


       base_reachable_time
              Once a neighbour has been found, the entry is  con-
              sidered  to  be  valid  for at least a random value
              between  base_reachable_time/2  and   3*base_reach-
              able_time/2.   An entry's validity will be extended
              if it receives positive feedback from higher  level
              protocols.  Defaults to 30 seconds.

       delay_first_probe_time
              Delay  before first probe after it has been decided
              that a neighbour is stale.  Defaults to 5  seconds.

       gc_interval
              How  frequently the garbage collector for neighbour
              entries should attempt to run.  Defaults to 30 sec-
              onds.

       gc_stale_time
              Determines  how  often to check for stale neighbour
              entries.  When  a  neighbour  entry  is  considered
              stale  it  is resolved again before sending data to
              it.  Defaults to 60 seconds.

       gc_thresh1
              The minimum number of entries to keep  in  the  ARP
              cache.  The garbage collector will not run if there
              are fewer than this number of entries in the cache.
              Defaults to 128.

       gc_thresh2
              The  soft  maximum number of entries to keep in the
              ARP cache.  The garbage collector  will  allow  the
              number  of  entries  to  exceed  this for 5 seconds
              before collection will be performed.   Defaults  to
              512.

       gc_thresh3
              The  hard  maximum number of entries to keep in the
              ARP cache.  The garbage collector will  always  run
              if  there  are  more than this number of entries in
              the cache.  Defaults to 1024.

       locktime
              The minimum number of jiffies to keep an ARP  entry
              in the cache.  This prevents ARP cache thrashing if
              there is more than one potential mapping (generally
              due  to  network  misconfiguration).  Defaults to 1
              second.

       mcast_solicit
              The  maximum  number  of  attempts  to  resolve  an
              address  by  multicast/broadcast before marking the
              entry as unreachable.  Defaults to 3.




Linux Man Page              3 Jun 1999                          3





ARP(7)              Linux Programmer's Manual              ARP(7)


       proxy_delay
              When an ARP request for a known  proxy-ARP  address
              is received, delay up to proxy_delay jiffies before
              replying.  This is used to prevent network flooding
              in some cases.  Defaults to 0.8 seconds.

       proxy_qlen
              The  maximum  number of packets which may be queued
              to proxy-ARP addresses.  Defaults to 64.

       retrans_time
              The number of jiffies to delay  before  retransmit-
              ting a request.  Defaults to 1 second.

       ucast_solicit
              The  maximum  number  of  attempts  to send unicast
              probes  before   asking   the   ARP   daemon   (see
              app_solicit).  Defaults to 3.

       unres_qlen
              The  maximum  number of packets which may be queued
              for each unresolved address by other  network  lay-
              ers.  Defaults to 3.



BUGS

       Some  timer  settings  are  specified in jiffies, which is
       architecture related.  On the Alpha a jiffy is 1/1024 of a
       second, on most other architectures it is 1/100s.

       There  is  no  way  to  signal positive feedback from user
       space. This means  connection  oriented  protocols  imple-
       mented  in user space will generate excessive ARP traffic,
       because ndisc will regularly reprobe the MAC address.  The
       same  problem  applies for some kernel protocols (e.g. NFS
       over UDP).

       This man page mashes IPv4 specific and shared between IPv4
       and IPv6 functionality together.



VERSIONS

       The  struct  arpreq  changed  in  Linux 2.0 to include the
       arp_dev member and the ioctl numbers changed at  the  same
       time.   Support  for  the  old ioctls was dropped in Linux
       2.2.

       Support for proxy arp entries for  networks  (netmask  not
       equal 0xffffffff) was dropped in Linux 2.2. It is replaced
       by automatic proxy arp setup by the kernel for all  reach-
       able  hosts on other interfaces (when forwarding and proxy
       arp is enabled for the interface).

       The neigh/* sysctls did not exist before Linux 2.2.



Linux Man Page              3 Jun 1999                          4





ARP(7)              Linux Programmer's Manual              ARP(7)



SEE ALSO

       ip(7)

       RFC826 for a description of ARP.
       RFC2461 for a description of IPv6 neighbour discovery  and
       the base algorithms used.

       Linux 2.2+ IPv4 ARP uses the IPv6 algorithms when applica-
       ble.
















































Linux Man Page              3 Jun 1999                          5