logtool(1)

logtool
logtool - parse and filter syslog files

SYNOPSIS
logtool -[vVhbspc:o:y:g:i:e:t:] Logtool is a command line program that will parse syslog (and syslog-like) logfiles into a more palatable format. It will take anything resembling a standard syslog file (this includes syslog-ng, and probably most of the other variants out there), and crunch it into one of the following formats for your viewing pleasure:

ANSI (colorized for easy "at a glance" viewing)

ASCII (e-mail reports/term's w/o color)

CSV (spreadsheet/database imports)

HTML (for generating web pages)

RAW (for no good reason)

OPTIONS

-o [ ANSI | ASCII | CSV | HTML | RAW ]
    Allows you to specify the output format to be one of the following: ANSI (default), ASCII, CSV, HTML, RAW. Options are not case sensitive (ie: -o CSV and -o csv should yield the same results)

-t [ long | short ]
    Allows you to specify the time display format to be one of the following: (Long [default]) Mon Dy HH:MM:SS or (Short) HH:MM

-b  Causes logtool to beep on RED events (ANSI output only). This is usefull when you want to monitor a logfile on an ongoing basis, and wish to have your terminal beep whenever something out of the ordinary happens.

-s  Causes logtool to not display the syslog "source" field

-p  Causes logtool to not display the "program" field

-c [/path/config.file]
    Allows you to specify a config file other than the default /usr/local/etc/logtool/logtool.conf

-i [/path/includefile]
    Allows you to specify an alterate file containing regex's for inclusion [default=/usr/local/etc/logtool/include]

-e [/path/excludefile]
    Allows you to specify an alternate file containing regex's for exclusion [default=/usr/local/etc/logtool/exclude]

-y [/path/yellowfile]
    Allows you to specify an alternate file containing regex's for yellow colorization [default=/usr/local/etc/logtool/yellow]

-g [/path/greenfile]
    Allows you to specify an alternate file containing regex's for green colorization [default=/usr/local/etc/logtool/green]

-v  Set logtool to operate in verbose mode (does nothing currently)

-V  Causes logtool to print it's version information and exit

-h  Display the help message

SUGGESTED USAGE(S)

As a 'live' logfile monitoring tool:
    tail -f /var/log/messages | logtool -o ANSI -b

To generate colorized webpages of logfiles:
    cat /var/log/messages | logtool -o HTML > /home/httpd/html/logs/messages.html

To generate reports via a cronjob:
    logtail /var/log/messages | logtool -o ASCII | mail -s "Daily report" someuser@somedomain.ext

EXAMPLES/DETAILED USAGE

At the command prompt, type

tail /var/log/messages | logtool

    By default, logtool will ignore no messages, so you should have some output on your screen in pretty ANSI colors (if your terminal does not support the (mostly) standard escape sequences to alter colors, then you should switch to one that does). Also note, that unless it already exists, the logtool binary (.exe to you DOS/Windows users who recently converted to UNIX), will be symlinked to "lt". So you can probably get the exact same results as above by typing:

tail /var/log/messages | lt

    You may also need to specify a different logfile if your system does not dump it's syslog files to /var/log/messages (it's in the /var/adm tree on most *BSD's as I recall).

    You can experiment with the output options by typing:

tail /var/log/messages | logtool -o csv

    The output options are not case sensitive, so "-o CSV" should yield the same result. Try the other options as well (listed at the beginning of this file). Try some of the other options until you feel comfortable that you know what to expect from the logtool program.

    Once you have a good grasp of the options, and what they do, open up /usr/local/etc/logtool/logtool.conf in your favorite text editor, and set your preferences to be the defaults.

    Now, the color definition and regular expression files are something you will want to customize as well. You will want to populate the files with regular old POSIX regular expressions. One example of a regular expression would be:

    FTP session (opened|closed)

    This will match either of the following strings: "FTP session open" "FTP session closed"

    You can also use wildcards in your regular expressions like this:

    usermod.*changed

    Which will match any string that contains: "usermod[anything]changed"

    NOTE: The strings you put in these files are _CASE SENSITIVE_. Keep that in mind as you build your own lists.

    Unlike the color definition files which only define certain strings of text to be defined as a certain color/severity of log message, the include and exclude files define log messages to include or exclude. By default, nothing is included, or excluded. The logic of these two things can best be explained by the following:

    include file = only include these log messages

    exclude file = include all log messages except for these

    You can use this logic go build your own boolean searches. An example script is listed below:

--cut--

#!/bin/sh

# mail a report to john_doe@somedomain.com logtail /var/log/messages /var/log/secure | lt -o ascii -c /home/john/report.cfg -i /home/john/report.inc | mail -s "Your report" john_doe@somedomain.com

# NOTE: all of the above should be on one line, not wordwrapped as it is for this display.

# mail a report as a CSV file to me@mydomain.com

tmpfile=/tmp/$RANDOM.$$.tempfile

logtail /var/log/messages | lt -o csv -e /home/me/report.exc > $tmpfile

mutt -a $tmpfile -s "Your report" me@mydomain.com

rm -f $tmpfile

# EOF

--cut--

    In these examples, there are include and exclude files which have been set up prior to running this script which contain the events relevant to the user the report is being mailed to.

    John's include file specify's that he only views events generated by (host1|host2), which contain the strings (error|warning). He also has a customized configuration file which alters the system-wide default behavior.

    Me's include file specifies that I only look at messages generated by (host1), and that Me excludes events that contain (notice).

    You'll also notice, that the report is formated to each users preference. John just likes a flat ASCII dump of the logfiles, whereas Me likes a CSV file as an attachment so I can import it into my favorite spreadsheet for easy manipulation/viewing.

    If you wrote a simple shell script similar to the one above, and put it in /etc/cron.daily (or whatever your flavor of UNIX uses for such things), you would have an instant daily report based on your logfiles show up in Me and John's INBOX every day.

    Another example use would be something like the following:

--cut--

#!/bin/sh

# Generate a webpage of the logfiles

cat /var/log/messages | lt > /home/httpd/html/logs/index.html

# EOF

--cut--

    This will use the system defaults to generate a webpage for viewing anytime you get in the mood to go look at your logfiles (assuming you have a webserver configured to have access to /home/httpd/html/logs/).

    Pretty simple stuff, eh? You can peruse the scripts in the examples/ subdirectory of the documentation for more examples on uses of logtool.

AVAILABILITY
Logtool is known to compile/run on all UNIX flavors using a 2.95.x GNU C Compiler, the GNU Make utility, and a proper ANSI C library (glibc is recommended, but not required). Specific reports of success include FreeBSD, OpenBSD, Solaris, SunOS, AIX, SCO, and of course, any known flavor of Linux.

SEE ALSO
regex(7) for help with constructing regular expressions for the include/exclude/colors files.

AUTHOR
A.L.Lambert