arpwatch(8)

1ARPWATCH(8)               BSD System Manager's Manual              ARPWATCH(8)
2

NAME

4     arpwatch — keep track of ethernet/ip address pairings
5

SYNOPSIS

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

DESCRIPTION

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
16     The -C flag (default) uses compact padded ethernet addresses in arp.dat,
17     e.g. 0:8:e1:1:2:d6.
18
19     The -d flag is used enable debugging. This also inhibits forking into the
20     background and emailing the reports. Instead, they are sent to stderr.
21
22     The -D flag is used to specify the arpwatch working directory. This de‐
23     faults to /var/lib/arpwatch.
24
25     The -f flag is used to set the ethernet/ip address database filename.
26     The default is arp.dat.
27
28     The -F flag is prevents arpwatch from forking causing it to run in the
29     foreground.
30
31     The -i flag is used to override the default interface.
32
33     The -n flag specifies additional local networks. This can be useful to
34     avoid "bogon" warnings when there is more than one network running on the
35     same wire. If the optional width is not specified, the default netmask
36     for the network's class is used.
37
38     The -N flag disables reporting any bogons.
39
40     The -p flag disables promiscuous mode.
41
42     The -P flag specifies the pidfile.
43
44     The -q flag suppresses reports being logged or printed to stderr.
45
46     The -r flag is used to specify a savefile (perhaps created by tcpdump(8)
47     or pcapture(8)) to read from instead of reading from the network. In this
48     case arpwatch does not fork.
49
50     Note that an empty arp.dat file must be created before the first time you
51     run arpwatch.  Also, the default directory (where arp.dat is stored) must
52     be owned by username if the -u flag is used.
53
54     The -s flag suppresses reports sent by email.
55
56     The -u flag causes arpwatch to drop root privileges and change user ID to
57     username and group ID to that of the primary group of username.  This is
58     recommended for security reasons.
59
60     The -v flag disables the reporting of VRRP/CARP ethernet prefixes as de‐
61     scribed in RFC5798 (00:00:5e:00:01:xx).
62
63     The -w flag is used to specify the target address for email reports. The
64     default is root.
65
66     The -W flag is used specifies the from address for email reports. The de‐
67     fault is root.
68
69     The -z flag disables reporting 0.0.0.0 changes, helpful in busy DHCP-
70     served networks.
71
72     The -Z flag uses zero padded ethernet addresses in arp.dat, e.g.
73     00:08:e1:01:02:d6.
74

REPORT MESSAGES

76     Here's a quick list of the report messages generated by arpwatch(8) (and
77     arpsnmp(8)):
78
79     new activity
80          This ethernet/ip address pair has been used for the first time six
81          months or more.
82
83     new station
84          The ethernet address has not been seen before.
85
86     flip flop
87          The ethernet address has changed from the most recently seen address
88          to the second most recently seen address.  (If either the old or new
89          ethernet address is a DECnet address and it is less than 24 hours,
90          the email version of the report is suppressed.)
91
92     changed ethernet address
93          The host switched to a new ethernet address.
94

SYSLOG MESSAGES

96     Here are some of the syslog messages; note that messages that are re‐
97     ported are also sysloged.
98
99     ethernet broadcast
100          The mac ethernet address of the host is a broadcast address.
101
102     ip broadcast
103          The ip address of the host is a broadcast address.
104
105     bogon
106          The source ip address is not local to the local subnet.
107
108     ethernet broadcast
109          The source mac or arp ethernet address was all ones or all zeros.
110
111     ethernet mismatch
112          The source mac ethernet address didn't match the address inside the
113          arp packet.
114
115     reused old ethernet address
116          The ethernet address has changed from the most recently seen address
117          to the third (or greater) least recently seen address.  (This is
118          similar to a flip flop.)
119
120     suppressed DECnet flip flop
121          A "flip flop" report was suppressed because one of the two addresses
122          was a DECnet address.
123

FILES

125     /var/lib/arpwatch  default directory
126     arp.dat            default ethernet/ip address database
127     ethercodes.dat     vendor ethernet block list
128

AUTHORS

133     Craig Leres of the Lawrence Berkeley National Laboratory Network Research
134     Group, University of California, Berkeley, CA.
135
136     The current version is available via anonymous ftp:
137
138           ftp://ftp.ee.lbl.gov/arpwatch.tar.gz
139

BUGS

141     Please send bug reports to ⟨arpwatch@ee.lbl.gov⟩.
142
143     Attempts are made to suppress DECnet flip flops but they aren't always
144     successful.
145
146     Most error messages are posted using syslog.
147
148                                1 December 2019