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 environ agent is responsible for reporting information relating to the environment of a Challenge system, such as the cabinet temperature and voltage levels of the power supply.
The agents may be processes started by pmcd, independent processes or Dynamic Shared Objects (DSOs, see dso(5)) attached to pmcd's address space. The configuration section below describes how connections to agents are specified.
The options to pmcd are as follows.
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).
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.
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 host-level access control to pmcd. This allows one to prevent users from certain hosts from accessing the metrics provided by pmcd and is described in more detail in the Section on ACCESS CONTROL below.
Warning: pmcd is usually started as part of the boot sequence and runs 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 (there must be whitespace before the opening and after the closing quote). 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.
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:
should appear. Where,
For agents providing socket connections, a line of the form
should appear. Where,
For agents interacting with the pmcd via stdin/stdout, a line of the form:
should appear. Where,
The access control section of the file must start with a line of the form:
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:
Access to pmcd is granted at the host level, i.e. all users on a host are granted the same level of access. Permission to perform the store operation should not be given indiscriminately; it has the potential to be abused by malicious users.
Hosts may be identified by name, IP address or a wildcarded IP address with the single wildcard character ``*'' as the last-given component of the IP address. Host names 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.* *
The following are not valid host identifiers:
*.melbourne 129.127.*.* 129.*.114.9 129.127*
The first example is not allowed because only (numeric) IP addresses may contain a wildcard. The second example is not valid because there is more than one wildcard character. The third contains an embedded wildcard, the fourth has a wildcard character that is not the last component of the IP address (the last component is 127*).
The name localhost is given special treatment to make the behavior of host wildcarding consistent. Rather than being 127.0.0.1, it is mapped to the primary IP address associated with the name of the host on which pmcd is running. Beware of this when running pmcd on multi-homed hosts.
Access for hosts are allowed or disallowed by specifying statements of the form:
Where no specific allow or disallow statement applies to an operation for some host, the default is to allow the operation from that host. In the trivial case when there is no access control section in the configuration file, all operations from all hosts are permitted.
If a new connection to pmcd is attempted from a 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 clank : fetch, store; disallow 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 clank : all;
overrides
disallow 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 * : all;
It is possible to limit the number of connections from a host to pmcd. This may be done by adding a clause of the form
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 hosts matching the host identifier(s) used in the statement.
An access control statement with a list of host identifiers is equivalent to a group of access control statements, with each specifying one of the host identifiers in the list and all with the same access controls (both permissions and connection limits). 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 IP addresses that match the host 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.
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). This may be significant for subsequent connection requests.
Note that because most specific match semantics are used when checking the connection limit, priority is given to clients with more specific host identifiers. It is also possible to exceed connection limits in some situations. Consider the following:
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.
# 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.
# $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 one or more well-known TCP/IP port numbers (historically 4321 and more recently the officially registered port 44321; in the current release, pmcd listens on only port 44321 by default). 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 specficiation 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.
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 host access control (see below) and DBG_TRACE_APPL2 for tracing the configuration file scanner and parser.
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.