NAME

vlog - Logfile viewer for IP-Filter

VERSION

1.1

SYNOPSIS

vlog [ -r ] [ -i ] [ -g regexp ] [ -v regexp ]
[ -l logfile or -l{imsxladcq} ] [ -[<nn>]f or -f ]
[ -<nn> or -n <nn> ] [ -s <date> ] [ -e <date> ]
[ -o{dtuhfrilan} ] [ -t ] [ -d ] [ -w <nn> ]

DESCRIPTION

vlog is a text-based real-time logfile viewer. Its primary aims are:

ipmon viewer: to display IP-Filter log lines in a readable way, in a curses-based scrollable window
isba ruleset debugging: to display the number of the isba source rule that generated each log line
real time tool: to ``follow'' the log file in real time and to handle logfile rotation transparently. Log lines are added to the window as soon as they are generated by ipmon
log analysis tool: to be able to browse all log files including old, rotated ones
filtering log lines: to be able to select the lines to be displayed with a regexp given on command line

Additionnally:

selecting fields to be displayed: for small screens: you can control which fields you want to see (e.g. time but not date, packet length but not IP header length, etc) (option -o, and key o in curses mode)
searching and jumping: in curses mode you can search a regexp, mark a line in video reverse, jump to next or previous marked line, jump to next or previous day boundary
tail -f mode: vlog can mimic the `tail -f' behaviour. Log lines are formatted and printed on stdout (no curses) as soon as they are generated (option -[<nnn>]f)
print mode: vlog can extract a specified set of log lines (print mode: no curses). Start date, end date, and/or a fixed number of lines can be given on command line (options -s, -e and -<nnn>)
view other logfiles: vlog can be used to view any syslogd-type log file (option -l).

If an ipfilter logfile is being viewed, vlog's formatting process renders ipmon informations with some slight differences:

TCP flags are displayed in a fixed position 6-chars segment. If a flag is set its letter is printed, otherwise a dot is printed as a placeholder (e.g. `SA....' is a Syn/Ack packet). Additionnally, flags S, F and R are (arbitrarily) displayed bold, as they represent the start/end of a connection. vlog recognizes flags S, A, P, U, F, R only.
vlog tries to guess the service involved in each log line and prints it between parentheses at the end of the line. If possible, its name is printed instead of the port number. If it's a block log line, the service is printed bold, so that one can see blocked services at a glance.

OPTIONS

-r (rotated)

show not only the current logfile, but also the previously rotated ones (logfile.0, logfile.1, ...).

Note: gzipped rotated files are not supported: if you want to be able to browse them, you must first gunzip them, then eventually remove automatic compression option (maybe in /etc/newsyslog.conf).

-i (ipmon)

show only loglines generated by ipmon. Default behaviour is to show every line of logfile.

-g regexp (grep)

show only loglines that match the regular expression regexp.

-v regexp (grep -v)

show only loglines that do not match the regular expression regexp.

-l logfile of -l{imsxladcq...}

specify the logfile to read instead of /var/log/ipflog. The logfile path can be fully specified on command line, or a single letter can be used: i = /var/log/ipflog (default), m = /var/log/messages (or /var/adm/messages on Solaris), s = /var/log/syslog, x = /var/log/xferlog, l = /var/log/maillog, a = /var/log/authlog, d = /var/log/daemon, c = /var/cron/log (or /var/cron/olog on Solaris), q = /var/log/squid.

For instance, vlog -lm shows system messages.

You can define your own key-to-logfile mapping in /etc/vlog.conf or ~/.vlogrc. See vlogrc.sample for the syntax (which is rather strict).

-<nn>f

``tail -f'' mode: format and print the last <nn> loglines (default 10) on stdout (no curses), then print them as soon as they are appended to logfile

-n <nn> or -<nn>

``print'' mode: print <nn> loglines on stdout and exit (no curses). If option -s is not given, the lines printed are the last ones.

-s [[Mmm] dd] [hh[:mm[:ss]] (start date)

show lines starting at specified date/time. If Mmm and dd are not given, use current day (ex: vlog -s Jul 21) (ex: vlog -s 12:30)

-e [[Mmm] dd] [hh[:mm[:ss]] (end date)

show lines up to specified date/time. This option implies simple text mode (no curses) (ex: vlog -s 12:30 -e 13:00)

-o{dtuhfrilan} (optional fields)

choose which optional fields to display.

For ipfilter logfiles the following fields are available: d=date, t=time, u=microseconds, h=hostname, f=interface, r=rule/group number, i=isba source rule number, l=IP header length.

For non-ipfilter logfiles the following fields are available: d=date, t=time, h=hostname, p=process name, i=pid of process.

Additionnally a=all optional fields and n=no optional fields.

If this option is not given, vlog arbitrarily chooses which fields to display according to window width. In curses mode this choice can be modified with the key o.

-t (text only)

for no curses modes: don't print ANSI codes (bold chars, etc). Suitable for redirecting output to a plain text file.

-w <nn> or -ww (terminal width)

for no curses modes: force vlog output to be nn chars max. Option -ww tells vlog to print full loglines whatever length they are.

-d (disguise)

disguises IP addresses and hostnames for publishing purposes. Broadcast, multicast, localhost addresses are unchanged. RFC1918 addresses have their last two bytes randomly changed, other addresses are completely changed. The first three letters of hostnames are randomized.

-h

command-line options help.

CURSES MODE

vlog enters curses mode if none of the following options are given: -<nn>f, -<nn> or -n <nn>, -e <date>.

In curses mode, the terminal window is split into three areas:

a header line which displays the column titles (date, time, ...)
a bottom line which displays general status informations
the big area in between displays the log lines, one per screen line. Log lines that are wider than screen width are cut, but they can be fully viewed by scrolling the window to the right (keys l and L). Day boundary log lines are underlined.

Movement keys

the arrow keys scroll the window in the four directions
the vi-like keys h, j, k, l do the same, and the caps keys H, J, K, L scroll it faster
b (back) and space scroll one page up or down
PgUp and PgDown work under Xfree86 only.

Jump keys

g = jump to a given logline
G = jump to last logline, or if already there, jumps back to where you were before
T = jumps to first logline (top)
0 = scroll window to leftmost
/ = search a given regexp forward
? = search a given regexp backwards
n = go to next occurence of last search
N = go to previous occurence of last search
> = go to next day boundary
< = go to previous day boundary
] = go to next marked line
[ = go to previous marked line

Misc keys

a = toggle AutoScroll mode. When it is on, the window is automatically scrolled down to bottom each time a new log line is appended to logfile.
r = toggle Raw mode. When it is on, no pretty-printing is done, the log line is displayed as it is in the logfile.
i = toggle IP address display style. There are two styles: compact (all figures and dots are joined, e.g. '10.0.1.12') and column-aligned (each of the four numbers is on three chars for units, tens and hundreds to be vertically aligned, e.g. ' 10. 0. 1. 12')
m = mark (display in video reverse) the line at the window bottom. When vlog is used for watching logfile once in a while, such marks can be useful to remember where you were last time you looked at it.
M = clear all marks
^L = redraw screen
o = toggle optional fields. See option -o above.
s = load another logfile, specify it with a single keystroke (see the key-to-logfile mapping in option -l above)
S = load another logfile, specify it with its full pathname
* = display a help page
& = display the current hostname:/path/to/logfile.
! = spawn a subshell.
Q = quit vlog.

``TAIL -f'' MODE

When option -f or -<nn>f is given on command line, vlog behaves like a ``tail -<nn>f logfile'' (see tail(1)). The only difference is that loglines are pretty-printed. This mode doesn't use curses. If current logfile is rotated, vlog silently switches to new logfile.

For instance: vlog -12f prints the last twelve lines of /var/log/ipflog, then wait and print new log lines as soon as they're appended to logfile.

``PRINT'' MODE

This mode is entered when option -n <nn> or -<nn> or -e is given on command line. vlog simply prints out the specified lines and exits. Examples:

vlog -n 12 or vlog -12 print the last 12 lines of /var/log/ipflog.

vlog -s Jul 1 -e Jul 14 print log lines between specified dates.

ISBA RULE NUMBERS

Each IP-Filter log line contains the number of the group and rule that generated this log line.

If the ruleset currently loaded in kernel has been generated by the IP-Filter GUI isba (http://inc2.com/isba), which uses ``composite'' rules (one isba source rule may be compiled into many ipfilter rules), it is interesting to know which isba rule generated a given logline.

vlog can display the isba source rule number for each log line (optional field: key i) if the ruleset was generated by isba-1.1 or later.

In case the machine you run vlog on is a log-centralizing machine, vlog can show the isba rule number only for log lines generated by this machine, not foreign ones, because vlog needs to read the ipf.conf file.

BUGS

vlog isn't optimized at all for slow links. It has been tested in an xterm, in a dtterm and in a Sun VT100 console.
in curses mode with option -r (rotated logfiles), vlog can consume a lot of memory (sum of logfiles sizes + 40%).
vlog doesn't format ipfilter NAT and STATE log lines, nor 'frag' log lines. They're displayed as is.
vlog can't read gzipped logfiles (logfile.0.gz, etc.). See option -r above.

REFERENCES

Vlog's home page is http://inc2.com/vlog.

IP-Filter is a stateful TCP/IP packet filter written by Darren Reed (see http://coombs.anu.edu.au/~avalon/ip-filter.html).
vlog uses the hash table data type provided by the Kazlib package written by Kaz Kylheku (see http://users.footprints.net/~kaz/kazlib.html).
isba is a Perl/Tk graphical tool for edition and management of IP-Filter rulesets written by myself (see http://inc2.com/isba).

vlog	[ -r ] [ -i ] [ -g regexp ] [ -v regexp ]
	[ -l logfile or -l{imsxladcq} ] [ -[<nn>]f or -f ]
	[ -<nn> or -n <nn> ] [ -s <date> ] [ -e <date> ]
	[ -o{dtuhfrilan} ] [ -t ] [ -d ] [ -w <nn> ]