1PMCD(1) General Commands Manual PMCD(1)
2
6 pmcd - performance metrics collector daemon
7
9 pmcd [-f] [-i ipaddress] [-l logfile] [-L bytes] [-n pmnsfile] [-p
10 port[,port ...] [-q timeout] [-T traceflag] [-t timeout] [-x file]
11
13 pmcd is the collector used by the Performance Co-Pilot (see PCPIn‐
14 tro(1)) to gather performance metrics on a system. As a rule, there
15 must be an instance of pmcd running on a system for any performance
16 metrics to be available to the PCP.
17 pmcd accepts connections from client applications running either on the
19 same machine or remotely and provides them with metrics and other
20 related information from the machine that pmcd is executing on. pmcd
21 delegates most of this request servicing to a collection of Performance
22 Metrics Domain Agents (or just agents), where each agent is responsible
23 for a particular group of metrics, known as the domain of the agent.
24 For example the environ agent is responsible for reporting information
25 relating to the environment of a Challenge system, such as the cabinet
26 temperature and voltage levels of the power supply.
27 The agents may be processes started by pmcd, independent processes or
29 Dynamic Shared Objects (DSOs, see dso(5)) attached to pmcd's address
30 space. The configuration section below describes how connections to
31 agents are specified.
32 The options to pmcd are as follows.
34 -f By default pmcd is started as a daemon. The -f option indicates
36 that it should run in the foreground. This is most useful when
37 trying to diagnose problems with misbehaving agents.
38 -i ipaddress
40 This option is usually only used on hosts with more than one
41 network interface. If no -i options are specified pmcd accepts
42 connections made to any of its host's IP (Internet Protocol)
43 addresses. The -i option is used to specify explicitly an IP
44 address that connections should be accepted on. ipaddress
45 should be in the standard dotted form (e.g. 100.23.45.6). The
46 -i option may be used multiple times to define a list of IP
47 addresses. Connections made to any other IP addresses the host
48 has will be refused. This can be used to limit connections to
49 one network interface if the host is a network gateway. It is
50 also useful if the host takes over the IP address of another
51 host that has failed. In such a situation only the standard IP
52 addresses of the host should be given (not the ones inherited
53 from the failed host). This allows PCP applications to deter‐
54 mine that a host has failed, rather than connecting to the host
55 that has assumed the identity of the failed host.
56 -l logfile
58 By default a log file named pmcd.log is written in the directory
59 $PCP_LOG_DIR/pmcd. The -l option causes the log file to be
60 written to logfile instead of the default. If the log file can‐
61 not be created or is not writable, output is written to the
62 standard error instead.
63 -L bytes
65 PDUs received by pmcd from monitoring clients are restricted to
66 a maximum size of 65536 bytes by default to defend against
67 Denial of Service attacks. The -L option may be used to change
68 the maximum incoming PDU size.
69 -n pmnsfile
71 Normally pmcd loads the default Performance Metrics Name Space
72 (PMNS) from $PCP_VAR_DIR/pmns/root, however if the -n option is
73 specified an alternative namespace is loaded from the file pmns‐
74 file.
75 -q timeout
77 The pmcd to agent version exchange protocol (new in PCP 2.0 -
78 introduced to provide backward compatibility) uses this timeout
79 to specify how long pmcd should wait before assuming that no
80 version response is coming from an agent. If this timeout is
81 reached, the agent is assumed to be an agent which does not
82 understand the PCP 2.0 protocol. The default timeout interval
83 is five seconds, but the -q option allows an alternative timeout
84 interval (which must be greater than zero) to be specified. The
85 unit of time is seconds.
86 -t timeout
88 To prevent misbehaving agents from hanging the entire Perfor‐
89 mance Metrics Collection System (PMCS), pmcd uses timeouts on
90 PDU exchanges with agents running as processes. By default the
91 timeout interval is five seconds. The -t option allows an
92 alternative timeout interval in seconds to be specified. If
93 timeout is zero, timeouts are turned off. It is almost impossi‐
94 ble to use the debugger interactively on an agent unless time‐
95 outs have been turned off for its "parent" pmcd.
96 Once pmcd is running, the timeout may be dynamically modified by
98 storing an integer value (the timeout in seconds) into the met‐
99 ric pmcd.control.timeout via pmstore(1).
100 -T traceflag
102 To assist with error diagnosis for agents and/or clients of pmcd
103 that are not behaving correctly, an internal event tracing mech‐
104 anism is supported within pmcd. The value of traceflag is
105 interpreted as a bit field with the following control functions:
106 1 enable client connection tracing
108 2 enable PDU tracing
109 256 unbuffered event tracing
110 By default, event tracing is buffered using a circular buffer
112 that is over-written as new events are recorded. The default
113 buffer size holds the last 20 events, although this number may
114 be over-ridden by using pmstore(1) to modify the metric
115 pmcd.control.tracebufs.
116 Similarly once pmcd is running, the event tracing control may be
118 dynamically modified by storing 1 (enable) or 0 (disable) into
119 the metrics pmcd.control.traceconn, pmcd.control.tracepdu and
120 pmcd.control.tracenobuf. These metrics map to the bit fields
121 associated with the traceflag argument for the -T option.
122 When operating in buffered mode, the event trace buffer will be
124 dumped whenever an agent connection is terminated by pmcd, or
125 when any value is stored into the metric pmcd.control.dumptrace
126 via pmstore(1).
127 In unbuffered mode, every event will be reported when it occurs.
129 -x file
131 Before the pmcd logfile can be opened, pmcd may encounter a
132 fatal error which prevents it from starting. By default, the
133 output describing this error is sent to /dev/tty but it may
134 redirected to file.
135 If a PDU exchange with an agent times out, the agent has violated the
137 requirement that it delivers metrics with little or no delay. This is
138 deemed a protocol failure and the agent is disconnected from pmcd. Any
139 subsequent requests for information from the agent will fail with a
140 status indicating that there is no agent to provide it.
141 It is possible to specify host-level access control to pmcd. This
143 allows one to prevent users from certain hosts from accessing the met‐
144 rics provided by pmcd and is described in more detail in the Section on
145 ACCESS CONTROL below.
146
148 On startup pmcd looks for a configuration file named $PCP_PMCD‐
149 CONF_PATH. This file specifies which agents cover which performance
150 metrics domains and how pmcd should make contact with the agents. An
151 optional section specifying host-based access controls may follow the
152 agent configuration data.
153 Warning: pmcd is usually started as part of the boot sequence and runs
155 as root. The configuration file may contain shell commands to create
156 agents, which will be executed by root. To prevent security breaches
157 the configuration file should be writable only by root. The use of
158 absolute path names is also recommended.
159 The case of the reserved words in the configuration file is unimpor‐
161 tant, but elsewhere, the case is preserved.
162 Blank lines and comments are permitted (even encouraged) in the config‐
164 uration file. A comment begins with a ``#'' character and finishes at
165 the end of the line. A line may be continued by ensuring that the last
166 character on the line is a ``\'' (backslash). A comment on a continued
167 line ends at the end of the continued line. Spaces may be included in
168 lexical elements by enclosing the entire element in double quotes
169 (there must be whitespace before the opening and after the closing
170 quote). A double quote preceded by a backslash is always a literal
171 double quote. A ``#'' in double quotes or preceded by a backslash is
172 treated literally rather than as a comment delimiter. Lexical elements
173 and separators are described further in the following sections.
174
176 Each line of the agent configuration section of the configuration file
177 contains details of how to connect pmcd to one of its agents and speci‐
178 fies which metrics domain the agent deals with. An agent may be
179 attached as a DSO, or via a socket, or a pair of pipes.
180 Each line of the agent configuration section of the configuration file
182 must be either an agent specification, a comment, or a blank line.
183 Lexical elements are separated by whitespace characters, however a sin‐
184 gle agent specification may not be broken across lines unless a \
185 (backslash) is used to continue the line.
186 Each agent specification must start with a textual label (string) fol‐
188 lowed by an integer in the range 1 to 510. The label is a tag used to
189 refer to the agent and the integer specifies the domain for which the
190 agent supplies data. This domain identifier corresponds to the domain
191 portion of the PMIDs handled by the agent. Each agent must have a
192 unique label and domain identifier.
193 For DSO agents a line of the form:
195 label domain-no dso entry-point path
197 should appear. Where,
199 label is a string identifying the agent
201 domain-no is an unsigned integer specifying the agent's domain in
202 the range 1 to 510
203 entry-point is the name of an initialization function which will be
204 called when the DSO is loaded
205 path designates the location of the DSO. This field is treated
206 differently on Irix and on Linux. Later expects it to be
207 an absolute pathname, while former uses some heuristics
208 to find an agent. If path begins with a / it is taken as
209 an absolute path specifying the DSO. If path is relative,
210 pmcd will expect to find the agent in a file with the
211 name mips_simabi.path, where simabi is either o32, n32 or
212 64. pmcd is only able to load DSO agents that have the
213 same simabi (Subprogram Interface Model ABI, or calling
214 conventions) as it does (i.e. only one of the simabi ver‐
215 sions will be applicable). The simabi version of a run‐
216 ning pmcd may be determined by fetching pmcd.simabi.
217 Alternatively, the file(1) command may be used to deter‐
218 mine the simabi version from the pmcd executable.
219 For a relative path the environment variable PMCD_PATH
221 defines a colon (:) separated list of directories to
222 search when trying to locate the agent DSO. The default
223 search path is $PCP_SHARE_DIR/lib:/usr/pcp/lib.
224 For agents providing socket connections, a line of the form
226 label domain-no socket addr-family address [ command ]
228 should appear. Where,
230 label is a string identifying the agent
232 domain-no is an unsigned integer specifying the agent's domain in
233 the range 1 to 510
234 addr-family designates whether the socket is in the AF_INET or
235 AF_UNIX domain, and the corresponding values for this
236 parameter are inet and unix respectively.
237 address specifies the address of the socket within the previously
238 specified addr-family. For unix sockets, the address
239 should be the name of an agent's socket on the local host
240 (a valid address for the UNIX domain). For inet sockets,
241 the address may be either a port number or a port name
242 which may be used to connect to an agent on the local
243 host. There is no syntax for specifying an agent on a
244 remote host as a pmcd deals only with agents on the same
245 machine.
246 command is an optional parameter used to specify a command line
247 to start the agent when pmcd initializes. If command is
248 not present, pmcd assumes that the specified agent has
249 already been created. The command is considered to start
250 from the first non-white character after the socket
251 address and finish at the next newline that isn't pre‐
252 ceded by a backslash. After a fork(2) the command is
253 passed unmodified to execve(2) to instantiate the agent.
254 For agents interacting with the pmcd via stdin/stdout, a line of the
256 form:
257 label domain-no pipe protocol command
259 should appear. Where,
261 label is a string identifying the agent
263 domain-no is an unsigned integer specifying the agent's domain
264 protocol The value for this parameter should be binary.
265 Additionally, the protocol can include the notready key‐
267 word to indicate that the agent must be marked as not
268 being ready to process requests from pmcd. The agent will
269 explictily notify the pmcd when it is ready to process
270 the requests by sending PM_ERR_PMDAREADY PDU.
271 command specifies a command line to start the agent when pmcd
273 initializes. Note that command is mandatory for pipe-
274 based agents. The command is considered to start from
275 the first non-white character after the protocol parame‐
276 ter and finish at the next newline that isn't preceded by
277 a backslash. After a fork(2) the command is passed
278 unmodified to execve(2) to instantiate the agent.
279
281 The access control section of the configuration file is optional, but
282 if present it must follow the agent configuration data. The case of
283 reserved words is ignored, but elsewhere case is preserved. Lexical
284 elements in the access control section are separated by whitespace or
285 the special delimiter characters: square brackets (``['' and ``]''),
286 braces (``{'' and ``}''), colon (``:''), semicolon (``;'') and comma
287 (``,''). The special characters are not treated as special in the
288 agent configuration section.
289 The access control section of the file must start with a line of the
291 form:
292 [access]
294 Leading and trailing whitespace may appear around and within the brack‐
296 ets and the case of the access keyword is ignored. No other text may
297 appear on the line except a trailing comment.
298 Following this line, the remainder of the configuration file should
300 contain lines that allow or disallow operations from particular hosts
301 or groups of hosts.
302 There are two kinds of operations that occur via pmcd:
304 fetch allows retrieval of information from pmcd. This may be
306 information about a metric (e.g. its description,
307 instance domain or help text) or a value for a metric.
308 store allows pmcd to be used to store metric values in agents
310 that permit store operations.
311 Access to pmcd is granted at the host level, i.e. all users on a host
313 are granted the same level of access. Permission to perform the store
314 operation should not be given indiscriminately; it has the potential to
315 be abused by malicious users.
316 Hosts may be identified by name, IP address or a wildcarded IP address
318 with the single wildcard character ``*'' as the last-given component of
319 the IP address. Host names may not be wildcarded. The following are
320 all valid host identifiers:
321 boing
323 localhost
324 giggle.melbourne.sgi.com
325 129.127.112.2
326 129.127.114.*
327 129.*
328 *
329 The following are not valid host identifiers:
331 *.melbourne
333 129.127.*.*
334 129.*.114.9
335 129.127*
336 The first example is not allowed because only (numeric) IP addresses
338 may contain a wildcard. The second example is not valid because there
339 is more than one wildcard character. The third contains an embedded
340 wildcard, the fourth has a wildcard character that is not the last com‐
341 ponent of the IP address (the last component is 127*).
342 The name localhost is given special treatment to make the behavior of
344 host wildcarding consistent. Rather than being 127.0.0.1, it is mapped
345 to the primary IP address associated with the name of the host on which
346 pmcd is running. Beware of this when running pmcd on multi-homed
347 hosts.
348 Access for hosts are allowed or disallowed by specifying statements of
350 the form:
351 allow hostlist : operations ;
353 disallow hostlist : operations ;
354 hostlist is a comma separated list of host identifiers.
356 operations is a comma separated list of the operation types
358 described above, all (which allows/disallows all opera‐
359 tions), or all except operations (which allows/disallows
360 all operations except those listed).
361 Where no specific allow or disallow statement applies to an operation
363 for some host, the default is to allow the operation from that host.
364 In the trivial case when there is no access control section in the con‐
365 figuration file, all operations from all hosts are permitted.
366 If a new connection to pmcd is attempted from a host that is not per‐
368 mitted to perform any operations, the connection will be closed immedi‐
369 ately after an error response PM_ERR_PERMISSION has been sent to the
370 client attempting the connection.
371 Statements with the same level of wildcarding specifying identical
373 hosts may not contradict each other. For example if a host named clank
374 had an IP address of 129.127.112.2, specifying the following two rules
375 would be erroneous:
376 allow clank : fetch, store;
378 disallow 129.127.112.2 : all except fetch;
379 because they both refer to the same host, but disagree as to whether
381 the fetch operation is permitted from that host.
382 Statements containing more specific host specifications override less
384 specific ones according to the level of wildcarding. For example a
385 rule of the form
386 allow clank : all;
388 overrides
390 disallow 129.127.112.* : all except fetch;
392 because the former contains a specific host name (equivalent to a fully
394 specified IP address), whereas the latter has a wildcard. In turn, the
395 latter would override
396 disallow * : all;
398 It is possible to limit the number of connections from a host to pmcd.
400 This may be done by adding a clause of the form
401 maximum n connections
403 to the operations list of an allow statement. Such a clause may not be
405 used in a disallow statement. Here, n is the maximum number of connec‐
406 tions that will be accepted from hosts matching the host identifier(s)
407 used in the statement.
408 An access control statement with a list of host identifiers is equiva‐
410 lent to a group of access control statements, with each specifying one
411 of the host identifiers in the list and all with the same access con‐
412 trols (both permissions and connection limits). A wildcard should be
413 used if you want hosts to contribute to a shared connection limit.
414 When a new client requests a connection, and pmcd has determined that
416 the client has permission to connect, it searches the matching list of
417 access control statements for the most specific match containing a con‐
418 nection limit. For brevity, this will be called the limiting state‐
419 ment. If there is no limiting statement, the client is granted a con‐
420 nection. If there is a limiting statement and the number of pmcd
421 clients with IP addresses that match the host identifier in the limit‐
422 ing statement is less than the connection limit in the statement, the
423 connection is allowed. Otherwise the connection limit has been reached
424 and the client is refused a connection.
425 The wildcarding in host identifiers means that once pmcd actually
427 accepts a connection from a client, the connection may contribute to
428 the current connection count of more than one access control statement
429 (the client's host may match more than one access control statement).
430 This may be significant for subsequent connection requests.
431 Note that because most specific match semantics are used when checking
433 the connection limit, priority is given to clients with more specific
434 host identifiers. It is also possible to exceed connection limits in
435 some situations. Consider the following:
436 allow clank : all, maximum 5 connections;
438 allow * : all except store, maximum 2 connections;
439 This says that only 2 client connections at a time are permitted for
441 all hosts other than "clank", which is permitted 5. If a client from
442 host "boing" is the first to connect to pmcd, its connection is checked
443 against the second statement (that is the most specific match with a
444 connection limit). As there are no other clients, the connection is
445 accepted and contributes towards the limit for only the second state‐
446 ment above. If the next client connects from "clank", its connection
447 is checked against the limit for the first statement. There are no
448 other connections from "clank", so the connection is accepted. Once
449 this connection is accepted, it counts towards both statements' limits
450 because "clank" matches the host identifier in both statements. Remem‐
451 ber that the decision to accept a new connection is made using only the
452 most specific matching access control statement with a connection
453 limit. Now, the connection limit for the second statement has been
454 reached. Any connections from hosts other than "clank" will be
455 refused.
456 If instead, pmcd with no clients saw three successive connections
458 arrived from "boing", the first two would be accepted and the third
459 refused. After that, if a connection was requested from "clank" it
460 would be accepted. It matches the first statement, which is more spe‐
461 cific than the second, so the connection limit in the first is used to
462 determine that the client has the right to connect. Now there are 3
463 connections contributing to the second statement's connection limit.
464 Even though the connection limit for the second statement has been
465 exceeded, the earlier connections from "boing" are maintained. The
466 connection limit is only checked at the time a client attempts a con‐
467 nection rather than being re-evaluated every time a new client connects
468 to pmcd.
469 This gentle scheme is designed to allow reasonable limits to be imposed
471 on a first come first served basis, with specific exceptions.
472 As illustrated by the example above, a client's connection is honored
474 once it has been accepted. However, pmcd reconfiguration (see the next
475 section) re-evaluates all the connection counts and will cause client
476 connections to be dropped where connection limits have been exceeded.
477
479 If the configuration file has been changed or if an agent is not
480 responding because it has terminated or the PMNS has been changed, pmcd
481 may be reconfigured by sending it a SIGHUP, as in
482 # pmsignal -a -s HUP pmcd
484 When pmcd receives a SIGHUP, it checks the configuration file for
486 changes. If the file has been modified, it is reparsed and the con‐
487 tents become the new configuration. If there are errors in the config‐
488 uration file, the existing configuration is retained and the contents
489 of the file are ignored. Errors are reported in the pmcd log file.
490 It also checks the PMNS file for changes. If the PMNS file has been
492 modified, then it is reloaded. Use of tail(1) on the log file is rec‐
493 ommended while reconfiguring pmcd.
494 If the configuration for an agent has changed (any parameter except the
496 agent's label is different), the agent is restarted. Agents whose con‐
497 figurations do not change are not restarted. Any existing agents not
498 present in the new configuration are terminated. Any deceased agents
499 are that are still listed are restarted.
500 Sometimes it is necessary to restart an agent that is still running,
502 but malfunctioning. Simply stop the agent (e.g. using SIGTERM from
503 pmsignal(1)), then send pmcd a SIGHUP, which will cause the agent to be
504 restarted.
505
507 Normally, pmcd is started automatically at boot time and stopped when
508 the system is being brought down (see rc2(1M) and rc0(1M)). Under cer‐
509 tain circumstances it is necessary to start or stop pmcd manually. To
510 do this one must become superuser and type
511 # $PCP_RC_DIR/pcp start
513 to start pmcd, or
515 # $PCP_RC_DIR/pcp stop
517 to stop pmcd. Starting pmcd when it is already running is the same as
519 stopping it and then starting it again.
520 Sometimes it may be necessary to restart pmcd during another phase of
522 the boot process. Time-consuming parts of the boot process are often
523 put into the background to allow the system to become available sooner
524 (e.g. mounting huge databases). If an agent run by pmcd requires such
525 a task to complete before it can run properly, it is necessary to
526 restart or reconfigure pmcd after the task completes. Consider, for
527 example, the case of mounting a database in the background while boot‐
528 ing. If the PMDA which provides the metrics about the database cannot
529 function until the database is mounted and available but pmcd is
530 started before the database is ready, the PMDA will fail (however pmcd
531 will still service requests for metrics from other domains). If the
532 database is initialized by running a shell script, adding a line to the
533 end of the script to reconfigure pmcd (by sending it a SIGHUP) will
534 restart the PMDA (if it exited because it couldn't connect to the data‐
535 base). If the PMDA didn't exit in such a situation it would be neces‐
536 sary to restart pmcd because if the PMDA was still running pmcd would
537 not restart it.
538 Normally pmcd listens for client connections on one or more well-known
540 TCP/IP port numbers (historically 4321 and more recently the officially
541 registered port 44321; in the current release, pmcd listens on only
542 port 44321 by default). Either the environment variable PMCD_PORT or
543 the -p command line option may be used to specify alternative port num‐
544 ber(s) when pmcd is started; in each case, the specficiation is a
545 comma-separated list of one or more numerical port numbers. Should
546 both methods be used or multiple -p options appear on the command line,
547 pmcd will listen on the union of the set of ports specified via all -p
548 options and the PMCD_PORT environment variable. If non-default ports
549 are used with pmcd care should be taken to ensure that PMCD_PORT is
550 also set in the environment of any client application that will connect
551 to pmcd.
552
554 $PCP_PMCDCONF_PATH
555 default configuration file
556 $PCP_PMCDOPTIONS_PATH
557 command line options to pmcd when launched from
558 $PCP_RC_DIR/pcp All the command line option lines should
559 start with a hyphen as the first character. This file can
560 also contain environment variable settings of the form "VARI‐
561 ABLE=value".
562 ./pmcd.log
563 (or $PCP_LOG_DIR/pmcd/pmcd.log when started automatically)
564 $PCP_RUN_DIR/pmcd.pid
565 contains an ascii decimal representation of the process ID of
566 pmcd , when it's running.
567 All messages and diagnostics are directed here
568
570 In addition to the PCP environment variables described in the PCP ENVI‐
571 RONMENT section below, the PMCD_PORT variable is also recognised as the
572 TCP/IP port for incoming connections (default 44321).
573
575 Environment variables with the prefix PCP_ are used to parameterize the
576 file and directory names used by PCP. On each installation, the file
577 /etc/pcp.conf contains the local values for these variables. The
578 $PCP_CONF variable may be used to specify an alternative configuration
579 file, as described in pcp.conf(4).
580
582 PCPIntro(1), pmdbg(1), pmerr(1), pmgenmap(1), pminfo(1), pmstat(1),
583 pmstore(1), pmval(1), pcp.conf(4), and pcp.env(4).
584
586 If pmcd is already running the message "Error: OpenRequestSocket bind:
587 Address may already be in use" will appear. This may also appear if
588 pmcd was shutdown with an outstanding request from a client. In this
589 case, a request socket has been left in the TIME_WAIT state and until
590 the system closes it down (after some timeout period) it will not be
591 possible to run pmcd.
592 In addition to the standard PCP debugging flags, see pmdbg(1), pmcd
594 currently uses DBG_TRACE_APPL0 for tracing I/O and termination of
595 agents, DBG_TRACE_APPL1 for tracing host access control (see below) and
596 DBG_TRACE_APPL2 for tracing the configuration file scanner and parser.
597
599 pmcd does not explicitly terminate its children (agents), it only
600 closes their pipes. If an agent never checks for a closed pipe it may
601 not terminate.
602 The configuration file parser will only read lines of less than 1200
604 characters. This is intended to prevent accidents with binary files.
605 The timeouts controlled by the -t option apply to IPC between pmcd and
607 the PMDAs it spawns. This is independent of settings of the environ‐
608 ment variables PMCD_CONNECT_TIMEOUT and PMCD_REQUEST_TIMEOUT (see
609 PCPIntro(1)) which may be used respectively to control timeouts for
610 client applications trying to connect to pmcd and trying to receive
611 information from pmcd.
612Performance Co-Pilot SGI PMCD(1)