NAME

     kstats -- produce kerberos statistics reports

SYNOPSIS

        $ setup ktools
        $ kstats <report-type> [options]

     as in

        $ kstats dbg [options]
        $ kstats pri[ncipals] [-v] [-d] [-?]
        $ kstats kdc[log] [-v] [-Q] [-r realm] [-d] [?]
        $ kstats timestamp [-v] [-Q] [-l time-period] [-d] [?]

REPORT TYPES:

     dbg     Debugging utility.

     pri[ncipals]
             Report on the principals registered in the KDC; that
             is, the principals that have been added to our KDCs.

     kdc[log]
             Report on the systems/users who have been  noted  in
             the  KDC  log  files  as  having  requested kerberos
             authorization.

     tim[estamp]
             Report on the number of transactions per  unit  time
             (default: 1 hour) noted in the KDC log files.

OPTIONS:

     -Q   Quiet mode (minimal information).   For  reports  which
          can  be piped to other utilities, this option should be
          used so that the second utility receives only the  data
          it  is expecting (e.g., report headers and trailers and
          descriptive comments are stripped).

     For the kdclog report, quiet mode  produces  a  list  of  ip
     addresses (one per line) which received initial AS_REQ tick-
     ets.  For the timestamp report, quiet mode produces  a  tab-
     separated  list  of  time-stamp/transaction-count pairs (one
     pair per line).

     -d   Debugging mode.  Lots of extra screen information.

     -l Nseconds
          Specify  the  length  of  time-period  in  seconds  for
          transactions/time  report.   Default is 3600 seconds (1
          hour).

     -r realm
          By default, the kdc report  will  determine  the  realm
          from  the  local  /etc/krb5.conf  file.   If you want a
          report for a different realm, use -r realm .

     -v   Verbose mode (more detailed report).

DESCRIPTION

     kstats allows you  to  create  several  different  types  of
     reports relating to kerberos usage.

kstats principals

     The  "kstats principals" report gives statistics on how many
     nodes and users (and realms) are listed as having principals
     in the KDC.  The input is a file that lists all of the prin-
     cipals from the KDC (alternately, you can pipe this input on
     STDIN).

     Examples:
         $ kadmin -p lauri/admin -w myAdminPasswordgoesHere! \
          -q list_principals | \
         $ kstats principals -v > principals.report

     In this example, the lauri/admin account (with the  password
     specific   on   the  commandline)  is  issuing  the  command
     list_principals, piping this output  to  "kstats  principals
     -v"  and then writing the output to a file principals.report
     in the current directory.

     This is equivalent to
        $ kadmin -p lauri/admin       \                  # -p adminPrincipal
                 -w passwordGoesHere! \                  # -w adminPasswd
              -q list_principals   \                  # -q query
          > intermediate.file                             # stdout to a file

        $ kstats principals -v intermediate.file > principals.report

kstats kdc

     The "kstats kdc" report gives statistics on  which  machines
     (and  users)  attempted  to gain authorization from the KDC.
     The input file(s) are KDC log files.

     Examples:
        $ kstats kdc Jan2000.kdc.log > Jan2000.kdc.rpt

     In this example, a file named Jan2000.kdc.log is presumed to
     be  a  kdc  log  file.   The  Jan2000.kdc.rpt file will be a
     report on which nodes were attempting to access the KDC.

        $ kstats kdc -v *kdc*.log > verbose.kdc.rpt

     In this example, all files of the form *kdc.log will be used
     as  input,  and the verbose.kdc.rpt will contain a more ver-
     bose output.

        $ kstats kdc -Q *kdc*.log | kprobe > probe.status

     In this example, the -Q option is  used  so  that  only  the
     nodenames  of  interest  are  produced  from  the kdc report
     (i.e., the nodes who attempted to  access  the  KDC).   This
     list of nodes is then piped into kprobe, a utility to see if
     the nodes are conforming to strengthened  realm  rules  (not
     yet written!).  The final report is probe.status.

kstats timestamp

     The "kstats timestamp" report would be useful  to  determine
     if  load  balancing  is  working between multiple KDC nodes,
     and/or if a particular KDC is being bombarded with load.

        $ kstats timestamp *kdc*.log > kdc.time.rpt

     In this example, the kdc.time.rpt is using the default  time
     period  (one hour) and generating a report of how many tran-
     sactions per hour per KDC.

        $ kstats timestamp -Q -l 5 *kdc*.log | plotting-routine > plot.rpt

     In this example,  we  set  the  time  period  to  5  seconds
     (transactions/5sec),  and  use the -Q qualifier so that only
     the relevent information  comes  out  (no  headers/trailers,
     just  information  suitable  for  piping to other programs).
     Presumably the plotting-routine program knows how to  handle
     the data and creates a plot.rpt.  These routines are not yet
     written.

AUTHOR

     Lauri   Loebel   Carpenter   Fermilab   Computing   Division
     (lauri@fnal.gov)