1ADDRWATCH(8)                  addrwatch man page                  ADDRWATCH(8)
2
3
4

NAME

6       addrwatch - ethernet/ip address monitoring tool
7

SYNOPSIS

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

DESCRIPTION

14       addrwatch is a similar software to arpwatch. It main purpose is to mon‐
15       itor network and log ethernet/ip pairings.
16
17       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

OPTIONS

25       -l, --syslog
26              Log  discovered  ethernet/ip  address pairings to syslog (daemon
27              facility).
28
29       -o file, --output=file
30              Write discovered ethernet/ip address  pairings  to  a  specified
31              file.  See OUTPUT section for more details.
32
33       -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
44              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
60       --mysql-table=TBL
61              Insert data to MySQL table TBL.
62
63       -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
68              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
78       -q, --quiet
79              Suppress any output to stdout and stderr.
80
81       -v, --verbose
82              Enable debug messages.
83
84       -4, --ipv4-only
85              Capture only IPv4 packets.
86
87       -6, --ipv6-only
88              Capture only IPv6 packets.
89
90       -b ip, --blacklist=ip
91              Ignore pairings with specified ip address.
92
93       -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
100       -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
106              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
110       -d, --daemon
111              Become a daemon after start. This option  implies  -q  (--quiet)
112              argument.
113
114       -h hostname, --hostname=hostname
115              Override system hostname.
116
117       -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
124       -P, --no-promisc
125              Disable promisc mode on network interfaces.
126
127       -u user, --user=user
128              Suid to user after opening network interfaces.
129
130       -?, --help
131              Show command line arguments.
132
133       --usage
134              Give a short usage message.
135
136       -V, --version
137              Print program version.
138

OUTPUT

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
145       Packets without vlan tag is represented by tag value 0.
146
147       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
151       ARP_REQ
152              ARP Request packet. Sender hardware address  (from  ARP  header)
153              and sender protocol address (from ARP header) is saved.
154
155       ARP_REP
156              ARP  Reply packet. Sender hardware address (from ARP header) and
157              sender protocol address (from ARP header) is saved.
158
159       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
164       ND_NS  Neighbor Solicitation packet. Source link-layer address (from NS
165              option) and source address (from IPv6 header) is saved.
166
167       ND_NA  Neighbor  Advertisement  packet. Target link-layer address (from
168              NA option) and source address (from IPv6 header) is saved.
169
170       ND_DAD Duplicate Address Detection packet. Source  MAC  (from  Ethernet
171              header) and target address (from NS header) is saved.
172
173       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

RATELIMITING

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
188       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
194       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
200       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
211       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
218       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
223       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
226       To  sum up ratelimiting reduces amount of duplicate information without
227       loosing any ethernet address change events.
228
229       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
236       If  num is set to 0, ratelimiting is disabled and all pairing discovery
237       events are reported.
238
239       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
244       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

NOTES

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

EXAMPLES

255       Start monitoring first non loopback network interface. Output  will  be
256       send to stdout:
257
258              addrwatch
259
260       Start monitoring on multiple interfaces:
261
262              addrwatch eth0 eth1 eth2
263
264       Start  addrwatch as a daemon, write output to file, enable ratelimiting
265       to 1 event per minute:
266
267              addrwatch -d -o /var/lib/addrwatch.dat -r 60 eth0
268
269       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
272              addrwatch -d -p /var/run/addrwatch.pid -s -r 3600 -u nobody eth0
273              eth1 eth3
274

SEE ALSO

276       logrotate(8)
277
278
279
280addrwatch 0.3                     06 Jun 2012                     ADDRWATCH(8)
Impressum