NAME
    Karma - Configuration Guide

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

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

    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:

    SQL> @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.

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.

    `karma:*:VENUS:karma:amrak' `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:

    `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:

    `redologs' `rollback' `tablespace' `slowsql' `hitratios' `fragmentation'
    `extents' `latch'

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

    `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.

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:

    `karma:*:MARS:karma:amrak' `karma::MARS:karma:amrak'
    `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.

    `karma:New York:MARS:karma:amrak' `New York:tablespace:10:80:90' `New
    York:slowsql' `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

    .

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:

    `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.

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

    (see user creation section)

    and do the following:

    SQL> @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 `-h' option:

    `$ ./karmagentd `-h''

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

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

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 `$ perldoc karmactl' or the following:

    `$ bin/karmactl `-h''

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

    `karmactl [`-h'|`-v'|-w|-s|-p|-t|-r|-d] [-l file] [-c file] [-k dir]'

    Get the status of a running karma daemon as follows:

    `$ bin/karmactl -s' Starting karma daemon...

    `$ 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