# pcp-check

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


* * *