.\"
.\" Copyright (c) 1992, 1994, 1996, 1997, 2000
.\"	The Regents of the University of California.  All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that: (1) source code distributions
.\" retain the above copyright notice and this paragraph in its entirety, (2)
.\" distributions including binary code include the above copyright notice and
.\" this paragraph in its entirety in the documentation or other materials
.\" provided with the distribution, and (3) all advertising materials mentioning
.\" features or use of this software display the following acknowledgement:
.\" ``This product includes software developed by the University of California,
.\" Lawrence Berkeley Laboratory and its contributors.'' Neither the name of
.\" the University nor the names of its contributors may be used to endorse
.\" or promote products derived from this software without specific prior
.\" written permission.
.\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR IMPLIED
.\" WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
.\"
.TH ARPWATCH 1M "24 August 2016"
.SH NAME
arpwatch \- keep track of ethernet/ip address pairings


.SH SYNOPSIS
.nh
.na
.HP
\fBarpwatch\fR [\-a] [\-D] [\-e\ \fIfile\fR] [\-d] [\-f\ \fIdatafile\fR] [\-i\ \fIinterface\fR]
[\-l\ \fIfacility\fR]
[\-m\ \fIaddr\fR]  [\-N] [\-n\ \fInet\fR[/\fIwidth\fR]] [\-p] [\-r\ \fIfile\fR]
[\-S] [\-X\ \fIfile\fR] [\-Z] [\-z\ \fInet\fR/\fImask\fR]
.ad
.hy


.SH DESCRIPTION
.B Arpwatch
keeps track for ethernet/ip address pairings by listening for arp packets on a
local ethernet interface.
It syslogs activity and optionally reports certain changes via email.


.SH OPTIONS
.TP
.B \-a
Process all bogons.  Bogons are packets with a source IP address not matching
the same subnet as the first IP address of the related interface or any subnet
added via option \fB-n\ \fI...\fR. By default \fBarpwatch\fR just syslogs a 
related message and stops analyzing such a packet.
.TP
.B \-D
Turn off reverse-DNS queries for detected source IP addresses. This may speed
up generating reports significantly.

.TP
.B \-d
Enable debugging. This also inhibits forking into the
background and emailing the reports. Instead, they are sent to \fBstderr\fR .

.TP
.BI \-e\  file
Use the given \fIfile\fR as vendor ethernet block list (default:
\fB/var/arpwatch/ethercodes.dat\fR). If it is unavailable, \fBarpwatch\fR will
not resolve MAC address prefixes to vendor names.

.TP
.BI \-f\  datafile
Set the ethernet/ip address database filename to use (default: 
.BR /var/arpwatch/arp.dat ).
A relative path gets resolved to the current working from which this tool
gets started.
.IP
This file must exist before you run this tool.
.IP
Every 15 minutes, when it receives a \fBQUIT\fR or \fBALRM\fR signal and
when \fBarpwatch\fR exits, it
tries to save the in memory data by creating \fIdatafile\fB.new\fR , write all
in memory data to it, rename the current \fIdatafile\fR to \fIdatafile\fB-\fR
and finally rename \fIdatafile\fB.new\fR to \fIdatafile\fR. So make sure
that \fBarpwatch\fR has proper permissions to write such files within the
related directory. 

.TP
.BI \-i\  interface
Set the interface to use.

.TP
.BI \-l\  facility
Set the \fBsyslog\fR(3) facility to use. Default: \fBDAEMON\fR.

.TP
.BI \-m\  addr
Specify the e\-mail address to which reports will be
sent.  By default no reports are sent.

.TP
.B \-N
No bogon check. This is similar to option \fB\-a\fR, however the bogon check
gets skipped completely and thus even syslog messages for bogons disappear.
.TP
\fB\-n\fR\ \fInet\fR[/\fIwidth\fR]
Specify additional local networks. This can be useful to
avoid "bogon" warnings when there is more than one network running
on the same wire. If the optional
.I width
is not specified, the default netmask for the network's class is used.

.TP
.B \-p
Disable promiscuous operation.  ARP broadcasts get through hubs without
having the interface in promiscuous mode, while saving considerable resources
that would be wasted on processing gigabytes of non-broadcast traffic.
However, setting promiscuous mode does not mean getting 100% traffic that
would concern \fBarpwatch\fR anyway.

.TP
.BI \-r\  file
Specify a savefile
(perhaps created by
.BR tcpdump (1M))
to read from instead
of reading from the network. In this case,
.B arpwatch
does not fork.

.TP
.B \-S
Disable reporting of new stations.

.TP
.BI \-X\  file
Exclude ethernet addresses listed in the given \fIfile\fR from processing or
reporting. The file format is simple:
.RS 7
.P
Every line with a length of zero or starting with a hash mark ('#') gets
ignored.
.P
A line which starts with \fBone\fR of the the following letters (case sensitive)
followed by a whitespace (space, tab or newline) determines the exclude type,
i.e. how subsequent ethernet address(es) should be handled: \fBX\fR (ignore
completely, i.e. no processing at all), \fBD\fR (ignore wrt. database and
reports), \fBA\fR (no activity reports), \fBS\fR (no "new station" reports),
\fBF\fR (no flipflop reports) and \fBC\fR (no "changed" reports).
.P
Any number of lines just containing the ethernet address to exclude.
.RE
.IP
Within the file the exclude type can be switched as often as desired. The order
of the ethernet address list which follows, is important - this tool just
iterates through each list to find an ethernet address, i.e. no special
sort/find algorithm will be used (only small lists are expected for now).

.TP
\fB\-z\ \fInet\fR/\fImask\fR
Set a range of ip addresses to ignore (such as a DHCP
range). Netmask is specified as 255.255.128.0.
.TP
.B \-Z
Ignore any packet which has no or an IP address of all-zeros (0.0.0.0).


.SH EXAMPLES
Within the following examples, the dollar sign ($ ) represents the shell prompt.
Commands are assumed to be executed by an user having related profile(s)
and/or authorizations assigned to its account (see \fBNOTES\fR).

.HP
\fBExample 1\fR: Enable the default arpwatch service:
.sp
.IP
.nf
$ \fBsvcadm enable arpwatch\fR
.fi
 
.HP
\fBExample 2\fR: Disable the arpwatch:net1 service:
.sp
.IP
.nf
$ \fBsvcadm disable arpwatch:net2\fR
.fi
 
.HP
\fBExample 3\fR: Show the arpwatch service description of the "config"
property group:
.sp
.IP
.nf
$ \fBsvccfg -s arpwatch describe config\fR
.fi
 
.HP
\fBExample 4\fR: Setup a new service instance for the interface
named \fInet2\fR:
.sp
.IP
.nf
$ \fBsvccfg -s network/arpwatch "add net2"\fR
$ \fBsvccfg -s network/arpwatch:net2 \\
	"setprop config/datafile = /var/arpwatch/arp2.dat"\fR
$ \fBsvccfg -s network/arpwatch:net2 "setprop config/interface = net2"\fR
$ \fBsvccfg -s network/arpwatch:net2 refresh\fR
$ \fBsvcadm enable arpwatch:net2\fR
.fi

.P
For better user experience the \fBsvccfg\fR(1M) commands shown above use one
svccfg command per execution, only. However, as usual, they can be combined
on CLI or written to a file and executed by svccfg as a normal "batch" job.

.SH SIGNALS
.TP
.BR QUIT ,\  ALRM
Save the current in memory data to file (see option \fB\-f\ \fI...\fR)
and continue.
.TP
.BR INT ,\  HUP ,\  TERM 
Save the current in memory data to file (see option \fB\-f\ \fI...\fR)
and exit.


.SH FILES
.TP
.B /var/arpwatch/arp.dat
Default ethernet/ip address database maintained by arpwatch.
.TP
.B /var/arpwatch/ethercodes.dat
The default vendor ethernet block list used by arpwatch.
.TP
.B /etc/security/auth_attr.d/arpwatch
Location of the arpwatch authorization definitions.
On Solaris 10 these authorizations are append to /etc/security/auth_attr.
.TP
.B /etc/security/prof_attr.d/arpwatch
Location of the definition of the arpwatch profile description.
On Solaris 10 it is append to /etc/security/prof_attr.
.TP
.B /etc/security/exec_attr.d/arpwatch
Location of the arpwatch execution profile.
On Solaris 10 it is append to /etc/security/exec_attr.


.SH "SEE ALSO"
.BR arpsnmp (1M),
.BR arp (1M),
.BR bpf (7D),
.BR tcpdump (1M),
.BR pcap (3),
.BR svcadm (1M),
.BR svcprop (1),
.BR svccfg (1M),
.BR auths (1),
.BR profiles (1).

.SH DIAGNOSTICS
.BR arpwatch (1M)
and
.BR arpsnmp (1M)
generate the following reports, i.e. syslogs and optionally sends these messages via e\-mail:
.RS
.TP 3
.B "new activity"
This ethernet/ip address pair has been used for the first time six
months or more.
.TP
.B "new station"
The ethernet address has not been seen before.
.TP
.B "flip flop"
The ethernet address has changed from the most recently seen address to
the second most recently seen address.
(If either the old or new ethernet address is a DECnet address and it
is less than 24 hours, the email version of the report is suppressed.)
.TP
.B "changed ethernet address"
The host switched to a new ethernet address.
.RE
.PP
Other syslog messages (not send via e\-mail) are:
.RS
.TP 3
.B "ethernet broadcast"
The mac ethernet address of the host is a broadcast address, i.e. source mac
or arp ethernet address was all ones or all zeros.
.TP
.B "ip broadcast"
The ip address of the host is a broadcast address.
.TP
.B "bogon"
The source ip address is not local to the local subnet.
.TP
.B "ethernet mismatch"
The source mac ethernet address didn't match the address inside
the arp packet.
.TP
.B ignored
The arp packet gets ignored because it matches an IP address specified via
option \fB\-z\fR\ \fInet\fR/\fImask\fR (in debug mode, only).
.TP
.B "reused old ethernet address"
The ethernet address has changed from the most recently seen address to
the third (or greater) least recently seen address.
(This is similar to a flip flop.)
.TP
.B "hostname changed"
The hostname associated with a certain mac address has changed.
.TP
.B "suppressed DECnet flip flop"
A "flip flop" report was suppressed because one of the two
addresses was a DECnet address.
.RE
.IP
In daemon mode error messages are also syslogged, in debug or "not yet daemon"
mode they get printed to stderr.


.SH NOTES
On Solaris/Illumos the \fBsvc:/network/arpwatch:default\fR service gets
installed but not enabled per default. When enabled it runs arpwatch as the
normal user \fBarpwatchd\fR, but with the \fBnet_rawaccess\fR privillege so
that it can (and will by default) use the promiscuous mode. To show the
current service configuration or to change it, one may use the wellknown
commands \fBsvcprop\fR(1) and \fBsvccfg\fR(1M) as shown in the examples section
above.
.P
In case you want to have arpwatch listen to more than one 
interface, it is recommended to setup a new service instance (e.g.
\fBsvc:/network/arpwatch:\fInet1\fR) for each additional interface as shown in
the examples section above as well, because arpwatch itself does not support
listening to more than a single interface. In this case one should explictly
set the service properties \fBconfig/interface\fR and \fBconfig/datafile\fR to
avoid that the services listen to the same interface or overwrite each others
database file.
.P
Any user having the \fBNetwork Management\fR or \fBNetwork Observability\fR
profile assigned to it, can execute the \fBarpwatch\fR command using its
promiscuous mode - it gets the \fBnet_rawaccess\fR privillege automatically
if the executing shell is privilege-aware or a related \fBpf\fI*\fR command
is used. Therefore there is no need to run arpwatch as user root.
.P
The start/stop if the service requires \fBsolaris.smf.manage.arpwatch\fR
authorization, changing service parameters requires
\fBsolaris.smf.value.arpwatch\fR, which are assigned to the profiles mentioned
above, too.


.SH AUTHORS
Craig Leres of the
Lawrence Berkeley National Laboratory Network Research Group,
University of California, Berkeley, CA.
.LP
The current version is available via anonymous ftp:
.LP
.RS
.I ftp://ftp.ee.lbl.gov/arpwatch.tar.gz
.RE


.SH BUGS
Please send bug reports to arpwatch@ee.lbl.gov.
.LP
Attempts are made to suppress DECnet flip flops but they
aren't always successful.
.LP
Most error messages are posted using syslog.