| | Development Kit Table of Contents | |
This checklist steps through the procedure
for installing the log collection software on a new client. The installation
consists of creating the logger account on the client, ensuring that ssh is
available and working between the client and the log server (logger.worlds.net), installing and configuring the collector, and
testing that the collector is working.
1.0 CREATE NEW ACCOUNT ON CLIENT: Log into the client as root
and create a new user and group, both named logger. If possible, the
user and group ids should both be 125. The logger's home directory
should be /home/logger, and the shell should be /bin/csh.
There is a perl script, /home/logger/loggeradd, on logger.worlds.net that automates this step. This script can be copied
to /tmp and executed as follows:
client% /usr/local/bin/scp
logger.worlds.net:/home/logger/loggeradd /tmp
client% /usr/local/bin/perl /tmp/loggeradd
The loggeradd script will prompt for the password and confirmation. This is the
preferred method as it also tests that ssh and perl are both properly installed. If scp
and/or perl fail, make sure they are installed properly before
continuing.
2.0 VERIFY THAT SSH IS CONFIGURED: While logged in as root on the client, attempt to
use ssh to login to the log server, logger.worlds.net. You must be able to do this without supplying a
password in order for the collector to function properly. Try the following
test:
client% /usr/local/bin/slogin -v -l logger
logger.worlds.net
This will produce verbose output which will
be useful if you are prompted for a password. If you are not prompted for a
password, you are home free, just exit and continue. If you are prompted, enter
the password. Use the following steps to correct this problem.
2.A
DETERMINE HOST NAME OF CLIENT: The
full hostname for the client is needed to setup ssh properly. It can be
found in the verbose output of slogin. It is the client host on a line that looks like:
oprah: Remote: Rhosts/hosts.equiv
authentication refused: client user 'logger', server user 'logger', client host
'm214.worlds.net'.
2.B
EDIT THE SHOSTS FILE ON LOGGER: You
should already be logged into logger.worlds.net, so now edit ~logger/.shosts and add an entry with the client's full host name
and the user root to the end of ~logger/.shosts. Following our example we would add:
m214.worlds.net root
2.C
SLOGIN BACK TO CLIENT: To complete
the authentication, it is necessary to slogin from logger.worlds.net back to the client using the client's full host name
found above. Don't worry if you are prompted for a password, this will not
effect the log collection. This step isneeded so that ssh on
logger.worlds.net knows to trust the client. To continue our example:
logger% slogin m214.worlds.net
Password: ********
client%
2.D
VERIFY SSH IS PROPERLY CONFIGURED:
Just to be sure, exit back to logger.worlds.net and back to the client. Then try slogin
back to logger.worlds.net. This time you should get the shell prompt without
being asked for a password. If you are prompted for a password, find an ssh
expert before continuing.
client% slogin -l logger logger.worlds.net
logger%
3.0 INSTALL THE COLLECTOR: Now login to the client as user logger
and create two subdirectories, bin and log, in logger's home directory. The log directory will store
the collector's log file and the bin directory will hold the perl scripts and
configuration file. Now install the files:
client% alias scp /usr/local/bin/scp
client% scp -p logger.worlds.net:bin/CollectLogs.pl bin/
client% scp -p logger.worlds.net:bin/Logger.pm bin/
client% scp logger.worlds.net:bin/CollectLogs.default
bin/CollectLogs.config
This installs the perl script and the
default configuration file which will collect the collector's log file and the
standard system log files.
4.0 TEST COLLECTOR INSTALLATION: Next, test to see that the collector is installed
properly by running it once by hand and verifying the default files make it to logger.worlds.net.
4.A
RUN COLLECTOR BY HAND: Login to the
client as root (or become the superuser) and execute the collector script,
preferably in debug mode.
client% su
Password: ********
client# /home/logger/bin/CollectLogs.pl -debug |& tee debug.log
This will produce lots of output with hopefully no FATAL
errors, ERRORs or WARNINGs. If there are errors or warnings, examine the debug.log that was created and correct the problems before proceeding. Some of
the log rotations may take several minutes, so don't be alarmed by having to
wait for up to 10 minutes.
4.B
VERIFY LOG FILES ON SERVER: Login to
logger.worlds.net and use ls to verify the default files made it.
logger% ls -1 /logger/incoming/client
CollectLogs.log.2000-01-12
cron_log.2000-01-12.gz
messages.2000-01-12.gz
sulog.2000-01-12.gz
If
this test should fail, examine the debug.log created above and correct the problems before
proceeding.
5.0 MODIFY ROOT CRONTAB: Now a job must be added to the root crontab
on the client so that the collector runs every hour.
5.A
REMOVE LOGCHECKER: The root crontab
probably runs logchecker which rotates the cron log file. Our default
collection configuration also rotates this log, so we should remove (or
comment) the line that looks like:
10 3 * * 0,4 /etc/cron.d/logchecker
5.B
ADD LOG COLLECTOR: Add the following
at the end of the root crontab:
#
# Collect logs every hour
0 * * * * /home/logger/bin/CollectLogs.pl
6.0 ADD OTHER LOGS TO BE COLLECTED: Consult the "Adding a log file to the
collector" checklist in order to add additional log files to the
collector on this new client.
This guide explains the options available
for configuring the log collector on a client machine. The collector runs
hourly on the client and uses its configuration file to determine which log files
to collect and transfer to the log server, logger.worlds.net.
The log collector's configuration file, CollectLogs.config, is located in the same directory as its Perl
script, typically /home/logger/bin. This file is a plain text file that can be edited
with any editor. There are two types of options in the file, general options
and log file options. Each will be explained below.
There is a set of options that controls the
overall running of the collector. Some of the more useful ones will be
explained here, but to find all of them, take a look at the script and look for
$ConfigFile{parameter}. Most of these parameters have reasonable defaults,
so it is only necessary to change them on rare occasions.
General options are specified one per line
with the parameter name, an equal size ("=") and the value.
Whitespace around the equal sign is optional, everything to the right of the
equal sign (and optional whitespace) is used for the value.
For example:
LOG=/home/logger/log/CollectLogs.log
In this example, the collector's log is
configured to be the file /home/logger/log/CollectLogs.log. The following table describes some of the common
options.
|
DEBUG |
|
The debugging output
level.
|
||||||||||||
|
LOG |
|
The location of the
collector's log file. |
||||||||||||
|
REMOTEHOST |
|
The name of log server
(the machine that the logs will be sent to). |
||||||||||||
|
REMOTEUSER |
|
The name of the account
that will be used for executing remote commands. |
||||||||||||
|
REMOTEROOT |
|
The root directory on the log server under
which the logs will be stored. |
||||||||||||
|
TIMEOUT |
|
Specifies the default
number of minutes to wait for a new log file to be created after the old one
has been rotated. See below to instructions on how to override this for an
individual file. |
The second set of options in the
configuration file specifies the names and locations of the files to be collected
and any options for handling each specific file. Each file and all of its
options is specified on its own line, for example:
LOGFILE=/home/apache/logs/access_log,TYPE=APACHE,COMPRESS
This line specifies that the file /home/apache/logs/access_log is to be collected; it is of TYPE APACHE
and it is to be COMPRESSed.
Each log file configuration line must begin
with LOGFILE, an equal sign ("=") and the full
path name to the file (some exceptions to the full path name rule will be
discussed below). The name of the log file is followed by any optional
parameters for the file in the key=value form, separated by commas. White space around commas
and equal signs is optional. If the =value portion of an option is omitted, then the option's
value is set to 1 (that is, COMPRESS and COMPRESS=1 are equivalent).
Examples of all supported file types can be
found in the the file Example.config.
The following table describes all the log
file options available:
|
NAME |
|
Specifies the name to be
given to this file on the log server. This is useful if two log files have
the same name locally or to give a more descriptive name on the server. For
example, in the default configuration, the cron log (/var/cron/log) is collected with a NAME of cron_log. |
||||||||||||||
|
COMPRESS |
|
Specifies that the log
file is to be compressed. |
||||||||||||||
|
CREATENEW |
|
Specifies that when this
file is rotated, a new empty file with the same owner, group and permissions
should be created in its place. This is useful for log files from CGI scripts
since they often run under a different username and/or group than the owner
of the directory that holds the log file. |
||||||||||||||
|
FLOCK |
|
Specifies that flock
should be used to obtain a write long on the file after rotating it to ensure
that other processes have finished writing to it. In order for this to work
properly, the other processes must also use flock to write to the
file. |
||||||||||||||
|
TIMEOUT |
|
Overrides the general TIMEOUT option for this particular file. |
||||||||||||||
|
TRUNCATE |
|
Do not use this! This option is available for one and only one
special case which is the system cron log. |
||||||||||||||
|
TYPE |
|
Specifies the type for this file. The type
is used to group files so they can be processed together and also, there are
several file types that require special handling. Some of the special types
have their own general and log file specific options. These special types are
described in the following table:
|
||||||||||||||
|
KEEP |
|
For files of type NUMBERED, NFS, USERS or TRC, specifies the number of days to keep files before
they are collected. |
||||||||||||||
|
REMOVE |
|
For files of type NUMBERED, NFS, USERS or TRC, specifies that the file should be removed after
it is collected. |
Adding a log file to the collector
This checklist steps through the procedure to be used to add a log file to the
log file collection process. The collector is configured through a
configuration file on the client that the file is to be collected from.
Throughout this checklist there will be
references to two machines, the log server (logger.worlds.net, aka
the server) and the log client. The client is the machine from which the log
file is to be collected.
1.0 LOGIN: Log into the log server, logger.worlds.net, as user logger. From this account and machine it should be possible
to use slogin to login to any other machine from which, logs are collected.
2.0 VERIFY LOGGER ACCOUNT: Verify the logger account is installed on the client.
2.A
"slogin <client>".
IF THIS FAILS, obtain and follow the "Installing log collector on a
client" checklist.
2.B
Check the crontab
of the root user on the client to verify that it is running the
collector:
client% su
Password: ********
client# crontab -l | grep CollectLogs
0 * * * * /home/logger/bin/CollectLogs.pl
IF
IT DOES NOT, obtain and follow the "Installing log collector on a
client" checklist.
3.0 MODIFY CLIENT CONFIG FILE: The client's config file is:
/home/logger/bin/CollectLogs.config
To add a log file, one line should be added
to the file that specifies the location of the file and any options required
for handling that file.
3.A
READ THE DOCUMENTATION: The "Log Collection Configuration Guide" explains all
the options available in the configuration file.
3.B
CONSULT THE EXAMPLE CONFIG: Look at
the example config file (Example.config) which contains examples of all the types of files
currently collected by the collector. If there is one similar (or identical) to
the one you are adding, use it as a starting point.
3.C
CHECK FOR DUPLICATE NAMES: Compare
the name of the log file that you are adding to the names of the other log
files mentioned in the config file. If there is a conflict, supply a NAME=
option for your log file. (Be sure to look for names in both the actual log
file names as well as any NAME= options).
4.0 TEST NEW CONFIGURATION: The new configuration can be tested by waiting for
the next scheduled run for the collector (currently it is run hourly) or it can
be run by hand. To run it by hand, log in as root and run the collector perl
script as follows:
client% su
Password: *******
client% /home/logger/bin/CollectLogs.pl -debug
4.A
CHECK LOG FILE FOR ERRORS: Once the
collector has run, check the log file for errors. The log file will typically
be in /home/logger/log/CollectLogs.log. However, you should check the configuration file to
see if another location has been specified by the configuration parameter LOG.
If any errors were encountered determine if they were due to changes in the
configuration and fix appropriately.
4.B
CHECK THE SERVER: Check on the
server to see if the log file was stored properly. The default location for the
collected logs on the server is /logger/incoming/<client>, where client is the hostname of the client machine.
The root directory (/logger/incoming) can be configured on the client machine, so it is a
good idea to check there and look for the parameter REMOTEROOT. In that directory you should see the log file with the date appended
and another file, in the status subdirectory, with the same name and a ".status"
extension. If these files are not present, recheck the collector's log file for
errors
|
Logfile |
Fields/Data |
Category |
Server(s) |
Directory |
Rotation |
Comments |
||||||||||||||||||||||||
|
|
|
Apache |
all (?) |
|
can use collector |
Jeremy - not currently analyzed |
||||||||||||||||||||||||
|
Example: |
||||||||||||||||||||||||||||||
|
|
|
Apache |
all (?) |
|
can use collector |
ditto |
||||||||||||||||||||||||
|
Example: |
||||||||||||||||||||||||||||||
|
|
|
??? |
most |
|
can use collector, should use flock |
Jeremy - read by period.pl, currently reports are broken |
||||||||||||||||||||||||
|
Example: |
||||||||||||||||||||||||||||||
|
|
|
Store |
ss100 |
|
Already rotated |
Bo - probably won't need data, data available
elsewhere |
||||||||||||||||||||||||
|
Example: |
||||||||||||||||||||||||||||||
|
|
|
Store |
ss100 |
|
Already rotated |
none |
||||||||||||||||||||||||
|
Example: |
||||||||||||||||||||||||||||||
|
|
|
Store |
ss100 |
|
can't be rotated |
Bo - files are named by date, may want to retrieve them
(via rsync?), but they must be left there. Are they needed for reports? |
||||||||||||||||||||||||
|
Example: |
||||||||||||||||||||||||||||||
|
|
|
Store |
ss100 |
|
ditto |
ditto |
||||||||||||||||||||||||
|
Example: |
||||||||||||||||||||||||||||||
|
|
|
Store |
ss100 |
|
ditto |
ditto |
||||||||||||||||||||||||
|
Example: |
||||||||||||||||||||||||||||||
|
|
|
Store |
ss100 |
|
already rotated, could grab rotated files, probably need
to use flock |
Bo - Most (all?) data is already in database (see
bin/payup.pl). Is this needed for reports? |
||||||||||||||||||||||||
|
Example: |
||||||||||||||||||||||||||||||
|
|
|
Store |
ss100 |
|
ditto |
ditto |
||||||||||||||||||||||||
|
Example: |
||||||||||||||||||||||||||||||
|
|
|
Store |
ss100 |
|
ditto |
ditto |
||||||||||||||||||||||||
|
Example: |
||||||||||||||||||||||||||||||
|
|
|
Store |
ss100 |
|
ditto |
ditto |
||||||||||||||||||||||||
|
Example: |
||||||||||||||||||||||||||||||
|
|
|
Netscape |
ss100 |
|
already rotated daily |
none |
||||||||||||||||||||||||
|
Example: |
||||||||||||||||||||||||||||||
|
|
same as Apache access_log, plus |
Netscape |
ss100 |
|
ditto |
none |
||||||||||||||||||||||||
|
Example: |
||||||||||||||||||||||||||||||
|
|
|
Netscape |
ss100 |
|
ditto |
none |
||||||||||||||||||||||||
|
Example: |
||||||||||||||||||||||||||||||
|
|
|
Oracle |
us1 |
|
rotate and wait |
Is there anything useful? |
||||||||||||||||||||||||
|
Example: |
||||||||||||||||||||||||||||||
|
|
|
Oracle |
us1 |
|
just copy and delete |
none |
||||||||||||||||||||||||
|
Example: |
||||||||||||||||||||||||||||||
|
|
|
Register |
uk0 |
|
? |
New user information |
||||||||||||||||||||||||
|
Example: |
||||||||||||||||||||||||||||||
|
|
|
? |
us1 |
|
? |
? |
||||||||||||||||||||||||
|
Example: |
||||||||||||||||||||||||||||||
|
|
|
? |
various |
|
? |
none |
||||||||||||||||||||||||
|
Example: |
||||||||||||||||||||||||||||||
|
|
|
Register |
us1 |
|
? |
Changes to user information |
||||||||||||||||||||||||
|
Example: |
||||||||||||||||||||||||||||||
|
|
|
System |
all |
|
? |
Binary data! |
||||||||||||||||||||||||
|
Example: |
||||||||||||||||||||||||||||||
|
|
|
System |
all |
|
? |
none |
||||||||||||||||||||||||
|
Example: |
||||||||||||||||||||||||||||||
|
|
|
System |
all |
|
rotated by system, grabe the .0 file |
none |
||||||||||||||||||||||||
|
Example: |
||||||||||||||||||||||||||||||
|
|
|
System |
all |
|
rotated by system, grab the .0 file |
none |
||||||||||||||||||||||||
|
Example: |
||||||||||||||||||||||||||||||
|
|
|
UserServer |
us1 |
|
rotated weekly |
what does 'active' versus 'connected' mean? |
||||||||||||||||||||||||
|
Example: |
||||||||||||||||||||||||||||||
|
|
|
UserServer |
us1 |
|
rotated weekly |
needs further analysis |
||||||||||||||||||||||||
|
Example: |
||||||||||||||||||||||||||||||
|
|
|
RoomServer |
rs100 |
|
rotated weekly |
none |
||||||||||||||||||||||||
|
Example: |
||||||||||||||||||||||||||||||
|
|
|
RoomServer |
rs100 |
|
rotated weekly |
none |
||||||||||||||||||||||||
|
Example: |
||||||||||||||||||||||||||||||
|
|
|
CyberCash |
ss100 |
|
? |
Bo - The notification.log might be useful for seeing why
Cybercash rejected |
||||||||||||||||||||||||
|
Example: |
||||||||||||||||||||||||||||||
|
|
|
CyberCash |
ss100 |
|
? |
ditto |
||||||||||||||||||||||||
|
Example: |
||||||||||||||||||||||||||||||
|
|
|
Network |
oprah |
|
use collector with flock |
none |
||||||||||||||||||||||||
|
Example: |
||||||||||||||||||||||||||||||
Other Comments/Notes:
|
Bo |
2DChat/eShare moving to NT, how will logs be collected
there? |
|
Matt |
uk0's hostname() is us0! Beware! |
Common Fields
IP
authuser
date/time
script
keyword
|
Script |
Keyword |
Fields |
Comments |
|
|
All |
|
number of username/passwords and codewords emailed to
address |
|
Example: |
|||
|
|
Bad |
|
invalid password entered |
|
Example: |
|||
|
Changed |
|
username is lowercase |
|
|
Example: |
|||
|
|
Changed |
|
none |
|
Example: |
|||
|
|
Bad |
|
invalid password entered |
|
Example: |
|||
|
Changed |
|
none |
|
|
Example: |
|||
|
|
Cleared |
|
none |
|
Example: |
|||
|
Re-sent |
|
none |
|
|
Example: |
|||
|
Register |
|
none |
|
|
Example: |
|||
|
Sign-up |
|
trans is always '!', huh? |
|
|
Example: |
|||
|
|
Allocated |
|
|
|
Example: |
|||
|
|
Level |
|
Mostly redundant with Subscription |
|
Example: |
|||
|
Renew |
|
Mostly redundant with Renewal |
|
|
Example: |
|||
|
Renewal |
|
|
|
|
Example: |
|||
|
Subscription |
|
none |
|
|
Example: |
|||
|
Cancellation |
|
|
|
|
Example: |
|||
|
|
Confirmed |
|
There may be multiple emails separated by a space |
|
Example: |
|||
|
Referral |
|
|
|
|
Example: |
|||
|
Registered |
|
There may be multiple emails separated by a space |
|
|
Example: |
|||
|
|
None! |
|
|
|
Example: |
|||
|
|
None! |
|
|
|
Example: |
|||