pmcd(1) — Linux manual page

NAME | SYNOPSIS | DESCRIPTION | OPTIONS | CONFIGURATION | AGENT CONFIGURATION | ACCESS CONTROL CONFIGURATION | AGENT FENCING | RECONFIGURING PMCD | STARTING AND STOPPING PMCD | CAVEATS | DIAGNOSTICS | FILES | ENVIRONMENT | PCP ENVIRONMENT | SEE ALSO | COLOPHON

PMCD(1)                  General Commands Manual                 PMCD(1)

NAME         top

       pmcd - performance metrics collector daemon

SYNOPSIS         top

       pmcd [-AfQSv?]  [-c config] [-H hostname] [-i ipaddress] [-l
       logfile] [-L bytes] [-[n|N] pmnsfile] [-p port[,port ...]]  [-q
       timeout] [-s sockname] [-t timeout] [-T traceflag] [-U username]
       [-x file]

DESCRIPTION         top

       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         top

       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.

       -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.

       -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 port, --port=port
            Specify port to listen on.  By default port 44321 is used.

       -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 three seconds, but the -q option allows
            an alternative timeout interval (which must be greater than
            zero) to be specified.  The unit of timeout is seconds.
            Alternatively, if -q is not used, the PMCD_CREDS_TIMEOUT
            environment valriable may be used to define the timeout
            interval.

       -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, --reqauth
            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         top

       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         top

       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         top

       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         top

       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         top

       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         top

       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         top

       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         top

       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         top

       $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
            Environment variables that will be set when pmcd executes.
            Only settings of the form "PMCD_VARIABLE=value" or
            "PCP_VARIABLE=value" are honoured.

       $PCP_SYSCONF_DIR/labels.conf
            settings related to labels used globally throughout the
            PMCS.

       $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 metrics.

       $PCP_SYSCONF_DIR/labels/optional
            directory of files containing the global metric labels that
            will be set for every client context created by pmcd, but
            which are flagged as optional.  These labels are exactly the
            same as other context labels except that they are not used
            in time series identifier calculations.

       ./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/pcp/tls.conf
            OpenSSL certificate configuration information file, used for
            optional Secure Socket Layer connections.

       /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         top

       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         top

       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         top

       PCPIntro(1), pmdbg(1), pmerr(1), pmgenmap(1), pminfo(1),
       pmrep(1), pmstat(1), pmstore(1), pmval(1), getpwent(3),
       getgrent(3), labels.conf(5), pcp.conf(5), pcp.env(5) and PMNS(5).

COLOPHON         top

       This page is part of the PCP (Performance Co-Pilot) project.
       Information about the project can be found at 
       ⟨http://www.pcp.io/⟩.  If you have a bug report for this manual
       page, send it to pcp@groups.io.  This page was obtained from the
       project's upstream Git repository
       ⟨https://github.com/performancecopilot/pcp.git⟩ on 2023-12-22.
       (At that time, the date of the most recent commit that was found
       in the repository was 2023-12-16.)  If you discover any rendering
       problems in this HTML version of the page, or you believe there
       is a better or more up-to-date source for the page, or you have
       corrections or improvements to the information in this COLOPHON
       (which is not part of the original manual page), send a mail to
       man-pages@man7.org

Performance Co-Pilot               PCP                           PMCD(1)

Pages that refer to this page: dbpmda(1)dbprobe(1)genpmda(1)pcp(1)pcp2elasticsearch(1)pcp2graphite(1)pcp2influxdb(1)pcp2json(1)pcp2spark(1)pcp2template(1)pcp2xlsx(1)pcp2xml(1)pcp2zabbix(1)pcp-atopsar(1)pcpcompat(1)pcp-dstat(1)pcp-geolocate(1)pcpintro(1)pcp-iostat(1)pcp-kube-pods(1)pcp-tapestat(1)pmcd_wait(1)pmchart(1)pmclient(1)pmdaactivemq(1)pmdaapache(1)pmdabash(1)pmdabcc(1)pmdabind2(1)pmdabonding(1)pmdabpf(1)pmdabpftrace(1)pmdacifs(1)pmdacisco(1)pmdadbping(1)pmdadenki(1)pmdadm(1)pmdadocker(1)pmdads389(1)pmdads389log(1)pmdaelasticsearch(1)pmdafarm(1)pmdagfs2(1)pmdagluster(1)pmdagpfs(1)pmdahacluster(1)pmdahaproxy(1)pmdaib(1)pmdajbd2(1)pmdajson(1)pmdakernel(1)pmdakvm(1)pmdalibvirt(1)pmdalio(1)pmdalmsensors(1)pmdalogger(1)pmdalustre(1)pmdalustrecomm(1)pmdamailq(1)pmdamemcache(1)pmdamic(1)pmdammv(1)pmdamongodb(1)pmdamounts(1)pmdamssql(1)pmdamysql(1)pmdanetcheck(1)pmdanetfilter(1)pmdanfsclient(1)pmdanginx(1)pmdanutcracker(1)pmdanvidia(1)pmdaopenmetrics(1)pmdaopenvswitch(1)pmdaoracle(1)pmdaoverhead(1)pmdaperfevent(1)pmdapipe(1)pmdapodman(1)pmdapostfix(1)pmdapostgresql(1)pmdaproc(1)pmdarabbitmq(1)pmdaredis(1)pmdaresctrl(1)pmdaroomtemp(1)pmdaroot(1)pmdarsyslog(1)pmdasample(1)pmdasendmail(1)pmdashping(1)pmdasimple(1)pmdaslurm(1)pmdasmart(1)pmdasockets(1)pmdastatsd(1)pmdasummary(1)pmdasystemd(1)pmdatrace(1)pmdatrivial(1)pmdatxmon(1)pmdaunbound(1)pmdaweblog(1)pmdaxfs(1)pmdazfs(1)pmdazimbra(1)pmdazswap(1)pmdumptext(1)pmfind(1)pmfind_check(1)pmie(1)pminfo(1)pmlc(1)pmlogconf(1)pmlogctl(1)pmlogextract(1)pmlogger(1)pmlogpaste(1)pmprobe(1)pmproxy(1)pmrep(1)pmrepconf(1)pmseries(1)pmsocks(1)pmstat(1)pmstore(1)pmtrace(1)pmval(1)pmview(1)logimport(3)pcpintro(3)pmapi(3)__pmconnectlogger(3)pmda(3)pmdaconnect(3)pmdadso(3)pmdafetch(3)pmdainit(3)pmdamain(3)pmdaopenlog(3)pmdaprofile(3)pmdarootconnect(3)pmdasenderror(3)pmdatrace(3)pmdestroycontext(3)pmdiscoverservices(3)pmdupcontext(3)pmfetch(3)pmgetoptions(3)__pmlocalpmda(3)pmlookuplabels(3)pmnewcontext(3)pmparsehostattrsspec(3)pmparsehostspec(3)pmreconnectcontext(3)pmrecord(3)pmspeclocalpmda(3)pmtrimnamespace(3)pmusecontext(3)pmwebapi(3)pmwhichcontext(3)labels.conf(5)pmlogger.control(5)pmns(5)