1ADDRWATCH(8) addrwatch man page ADDRWATCH(8)
2
6 addrwatch - ethernet/ip address monitoring tool
7
9 addrwatch [-lmqv46dP?V] [-m[database]] [-o file] [-s sqlite3.db] [-b
10 ip] [-H size] [-r num] [-p pidfile] [-u user] [-h hostname] [--mysql-
11 table=table] [--sqlite3-table=table] [INTERFACE1 INTERFACE2 ...]
12
14 addrwatch is a similar software to arpwatch. It main purpose is to mon‐
15 itor network and log ethernet/ip pairings.
16 To simply try out addrwatch start it without any arguments. When
18 started without arguments it will open first non loopback interface and
19 start logging events to the console without writing anything to disk.
20 All discovered ethernet/ip address pairings will be printed to stdout.
21 All debug, warning, and err messages will be sent to syslog and printed
22 to stderr.
23
25 -l, --syslog
26 Log discovered ethernet/ip address pairings to syslog (daemon
27 facility).
28 -o file, --output=file
30 Write discovered ethernet/ip address pairings to a specified
31 file. See OUTPUT section for more details.
32 -m[database], --mysql=[database]
34 Write discovered ethernet/ip address pairings to MySQL database.
35 Default MySQL server, login information and database should be
36 specified in ~/.my.cnf configuration file in addrwatch section.
37 Example of ~/.my.cnf configuration file:
38 [addrwatch]
39 host=localhost
40 user=db_user
41 password=db_password
42 database=db_name
43 Pairings are written in a table having such schema:
45 CREATE TABLE IF NOT EXISTS `addrwatch` (
46 `tstamp` timestamp NOT NULL,
47 `hostname` varchar(256) NOT NULL,
48 `interface` varchar(16) NOT NULL,
49 `vlan_tag` int(11) NOT NULL,
50 `mac_address` varchar(17) NOT NULL,
51 `ip_address` varchar(42) NOT NULL,
52 `origin` varchar(8) NOT NULL,
53 KEY `interface` (`interface`),
54 KEY `vlan_tag` (`vlan_tag`),
55 KEY `interface_vlan_tag` (`interface`,`vlan_tag`)
56 )
57 Default table name is addrwatch unless option --mysql-table is
58 specified.
59 --mysql-table=TBL
61 Insert data to MySQL table TBL.
62 -s sqlite3.db, --sqlite3=sqlite3.db
64 Write discovered ethernet/ip address pairings to sqlite3 data‐
65 base in sqlite3.db file. Database file and tables are created
66 during startup if does not exists.
67 Pairings are written in a table having such schema:
69 CREATE TABLE addrwatch(
70 timestamp UNSIGNED BIG INT,
71 interface varchar(16),
72 vlan_tag UNSIGNED INT,
73 mac_address varchar(17),
74 ip_address varchar(42),
75 origin TINYINT
76 );
77 -q, --quiet
79 Suppress any output to stdout and stderr.
80 -v, --verbose
82 Enable debug messages.
83 -4, --ipv4-only
85 Capture only IPv4 packets.
86 -6, --ipv6-only
88 Capture only IPv6 packets.
89 -b ip, --blacklist=ip
91 Ignore pairings with specified ip address.
92 -r num, --ratelimit=num
94 If num > 0, ratelimit duplicate ethernet/ip pairings to 1 every
95 num seconds.
96 If num = 0, ratelimiting of duplicate entries is disabled.
97 If num = -1, duplicate entries are suppressed indefinitely. See
98 RATELIMITING section for more details.
99 -H size, --hashsize=size
101 Size of ratelimiting hash table used to store recent ethernet/ip
102 address pairings. Minimum value is 1, maximum value is 65536.
103 Default value is 1 (no hash table), all pairings are stored in a
104 linked list.
105 The size of hash table should be increased in active networks
107 with many nodes. Lager hash table speeds up cache lookups at
108 the cost of increased memory usage.
109 -d, --daemon
111 Become a daemon after start. This option implies -q (--quiet)
112 argument.
113 -h hostname, --hostname=hostname
115 Override system hostname.
116 -p pidfile, --pid=pidfile
118 Write process id to pidfile. Pidfile is deleted when applica‐
119 tion is terminated. This option is usually used with -d (--dae‐
120 mon) argument. When used with -u (--user) argument pidfle will
121 be created before changing active user and in most cases addr‐
122 watch will not be able to delete pidfile on exit.
123 -P, --no-promisc
125 Disable promisc mode on network interfaces.
126 -u user, --user=user
128 Suid to user after opening network interfaces.
129 -?, --help
131 Show command line arguments.
132 --usage
134 Give a short usage message.
135 -V, --version
137 Print program version.
138
140 In output file or stdout each line represents one ethernet/ip address
141 pairing discovery event. Event has following format unix timestamp,
142 interface, vlan tag, mac address, ip address and packet type separated
143 by a space.
144 Packets without vlan tag is represented by tag value 0.
146 Possible packet types are ARP_REQ, ARP_REP, ARP_ACD, ND_ND, ND_NA,
148 ND_DAD. Ethernet address and IP address are extracted from different
149 parts of the packet based on packet type.
150 ARP_REQ
152 ARP Request packet. Sender hardware address (from ARP header)
153 and sender protocol address (from ARP header) is saved.
154 ARP_REP
156 ARP Reply packet. Sender hardware address (from ARP header) and
157 sender protocol address (from ARP header) is saved.
158 ARP_ACD
160 ARP Address collision detection packet. Sender hardware address
161 (from ARP header) and target protocol address (from ARP header)
162 is saved.
163 ND_NS Neighbor Solicitation packet. Source link-layer address (from NS
165 option) and source address (from IPv6 header) is saved.
166 ND_NA Neighbor Advertisement packet. Target link-layer address (from
168 NA option) and source address (from IPv6 header) is saved.
169 ND_DAD Duplicate Address Detection packet. Source MAC (from Ethernet
171 header) and target address (from NS header) is saved.
172 Output example:
174 timestamp iface vlan mac ip type
175 1339405924 eth0 502 e0:ca:94:30:06:8b 2001:db8:200:4202:8946:e6b7:976a:cef3 ND_NA
176 1339406009 eth0 257 f0:4d:a2:2e:ad:0d 169.254.227.85 ARP_ACD
177 1339406018 eth0 502 58:1f:aa:d0:92:7d 2001:db8:200:4202:805d:b5ae:8374:436c ND_DAD
178 1339406029 eth0 502 38:59:f9:3a:de:65 172.16.2.19 ARP_REP
179 1339406030 eth0 12 00:c0:ee:5a:89:c7 10.1.32.221 ARP_REQ
180 1339406030 eth0 252 00:1c:c0:79:ab:ee 2001:db8:200:2381::657b ND_NS
181
183 If used without ratelimiting addrwatch reports etherment/ip pairing
184 every time it gets usable ARP or IPv6 ND packet. In actively used net‐
185 works it generates many duplicate pairings especially for routers and
186 servers.
187 Ratelimiting option -r num ( --ratelimit=num ) suppress output of
189 duplicate pairings for at least NUM seconds (all non duplicate pairings
190 will be reported). In other words if addrwatch have discovered some
191 pairing (mac,ip) it will not report (mac,ip) again unless NUM seconds
192 have passed.
193 There is an exception to this rule to allow tracking ethernet address
195 changes. If addrwatch have discovered pairings:
196 (mac1,ip),(mac2,ip),(mac1,ip) within ratelimit time window it will
197 report all three pairings. By doing so ratelimiting will not loose any
198 information about ethernet address changes.
199 For example if we have a stream of events:
201 time ethernet ip
202 01 11:22:33:44:55:66 192.168.0.1
203 15 11:22:33:44:55:66 192.168.0.1
204 20 aa:bb:cc:dd:ee:ff 192.168.0.1
205 25 aa:bb:cc:dd:ee:ff 192.168.0.1
206 30 11:22:33:44:55:66 192.168.0.1
207 35 11:22:33:44:55:66 192.168.0.1
208 40 aa:bb:cc:dd:ee:ff 192.168.0.1
209 65 aa:bb:cc:dd:ee:ff 192.168.0.1
210 With --ratelimit=100 we would get:
212 time ethernet ip
213 01 11:22:33:44:55:66 192.168.0.1
214 20 aa:bb:cc:dd:ee:ff 192.168.0.1
215 30 11:22:33:44:55:66 192.168.0.1
216 40 aa:bb:cc:dd:ee:ff 192.168.0.1
217 Without the exception output would be:
219 time ethernet ip
220 01 11:22:33:44:55:66 192.168.0.1
221 20 aa:bb:cc:dd:ee:ff 192.168.0.1
222 And we would loose information that address 192.168.0.1 was used by
224 11:22:33:44:55:66 between 30-40th seconds.
225 To sum up ratelimiting reduces amount of duplicate information without
227 loosing any ethernet address change events.
228 Ratelimit option essentially limits data granularity for IP address
230 usage duration information (when and for what time period specific IP
231 address was used). On the other hand without ratelimiting at all you
232 would not get very precise IP address usage duration information any‐
233 ways because some hosts might use IP address without sending ARP or ND
234 packets as often as others do.
235 If num is set to 0, ratelimiting is disabled and all pairing discovery
237 events are reported.
238 If num is set to -1, ratelimiting is enabled with infinitely long time
240 window therefore all duplicate pairings are suppressed indefinitely. In
241 this mode addrwatch acts almost as arpwatch with the exception that
242 ethernet address changes are still reported.
243 It might look tempting to always use addrwatch with --ratelimit=-1 how‐
245 ever by doing so you loose the information about when and for what
246 period of time specific IP address was used. There will be no differ‐
247 ence between temporary IPv6 addressed which was used once and stati‐
248 cally configured permanent addresses.
249
251 You can send SIGHUP signal to addrwatch to force it reopen output file.
252 It may be useful if used in combination with logrotate(8).
253
255 Start monitoring first non loopback network interface. Output will be
256 send to stdout:
257 addrwatch
259 Start monitoring on multiple interfaces:
261 addrwatch eth0 eth1 eth2
263 Start addrwatch as a daemon, write output to file, enable ratelimiting
265 to 1 event per minute:
266 addrwatch -d -o /var/lib/addrwatch.dat -r 60 eth0
268 Start as a daemon, save pid file, send output to syslog, ratelimit to 1
270 event per hour, suid to nobody, monitor multiple interfaces:
271 addrwatch -d -p /var/run/addrwatch.pid -s -r 3600 -u nobody eth0
273 eth1 eth3
274
276 logrotate(8)
277addrwatch 0.3 06 Jun 2012 ADDRWATCH(8)