pmcheck - Man Page

pmcheck [-a] [-d] [-l] [-n] [-s] [-v] [-x] [component ...]
pmcheck [-a] [-c script]] [-d] [-l] [-n] [-s] [-v] [-x]

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.

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

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.

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

init(1), PCPIntro(1), pmcd(1), pmlogger(1), pmproxy(1), sh(1), systemctl(1), pcp.conf(5) and pcp.env(5).