As outlined below there are a number of variables that can be set
in a PMDA's Install script to influence the behaviour of the
installation procedures. These would typically need to be set
before the call to pmdaInstall, but in some instances (like $iam
and the cases specifically noted below), before the call to
pmdaSetup.
The following variables control the communication options between
the PMDA and pmcd(1). At least one of $daemon_opt, $dso_opt,
$perl_opt or $python_opt must be set to define the supported
mode(s) of communication. If more than one of these is set the
user will be prompted to make a selection when the Install script
is run.
daemon_opt
We are willing to install the PMDA as a daemon.
Default: true
dso_opt
We are willing to install the PMDA as a DSO, so pmcd(1)
will use the dynamic linking loader to attach the PMDA's
DSO at run-time and communication from pmcd(1) to the PMDA
and back uses procedure calls, not an IPC channel.
Default: false
dso_entry
For a DSO PMDA, this is the name of the PMDA's
initialization routine.
Default: ${iam}_init
dso_name
For a DSO PMDA, this is the full pathanme of the PMDA's
DSO file.
Default: $PCP_PMDAS_DIR/$iam/pmda_$iam.$dso_suffix
pipe_opt
For a daemon PMDA, is the default IPC channel via a
pipe(2)?
Default: Platform-specific, so true for most, but false
for Windows
perl_opt
We are willing to install the PMDA as a Perl script and
pmcd(1) will use the perl(1) interpreter to run the PMDA.
Default: false
pmda_dir
Full pathname to the directory where the PMDA's
installation files (executable, script, PMNS source, help
text source, etc) are to be found.
Default: output from pwd(1)
If set, must be done before the call to
pmdaSetup.
pmda_name
For a daemon PMDA, this is the name of the PMDA's
executable binary relative to the $pmda_dir directory.
Default: pmda$iam
python_opt
We are willing to install the PMDA as a Python script and
pmcd(1) will use the python(1) interpreter to run the
PMDA.
Default: false
ipc_prot
For a daemon PMDA, this can be set to either binary or
text. The default is binary and text is rarely used. In
addition, an optional IPC parameter notready can be used
to signify that the PMDA will start up in the notready
state, e.g. ipc_prot="binary notready". Note that the
quotes are required. The IPC parameters for a PMDA appear
in pmcd.conf in the IPC Params column. For further
details, see pmcd(1) but basically pmcd will not issue any
requests to a PMDA that has started in the notready state
until the PMDA sends a PM_ERR_PMDAREADY PDU. This allows
PMDAs with long startup times to initialize correctly
without timing out. For details, see pmdaSendError(3) and
pmcd(1). When a PMDA is in the notready state, any client
requests sent to pmcd for the PMDA domain will return with
the PM_ERR_PMDANOTREADY error.
socket_inet_def
For a daemon PMDA using a socket(2) as the IPC channel the
default Internet port number or service name (if known).
Default: ""
socket_opt
For a daemon PMDA, is the default IPC channel via a
socket(2)?
Default: Platform-specific, so false for most, but true
for Windows
The following variables control the PMNS options.
pmns_dupok
Most PMDAs do not have duplicate names for the same PMID
in their PMNS. But if this is not the case, pmns_dupok
should be set to true.
Default: false
pmns_name
Each PMDA will add one or more non-leaf nodes to the top
of the PMNS. The most common case is that all of the
metrics for a PMDA will be placed below the node named
$iam. If this is not the case, and especially when the
PMDA adds more than one non-leaf node at the top of the
PMNS, pmns_name needs to be set to the list of node names
(separated by white space), e.g. for pmdaproc(1) pmns_name
is set to "proc cgroup hotproc".
Default: $iam
It is most important that if pmns_name is set to
a non-default value in the Install script then it
must also be set to the same value in the Remove
script.
pmns_source
The name of the PMDA's PMNS source file. By default, the
name is interpreted as a relative pathname from the
$pmda_dir directory.
Default: pmns
The following variables provide assorted additional options
associated with the installation of a PMDA.
args Additional command line args for the PMDA. These will be
appended to the PMDA's control line in $PCP_PMCDCONF_PATH.
Default: ""
check_delay
Delay (in seconds) after finishing the PMDA installation
(or removal) before checking the availability of metrics
from the PMDA. May need to be increased if the PMDA has a
lengthy startup procedure.
Default: 0.3
signal_delay
Delay (in seconds) after notifying pmcd(1) with a signal.
Required to allow pmcd(1) to complete processing before
proceeding to the next step of the installation (or
removal).
Default: 1
configdir
Determines the directory in which a PMDA's configuration
file will be stored. Used by pmdaChooseConfigFile so
should be set before calling that procedure.
Default: $PCP_VAR_DIR/config/$iam
configfile
Preferred configuration file for the PMDA. Used by
pmdaChooseConfigFile so should be set before calling that
procedure.
Default: ""
default_configfile
Default configuration file for the PMDA. Used by
pmdaChooseConfigFile so should be set before calling that
procedure.
Default: ""
dso_suffix
Standard suffix for a DSO. Should not need to be changed
under normal circumstances.
Default: Platform-specific, so 'so' for Linux, 'dylib' for
Mac OS X, 'dll' for Windows, etc.
If set, must be done before the call to
pmdaSetup.
help_source
The name of the help text source file that should be used
as input to pmnewhelp(1). By default, the name is
interpreted as a relative pathname from the $pmda_dir
directory.
Default: help
python_name
Full pathname of the Python script for a Python PMDA.
Default: $pmda_dir/pmda$iam.python or
$pmda_dir/pmda$iam.py
The shell procedures in $PCP_SHARE_DIR/lib/pmdaproc.sh manipulate
a number of temporary files using the variable $tmp as the prefix
for the name of the temporary files. $tmp is a directory that is
created, used and removed internally within the procedures of
$PCP_SHARE_DIR/lib/pmdaproc.sh but can also be used as the prefix
for temporary files needed by a PMDA's Install or Remove scripts.
When used in this way, $tmp should be followed by a ``/'' and
then a suffix, e.g. $tmp/myfoo. The Install and Remove scripts
should not use other temporary file name prefixes nor use sh(1)
trap statements to clean up temporary files as this is all done
within $PCP_SHARE_DIR/lib/pmdaproc.sh.
