FreeBSD Manual Pages
ADDRWATCH(8) addrwatch man page 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 mon- itor 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 data- base 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 applica- tion is terminated. This option is usually used with -d (--dae- mon) argument. When used with -u (--user) argument pidfle will be created before changing active user and in most cases addr- watch 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, in- terface, 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 net- works it generates many duplicate pairings especially for routers and servers. Ratelimiting option -r num ( --ratelimit=num ) suppress output of du- plicate 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 re- port 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 us- age duration information (when and for what time period specific IP ad- dress was used). On the other hand without ratelimiting at all you would not get very precise IP address usage duration information any- ways 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 how- ever by doing so you loose the information about when and for what pe- riod 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) addrwatch 0.3 06 Jun 2012 ADDRWATCH(8)
NAME | SYNOPSIS | DESCRIPTION | OPTIONS | OUTPUT | RATELIMITING | NOTES | EXAMPLES | SEE ALSO
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=addrwatch&sektion=8&manpath=FreeBSD+Ports+15.0>