--- name: "pcp-check" section: "1" platform: "linux" package: "pcp" version: "7.2.2-2" release: "Arch Linux 2026-11-01" platforms: ["linux"] url: "https://new.carta.tech/pcp-check" --- # pcp-check(1) 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)](/pmcd/1.md), [**pmlogger**(1)](/pmlogger/1.md), [**pmproxy**(1)](/pmproxy/1.md), etc. or optional Performance Metric Domain Agents (PMDAs) that augment the available performance metrics exported by [**pmcd**(1)](/pmcd/1.md). **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)](/sh/1.md) (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)](/sh/1.md) *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)](/sh/1.md) 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)](/sh/1.md). 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)](/sh/1.md), if you need some other scripting language then you must provide a [**sh**(1)](/sh/1.md) 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)](/pmcd/1.md) 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)](/pmcd/1.md) 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)](/systemctl/1.md) or [**init**(1)](/init/1.md) 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)](/systemctl/1.md) managed components, *name* should be the basename of the service, e.g. **pmcd** for the **pmcd.service** [**systemd**(1)](/systemd/1.md) unit, otherwise *name* is the name of the [**init**(1)](/init/1.md) 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)](/pmcd/1.md). **\_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)](/pcp.conf/5.md). ## SEE ALSO [**init**(1)](/init/1.md), [**PCPIntro**(1)](/PCPIntro/1.md), [**pmcd**(1)](/pmcd/1.md), [**pmlogger**(1)](/pmlogger/1.md), [**pmproxy**(1)](/pmproxy/1.md), [**sh**(1)](/sh/1.md), [**systemctl**(1)](/systemctl/1.md), [**pcp.conf**(5)](/pcp.conf/5.md) and [**pcp.env**(5)](/pcp.env/5.md).