PMCD(1) | General Commands Manual | PMCD(1) |
NAME¶
pmcd - performance metrics collector daemonSYNOPSIS¶
pmcd [ -AfS] [ -c config] [ -C dirname] [ -H hostname] [ -i ipaddress] [ -l logfile] [ -L bytes] [ -[n|N] pmnsfile] [ -p port[,port ...] [ -P passfile] [ -q timeout] [ -s sockname] [ -T traceflag] [ -t timeout] [ -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 example 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. The options to pmcd are as follows.- -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
- 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
- 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
- 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
- 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
- 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
- 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
- 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
- Same function as -n, except for the handling of duplicate Performance Metric Identifiers (PMIDs) in pmnsfile - duplicates are allowed with -N they are not allowed with -n.
- -P 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.
- -S
- 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.
- -s 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.
- -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
- 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
- -U username
- 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.
- -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.
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
- 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.
- label domain-no socket addr-family address [ command ]
- 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.
- label domain-no pipe protocol command
- 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 PM_ERR_PMDAREADY PDU.
- 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]
- fetch
- allows retrieval of information from pmcd. This may be information about a metric (e.g. its description, instance domain or help text) or a value for a metric.
- 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.
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 ;
- 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).
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
- allow host clank : all, maximum 5 connections;
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 for changes. If the PMNS file has been modified, then it is 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 (see rc2(1M) and rc0(1M)). Under certain circumstances it is necessary to start or stop pmcd manually. To do this one must become superuser and type# $PCP_RC_DIR/pcp start
to start pmcd, or
# $PCP_RC_DIR/pcp 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).
FILES¶
- $PCP_PMCDCONF_PATH
- default configuration file
- $PCP_PMCDOPTIONS_PATH
- command line options to pmcd when launched from $PCP_RC_DIR/pcp All the command line option lines should start with a hyphen as the first character. This file can also contain environment variable settings of the form "VARIABLE=value".
- ./pmcd.log
- (or $PCP_LOG_DIR/pmcd/pmcd.log when started automatically)
- $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¶
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.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).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 DBG_TRACE_APPL0 for tracing I/O and termination of agents, DBG_TRACE_APPL1 for tracing access control and DBG_TRACE_APPL2 for tracing the configuration file scanner and parser.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.SEE ALSO¶
PCPIntro(1), pmdbg(1), pmerr(1), pmgenmap(1), pminfo(1), pmstat(1), pmstore(1), pmval(1), getpwent(3), getgrent(3), pcp.conf(5), and pcp.env(5).PCP | Performance Co-Pilot |