'\"macro stdmacro
.\"
.\" Copyright (c) 2024 Ken McDonell.  All Rights Reserved.
.\"
.\" This program is free software; you can redistribute it and/or modify it
.\" under the terms of the GNU General Public License as published by the
.\" Free Software Foundation; either version 2 of the License, or (at your
.\" option) any later version.
.\"
.\" This program is distributed in the hope that it will be useful, but
.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
.\" or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
.\" for more details.
.\"
.\"
.TH PCP-CHECK 1 "PCP" "Performance Co-Pilot"
.SH NAME
\f3pcp-check\f1 \- manage the configuration of optional PCP components
.SH SYNOPSIS
\f3$pcp-check\f1
[\f3\-a\f1] [\f3\-d\f1] [\f3\-l\f1] [\f3\-n\f1] [\f3\-s\f1]
[\f3\-v\f1] [\f3\-x\f1] [component ...]
.br
\f3$pcp-check\f1
[\f3\-a\f1] [\f3\-c\f1 script]] [\f3\-d\f1] [\f3\-l\f1] [\f3\-n\f1] [\f3\-s\f1]
[\f3\-v\f1] [\f3\-x\f1]
.br
\f3$PCP_BINADM_DIR/pmcheck\f1 ...
.SH 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
.B pmcheck
these components cover services that are typically started as part
of the system boot procedure, e.g.
.BR pmcd (1),
.BR pmlogger (1),
.BR pmproxy (1),
etc.\& or optional
Performance Metric Domain Agents (PMDAs) that augment the available
performance metrics exported by
.BR pmcd (1).
.PP
.B pmcheck
allows the interrogation of the state of components with
the \fB\-s\fR, \fB\-\-state\fR option.
Components can be
activated with the
\fB\-a\fR, \fB\-\-activate\fR option,
or deactivated with the
\fB\-d\fR, \fB\-\-deactivate\fR option.
These three options are clearly mutually exclusive for any single
execution of
.BR pmcheck ,
and in the absence of any of them
.B \-s
is assumed to be the default.
.PP
The set of components to be interrogated or configured are specified
by the
.I component
name(s) from the command line, else all known components in the absence
of any
.I component
arguments.
When one or more
.I component
arguments are specified, these may optionally be
.BR sh (1)
(glob) patterns that are matched against the names of the known
components.
.PP
The \fB\-l\fR, \fB\-\-list\fR option
reports on known components.
With one or more
.I components
each is reported.
Without any
.I component
arguments the
.I \-l
option lists all known components,
which is simply all the component scripts (see the
.B "COMPONENT SCRIPTS"
section below)
stored in the
.I $PCP_SHARE_DIR/lib/pmcheck
directory.
If the
.B \-v
option is also used, a short description of each requested component is also
displayed.
.PP
Additional components can be integrated into the
.B pmcheck
framework, and the
\fB\-c\fR, \fB\-\-file\fR option
allows an alternate
.BR sh (1)
.I script
to be used instead of a script associated with a known
.IR component .
.PP
In concert with the
.B \-a
or
.B \-d
options,
the \fB\-n\fR, \fB\-\-show-me\fR option performs a dry run,
showing the
.BR 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
.B #
and other commands are prefixed with
.BR $ .
.PP
The \fB\-v\fR, \fB\-\-verbose\fR option increases reporting
verbosity.
.PP
The \fB\-x\fR, \fB\-\-trace\fR option may be used specify that
the component scripts are run with
.B \-x
option to
.BR 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
.B \-c
option to
.BR pmcheck .
.PP
The \fB\-?\fR, \fB\-\-help\fR
option displays a usage message.
.PP
As a convience,
.B pmcheck .
is an alias for
.BR pcp-check .
.SH COMPONENT SCRIPTS
The
.B pmcheck
framework is extensible, as the set of known components is defined
by the names of the component scripts in the
.I $PCP_SHARE_DIR/lib/pmcheck
directory.
.PP
Each component script needs to abide by the following rules
for correct integration with
.BR pmcheck :
.IP \(bu 2n
.PD 0
The script will be run with
.BR sh (1),
if you need some other scripting language then you must provide a
.BR sh (1)
wrapper.
.IP \(bu
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
.B pmcheck
as the sole argument after the options.
This allows generic component scripts to be implemented as hard
links below
.IR $PCP_SHARE_DIR/lib/pmcheck .
.IP \(bu
When called with a
\fB\-l\fR, \fB\-\-list\fR option the script does nothing,
unless it is also called with a
.B \-v
option in which case
a short description of the component is displayed on standard output.
.IP \(bu
When called with a
\fB\-s\fR, \fB\-\-state\fR option, the script must exit with the an
exit code that indicates the component's state, namely 0
(active), 1 (inactive, but
.I could
be activated by
.BR pmcheck ),
2 (inactive and
.I cannot
be activated by
.BR 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.
.IP \(bu
When called with a \fB\-a\fR, \fB\-\-activate\fR option
the script must activate the component.
This means making any required configuration change so that it
.I is
restarted at the next system reboot or
.BR pmcd (1)
restart, and
starting the component if it is currently inactive,
.IP \(bu
When called with a \fB\-d\fR, \fB\-\-deactivate\fR 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
.I "is not"
restarted at the next system reboot or
.BR pmcd (1)
restart.
.IP \(bu
When called with a \fB\-n\fR, \fB\-\-show-me\fR option
the script must perform a dry run and echo any required
commands on standard output as per the rules described above
for the
.B \-n
option of
.BR pmcheck .
.IP \(bu
If a \fB\-v\fR, \fB\-\-verbose\fR 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.
.PD
.PP
To assist with component script development, the file
.I $PCP_SHARE_DIR/lib/checkproc.sh
may be sourced (after sourcing
.IR $PCP_DIR/etc/pcp.env ).
.I checkproc.sh
provides the following services:
.IP \(bu 2n
.PD 0
A temporary directory is created and the shell variable
.BR $tmp
is assigned to the full pathname of the directory.
.IP \(bu
The shell variable
.B $status
is used to return the exit status from the script [defaults to 0].
.IP \(bu
The shell variable
.B $component
is assigned to the associated component name.
.IP \(bu
The shell variable
.B $prog
is assigned to the script's basename (so the component name
in the default case).
.IP \(bu
A
.B trap
is installed to cleanup
.B $tmp
and exit with
.BR $status .
.IP \(bu
A
.B _do_args
shell procedure that handles all command argument parsing.
.IP \(bu
Shell variables
.BR $aflag ,
.BR $dflag ,
.BR $lflag
or
.B $sflag
have default values of
.B false
and are set to
.B true
by
.B _do_args
when the
.BR \-a ,
.BR \-d ,
.BR \-l
or
.B \-s
options are parsed.
.IP \(bu
The shell variable
.B $show_me
has the default value of
.B false
and is set to
.B true
by
.B _do_args
when the
.B \-n
option is parsed.
.IP \(bu
The shell variable
.B $verbose
counts number of
.B \-v
options parsed by
.BR _do_args .
.IP \(bu
A
.B _ctl_svc
shell procedure that handles status requests
and all reconfiguration operations for
services that are managed by
.BR systemctl (1)
or
.BR init (1)
or similar infrastructure layers.
.B _ctl_svc
takes 2 arguments, the first is an
.I action
(one of
.BR state ,
.BR start ,
.BR stop ,
.B activate
(enable and start),
or
.B deactivate
(stop and disable),
and the second is the
.I name
of the component;
for
.BR systemctl (1)
managed components,
.I name
should be the basename of the service, e.g.
.B pmcd
for the
.B pmcd.service
.BR systemd (1)
unit, otherwise
.I name
is the name of the
.BR init (1)
or similar ``rc'' script.
.IP \(bu
.B _ctl_svc
will return a value (via
.B $?
when called from a shell script) that matches the exit codes
defined above for each action.
.IP \(bu
A
.B _ctl_pmda
shell procedure that handles status requests
and all reconfiguration operations for a PMDA
that is connected to
.BR pmcd (1).
.B _ctl_pmda
takes at least 2 arguments, the first is an action (one of
.BR state ,
.B activate
or
.BR deactivate ,
and the second argument is the name of the PMDA.
For the
.B 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
.I Install
script (defaults to /dev/null).
.IP \(bu
.B _ctl_pmda
will return a value (via
.B $?
when called from a shell script) that matches the exit codes
defined above for each action.
.PD
.PP
So the following is the simplest possible component script for
a system service.
.PP
.ft CR
.nf
#!/bin/sh
\&. $PCP_DIR/etc/pcp.env || exit 1
\&. $PCP_SHARE_DIR/lib/checkproc.sh
.sp 0.5v
_do_args "$@"
.sp 0.5v
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
.fi
.ft
.PP
And the following is the simplest possible component script for
a PMDA.
.PP
.ft CR
.nf
#!/bin/sh
\&. $PCP_DIR/etc/pcp.env || exit 1
\&. $PCP_SHARE_DIR/lib/checkproc.sh
.sp 0.5v
_do_args "$@"
.sp 0.5v
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
.fi
.ft
.SH DIAGNOSTICS
For
.B pmcheck
(not the component scripts) the exit status is typically 0, but values of 9 or 99 indicate serious
internal botches.
.PP
When the
.B \-a
or
.B \-d
options are used, the success or failure of the reconfiguration is
reported on standard output.
.PD
.SH 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
.B pmcheck
is run as a non-root user, then the output from
.B \-s
(the default)
may be incomplete or misleading; in these circumstances, running
.B pmcheck
as root should provide a more accurate report.
.SH PCP ENVIRONMENT
Environment variables with the prefix \fBPCP_\fP are used to parameterize
the file and directory names used by PCP.
On each installation, the
file \fI/etc/pcp.conf\fP contains the local values for these variables.
The \fB$PCP_CONF\fP variable may be used to specify an alternative
configuration file, as described in \fBpcp.conf\fP(5).
.SH SEE ALSO
.BR init (1),
.BR PCPIntro (1),
.BR pmcd (1),
.BR pmlogger (1),
.BR pmproxy (1),
.BR sh (1),
.BR systemctl (1),
.BR pcp.conf (5)
and
.BR pcp.env (5).

.\" control lines for scripts/man-spell
.\" +ok+ _ctl_pmda _ctl_svc _do_args aflag checkproc dflag
.\" +ok+ gt {from test -gt}  lflag pre prog rc {from ``rc'' script}
.\" +ok+ sflag show_me tmp