NAME

       pmie_check  -  administration  of the Performance Co-Pilot
       inference engine


SYNOPSIS

       $PCP_BINADM_DIR/pmie_check [-NsV] [-c control]


DESCRIPTION

       This shell script and associated control file may be  used
       to  create  a customized regime of administration and man­
       agement for the  Performance  Co-Pilot  (see  PCPintro(1))
       inference engine, pmie(1).

       pmie_check  may  be  run  at  any time, and is intended to
       check that the desired set of pmie(1) processes  are  run­
       ning,  and  if  not  to  re-launch  any  failed  inference
       engines.  Use of the -s option provides the reverse  func­
       tionality,  allowing  the  set  of  pmie  processes  to be
       cleanly shutdown.

       pmie_check is controlled by a PCP inference engine control
       file that specifies the pmie instances to be managed.  The
       default control file  is  $PCP_VAR_DIR/config/pmie/control
       (where $PCP_VAR_DIR is normally /var/pcp) but an alternate
       may be specified using the -c option.

       The control file should be  customized  according  to  the
       following rules.

       1.     Lines beginning with a ``#'' are comments.
       2.     Lines  beginning  with  a  ``$''  are assumed to be
              assignments to environment variables in  the  style
              of  sh(1), and all text following the ``$'' will be
              eval'ed by the script reading the control file, and
              the  corresponding variable exported into the envi­
              ronment.  This is particularly useful  to  set  and
              export variables into the environment of the admin­
              istrative script, e.g.
                  $ PMCD_CONNECT_TIMEOUT=20
              Warning: The $PCP_VAR_DIR/config/pmie/control  file
              is  a  potential security risk if it is writable by
              any user other than root.
       3.     There should be one line in the  control  file  for
              each pmie instance of the form:

                  host y|n logfile args

       4.     Fields  within a line of the control file are sepa­
              rated by one or more spaces or tabs.
       5.     The first field is the name of the host that is the
              default  source of the performance metrics for this
              pmie instance.

              instance  needs  to be started under the control of
              pmsocks(1) to connect to a pmcd through a  firewall
              (y  or  n).   Note  that pmsocks is part of the pcp
              product distribution, rather than the pcp_eoe  dis­
              tribution, and as such may not be installed on your
              system.  Refer to PCPintro (1) for full details.
       8.     The third field is the name of  the  pmie  activity
              log   file.   A  useful  convention  is  that  pmie
              instances monitoring the local host  with  hostname
              myhost    are    maintained    in   the   directory
              $PCP_LOG_DIR/pmie/myhost, while activity  logs  for
              the   remote   host   mumble   are   maintained  in
              $PCP_LOG_DIR/pmie/mumble.  This is consistent  with
              the way pmlogger(1) maintains its activity logs and
              archive files.
       9.     All other fields are interpreted as arguments to be
              passed  to  pmie(1).   Most typically this would be
              the -c option.

       The  following  sample  control  lines  specify  one  pmie
       instance  monitoring  the local host (wobbly), and another
       monitoring performance metrics from the host splat.

       wobbly  n  $PCP_LOG_DIR/pmie/wobbly  -c $PCP_VAR_DIR/config/pmie/config.default
       splat   n  $PCP_LOG_DIR/pmie/splat   -c $PCP_LOG_DIR/pmie/splat/cpu.conf

       A typical  crontab(5)  entry  for  periodic  execution  of
       pmie_check  is  given  in $PCP_VAR_DIR/config/pmie/crontab
       and shown below.

       # every 30 minutes, check pmie instances are running
       25,55   *       *       *       *       $PCP_BINADM_DIR/pmie_check

       Alternate redirection of the output from the cron(1)  exe­
       cution of the script may be controlled as follows:

       (1) The  -V option to the script will enable verbose trac­
           ing of their activity.  By default the  script  gener­
           ates  no output unless some error or warning condition
           is encountered.

       (2) To redirect the e-mail from cron(1) away from the root
           login,

           + Instead  of  using the ``root'' login, create a spe­
             cial account with uid equal to 0, e.g. su_pcp.   The
             password  may  be locked and/or the shell invalid to
             prevent login or su  (1),  but  the  home  directory
             should  exist.   For  example the following entry in
             /etc/passwd:

                 su_pcp:x:0:0:PCP Housekeeping:/usr/people/su_pcp:/dev/null

             /usr/lib/aliases  for su_pcp, redirecting the e-mail
             to a real user or user(s).

           + Add the ``crontab'' entries  above  to  the  crontab
             file   for   su_pcp  not  root,  e.g.  in  the  file
             /usr/spool/cron/crontabs/su_pcp

       The -N option  enables  a  ``show  me''  mode,  where  the
       actions  are  echoed,  but  not  executed, in the style of
       ``make -n''.  Using -N in conjunction  with  -V  maximizes
       the diagnostic capabilities for debugging.


FILES

       $PCP_VAR_DIR/config/pmie/control
                 the default PCP inference engine control file
                 Warning:  this file is a potential security risk
                 if it is writable by any user other than root.

       $PCP_VAR_DIR/config/pmie/crontab
                 sample crontab for automated script execution by
                 root

       logfile.lock
                 transient  lock  file  which  is named using the
                 control-specified pmie  logfile  names,  and  is
                 used   to   guarantee  mutual  exclusion  during
                 pmie_check execution - if present, can be safely
                 removed if pmie_check is not running

       $PCP_LOG_DIR/NOTICES
                 PCP ``notices'' file used by pmie(1) and friends


PCP ENVIRONMENT

       Environment variables with the prefix  PCP_  are  used  to
       parameterize the file and directory names used by PCP.  On
       each installation, the  file  /etc/pcp.conf  contains  the
       local  values for these variables.  The $PCP_CONF variable
       may be used to specify an alternative configuration  file,
       as described in pcp.conf(4).


SEE ALSO

       chkconfig(1),    cron(1),    PCPintro(1),    pmie(1)   and
       pmsocks(1).


Man(1) output converted with man2html