In addition to the PCP run-time environment and configuration
variables described in the PCP ENVIRONMENT section below, the
following environment variables apply to all installations.
Note that most uses of these environment variables are optimized
to check the environment only the first time the variable might
be used. As the environment usually is not checked again, the
only safe strategy is to ensure all PCP-related environment
variables are set before the first call into any of the PCP
libraries.
PCP_ALLOW_BAD_CERT_DOMAIN
When set, allow clients to accept certificates with
mismatched domain names with no prompt when they are sent
by pmcd or other server components. See
PCP_SECURE_SOCKETS.
PCP_ALLOW_SERVER_SELF_CERT
When set, allow clients to accept self-signed certificates
with no prompt when they are sent by pmcd or other server
components. See PCP_SECURE_SOCKETS.
PCP_CONSOLE
When set, this changes the default console from /dev/tty
(on Unix) or CON: (on Windows) to be the specified
console. The special value of none can be used to
indicate no console is available for use. This is used in
places where console-based tools need to interact with the
user, and in particular is used when authentication is
being performed.
PCP_DEBUG
When set, this variable provides an alternate to the -D
command line option described above to initialize the
diagnostic and debug options. The value for $PCP_DEBUG is
the same as for the -D command line option, namely a
comma-separated list of debugging option name(s), and/or
decimal integers, see pmdbg(1) for a description of the
supported option names and values.
PCP_DERIVED_CONFIG
When set, this variable defines a colon separated list of
files and/or directories (the syntax is the same as for
the $PATH variable for sh(1)). The components are
expanded into a list of files as follows: if a component
of $PCP_DERIVED_CONFIG is a file, then that file is added
to the list, else if a component is a directory then
recursive descent is used to enumerate all files below
that directory and these are added to the list.
Each file in the resulting list is assumed to contain
definitions of derived metrics as per the syntax described
in pmLoadDerivedConfig(3), and these are loaded in order.
Derived metrics may be used to extend the available
metrics with new (derived) metrics using simple arithmetic
expressions.
If PCP_DERIVED_CONFIG is set, the derived metric
definitions are processed automatically as each new source
of performance metrics is established (i.e. each time a
pmNewContext(3) is called) or when requests are made
against the PMNS.
Any component in the $PCP_DERIVED_CONFIG list or the
expanded list of files that is not a file, or is not a
directory or is not accessible (due to permissions or a
bad symbolic link) will be silently ignored.
PCP_IGNORE_MARK_RECORDS
When PCP archives logs are created there may be temporal
gaps associated with discontinuities in the time series of
logged data, for example when pmcd(1) is restarted or when
multiple archive logs are concatenated with
pmlogextract(1). These discontinuities are internally
noted with a <mark> record in the PCP archive logs, and
value interpolation as described in pmSetMode(3) is not
supported across <mark> records (because the values before
and after a <mark> record are not necessarily from a
continuous time series). Sometimes the user knows the
data semantics are sound in the region of the <mark>
records, and $PCP_IGNORE_MARK_RECORDS may be used to
suppress the default behaviour.
If PCP_IGNORE_MARK_RECORDS is set (but has no value) then
all <mark> records will be ignored. Otherwise the value
$PCP_IGNORE_MARK_RECORDS follows the syntax for an
interval argument described above for the -t option, and
<mark> records will be ignored if the time gap between the
last record before the <mark> and the first record after
the <mark> is not more than interval.
PCP_SECURE_SOCKETS
When set, this variable forces any monitor tool
connections to be established using the certificate-based
secure sockets feature. If the connections cannot be
established securely, they will fail.
PCP_SECURE_DB_METHOD
With secure socket connections, the certificate and key
database is stored using the sql: method by default. Use
PCP_SECURE_DB_METHOD to override the default, most usually
setting the value to the empty string (for the older
database methods).
PCP_SECURE_DB_PATH
When set, this variable specifies an alternate certificate
database path for client tools. Similar to the action of
the -C option for pmcd(1) and pmproxy(1).
PCP_NSS_INIT_MODE
Mode to use to initialize the NSS certificate database
when using secure connections. This variable may be set
to either readonly or readwrite. If unset, the default is
readwrite.
PCP_STDERR
Many PCP tools support the environment variable
PCP_STDERR, which can be used to control where error
messages are sent. When unset, the default behavior is
that ``usage'' messages and option parsing errors are
reported on standard error, other messages after initial
startup are sent to the default destination for the tool,
i.e. standard error for ASCII tools, or a dialog for GUI
tools.
If PCP_STDERR is set to the literal value DISPLAY then all
messages will be displayed in a dialog. This is used for
any tools launched from a Desktop environment.
If PCP_STDERR is set to any other value, the value is
assumed to be a filename, and all messages will be written
there.
PMCD_CONNECT_TIMEOUT
When attempting to connect to a remote pmcd(1) on a
machine that is booting, the connection attempt could
potentially block for a long time until the remote machine
finishes its initialization. Most PCP applications and
some of the PCP library routines will abort and return an
error if the connection has not been established after
some specified interval has elapsed. The default interval
is 5 seconds. This may be modified by setting
PMCD_CONNECT_TIMEOUT in the environment to a real number
of seconds for the desired timeout. This is most useful
in cases where the remote host is at the end of a slow
network, requiring longer latencies to establish the
connection correctly.
PMCD_RECONNECT_TIMEOUT
When a monitor or client application loses a connection to
a pmcd(1), the connection may be re-established by calling
a service routine in the PCP library. However, attempts
to reconnect are controlled by a back-off strategy to
avoid flooding the network with reconnection requests. By
default, the back-off delays are 5, 10, 20, 40 and 80
seconds for consecutive reconnection requests from a
client (the last delay will be repeated for any further
attempts after the fifth). Setting the environment
variable PMCD_RECONNECT_TIMEOUT to a comma separated list
of positive integers will re-define the back-off delays,
for example setting PMCD_RECONNECT_TIMEOUT to ``1,2'' will
back-off for 1 second, then attempt another connection
request every 2 seconds thereafter.
PMCD_REQUEST_TIMEOUT
For monitor or client applications connected to pmcd(1),
there is a possibility of the application "hanging" on a
request for performance metrics or metadata or help text.
These delays may become severe if the system running pmcd
crashes, or the network connection is lost. By setting
the environment variable PMCD_REQUEST_TIMEOUT to a number
of seconds, requests to pmcd will timeout after this
number of seconds. The default behavior is to be willing
to wait 10 seconds for a response from every pmcd for all
applications.
PMCD_WAIT_TIMEOUT
When pmcd(1) is started from $PCP_RC_DIR/pcp then the
primary instance of pmlogger(1) will be started if the
configuration flag pmlogger is chkconfig(8) or
systemctl(1) enabled and pmcd is running and accepting
connections.
The check on pmcd's readiness will wait up to
PMCD_WAIT_TIMEOUT seconds. If pmcd has a long startup
time (such as on a very large system), then
PMCD_WAIT_TIMEOUT can be set to provide a maximum wait
longer than the default 60 seconds.
PMNS_DEFAULT
If set, then interpreted as the full pathname to be used
as the default local PMNS for pmLoadNameSpace(3).
Otherwise, the default local PMNS is located at
$PCP_VAR_DIR/pcp/pmns/root for base PCP installations.
PCP_COUNTER_WRAP
Many of the performance metrics exported from PCP agents
have the semantics of counter meaning they are expected to
be monotonically increasing. Under some circumstances,
one value of these metrics may smaller than the previously
fetched value. This can happen when a counter of finite
precision overflows, or when the PCP agent has been reset
or restarted, or when the PCP agent is exporting values
from some underlying instrumentation that is subject to
some asynchronous discontinuity.
The environment variable PCP_COUNTER_WRAP may be set to
indicate that all such cases of a decreasing ``counter''
should be treated as a counter overflow, and hence the
values are assumed to have wrapped once in the interval
between consecutive samples. This ``wrapping'' behavior
was the default in earlier PCP versions, but by default
has been disabled in PCP release from version 1.3 on.
PMDA_PATH
The PMDA_PATH environment variable may be used to modify
the search path used by pmcd(1) and pmNewContext(3) (for
PM_CONTEXT_LOCAL contexts) when searching for a daemon or
DSO PMDA. The syntax follows that for PATH in sh(1), i.e.
a colon separated list of directories, and the default
search path is ``/var/pcp/lib:/usr/pcp/lib'', (or
``/var/lib/pcp/lib'' on Linux, depending on the value of
the $PCP_VAR_DIR environment variable).
PMCD_PORT
The TCP/IP port(s) used by pmcd(1) to create the socket
for incoming connections and requests, was historically
4321 and more recently the officially registered port
44321; in the current release, both port numbers are used
by default as a transitional arrangement. This may be
over-ridden by setting PMCD_PORT to a different port
number, or a comma-separated list of port numbers. If a
non-default port is used when pmcd is started, then every
monitoring application connecting to that pmcd must also
have PMCD_PORT set in their environment before attempting
a connection.
The following environment variables are relevant to installations
in which pmlogger(1), the PCP archive logger, is used.
PMLOGGER_PORT
The environment variable PMLOGGER_PORT may be used to
change the base TCP/IP port number used by pmlogger(1) to
create the socket to which pmlc(1) instances will try and
connect. The default base port number is 4330. When
used, PMLOGGER_PORT should be set in the environment
before pmlogger is executed.
PMLOGGER_REQUEST_TIMEOUT
When pmlc(1) connects to pmlogger(1), there is a remote
possibility of pmlc "hanging" on a request for information
as a consequence of a failure of the network or pmlogger.
By setting the environment variable
PMLOGGER_REQUEST_TIMEOUT to a number of seconds, requests
to pmlogger will timeout after this number of seconds.
The default behavior is to be willing to wait forever for
a response from each request to a pmlogger. When used,
PMLOGGER_REQUEST_TIMEOUT should be set in the environment
before pmlc is executed.
If you have the PCP product installed, then the following
environment variables are relevant to the Performance Metrics
Domain Agents (PMDAs).
PMDA_LOCAL_PROC
Use this variable has been deprecated and it is now
ignored. If the ``proc'' PMDA is configured as a DSO for
use with pmcd(1) on the local host then all of the
``proc'' metrics will be available to applications using a
PM_CONTEXT_LOCAL context.
The previous behaviour was that if this variable was set,
then a context established with the type of
PM_CONTEXT_LOCAL will have access to the ``proc'' PMDA to
retrieve performance metrics about individual processes.
PMDA_LOCAL_SAMPLE
Use this variable has been deprecated and it is now
ignored. If the ``sample'' PMDA is configured as a DSO
for use with pmcd(1) on the local host then all of the
``sample'' metrics will be available to applications using
a PM_CONTEXT_LOCAL context.
The previous behaviour was that if this variable was set,
then a context established with the type of
PM_CONTEXT_LOCAL will have access to the ``sample'' PMDA
if this optional PMDA has been installed locally.
PMIECONF_PATH
If set, pmieconf(1) will form its pmieconf(5)
specification (set of parameterized pmie(1) rules) using
all valid pmieconf files found below each subdirectory in
this colon-separated list of subdirectories. If not set,
the default is $PCP_VAR_DIR/config/pmieconf.
