ADDRWATCH(8)

NAME
addrwatch - ethernet/ip address monitoring tool

SYNOPSIS
addrwatch [-lmqv46dP?V] [-m[database]] [-o file] [-s sqlite3.db] [-b ip] [-H size] [-r num] [-p pidfile] [-u user] [-h hostname] [--mysql-table=table] [--sqlite3-table=table] [INTERFACE1 INTERFACE2 ...]

DESCRIPTION
addrwatch is a similar software to arpwatch. It main purpose is to monitor network and log ethernet/ip pairings.

To simply try out addrwatch start it without any arguments. When started without arguments it will open first non loopback interface and start logging events to the console without writing anything to disk. All discovered ethernet/ip address pairings will be printed to stdout. All debug, warning, and err messages will be sent to syslog and printed to stderr.

OPTIONS

-l, --syslog
    Log discovered ethernet/ip address pairings to syslog (daemon facility).

-o file, --output=file
    Write discovered ethernet/ip address pairings to a specified file. See OUTPUT section for more details.

-m[database], --mysql=[database]
    Write discovered ethernet/ip address pairings to MySQL database. Default MySQL server, login information and database should be specified in ~/.my.cnf configuration file in addrwatch section. Example of ~/.my.cnf configuration file:
    [addrwatch]
    host=localhost
    user=db_user
    password=db_password
    database=db_name
    Pairings are written in a table having such schema:
    CREATE TABLE IF NOT EXISTS `addrwatch` (
    `tstamp` timestamp NOT NULL,
    `hostname` varchar(256) NOT NULL,
    `interface` varchar(16) NOT NULL,
    `vlan_tag` int(11) NOT NULL,
    `mac_address` varchar(17) NOT NULL,
    `ip_address` varchar(42) NOT NULL,
    `origin` varchar(8) NOT NULL,
    KEY `interface` (`interface`),
    KEY `vlan_tag` (`vlan_tag`),
    KEY `interface_vlan_tag` (`interface`,`vlan_tag`)
    )
    Default table name is addrwatch unless option --mysql-table is specified.

--mysql-table=TBL
    Insert data to MySQL table TBL.

-s sqlite3.db, --sqlite3=sqlite3.db
    Write discovered ethernet/ip address pairings to sqlite3 database in sqlite3.db file. Database file and tables are created during startup if does not exists. Pairings are written in a table having such schema:
    CREATE TABLE addrwatch(
    timestamp UNSIGNED BIG INT,
    interface varchar(16),
    vlan_tag UNSIGNED INT,
    mac_address varchar(17),
    ip_address varchar(42),
    origin TINYINT
    );

-q, --quiet
    Suppress any output to stdout and stderr.

-v, --verbose
    Enable debug messages.

-4, --ipv4-only
    Capture only IPv4 packets.

-6, --ipv6-only
    Capture only IPv6 packets.

-b ip, --blacklist=ip
    Ignore pairings with specified ip address.

-r num, --ratelimit=num
    If num > 0, ratelimit duplicate ethernet/ip pairings to 1 every num seconds.
    If num = 0, ratelimiting of duplicate entries is disabled.
    If num = -1, duplicate entries are suppressed indefinitely. See RATELIMITING section for more details.

-H size, --hashsize=size
    Size of ratelimiting hash table used to store recent ethernet/ip address pairings. Minimum value is 1, maximum value is 65536. Default value is 1 (no hash table), all pairings are stored in a linked list. The size of hash table should be increased in active networks with many nodes. Lager hash table speeds up cache lookups at the cost of increased memory usage.

-d, --daemon
    Become a daemon after start. This option implies -q (--quiet) argument.

-h hostname, --hostname=hostname
    Override system hostname.

-p pidfile, --pid=pidfile
    Write process id to pidfile. Pidfile is deleted when application is terminated. This option is usually used with -d (--daemon) argument. When used with -u (--user) argument pidfle will be created before changing active user and in most cases addrwatch will not be able to delete pidfile on exit.

-P, --no-promisc
    Disable promisc mode on network interfaces.

-u user, --user=user
    Suid to user after opening network interfaces.

-?, --help
    Show command line arguments.

--usage
    Give a short usage message.

-V, --version
    Print program version.

OUTPUT
In output file or stdout each line represents one ethernet/ip address pairing discovery event. Event has following format unix timestamp, interface, vlan tag, mac address, ip address and packet type separated by a space.

Packets without vlan tag is represented by tag value 0.

Possible packet types are ARP_REQ, ARP_REP, ARP_ACD, ND_ND, ND_NA, ND_DAD. Ethernet address and IP address are extracted from different parts of the packet based on packet type.

ARP_REQ
    ARP Request packet. Sender hardware address (from ARP header) and sender protocol address (from ARP header) is saved.

ARP_REP
    ARP Reply packet. Sender hardware address (from ARP header) and sender protocol address (from ARP header) is saved.

ARP_ACD
    ARP Address collision detection packet. Sender hardware address (from ARP header) and target protocol address (from ARP header) is saved.

ND_NS
    Neighbor Solicitation packet.    Source link-layer address (from NS
    option) and source address (from IPv6 header) is saved.

ND_NA
    Neighbor Advertisement packet. Target link-layer address (from NA option) and source address (from IPv6 header) is saved.

ND_DAD
    Duplicate Address Detection packet. Source MAC (from Ethernet header) and target address (from NS header) is saved.

Output example:
timestamp iface vlan mac ip type
1339405924 eth0 502 e0:ca:94:30:06:8b 2001:db8:200:4202:8946:e6b7:976a:cef3 ND_NA
1339406009 eth0 257 f0:4d:a2:2e:ad:0d 169.254.227.85 ARP_ACD
1339406018 eth0 502 58:1f:aa:d0:92:7d 2001:db8:200:4202:805d:b5ae:8374:436c ND_DAD
1339406029 eth0 502 38:59:f9:3a:de:65 172.16.2.19 ARP_REP
1339406030 eth0 12 00:c0:ee:5a:89:c7 10.1.32.221 ARP_REQ
1339406030 eth0 252 00:1c:c0:79:ab:ee 2001:db8:200:2381::657b ND_NS

RATELIMITING
If used without ratelimiting addrwatch reports etherment/ip pairing every time it gets usable ARP or IPv6 ND packet. In actively used networks it generates many duplicate pairings especially for routers and servers.

Ratelimiting option -r num ( --ratelimit=num ) suppress output of duplicate pairings for at least NUM seconds (all non duplicate pairings will be reported). In other words if addrwatch have discovered some pairing (mac,ip) it will not report (mac,ip) again unless NUM seconds have passed.

There is an exception to this rule to allow tracking ethernet address changes. If addrwatch have discovered pairings: (mac1,ip),(mac2,ip),(mac1,ip) within ratelimit time window it will report all three pairings. By doing so ratelimiting will not loose any information about ethernet address changes.

For example if we have a stream of events:
time   ethernet          ip
01     11:22:33:44:55:66 192.168.0.1
15     11:22:33:44:55:66 192.168.0.1
20     aa:bb:cc:dd:ee:ff 192.168.0.1
25     aa:bb:cc:dd:ee:ff 192.168.0.1
30     11:22:33:44:55:66 192.168.0.1
35     11:22:33:44:55:66 192.168.0.1
40     aa:bb:cc:dd:ee:ff 192.168.0.1
65     aa:bb:cc:dd:ee:ff 192.168.0.1

With --ratelimit=100 we would get:
time   ethernet          ip
01     11:22:33:44:55:66 192.168.0.1
20     aa:bb:cc:dd:ee:ff 192.168.0.1
30     11:22:33:44:55:66 192.168.0.1
40     aa:bb:cc:dd:ee:ff 192.168.0.1

Without the exception output would be:
time   ethernet          ip
01     11:22:33:44:55:66 192.168.0.1
20     aa:bb:cc:dd:ee:ff 192.168.0.1

And we would loose information that address 192.168.0.1 was used by 11:22:33:44:55:66 between 30-40th seconds.

To sum up ratelimiting reduces amount of duplicate information without loosing any ethernet address change events.

Ratelimit option essentially limits data granularity for IP address usage duration information (when and for what time period specific IP address was used). On the other hand without ratelimiting at all you would not get very precise IP address usage duration information anyways because some hosts might use IP address without sending ARP or ND packets as often as others do.

If num is set to 0, ratelimiting is disabled and all pairing discovery events are reported.

If num is set to -1, ratelimiting is enabled with infinitely long time window therefore all duplicate pairings are suppressed indefinitely. In this mode addrwatch acts almost as arpwatch with the exception that ethernet address changes are still reported.

It might look tempting to always use addrwatch with --ratelimit=-1 however by doing so you loose the information about when and for what period of time specific IP address was used. There will be no difference between temporary IPv6 addressed which was used once and statically configured permanent addresses.

NOTES
You can send SIGHUP signal to addrwatch to force it reopen output file. It may be useful if used in combination with logrotate(8).

EXAMPLES
Start monitoring first non loopback network interface. Output will be send to stdout:

    addrwatch

Start monitoring on multiple interfaces:

    addrwatch eth0 eth1 eth2

Start addrwatch as a daemon, write output to file, enable ratelimiting to 1 event per minute:

    addrwatch -d -o /var/lib/addrwatch.dat -r 60 eth0

Start as a daemon, save pid file, send output to syslog, ratelimit to 1 event per hour, suid to nobody, monitor multiple interfaces:

    addrwatch -d -p /var/run/addrwatch.pid -s -r 3600 -u nobody eth0 eth1 eth3

SEE ALSO
logrotate(8)