1ARPWATCH(8) BSD System Manager's Manual ARPWATCH(8)
2
4 arpwatch — keep track of ethernet/ip address pairings
5
7 arpwatch [-CdFNpqsvzZ] [-D arpdir] [-f datafile] [-i interface]
8 [-P pidfile] [-w watcher@email] [-W watchee@email]
9 [-n net[/width]] [-x net[/width]] [-r file] [-u username]
10
12 arpwatch keeps track of ethernet/ip address pairings. It syslogs activity
13 and reports certain changes via email. arpwatch uses pcap(3) to listen
14 for arp packets on a local ethernet interface.
15 arp.dat contains three or four fields. First is the ethernet mac address,
17 second is the IPv4 address, and third is the time expressed in seconds
18 since midnight, January 1, 1970. The optional forth field is the short
19 hostname derrived from PTR record of the ip address when a mac/ip pair is
20 first seen; it is never updated and was intended to be a breadcrumb to
21 determine the origin of a mac/ip pair.
22 The -C flag uses compact padded ethernet addresses in arp.dat, e.g.
24 0:8:e1:1:2:d6.
25 The -d flag is used enable debugging. This also inhibits forking into the
27 background and emailing the reports. Instead, they are sent to stderr.
28 The -D flag is used to specify the arpwatch working directory. This de‐
30 faults to /var/lib/arpwatch.
31 The -f flag is used to set the ethernet/ip address database filename.
33 The default is arp.dat.
34 The -F flag is prevents arpwatch from forking causing it to run in the
36 foreground.
37 The -i flag is used to override the default interface.
39 The -n flag specifies additional local networks. This can be useful to
41 avoid "bogon" warnings when there is more than one network running on the
42 same wire. If the optional width is not specified, the default netmask
43 for the network's class is used.
44 The -N flag disables reporting any bogons.
46 The -p flag disables promiscuous mode.
48 The -P flag specifies the pidfile.
50 The -q flag suppresses reports being logged or printed to stderr.
52 The -r flag is used to specify a savefile (perhaps created by tcpdump(8)
54 or pcapture(8)) to read from instead of reading from the network. In this
55 case arpwatch does not fork.
56 Note that an empty arp.dat file must be created before the first time you
58 run arpwatch. Also, the default directory (where arp.dat is stored) must
59 be owned by username if the -u flag is used.
60 The -s flag suppresses reports sent by email.
62 The -u flag causes arpwatch to drop root privileges and change user ID to
64 username and group ID to that of the primary group of username. This is
65 recommended for security reasons.
66 The -v flag disables the reporting of VRRP/CARP ethernet prefixes as de‐
68 scribed in RFC5798 (0:0:5e:0:1:xx).
69 The -w flag is used to specify the target address for email reports. The
71 default is root.
72 The -W flag is used specifies the from address for email reports. The de‐
74 fault is root.
75 The -z flag disables reporting 0.0.0.0 changes, helpful in busy DHCP-
77 served networks.
78 The -Z flag uses zero padded ethernet addresses in arp.dat, e.g.
80 00:08:e1:01:02:d6.
81
83 Here's a quick list of the report messages generated by arpwatch(8) (and
84 arpsnmp(8)):
85 new activity
87 This ethernet/ip address pair has been used for the first time six
88 months or more.
89 new station
91 The ethernet address has not been seen before.
92 flip flop
94 The ethernet address has changed from the most recently seen address
95 to the second most recently seen address. (If either the old or new
96 ethernet address is a DECnet address and it is less than 24 hours,
97 the email version of the report is suppressed.)
98 changed ethernet address
100 The host switched to a new ethernet address.
101
103 Here are some of the syslog messages; note that messages that are re‐
104 ported are also sysloged.
105 ethernet broadcast
107 The mac ethernet address of the host is a broadcast address.
108 ip broadcast
110 The ip address of the host is a broadcast address.
111 bogon
113 The source ip address is not local to the local subnet.
114 ethernet broadcast
116 The source mac or arp ethernet address was all ones or all zeros.
117 ethernet mismatch
119 The source mac ethernet address didn't match the address inside the
120 arp packet.
121 reused old ethernet address
123 The ethernet address has changed from the most recently seen address
124 to the third (or greater) least recently seen address. (This is
125 similar to a flip flop.)
126 suppressed DECnet flip flop
128 A "flip flop" report was suppressed because one of the two addresses
129 was a DECnet address.
130
132 /var/lib/arpwatch default directory
133 arp.dat default ethernet/ip address database
134 ethercodes.dat vendor ethernet block list
135
137 arpsnmp(8), arp(8), bpf(2), tcpdump(8), pcapture(8), pcap(3)
138
140 Craig Leres of the Lawrence Berkeley National Laboratory Network Research
141 Group, University of California, Berkeley, CA.
142 The current version is available via anonymous ftp:
144 ftp://ftp.ee.lbl.gov/arpwatch.tar.gz
146
148 Please send bug reports to ⟨arpwatch@ee.lbl.gov⟩.
149 Attempts are made to suppress DECnet flip flops but they aren't always
151 successful.
152 Most error messages are posted using syslog.
154 26 October 2021