First thing you should do after install, is type "logtool -h" to see the help on command line options. I've included it below for your viewing pleasure. Command line options: logtool version 1.2.0, copyright Y2K-current A.L.Lambert Command line options: -c [/path/config.file] = specify a config file other than /etc/logtool/logtool.conf -i [/path/include.file] = a file containing regex's for inclusion -e [/path/exclude.file] = a file containing regex's for exclusion -o [ ANSI | ASCII | CSV | HTML | RAW ] Output Format: ANSI (default), ASCII, CSV, HTML, RAW -t [ long | short ] Time display Format: (Long [default]) Mon Dy HH:MM:SS or (Short) HH:MM -n = do not resolve IP addresses (if applicable) -b = beep on RED events (ANSI output only) -s = do not display the syslog "source" field -p = do not display the "program" field -v = verbose (print event processing info to stderr) -d = do debugging output on stderr (for us developers) -V = print version and exit -h = this help message Please take note, that on many non-Linux distributions of logtool, the default paths of the various config files in places other than /etc/logtool (such as /usr/local/etc/). However, since I don't think it appropriate to type half a dozen possible paths each time I refer to one of the config files, I shall use /etc/logtool in this documentation. You are responsible for translating this notation to whatever the reality may be. :) Now, give it a try, and see what it does. At the command prompt, type tail /var/log/messages | logtool # or some other syslog generated file 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). You may need to specify a different logfile if your system does not dump it's syslog files to /var/log/messages (IE: 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). Play around with the various options until you feel comfortable that you know how to run logtool from the command line. NOTE: If you're like me, and like to use 'less' to view your logtool output, you probably want to use the -R switch to keep it from clobbering the color escape sequences when in ANSI mode. . Once you have a good grasp of the options, and what they do, open up /etc/logtool/logtool.conf in your favorite text editor. This is the heart and soul of logtool's runtime configuration right here. By modifying the settings in this file, you can specify the default value for any of the command line switches available above, and much more. This file is well commented, and as such, should be self-documenting. If you find you have questions after reading the comments, please e-mail me so I can write better comments for the next release. :) Now, by this point, you should have played enough to grasp the concept of colorization well enough for me to skip the gory details. You have access to control all the ANSI colors, except dark red and black via files defined in logtool.conf. The color definition and regular expression files are something you will most certainly want to customize. An example of a color file is listed below. --cut-- # This file takes plain ole POSIX regex's, one per line (just like grep) FTP session (opened|closed) \(su\).*session (opened|closed) --cut-- Depending on which file this was (we'll assume 'green'), any log messages matching the regular expressions above would be displayed in green. The same logic applies to all the colors, as well as the include/exclude files explained below. NOTE: The strings you put in this file 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 when being displayed, 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 retail /var/log/messages /var/log/secure |\ logtool -o ascii -c /home/john/report.cfg -i /home/john/report.inc |\ mail -s "Your report" john_doe@somedomain.com # mail a report as a CSV file to me@mydomain.com tmpfile=/tmp/$RANDOM.$$.tempfile retail /var/log/messages |\ logtool -o csv -e /home/me/report.exc > $tmpfile mutt -a $tmpfile -s "Your report" me@mydomain.com # 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 in which he alters the system-wide default behavior to meet his personal preferences. 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 | logtool -o html > /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 ../scripts/ subdirectory for more examples on uses of logtool. I should include a quick note (plug) about the program 'retail' you may have noted me using above. It is a ground-zero re-implementation of the functionality of logtail by Craig H. Rowland , which attempts to better handle 'file changed' situations. I no longer include logtail in the logtool package, nor do I include retail, which is available seperately (probably from the same place you got logtool). Both retail and logtail will read the specified file(s), and output their contents to stdout. It will also create a record of where the file ended, and will pick up again at that point later when re-run. Long story short, it's a lot like "tail", with a memory. :) The usage is simple enough, I expect you'll get the hang of it without me having to spell it out for you in this documentation. More documentation stuff will be written later, but this should be enough to get you going, and suffice to call "documentation" for the time being.