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 /usr/local/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 /usr/local/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.  <thanks to Robert Huff for 
suggesting that I point this out in the documentation>.


	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.  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 <crowland@psionic.com>, 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.