cleanup man page (arp.8 2007-12-01)

diff --git a/man/en_US/arp.8 b/man/en_US/arp.8
index 3709cf6..4d20ed3 100644 (file)
--- a/man/en_US/arp.8
+++ b/man/en_US/arp.8
@@ -1,56 +1,111 @@
-.TH ARP 8 "2005-05-16" "net-tools" "Linux Programmer's Manual"
+.TH ARP 8 "2007-12-01" "net-tools" "Linux Programmer's Manual"
 .SH NAME
 arp \- manipulate the system ARP cache
 .SH SYNOPSIS
 .B arp 
 .RB [ \-vn ] 
-.RB [ "\-H type" ] 
-.RB [ "-i if" ] 
-.B -a 
-.RB [ hostname ]
+.RB [ \-H 
+.IR type ] 
+.RB [ \-i
+.IR if ] 
+.RB [ \-a ] 
+.RI [ hostname ]
 .PP
 .B arp 
 .RB [ \-v ]
-.RB [ "\-i if" ] 
-.B "\-d hostname"
+.RB [ \-i
+.IR if ] 
+.B \-d 
+.I hostname
 .RB [ pub ]
 .PP
 .B arp 
 .RB [ \-v ] 
-.RB [ "\-H type" ] 
-.RB [ "\-i if" ] 
-.B -s hostname hw_addr
+.RB [ \-H
+.IR type ] 
+.RB [ \-i
+.IR if ] 
+.B \-s
+.I hostname hw_addr
 .RB [ temp ] 
 .PP
 .B arp 
 .RB [ \-v ] 
-.RB [ "\-H type" ] 
-.RB [ "\-i if" ] 
-.B -s hostname hw_addr
-.RB [ "netmask nm" ] 
+.RB [ \-H
+.IR type ] 
+.RB [ \-i
+.IR if ] 
+.B \-s
+.I hostname hw_addr
+.RB [ netmask
+.IR nm ] 
 .B pub
 .PP
 .B arp 
 .RB [ \-v ] 
-.RB [ "\-H type" ] 
-.RB [ "\-i if" ] 
-.B -Ds hostname ifa
-.RB [ "netmask nm" ] 
+.RB [ \-H
+.IR type ] 
+.RB [ \-i
+.IR if ] 
+.B \-Ds 
+.I hostname
+.I ifname
+.RB [ netmask
+.IR nm ] 
 .B pub
 .PP
 .B arp 
 .RB [ \-vnD ]
-.RB [ "\-H type" ] 
-.RB [ "-i if" ]
-.B -f [filename]
+.RB [ \-H 
+.IR type ] 
+.RB [ \-i
+.IR if ]
+.B \-f 
+.RI [ filename ]
 
 .SH DESCRIPTION
 .B Arp
-manipulates the kernel's ARP cache in various ways.  The primary options
-are clearing an address mapping entry and manually setting up one.  For
-debugging purposes, the
+manipulates or displays the kernel's IPv4 network neighbour cache. It can add
+entries to the table, delete one or display the current content.
+
+.B ARP
+stands for Address Resolution Protocol, which is used to find the media
+access control address of a network neighbour for a given IPv4 Address.
+.SH MODES
 .B arp
-program also allows a complete dump of the ARP cache.
+with no mode specifier will print the current content of the table. It is
+possible to limit the number of entries printed, by specifying an hardware
+address type, interface name or host address.
+
+.B arp -d
+.I address
+will delete a ARP table entry. Root or netadmin priveledge is required to do
+this. The entry is found by IP address. If a hostname is given, it will be
+resolved before looking up the entry in the ARP table.
+
+.B arp -s
+.I address hw_addr
+is used to set up a new table entry. The format of the 
+.I hw_addr
+parameter is dependent on the hardware class, but for most classes one can
+assume that the usual presentation can be used.  For the Ethernet class,
+this is 6 bytes in hexadecimal, separated by colons. When adding proxy arp
+entries (that is those with the
+.BR pub lish 
+flag set a 
+.B netmask 
+may be specified to proxy arp for entire subnets. This is not good
+practice, but is supported by older kernels because it can be
+useful. If the
+.B temp
+flag is not supplied entries will be permanent stored into the ARP
+cache. To simplyfy setting up entries for one of your own network interfaces, you can use the
+.B "arp \-Ds"
+.I address ifname
+form. In that case the hardware address is taken from the interface with the
+specified name.
+
+.br
 .SH OPTIONS
 .TP
 .B "\-v, \-\-verbose"
@@ -76,21 +131,13 @@ Other values might include network technologies such as
 and
 .RB "NET/ROM (" netrom ")."
 .TP
-.B "\-a [hostname], \-\-display [hostname]"
-Shows the entries of the specified hosts.  If the
-.B hostname
-parameter is not used,
-.B all
-entries will be displayed.
-.TP
-.B "\-d hostname, \-\-delete hostname"
-Remove any entry for the specified host.  This can be used if the
-indicated host is brought down, for example.
+.B \-a
+Use alternate BSD style output format (with no fixed columns).
 .TP
 .B "\-D, \-\-use-device"
-Use the interface
-.BR ifa "'s"
-hardware address.
+Instead of a hw_addr, the given argument is the name of an interface. 
+.B arp
+will use the MAC address of that interface for the table entry. This is usually the best option to set up a proxy ARP entry to yourself.
 .TP
 .B "\-i If, \-\-device If"
 Select an interface. When dumping the ARP cache only entries matching
@@ -106,27 +153,6 @@ be answered.
 .B NOTE:
 This has to be different from the interface to which the IP
 datagrams will be routed.
-.TP
-.B "\-s hostname hw_addr, \-\-set hostname"
-Manually create an ARP address mapping entry for host
-.B hostname
-with hardware address set to
-.B hw_addr
-.  The format of the hardware address is dependent on the hardware
-class, but for most classes one can assume that the usual presentation
-can be used.  For the Ethernet class, this is 6 bytes in hexadecimal,
-separated by colons. When adding proxy arp entries (that is those with
-the 
-.BR pub lish 
-flag set a 
-.B netmask 
-may be specified to proxy arp for entire subnets. This is not good
-practice, but is supported by older kernels because it can be
-useful. If the
-.B temp
-flag is not supplied entries will be permanent stored into the ARP
-cache.
-.br
 .B NOTE:
 As of kernel 2.2.0 it is no longer possible to set an ARP entry for an 
 entire subnet. Linux instead does automagic proxy arp when a route
@@ -170,8 +196,18 @@ flag. Permanent entries are marked with
 and published entries have the
 .B P
 flag.
+.SH EXSAMPLES
+.B /usr/sbin/arp -i eth0 -Ds 10.0.0.2 eth1 pub
+
+This will answer ARP requests for 10.0.0.2 on eth0 with the MAC address for
+eth1.
+
+.B /usr/sbin/arp -i eth1 -d 10.0.0.1
+
+Delete the ARP table entry for 10.0.0.1 on interface eth1. This will match
+published proxy ARP entries and permanent entries.
 .SH FILES
-.I /proc/net/arp,
+.I /proc/net/arp
 .br
 .I /etc/networks
 .br
@@ -181,5 +217,4 @@ flag.
 .SH SEE ALSO
 rarp(8), route(8), ifconfig(8), netstat(8)
 .SH AUTHORS
-Fred N. van Kempen, <waltje@uwalt.nl.mugnet.org> with a lot of improvements
-from net-tools Maintainer Bernd Eckenfels <net-tools@lina.inka.de>.
+Fred N. van Kempen <waltje@uwalt.nl.mugnet.org>, Bernd Eckenfels <net-tools@lina.inka.de>.