Provided by: pcp_5.0.3-1_amd64 
NAME
pmcd - performance metrics collector daemon
SYNOPSIS
pmcd [-AfQSv?] [-c config] [-C dirname] [-H hostname] [-i ipaddress] [-l logfile] [-L
bytes] [-M certname] [-[n|N] pmnsfile] [-p port[,port ...]] [-P passfile] [-q timeout]
[-s sockname] [-t timeout] [-T traceflag] [-U username] [-x file]
DESCRIPTION
pmcd is the collector used by the Performance Co-Pilot (see PCPIntro(1)) to gather
performance metrics on a system. As a rule, there must be an instance of pmcd running on
a system for any performance metrics to be available to the PCP.
pmcd accepts connections from client applications running either on the same machine or
remotely and provides them with metrics and other related information from the machine
that pmcd is executing on. pmcd delegates most of this request servicing to a collection
of Performance Metrics Domain Agents (or just agents), where each agent is responsible for
a particular group of metrics, known as the domain of the agent. For instance, the
postgresql agent is responsible for reporting information relating to the PostgreSQL
database, such as the transaction and query counts, indexing and replication statistics,
and so on.
The agents may be processes started by pmcd, independent processes or Dynamic Shared
Objects (DSOs, see dlopen(3)) attached to pmcd's address space. The configuration section
below describes how connections to agents are specified.
Note that if a PDU exchange with an agent times out, the agent has violated the
requirement that it delivers metrics with little or no delay. This is deemed a protocol
failure and the agent is disconnected from pmcd. Any subsequent requests for information
from the agent will fail with a status indicating that there is no agent to provide it.
It is possible to specify access control to pmcd based on users, groups and hosts. This
allows one to prevent users, groups of users, and certain hosts from accessing the metrics
provided by pmcd and is described in more detail in the access control section below.
OPTIONS
The available command line options are:
-A Disable service advertisement. By default, pmcd will advertise its presence on the
network using any available mechanisms (such as Avahi/DNS-SD), assisting remote
monitoring tools with finding it. These mechanisms are disabled with this option.
-c config, --config=config
On startup pmcd uses a configuration file from either the $PCP_PMCDCONF_PATH,
configuration variable in /etc/pcp.conf, or an environment variable of the same name.
However, these values may be overridden with config using this option. The format of
this configuration file is described below.
-C dirname, --certdb=dirname
Specify the path to the Network Security Services certificate database, for
(optional) secure connections. The default is /etc/pki/nssdb. Refer also to the -P
option. If it does not already exist, this database can be created using the
certutil utility. This process and other certificate database maintenance
information is provided in the PCPIntro(1) manual page and the online PCP tutorials.
-f, --foreground
By default pmcd is started as a daemon. The -f option indicates that it should run
in the foreground. This is most useful when trying to diagnose problems with
misbehaving agents.
-H hostname, --hostname=hostname
This option can be used to set the hostname that pmcd will use to represent this
instance of itself. This is used by client tools like pmlogger(1) when reporting on
the (possibly remote) host. If this option is not set, the pmcd.hostname metric will
match that returned by pmhostname(1). Refer to the manual page for that tool for
full details on how the hostname is evaluated.
-i ipaddress, --interface=ipaddress
This option is usually only used on hosts with more than one network interface. If
no -i options are specified pmcd accepts connections made to any of its host's IP
(Internet Protocol) addresses. The -i option is used to specify explicitly an IP
address that connections should be accepted on. ipaddress should be in the standard
dotted form (e.g. 100.23.45.6). The -i option may be used multiple times to define a
list of IP addresses. Connections made to any other IP addresses the host has will
be refused. This can be used to limit connections to one network interface if the
host is a network gateway. It is also useful if the host takes over the IP address
of another host that has failed. In such a situation only the standard IP addresses
of the host should be given (not the ones inherited from the failed host). This
allows PCP applications to determine that a host has failed, rather than connecting
to the host that has assumed the identity of the failed host.
-l logfile, --log=logfile
By default a log file named pmcd.log is written in the directory $PCP_LOG_DIR/pmcd.
The -l option causes the log file to be written to logfile instead of the default.
If the log file cannot be created or is not writable, output is written to the
standard error instead.
-L bytes
PDUs received by pmcd from monitoring clients are restricted to a maximum size of
65536 bytes by default to defend against Denial of Service attacks. The -L option
may be used to change the maximum incoming PDU size.
-M certname, --certname=certname
By default, pmcd will try to use a certificate called PCP Collector certificate. The
-M option allows this to be changed.
-n pmnsfile, --namespace=pmnsfile
Normally pmcd loads the default Performance Metrics Name Space (PMNS) from
$PCP_VAR_DIR/pmns/root, however if the -n option is specified an alternative
namespace is loaded from the file pmnsfile.
-N pmnsfile, --uniqnames=pmnsfile
Same function as -n, except for the handling of duplicate Performance Metric
Identifiers (PMIDs) in pmnsfile - duplicate names are allowed with -n but they are
not allowed with -N.
-P passfile, --passfile=passfile
Specify the path to a file containing the Network Security Services certificate
database password for (optional) secure connections, and for databases that are
password protected. Refer also to the -C option. When using this option, great care
should be exercised to ensure appropriate ownership ("pcp" user, typically) and
permissions on this file (0400, so as to be unreadable by any user other than the
user running the pmcd process).
-q timeout
The pmcd to agent version exchange protocol (new in PCP 2.0 - introduced to provide
backward compatibility) uses this timeout to specify how long pmcd should wait before
assuming that no version response is coming from an agent. If this timeout is
reached, the agent is assumed to be an agent which does not understand the PCP 2.0
protocol. The default timeout interval is five seconds, but the -q option allows an
alternative timeout interval (which must be greater than zero) to be specified. The
unit of time is seconds.
-Q, --remotecert
Require that all remote client connections provide a certficate.
-s sockname, --socket=sockname
Specify the path to a local unix domain socket (for platforms supporting this socket
family only). The default value is $PCP_RUN_DIR/pmcd.socket.
-S, --allcert
Require that all client connections provide user credentials. This means that only
unix domain sockets, or authenticated connections are permitted (requires secure
sockets support). If any user or group access control requirements are specified in
the pmcd configuration file, then this mode of operation is automatically entered,
whether the -S flag is specified or not.
-t timeout
To prevent misbehaving clients or agents from hanging the entire Performance Metrics
Collection System (PMCS), pmcd uses timeouts on PDU exchanges with clients and agents
running as processes. By default the timeout interval is five seconds. The -t
option allows an alternative timeout interval in seconds to be specified. If timeout
is zero, timeouts are turned off. It is almost impossible to use the debugger
interactively on an agent unless timeouts have been turned off for its "parent" pmcd.
Once pmcd is running, the timeout may be dynamically modified by storing an integer
value (the timeout in seconds) into the metric pmcd.control.timeout via pmstore(1).
-T traceflag, --trace=traceflag
To assist with error diagnosis for agents and/or clients of pmcd that are not
behaving correctly, an internal event tracing mechanism is supported within pmcd.
The value of traceflag is interpreted as a bit field with the following control
functions:
1 enable client connection tracing
2 enable PDU tracing
256 unbuffered event tracing
By default, event tracing is buffered using a circular buffer that is over-written as
new events are recorded. The default buffer size holds the last 20 events, although
this number may be over-ridden by using pmstore(1) to modify the metric
pmcd.control.tracebufs.
Similarly once pmcd is running, the event tracing control may be dynamically modified
by storing 1 (enable) or 0 (disable) into the metrics pmcd.control.traceconn,
pmcd.control.tracepdu and pmcd.control.tracenobuf. These metrics map to the bit
fields associated with the traceflag argument for the -T option.
When operating in buffered mode, the event trace buffer will be dumped whenever an
agent connection is terminated by pmcd, or when any value is stored into the metric
pmcd.control.dumptrace via pmstore(1).
In unbuffered mode, every event will be reported when it occurs.
-U username, --username=USER
User account under which to run pmcd. The default is the unprivileged "pcp" account
in current versions of PCP, but in older versions the superuser account ("root") was
used by default.
-v, --verify
Verify the pmcd configuration file, reporting on any errors then exiting with a
status indicating verification success or failure.
-x file
Before the pmcd logfile can be opened, pmcd may encounter a fatal error which
prevents it from starting. By default, the output describing this error is sent to
/dev/tty but it may redirected to file.
-?, --help
Display usage message and exit.
CONFIGURATION
On startup pmcd looks for a configuration file named $PCP_PMCDCONF_PATH. This file
specifies which agents cover which performance metrics domains and how pmcd should make
contact with the agents. An optional section specifying access controls may follow the
agent configuration data.
Warning: pmcd is usually started as part of the boot sequence and runs initially as root.
The configuration file may contain shell commands to create agents, which will be executed
by root. To prevent security breaches the configuration file should be writable only by
root. The use of absolute path names is also recommended.
The case of the reserved words in the configuration file is unimportant, but elsewhere,
the case is preserved.
Blank lines and comments are permitted (even encouraged) in the configuration file. A
comment begins with a ``#'' character and finishes at the end of the line. A line may be
continued by ensuring that the last character on the line is a ``\'' (backslash). A
comment on a continued line ends at the end of the continued line. Spaces may be included
in lexical elements by enclosing the entire element in double quotes. A double quote
preceded by a backslash is always a literal double quote. A ``#'' in double quotes or
preceded by a backslash is treated literally rather than as a comment delimiter. Lexical
elements and separators are described further in the following sections.
AGENT CONFIGURATION
Each line of the agent configuration section of the configuration file contains details of
how to connect pmcd to one of its agents and specifies which metrics domain the agent
deals with. An agent may be attached as a DSO, or via a socket, or a pair of pipes.
Each line of the agent configuration section of the configuration file must be either an
agent specification, a comment, or a blank line. Lexical elements are separated by
whitespace characters, however a single agent specification may not be broken across lines
unless a \ (backslash) is used to continue the line.
Each agent specification must start with a textual label (string) followed by an integer
in the range 1 to 510. The label is a tag used to refer to the agent and the integer
specifies the domain for which the agent supplies data. This domain identifier
corresponds to the domain portion of the PMIDs handled by the agent. Each agent must have
a unique label and domain identifier.
For DSO agents a line of the form:
label domain-no dso entry-point path
should appear. Where,
label is a string identifying the agent
domain-no is an unsigned integer specifying the agent's domain in the range 1 to 510
entry-point is the name of an initialization function which will be called when the DSO
is loaded
path designates the location of the DSO and this is expected to be an absolute
pathname. pmcd is only able to load DSO agents that have the same simabi
(Subprogram Interface Model ABI, or calling conventions) as it does (i.e.
only one of the simabi versions will be applicable). The simabi version of
a running pmcd may be determined by fetching pmcd.simabi. Alternatively,
the file(1) command may be used to determine the simabi version from the
pmcd executable.
For a relative path the environment variable PMCD_PATH defines a colon (:)
separated list of directories to search when trying to locate the agent DSO.
The default search path is $PCP_SHARE_DIR/lib:/usr/pcp/lib.
For agents providing socket connections, a line of the form
label domain-no socket addr-family address [ command ]
should appear. Where,
label is a string identifying the agent
domain-no is an unsigned integer specifying the agent's domain in the range 1 to 510
addr-family designates whether the socket is in the AF_INET, AF_INET6 or AF_UNIX domain,
and the corresponding values for this parameter are inet, ipv6 and unix
respectively.
address specifies the address of the socket within the previously specified addr-
family. For unix sockets, the address should be the name of an agent's
socket on the local host (a valid address for the UNIX domain). For inet
and ipv6 sockets, the address may be either a port number or a port name
which may be used to connect to an agent on the local host. There is no
syntax for specifying an agent on a remote host as a pmcd deals only with
agents on the same machine.
command is an optional parameter used to specify a command line to start the agent
when pmcd initializes. If command is not present, pmcd assumes that the
specified agent has already been created. The command is considered to
start from the first non-white character after the socket address and finish
at the next newline that isn't preceded by a backslash. After a fork(2) the
command is passed unmodified to execve(2) to instantiate the agent.
For agents interacting with the pmcd via stdin/stdout, a line of the form:
label domain-no pipe protocol command
should appear. Where,
label is a string identifying the agent
domain-no is an unsigned integer specifying the agent's domain
protocol The value for this parameter should be binary.
Additionally, the protocol can include the notready keyword to indicate that
the agent must be marked as not being ready to process requests from pmcd.
The agent will explicitly notify the pmcd when it is ready to process the
requests by sending a PM_ERR_PMDAREADY PDU. For further details of this
protocol, including a description of the IPC parameters that can be
specified in a PMDA Install script with the ipc_prot parameter, see the
relevant section in PMDA(3).
command specifies a command line to start the agent when pmcd initializes. Note
that command is mandatory for pipe-based agents. The command is considered
to start from the first non-white character after the protocol parameter and
finish at the next newline that isn't preceded by a backslash. After a
fork(2) the command is passed unmodified to execve(2) to instantiate the
agent.
ACCESS CONTROL CONFIGURATION
The access control section of the configuration file is optional, but if present it must
follow the agent configuration data. The case of reserved words is ignored, but elsewhere
case is preserved. Lexical elements in the access control section are separated by
whitespace or the special delimiter characters: square brackets (``['' and ``]''), braces
(``{'' and ``}''), colon (``:''), semicolon (``;'') and comma (``,''). The special
characters are not treated as special in the agent configuration section. Lexical
elements may be quoted (double quotes) as necessary.
The access control section of the file must start with a line of the form:
[access]
In addition to (or instead of) the access section in the pmcd configuration file, access
control specifications are also read from a file having the same name as the pmcd
configuration file, but with '.access' appended to the name. This optional file must not
contain the [access] keyword.
Leading and trailing whitespace may appear around and within the brackets and the case of
the access keyword is ignored. No other text may appear on the line except a trailing
comment.
Following this line, the remainder of the configuration file should contain lines that
allow or disallow operations from particular hosts or groups of hosts.
There are two kinds of operations that occur via pmcd:
fetch allows retrieval of information from pmcd. This may be information about a
metric (e.g. its description, instance domain, labels or help text) or a
value for a metric. See pminfo(1) for further information.
store allows pmcd to be used to store metric values in agents that permit store
operations. This may be the actual value of the metric (e.g. resetting a
counter to zero). Alternatively, it may be a value used by the PMDA to
introduce a change to some aspect of monitoring of that metric (e.g. server
side event filtering) - possibly even only for the active client tool
performing the store operation, and not others. See pmstore(1) for further
information.
Access to pmcd can be granted in three ways - by user, group of users, or at a host level.
In the latter, all users on a host are granted the same level of access, unless the user
or group access control mechanism is also in use.
User names and group names will be verified using the local /etc/passwd and /etc/groups
files (or an alternative directory service), using the getpwent(3) and getgrent(3)
routines.
Hosts may be identified by name, IP address, IPv6 address or by the special host
specifications ``"unix:"'' or ``"local:"''. ``"unix:"'' refers to pmcd's unix domain
socket, on supported platforms. ``"local:"'' is equivalent to specifying ``"unix:"'' and
``localhost``.
Wildcards may also be specified by ending the host identifier with the single wildcard
character ``*'' as the last-given component of an address. The wildcard ``".*"'' refers
to all inet (IPv4) addresses. The wildcard ``":*"'' refers to all IPv6 addresses. If an
IPv6 wildcard contains a ``::'' component, then the final ``*'' refers to the final 16
bits of the address only, otherwise it refers to the remaining unspecified bits of the
address.
The wildcard ``*'' refers to all users, groups or host addresses, including ``"unix:"''.
Names of users, groups or hosts may not be wildcarded.
The following are all valid host identifiers:
boing
localhost
giggle.melbourne.sgi.com
129.127.112.2
129.127.114.*
129.*
.*
fe80::223:14ff:feaf:b62c
fe80::223:14ff:feaf:*
fe80:*
:*
"unix:"
"local:"
*
The following are not valid host identifiers:
*.melbourne
129.127.*.*
129.*.114.9
129.127*
fe80::223:14ff:*:*
fe80::223:14ff:*:b62c
fe80*
The first example is not allowed because only (numeric) IP addresses may contain a
wildcard. The second and fifth examples are not valid because there is more than one
wildcard character. The third and sixth contain an embedded wildcard, the fourth and
seventh have a wildcard character that is not the last component of the address (the last
components are 127* and fe80* respectively).
The name localhost is given special treatment to make the behavior of host wildcarding
consistent. Rather than being 127.0.0.1 and ::1, it is mapped to the primary inet and
IPv6 addresses associated with the name of the host on which pmcd is running. Beware of
this when running pmcd on multi-homed hosts.
Access for users, groups or hosts are allowed or disallowed by specifying statements of
the form:
allow users userlist : operations ;
disallow users userlist : operations ;
allow groups grouplist : operations ;
disallow groups grouplist : operations ;
allow hosts hostlist : operations ;
disallow hosts hostlist : operations ;
list userlist, grouplist and hostlist are comma separated lists of one or more
users, groups or host identifiers.
operations is a comma separated list of the operation types described above, all (which
allows/disallows all operations), or all except operations (which
allows/disallows all operations except those listed).
Either plural or singular forms of users, groups, and hosts keywords are allowed. If this
keyword is omitted, a default of hosts will be used. This behaviour is for backward-
compatibility only, it is preferable to be explicit.
Where no specific allow or disallow statement applies to an operation, the default is to
allow the operation from all users, groups and hosts. In the trivial case when there is
no access control section in the configuration file, all operations from all users,
groups, and hosts are permitted.
If a new connection to pmcd is attempted by a user, group or host that is not permitted to
perform any operations, the connection will be closed immediately after an error response
PM_ERR_PERMISSION has been sent to the client attempting the connection.
Statements with the same level of wildcarding specifying identical hosts may not
contradict each other. For example if a host named clank had an IP address of
129.127.112.2, specifying the following two rules would be erroneous:
allow host clank : fetch, store;
disallow host 129.127.112.2 : all except fetch;
because they both refer to the same host, but disagree as to whether the fetch operation
is permitted from that host.
Statements containing more specific host specifications override less specific ones
according to the level of wildcarding. For example a rule of the form
allow host clank : all;
overrides
disallow host 129.127.112.* : all except fetch;
because the former contains a specific host name (equivalent to a fully specified IP
address), whereas the latter has a wildcard. In turn, the latter would override
disallow host * : all;
It is possible to limit the number of connections from a user, group or host to pmcd.
This may be done by adding a clause of the form
maximum n connections
to the operations list of an allow statement. Such a clause may not be used in a disallow
statement. Here, n is the maximum number of connections that will be accepted from the
user, group or host matching the identifier(s) used in the statement.
An access control statement with a list of user, group or host identifiers is equivalent
to a set of access control statements, with each specifying one of the identifiers in the
list and all with the same access controls (both permissions and connection limits). A
group should be used if you want users to contribute to a shared connection limit. A
wildcard should be used if you want hosts to contribute to a shared connection limit.
When a new client requests a connection, and pmcd has determined that the client has
permission to connect, it searches the matching list of access control statements for the
most specific match containing a connection limit. For brevity, this will be called the
limiting statement. If there is no limiting statement, the client is granted a
connection. If there is a limiting statement and the number of pmcd clients with user ID,
group ID, or IP addresses that match the identifier in the limiting statement is less than
the connection limit in the statement, the connection is allowed. Otherwise the
connection limit has been reached and the client is refused a connection.
Group access controls and the wildcarding in host identifiers means that once pmcd
actually accepts a connection from a client, the connection may contribute to the current
connection count of more than one access control statement - the client's host may match
more than one access control statement, and similarly the user ID may be in more than one
group. This may be significant for subsequent connection requests.
Note that pmcd enters a mode where it runs effectively with a higher-level of security as
soon as a user or group access control section is added to the configuration. In this
mode only authenticated connections are allowed - either from a SASL authenticated
connection, or a Unix domain socket (which implicitly passes client credentials). This is
the same mode that is entered explicitly using the -S option. Assuming permission is
allowed, one can determine whether pmcd is running in this mode by querying the value of
the pmcd.feature.creds_required metric.
Note also that because most specific match semantics are used when checking the connection
limit, for the host-based access control case, priority is given to clients with more
specific host identifiers. It is also possible to exceed connection limits in some
situations. Consider the following:
allow host clank : all, maximum 5 connections;
allow host * : all except store, maximum 2 connections;
This says that only 2 client connections at a time are permitted for all hosts other than
"clank", which is permitted 5. If a client from host "boing" is the first to connect to
pmcd, its connection is checked against the second statement (that is the most specific
match with a connection limit). As there are no other clients, the connection is accepted
and contributes towards the limit for only the second statement above. If the next client
connects from "clank", its connection is checked against the limit for the first
statement. There are no other connections from "clank", so the connection is accepted.
Once this connection is accepted, it counts towards both statements' limits because
"clank" matches the host identifier in both statements. Remember that the decision to
accept a new connection is made using only the most specific matching access control
statement with a connection limit. Now, the connection limit for the second statement has
been reached. Any connections from hosts other than "clank" will be refused.
If instead, pmcd with no clients saw three successive connections arrived from "boing",
the first two would be accepted and the third refused. After that, if a connection was
requested from "clank" it would be accepted. It matches the first statement, which is
more specific than the second, so the connection limit in the first is used to determine
that the client has the right to connect. Now there are 3 connections contributing to the
second statement's connection limit. Even though the connection limit for the second
statement has been exceeded, the earlier connections from "boing" are maintained. The
connection limit is only checked at the time a client attempts a connection rather than
being re-evaluated every time a new client connects to pmcd.
This gentle scheme is designed to allow reasonable limits to be imposed on a first come
first served basis, with specific exceptions.
As illustrated by the example above, a client's connection is honored once it has been
accepted. However, pmcd reconfiguration (see the next section) re-evaluates all the
connection counts and will cause client connections to be dropped where connection limits
have been exceeded.
AGENT FENCING
Preventing sampling during the life of a PMDA is sometimes desirable, for example if that
sampling impacts on sensitive phases of a scheduled job. A temporary ``fence'' can be
raised to block all PMAPI client access to one or more agents in this situation. This
functionality is provided by the built-in PMCD PMDA and the pmstore(1) command, as in
# pmstore -i nfsclient,kvm pmcd.agent.fenced 1
If the optional comma-separated list of agent names is omitted, all agents will be fenced.
To resume normal operation, the ``fence'' can be lowered as follows
# pmstore -i nfsclient,kvm pmcd.agent.fenced 0
Lowering the fence for all PMDAs at once is performed using
# pmstore pmcd.agent.fenced 0
Elevated privileges are required to store to the pmcd.agent.fenced metric. For additional
information, see the help text associated with this metric, which can be accessed using
the -T, --helptext option to pminfo(1).
RECONFIGURING PMCD
If the configuration file has been changed or if an agent is not responding because it has
terminated or the PMNS has been changed, pmcd may be reconfigured by sending it a SIGHUP,
as in
# pmsignal -a -s HUP pmcd
When pmcd receives a SIGHUP, it checks the configuration file for changes. If the file
has been modified, it is reparsed and the contents become the new configuration. If there
are errors in the configuration file, the existing configuration is retained and the
contents of the file are ignored. Errors are reported in the pmcd log file.
It also checks the PMNS file and any labels files for changes. If any of these files have
been modified, then the PMNS and/or context labels are reloaded. Use of tail(1) on the
log file is recommended while reconfiguring pmcd.
If the configuration for an agent has changed (any parameter except the agent's label is
different), the agent is restarted. Agents whose configurations do not change are not
restarted. Any existing agents not present in the new configuration are terminated. Any
deceased agents are that are still listed are restarted.
Sometimes it is necessary to restart an agent that is still running, but malfunctioning.
Simply stop the agent (e.g. using SIGTERM from pmsignal(1)), then send pmcd a SIGHUP,
which will cause the agent to be restarted.
STARTING AND STOPPING PMCD
Normally, pmcd is started automatically at boot time and stopped when the system is being
brought down. Under certain circumstances it is necessary to start or stop pmcd manually.
To do this one must become superuser and type
# $PCP_RC_DIR/pmcd start
to start pmcd, or
# $PCP_RC_DIR/pmcd stop
to stop pmcd. Starting pmcd when it is already running is the same as stopping it and
then starting it again.
Sometimes it may be necessary to restart pmcd during another phase of the boot process.
Time-consuming parts of the boot process are often put into the background to allow the
system to become available sooner (e.g. mounting huge databases). If an agent run by pmcd
requires such a task to complete before it can run properly, it is necessary to restart or
reconfigure pmcd after the task completes. Consider, for example, the case of mounting a
database in the background while booting. If the PMDA which provides the metrics about
the database cannot function until the database is mounted and available but pmcd is
started before the database is ready, the PMDA will fail (however pmcd will still service
requests for metrics from other domains). If the database is initialized by running a
shell script, adding a line to the end of the script to reconfigure pmcd (by sending it a
SIGHUP) will restart the PMDA (if it exited because it couldn't connect to the database).
If the PMDA didn't exit in such a situation it would be necessary to restart pmcd because
if the PMDA was still running pmcd would not restart it.
Normally pmcd listens for client connections on TCP/IP port number 44321 (registered at
http://www.iana.org/). Either the environment variable PMCD_PORT or the -p command line
option may be used to specify alternative port number(s) when pmcd is started; in each
case, the specification is a comma-separated list of one or more numerical port numbers.
Should both methods be used or multiple -p options appear on the command line, pmcd will
listen on the union of the set of ports specified via all -p options and the PMCD_PORT
environment variable. If non-default ports are used with pmcd care should be taken to
ensure that PMCD_PORT is also set in the environment of any client application that will
connect to pmcd, or that the extended host specification syntax is used (see PCPIntro(1)
for details).
CAVEATS
pmcd does not explicitly terminate its children (agents), it only closes their pipes. If
an agent never checks for a closed pipe it may not terminate.
The configuration file parser will only read lines of less than 1200 characters. This is
intended to prevent accidents with binary files.
The timeouts controlled by the -t option apply to IPC between pmcd and the PMDAs it
spawns. This is independent of settings of the environment variables PMCD_CONNECT_TIMEOUT
and PMCD_REQUEST_TIMEOUT (see PCPIntro(1)) which may be used respectively to control
timeouts for client applications trying to connect to pmcd and trying to receive
information from pmcd.
DIAGNOSTICS
If pmcd is already running the message "Error: OpenRequestSocket bind: Address may already
be in use" will appear. This may also appear if pmcd was shutdown with an outstanding
request from a client. In this case, a request socket has been left in the TIME_WAIT
state and until the system closes it down (after some timeout period) it will not be
possible to run pmcd.
In addition to the standard PCP debugging flags, see pmdbg(1), pmcd currently uses the
options: appl0 for tracing I/O and termination of agents, appl1 for tracing access control
and appl2 for tracing the configuration file scanner and parser.
FILES
$PCP_PMCDCONF_PATH
default configuration file
$PCP_PMCDCONF_PATH.access
optional access control specification file
$PCP_PMCDOPTIONS_PATH
command line options to pmcd when launched from $PCP_RC_DIR/pmcd All the command line
option lines should start with a hyphen as the first character.
$PCP_SYSCONFIG_DIR/pmcd
additional environment variables that will be set when pmcd executes. Only settings
of the form "PMCD_VARIABLE=value" will be honoured.
$PCP_SYSCONF_DIR/labels
directory of files containing the global metric labels that will be set for every
client context created by pmcd. File names starting with a ``.'' are ignored, and
files ending in ``.json'' are ``JSONB'' formatted name:value pairs. The merged set
can be queried via the pmcd.labels metric. Context labels are applied universally to
all values.
./pmcd.log
(or $PCP_LOG_DIR/pmcd/pmcd.log when started automatically)
All messages and diagnostics are directed here.
$PCP_RUN_DIR/pmcd.pid
contains an ascii decimal representation of the process ID of pmcd, when it's
running.
/etc/pki/nssdb
default Network Security Services (NSS) certificate database directory, used for
optional Secure Socket Layer connections. This database can be created and queried
using the NSS certutil tool, amongst others.
/etc/passwd
user names, user identifiers and primary group identifiers, used for access control
specifications
/etc/groups
group names, group identifiers and group members, used for access control
specifications
ENVIRONMENT
The following variables are set in $PCP_SYSCONFIG_DIR/pmcd.
In addition to the PCP environment variables described in the PCP ENVIRONMENT section
below, the PMCD_PORT variable is also recognised as the TCP/IP port for incoming
connections (default 44321), and the PMCD_SOCKET variable is also recognised as the path
to be used for the Unix domain socket.
If set to the value 1, the PMCD_LOCAL environment variable will cause pmcd to run in a
localhost-only mode of operation, where it binds only to the loopback interface. The
pmcd.feature.local metric can be queried to determine if pmcd is running in this mode.
The PMCD_MAXPENDING variable can be set to indicate the maximum length to which the queue
of pending client connections may grow.
The PMCD_ROOT_AGENT variable controls whether or not pmcd or pmdaroot (when available),
start subsequent pmdas. When set to a non-zero value, pmcd will opt to have pmdaroot
start, and stop, PMDAs.
The PMCD_RESTART_AGENTS variable determines the behaviour of pmcd in the presence of child
PMDAs that have been observed to exit (this is a typical response in the presence of very
large, usually domain-induced, PDU latencies). When set to a non-zero value, pmcd will
attempt to restart such PMDAS once every minute. When set to zero, it uses the original
behaviour of just logging the failure.
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).
For environment variables affecting PCP tools, see pmGetOptions(3).
SEE ALSO
PCPIntro(1), pmdbg(1), pmerr(1), pmgenmap(1), pminfo(1), pmrep(1), pmstat(1), pmstore(1),
pmval(1), getpwent(3), getgrent(3), pcp.conf(5), pcp.env(5) and PMNS(5).