=head1 NAME

Karma - Configuration Guide

=for html <body bgcolor="#3399cc">

=head1 DESCRIPTION

This guide will help you step through the process of editing
the karma.conf configuration file to control the behavior of
Karma.

=head1 Installing a read-only user in your database

Karma needs to login to your target databases in order to monitor
them.  If you're not doing alertlog or OS monitoring

=for html <A HREF="config.html#agent">click here,</A>

then Karma is completely read-only.  If you're concerned about
Karma making changes in your database, create a read-only user
for it to login as.  The supplied script $KARMA/sql/karma_user.sql
will do just that.  Examine the script, then login as sys, and
run it like this (we're assuming here that you've cd'd into the
"sql" directory:

SQLE<gt> @karma_user.sql

Enter value for karma_password: amrak

User created.

Grant succeeded.

Grant succeeded.

You can now use this user and the password you specified
when configuring a karma.conf file.

=for html <A HREF="config.html#conf">click here for details</A>

=head1 Basic Editing of the karma.conf file

The karma.conf file is the core configuration file for karma.
Eventually it will be updatable via a web front-end, but for
now one must edit the file.

The 'karma' line is a directive to karma of a database it needs 
to monitor.

C<karma:*:VENUS:karma:amrak>
C<karma:*:MARS:karma:amrak>

In this case karma will monitor the VENUS and MARS databases.  The
last two parameters are the username and password to login with.
'MARS' and 'VENUS' must be defined in the tnsnames.ora file otherwise
an error will be returned.

The format of most other lines in this file are:

C<SERVICE:X:Y:Z>

The SERVICE can be one of these:

redologs rollback tablespaces slowsql alertlog hitratios
fragmentation extents latch mts repqueue reperror

X  - how often (in minutes) to monitor this info
Y  - warning threshold
Z  - alert threshold

A service is not monitored if it's time column is 0, or it is
commented out with the # character, or if it is not in the file
at all.  For repeated entries, the last one listed will be used.

A very simple configuration would look like this:

C<redologs>
C<rollback>
C<tablespace>
C<slowsql>
C<hitratios>
C<fragmentation>
C<extents>
C<latch>

In this case, the factory defaults for X, Y, and Z will be used.
Conversely, set your own values:

C<tablespace:15:85:95>

Which directs karma to check up on tablespace quotas every 15 
minutes, flagging a warning if they are 85% full, or an alert
if they are 95% full.

=head1 Editing the karma.conf using Preference Groups

By default karma uses a default preference group.  That's what
the '*' is for in the second field.  It can also be blank, or
the word default:

C<karma:*:MARS:karma:amrak>
C<karma::MARS:karma:amrak>
C<karma:default:MARS:karma:amrak>

All three achieve the same result.  However, one can break the 
preference settings up into groups.  These are given case sensitive
names in this karma line, and karma then looks for config lines
later in the file, PREPENDED with this name.

C<karma:New York:MARS:karma:amrak>
C<New York:tablespace:10:80:90>
C<New York:slowsql>
C<New York:hitratios:2:85:95>

Notice that the exact spelling is relevant here.  Case is checked, as
well as spaces.  In fact, any characters between the colons matter.

For more information on configuring services, see the services
documentation

=for html <A HREF=services.html>here</A>

.

=head1 Email Notification

Email notification is an important part of any monitoring app, so
I've tried to get this functionality working well in 1.0.  At
it's most basic form, you add a line in your config file like this:

C<notify_email:full:shull,root,oracle@somewhere.com,nobody@xyz.com>

The first field is obviously the directive.  The second can be
'full' or 'short'.  The 'short' format email is a very limited message
suitable for text pagers which often have an 80 character limitation.
The third field is a comma delimited list of email addresses.

Check the various *.conf files in the main directory.

=head1 Alertlog and OS monitoring

Karma has the ability to monitor the alertlog file and some OS
statistics of some or all of your target databases.  This is a some
what labor intensive task that the dba must perform regularly
and my goal here is to simplify this task.

If you're going to monitor the alertlog you must create the
KARMA_ALERTLOG_ERRORS table, and if you are going to monitor
OS stats, you must create the KARMA_OS_STATS table.  For
monitoring either, you must startup the karmagentd daemon.

Install the tables in your karma schema first.  Login as the
karma user created above 

=for html <a href=config.html#user">

(see user creation section)

=for html </a>

and do the following:

SQLE<gt> @karma_objs

Creating karma_os_stats table...

Table created.

Creating karma_alertlog_errors table...

Table created.

Monitoring is achieved via the karmagentd daemon.  This daemon
must be run on *each* target database.  This is necessary because
the alertlog is an OS logfile, which is only accessable locally
on the machine.  Karmagentd reads the alertlog and keeps track
of it's file position, periodically waking up to check for
changes.  In addition, it will run "uptime" on that machine as
well.  When it finds any ORA-xxx errors in the alert log, it
writes them to KARMA_ALERTLOG_ERRORS, and KARMA_OS_STATS
respectively.

For more help with the karmagentd daemon, use the C<-h> option:

C<$ ./karmagentd C<-h>>

C<h - print this help info>
C<f - fequency in minutes to wakeup & check things (default 1)>
C<r - reset the alert.log, and truncate it's table>
C<u - user to login as (default karma)>
C<p - oracle login password (otherwise you're prompted)>
C<j - jump j bytes in file (takes precedence over save file)>
C<t - tnsname of the database to watch (default local)>
C<a - specify alert.log file (default OFA)>
C<k - use this file to store seek position>
C<b - specify ORACLE_BASE (takes precedence over env)>
C<h - specify ORACLE_HOME (takes precedence over env)>
C<s - specify ORACLE_SID (takes precedence over env>
C<d - debug level (default 0, no debugging)>

C<./karmagentd [C<-h>] [-f #] [-r] [-u karma] [-p pass] [-j #]>
C<  [C<-t> DB]<br> [C<-a> alert.log] [C<-k> karmagent.sav]>
C<  [C<-b> ORACLE_BASE] [C<-h> ORACLE_HOME] [C<-s> ORACLE_SID] [-d #]>

=head1 Using the karmactl utility

The karmactl utility is a new addition to karma, and enables you
to more easily manage a running karma daemon.  You can use it to
stop or start the daemon, get status on a running daemon, reread
the config file or force a refresh of all services.  

To get help do C<$ perldoc karmactl> or the following:

C<$ bin/karmactl C<-h>>

C<-h print help and exit>
C<-v print version and exit>
C<-w print warranty and exit>
C<-s start karmad daemon>
C<-p stop karmad daemon>
C<-t print status of running karmad daemon>
C<-r reload karam.conf config file>
C<-i specify process id (if lock file is missing)>
C<-l specify logfile for karmad (ignored if not starting karmad)>
C<-c specify karma config file (ignored if not starting karmad)>
C<-k specify karma doc_root>
C<-d delete dynamically created karma files (karma.html, info/*.html)>

C<karmactl [C<-h>|C<-v>|-w|-s|-p|-t|-r|-d] [-l file] [-c file] [-k dir]>

Get the status of a running karma daemon as follows:

C<$ bin/karmactl -s>
Starting karma daemon...

C<$ bin/karmactl -t>
karmad started at 19:46
  pid:2853
  Using EMAIL for notification
    DB:AEON UP, Prefgroup:default - services:
    19:46 --    os
    19:46 --    mts
    19:46 OK    tablespace
    19:46 OK    slowsql
    19:46 OK    up
    19:46 WARN  hitratios
    19:46 OK    rollback
    19:46 --    alertlog
    19:46 OK    extents
    19:46 OK    latch
    19:46 OK    redolog
    19:46 OK    fragmentation



=cut 



