Ubuntu Manpage: pcp-check - manage the configuration of optional PCP components

NAME

       pcp-check - manage the configuration of optional PCP components

SYNOPSIS

       $pcp-check [-a] [-d] [-l] [-n] [-s] [-v] [-x] [component ...]
       $pcp-check [-a] [-c script]] [-d] [-l] [-n] [-s] [-v] [-x]
       $PCP_BINADM_DIR/pmcheck ...

DESCRIPTION

The Performance Co-Pilot (PCP) includes a number of core components that are likely to be pre-configured
and operational, but it also includes a larger number of components that are not active by default. In
the context of pmcheck these components cover services that are typically started as part of the system
boot procedure, e.g. pmcd(1), pmlogger(1), pmproxy(1), etc. or optional Performance Metric Domain Agents
(PMDAs) that augment the available performance metrics exported by pmcd(1).

pmcheck allows the interrogation of the state of components with the -s, --state option. Components can
be activated with the -a, --activate option, or deactivated with the -d, --deactivate option. These
three options are clearly mutually exclusive for any single execution of pmcheck, and in the absence of
any of them -s is assumed to be the default.

The set of components to be interrogated or configured are specified by the component name(s) from the
command line, else all known components in the absence of any component arguments. When one or more
component arguments are specified, these may optionally be sh(1) (glob) patterns that are matched against
the names of the known components.

The -l, --list option reports on known components. With one or more components each is reported.
Without any component arguments the -l option lists all known components, which is simply all the
component scripts (see the COMPONENT SCRIPTS section below) stored in the $PCP_SHARE_DIR/lib/pmcheck
directory. If the -v option is also used, a short description of each requested component is also
displayed.

Additional components can be integrated into the pmcheck framework, and the -c, --file option allows an
alternate sh(1) script to be used instead of a script associated with a known component.

In concert with the -a or -d options, the -n, --show-me option performs a dry run, showing the sh(1)
commands that would be needed to perform the reconfiguration, but no reconfiguration is done. Commands
that need to be run as ``root'' are prefixed with # and other commands are prefixed with $.

The -v, --verbose option increases reporting verbosity.

The -x, --trace option may be used specify that the component scripts are run with -x option to sh(1).
This can assist with debugging the failure of a component script or during the development of a new
component script, probably also involving the -c option to pmcheck.

The -?, --help option displays a usage message.

As a convience, pmcheck . is an alias for pcp-check.

COMPONENT SCRIPTS

The pmcheck framework is extensible, as the set of known components is defined by the names of the
component scripts in the $PCP_SHARE_DIR/lib/pmcheck directory.

Each component script needs to abide by the following rules for correct integration with pmcheck:

• The script will be run with sh(1), if you need some other scripting language then you must provide a
sh(1) wrapper.
• Since each script is responsible for one component, the name of the component is implied, however the
name of the component is also passed from pmcheck as the sole argument after the options. This allows
generic component scripts to be implemented as hard links below $PCP_SHARE_DIR/lib/pmcheck.
• When called with a -l, --list option the script does nothing, unless it is also called with a -v option
in which case a short description of the component is displayed on standard output.
• When called with a -s, --state option, the script must exit with the an exit code that indicates the
component's state, namely 0 (active), 1 (inactive, but could be activated by pmcheck), 2 (inactive and
cannot be activated by pmcheck). The distinction between exit codes 1 and 2 is based on many factors,
but 1 usually means all of the required software packages (PCP and other) are installed, required
prerequisite services are running or could be safely started, and any component configuration can
assume default settings or can be reliably deduced, e.g. a port number for communications. Conversely,
2 means automatic activation of the component is not possible and some end-user intervention is
required.
• When called with a -a, --activate option the script must activate the component. This means making any
required configuration change so that it is restarted at the next system reboot or pmcd(1) restart, and
starting the component if it is currently inactive,
• When called with a -d, --deactivate option the script must deactivate the component. This means
stopping the component if it is currently active, and making any required configuration change so that
it is not restarted at the next system reboot or pmcd(1) restart.
• When called with a -n, --show-me option the script must perform a dry run and echo any required
commands on standard output as per the rules described above for the -n option of pmcheck.
• If a -v, --verbose option is also specified, the script should provide explanatory text on standard
output to help explain, particularly in cases where the component is not active or the reconfiguration
failed.

To assist with component script development, the file $PCP_SHARE_DIR/lib/checkproc.sh may be sourced
(after sourcing $PCP_DIR/etc/pcp.env). checkproc.sh provides the following services:

• A temporary directory is created and the shell variable $tmp is assigned to the full pathname of the
directory.
• The shell variable $status is used to return the exit status from the script [defaults to 0].
• The shell variable $component is assigned to the associated component name.
• The shell variable $prog is assigned to the script's basename (so the component name in the default
case).
• A trap is installed to cleanup $tmp and exit with $status.
• A _do_args shell procedure that handles all command argument parsing.
• Shell variables $aflag, $dflag, $lflag or $sflag have default values of false and are set to true by
_do_args when the -a, -d, -l or -s options are parsed.
• The shell variable $show_me has the default value of false and is set to true by _do_args when the -n
option is parsed.
• The shell variable $verbose counts number of -v options parsed by _do_args.
• A _ctl_svc shell procedure that handles status requests and all reconfiguration operations for services
that are managed by systemctl(1) or init(1) or similar infrastructure layers. _ctl_svc takes 2
arguments, the first is an action (one of state, start, stop, activate (enable and start), or
deactivate (stop and disable), and the second is the name of the component; for systemctl(1) managed
components, name should be the basename of the service, e.g. pmcd for the pmcd.service systemd(1)
unit, otherwise name is the name of the init(1) or similar ``rc'' script.
• _ctl_svc will return a value (via $? when called from a shell script) that matches the exit codes
defined above for each action.
• A _ctl_pmda shell procedure that handles status requests and all reconfiguration operations for a PMDA
that is connected to pmcd(1). _ctl_pmda takes at least 2 arguments, the first is an action (one of
state, activate or deactivate, and the second argument is the name of the PMDA. For the install
action, there is a third argument for the name of the PMDA's executable or DSO and an optional fourth
argument is the name of a file providing the input required for the PMDA's Install script (defaults to
/dev/null).
• _ctl_pmda will return a value (via $? when called from a shell script) that matches the exit codes
defined above for each action.

So the following is the simplest possible component script for a system service.

#!/bin/sh
. $PCP_DIR/etc/pcp.env || exit 1
. $PCP_SHARE_DIR/lib/checkproc.sh
_do_args "$@"
if $lflag
then
[ $verbose -gt 0 ] && echo "my description"
elif $sflag
then
_ctl_svc state $component
status=$?
elif $aflag
then
_ctl_svc activate $component || status=1
elif $dflag
then
_ctl_svc deactivate $component || status=1
fi

And the following is the simplest possible component script for a PMDA.

#!/bin/sh
. $PCP_DIR/etc/pcp.env || exit 1
. $PCP_SHARE_DIR/lib/checkproc.sh
_do_args "$@"
if $lflag
then
[ $verbose -gt 0 ] && echo "my description"
elif $sflag
then
_ctl_pmda state $component
status=$?
elif $aflag
then
_ctl_pmda activate $component || status=1
elif $dflag
then
_ctl_pmda deactivate $component || status=1
fi

DIAGNOSTICS

       For  pmcheck  (not  the component scripts) the exit status is typically 0, but values of 9 or 99 indicate
       serious internal botches.

       When the -a or -d options are used, the success or failure of the reconfiguration is reported on standard
       output.

CAVEAT

       Some components have prerequisites that demand additional non-PCP services be installed,  configured  and
       operational,  e.g.  a  database  server or a key-value server.  In these cases, probing the status of the
       non-PCP service may be subject to some access controls and if pmcheck is run as a non-root user, then the
       output from -s (the default) may be incomplete or misleading; in these circumstances, running pmcheck  as
       root should provide a more accurate report.

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(5).