Introduction

Arpwatch is a network tool that monitors an ethernet broadcast domain and keeps a flat-file database of ethernet / ip address-pairings. Arpwatch furthermore reports certain changes via email and syslog messages.

When you allocate (part of) your ip address space using a dhcp server and run arpwatch as a daemon, it keeps you informed whenever a networked device gets a new network address. This allows you to see if someone is doing something he/she should not be doing, for instance messing with his/her network settings. When you connect a new device, like a new network printer, that out of the box gets its ip address from a dhcp server, arpwatch immediately emails you its ip address so you can telnet or surf to the printer's management agent and configure it, for instance assign it a static ip address.

Arpwatch2html is a Perl script to convert the arpwatch flat-file database into a nice-looking html page. There is an option to sort the arpwatch entries by time, mac address, ip address or hostname. The user can select which fields from the address-pairing database will be shown. It is furthermore possible to omit old entries. Finally, it is also possible to show the most recent messages that were sent by arpwatch to the syslog daemon.

License

Arpwatch2html is copyrighted software. It must be purchased if it is to be used in commercial endeavors, but it is free for non-commercial use.

When you buy arpwatch2html, you also get the cgi-bin version. It allows you to access the arpwatch data in real-time, to sort the data in different ways and to filter it.

The cgi-bin version is provided in source code as a Perl script, together with the necessary installation instructions. The layout is based on a css file that can be easily modified in order to integrate the script in an existing network monitoring environment.

Download

The latest release of arpwatch2html is version 0.9. It is available here.

Installation

Adapt the first line of arpwatch2html "#!/usr/bin/perl" so that it reflects the location of Perl on your system.

You can also add arpwatch2html to crontab so that the html page is regularly updated in an automatic way.

Usage

Arpwatch2html makes use of the Perl Getopt::Long module for parsing its command-line parameters. As a result, the option names may be abbreviated as long as they remain unique.

These are the options that are available with arpwatch2html:

option	meaning	default value
-datfile=filename	location of arpwatch data	/var/arpwatch/arp.dat
-msgfile=filename	location of arpwatch messages	/var/log/messages
-outfile=filename	the output html file	stdout
-sort=[mac\|ip\|time\|name]	sort entries by given key	ip
-columns=[mitn]	columns to show and their order	tmin
-pruneold=days	remove arpwatch older than "days"
-header=filename	file with an html header
-footer=filename	file with an html footer
-css=url	reference to a cascading stylesheet
-help or -usage	shows a help message

-datfile and -msgfile

Arpwatch save the ethernet/ip address mappings it discovers to a flat-file database that is by default located in /var/arpwatch/arp.dat. Should your arpwatch installation be configured to place this file in another place, you can use the -datfile option to specify its location.

Arpwatch furthermore sends messages to the syslog daemon. These messages are then written in a messages file. Arpwatch2html looks by default in /var/log/messages for the messages generated by arpwatch. Should your syslog daemon send the arpwatch messages to another file, you can specify its location using the -msgfile option.

-outfile

Arpwatch2html generates a report in the form of an html page. By default this page is sent to stdout. You can then pipe it to another application or send it to a file. You can however also use the -outfile option and specify a location to send the output directly to a file.

-sort

The -sort option defines the key that is used for sorting the entries in the ethernet/ip address mapping table.

The following keys can be specified with the -sort option (only one):

mac: sort by mac address
ip: sort by ip address
time: sort by time stamp
name: sort by hostname

By default the rows are sorted by ip address.

-columns

The -columns option defines the columns that are to be shown.

A combination of the following letters can be used to indicate which fields are to be shown and in which order:

m: the mac address
i: the ip address
t: the time stamp
n: the hostname

The default setting is mitn.

-pruneold

The -pruneold options filters out ethernet/ip address mappings that or older than the specified number of days.

The default value is to not remove any mappings.

-header and -footer

The -header and -footer options are used to specify files in html format that are to be included as a header and a footer to the generated html page.

-css

The -css option is used to specify a link to a css page that is be added to the generated html page.

This options can not be used in combination with the -header option. When you provide your own html header it is up to you to link to the appropriate css file.

-help or -usage

Display a help-text regarding the usage of arpwatch2html and the available options.

Examples

An example, generated using the command
arpwatch2html.pl -col=tmi -sort=time -out=example01.html
is available here.

Here is another example, this time generated using the command
arpwatch2html.pl -header example_header.html -footer example_footer.html -out example02.html
in combination with this header file and this footer file.

Finally, here is an example with a user defined css file. The sample css file can be downloaded here.

Links

We are pleased to announce that arpwatch2html has a page on freshmeat, is linked from linuxlinks, and is a part of the Linux network security toolkit (nst).

We also learned that arpwatch2html is being used at the German Ruhr-Universitat Bochum for a course on security in a lab session (local copy).