---

   pmcd    ( 1 )

---

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.