1PMCD(1) General Commands Manual PMCD(1)
2
6 pmcd - performance metrics collector daemon
7
9 pmcd [-AfQSv?] [-c config] [-C dirname] [-H hostname] [-i ipaddress]
10 [-l logfile] [-L bytes] [-M certname] [-[n|N] pmnsfile] [-p port[,port
11 ...]] [-P passfile] [-q timeout] [-s sockname] [-t timeout] [-T trace‐
12 flag] [-U username] [-x file]
13
15 pmcd is the collector used by the Performance Co-Pilot (see PCPIn‐
16 tro(1)) to gather performance metrics on a system. As a rule, there
17 must be an instance of pmcd running on a system for any performance
18 metrics to be available to the PCP.
19 pmcd accepts connections from client applications running either on the
21 same machine or remotely and provides them with metrics and other
22 related information from the machine that pmcd is executing on. pmcd
23 delegates most of this request servicing to a collection of Performance
24 Metrics Domain Agents (or just agents), where each agent is responsible
25 for a particular group of metrics, known as the domain of the agent.
26 For instance, the postgresql agent is responsible for reporting infor‐
27 mation relating to the PostgreSQL database, such as the transaction and
28 query counts, indexing and replication statistics, and so on.
29 The agents may be processes started by pmcd, independent processes or
31 Dynamic Shared Objects (DSOs, see dlopen(3)) attached to pmcd's address
32 space. The configuration section below describes how connections to
33 agents are specified.
34 Note that if a PDU exchange with an agent times out, the agent has vio‐
36 lated the requirement that it delivers metrics with little or no delay.
37 This is deemed a protocol failure and the agent is disconnected from
38 pmcd. Any subsequent requests for information from the agent will fail
39 with a status indicating that there is no agent to provide it.
40 It is possible to specify access control to pmcd based on users, groups
42 and hosts. This allows one to prevent users, groups of users, and cer‐
43 tain hosts from accessing the metrics provided by pmcd and is described
44 in more detail in the access control section below.
45
47 The available command line options are:
48 -A Disable service advertisement. By default, pmcd will advertise
50 its presence on the network using any available mechanisms (such
51 as Avahi/DNS-SD), assisting remote monitoring tools with finding
52 it. These mechanisms are disabled with this option.
53 -c config, --config=config
55 On startup pmcd uses a configuration file from either the
56 $PCP_PMCDCONF_PATH, configuration variable in /etc/pcp.conf, or an
57 environment variable of the same name. However, these values may
58 be overridden with config using this option. The format of this
59 configuration file is described below.
60 -C dirname, --certdb=dirname
62 Specify the path to the Network Security Services certificate
63 database, for (optional) secure connections. The default is
64 /etc/pki/nssdb. Refer also to the -P option. If it does not
65 already exist, this database can be created using the certutil
66 utility. This process and other certificate database maintenance
67 information is provided in the PCPIntro(1) manual page and the
68 online PCP tutorials.
69 -f, --foreground
71 By default pmcd is started as a daemon. The -f option indicates
72 that it should run in the foreground. This is most useful when
73 trying to diagnose problems with misbehaving agents.
74 -H hostname, --hostname=hostname
76 This option can be used to set the hostname that pmcd will use to
77 represent this instance of itself. This is used by client tools
78 like pmlogger(1) when reporting on the (possibly remote) host. If
79 this option is not set, the pmcd.hostname metric will match that
80 returned by pmhostname(1). Refer to the manual page for that tool
81 for full details on how the hostname is evaluated.
82 -i ipaddress, --interface=ipaddress
84 This option is usually only used on hosts with more than one net‐
85 work interface. If no -i options are specified pmcd accepts con‐
86 nections made to any of its host's IP (Internet Protocol)
87 addresses. The -i option is used to specify explicitly an IP
88 address that connections should be accepted on. ipaddress should
89 be in the standard dotted form (e.g. 100.23.45.6). The -i option
90 may be used multiple times to define a list of IP addresses. Con‐
91 nections made to any other IP addresses the host has will be
92 refused. This can be used to limit connections to one network
93 interface if the host is a network gateway. It is also useful if
94 the host takes over the IP address of another host that has
95 failed. In such a situation only the standard IP addresses of the
96 host should be given (not the ones inherited from the failed
97 host). This allows PCP applications to determine that a host has
98 failed, rather than connecting to the host that has assumed the
99 identity of the failed host.
100 -l logfile, --log=logfile
102 By default a log file named pmcd.log is written in the directory
103 $PCP_LOG_DIR/pmcd. The -l option causes the log file to be writ‐
104 ten to logfile instead of the default. If the log file cannot be
105 created or is not writable, output is written to the standard
106 error instead.
107 -L bytes
109 PDUs received by pmcd from monitoring clients are restricted to a
110 maximum size of 65536 bytes by default to defend against Denial of
111 Service attacks. The -L option may be used to change the maximum
112 incoming PDU size.
113 -M certname, --certname=certname
115 By default, pmcd will try to use a certificate called PCP Collec‐
116 tor certificate. The -M option allows this to be changed.
117 -n pmnsfile, --namespace=pmnsfile
119 Normally pmcd loads the default Performance Metrics Name Space
120 (PMNS) from $PCP_VAR_DIR/pmns/root, however if the -n option is
121 specified an alternative namespace is loaded from the file pmns‐
122 file.
123 -N pmnsfile, --uniqnames=pmnsfile
125 Same function as -n, except for the handling of duplicate Perfor‐
126 mance Metric Identifiers (PMIDs) in pmnsfile - duplicate names are
127 allowed with -n but they are not allowed with -N.
128 -P passfile, --passfile=passfile
130 Specify the path to a file containing the Network Security Ser‐
131 vices certificate database password for (optional) secure connec‐
132 tions, and for databases that are password protected. Refer also
133 to the -C option. When using this option, great care should be
134 exercised to ensure appropriate ownership ("pcp" user, typically)
135 and permissions on this file (0400, so as to be unreadable by any
136 user other than the user running the pmcd process).
137 -q timeout
139 The pmcd to agent version exchange protocol (new in PCP 2.0 -
140 introduced to provide backward compatibility) uses this timeout to
141 specify how long pmcd should wait before assuming that no version
142 response is coming from an agent. If this timeout is reached, the
143 agent is assumed to be an agent which does not understand the PCP
144 2.0 protocol. The default timeout interval is five seconds, but
145 the -q option allows an alternative timeout interval (which must
146 be greater than zero) to be specified. The unit of time is sec‐
147 onds.
148 -Q, --remotecert
150 Require that all remote client connections provide a certficate.
151 -s sockname, --socket=sockname
153 Specify the path to a local unix domain socket (for platforms sup‐
154 porting this socket family only). The default value is
155 $PCP_RUN_DIR/pmcd.socket.
156 -S, --allcert
158 Require that all client connections provide user credentials.
159 This means that only unix domain sockets, or authenticated connec‐
160 tions are permitted (requires secure sockets support). If any
161 user or group access control requirements are specified in the
162 pmcd configuration file, then this mode of operation is automati‐
163 cally entered, whether the -S flag is specified or not.
164 -t timeout
166 To prevent misbehaving clients or agents from hanging the entire
167 Performance Metrics Collection System (PMCS), pmcd uses timeouts
168 on PDU exchanges with clients and agents running as processes. By
169 default the timeout interval is five seconds. The -t option
170 allows an alternative timeout interval in seconds to be specified.
171 If timeout is zero, timeouts are turned off. It is almost impos‐
172 sible to use the debugger interactively on an agent unless time‐
173 outs have been turned off for its "parent" pmcd.
174 Once pmcd is running, the timeout may be dynamically modified by
176 storing an integer value (the timeout in seconds) into the metric
177 pmcd.control.timeout via pmstore(1).
178 -T traceflag, --trace=traceflag
180 To assist with error diagnosis for agents and/or clients of pmcd
181 that are not behaving correctly, an internal event tracing mecha‐
182 nism is supported within pmcd. The value of traceflag is inter‐
183 preted as a bit field with the following control functions:
184 1 enable client connection tracing
186 2 enable PDU tracing
187 256 unbuffered event tracing
188 By default, event tracing is buffered using a circular buffer that
190 is over-written as new events are recorded. The default buffer
191 size holds the last 20 events, although this number may be over-
192 ridden by using pmstore(1) to modify the metric pmcd.con‐
193 trol.tracebufs.
194 Similarly once pmcd is running, the event tracing control may be
196 dynamically modified by storing 1 (enable) or 0 (disable) into the
197 metrics pmcd.control.traceconn, pmcd.control.tracepdu and
198 pmcd.control.tracenobuf. These metrics map to the bit fields
199 associated with the traceflag argument for the -T option.
200 When operating in buffered mode, the event trace buffer will be
202 dumped whenever an agent connection is terminated by pmcd, or when
203 any value is stored into the metric pmcd.control.dumptrace via
204 pmstore(1).
205 In unbuffered mode, every event will be reported when it occurs.
207 -U username, --username=USER
209 User account under which to run pmcd. The default is the unprivi‐
210 leged "pcp" account in current versions of PCP, but in older ver‐
211 sions the superuser account ("root") was used by default.
212 -v, --verify
214 Verify the pmcd configuration file, reporting on any errors then
215 exiting with a status indicating verification success or failure.
216 -x file
218 Before the pmcd logfile can be opened, pmcd may encounter a fatal
219 error which prevents it from starting. By default, the output
220 describing this error is sent to /dev/tty but it may redirected to
221 file.
222 -?, --help
224 Display usage message and exit.
225
227 On startup pmcd looks for a configuration file named $PCP_PMCD‐
228 CONF_PATH. This file specifies which agents cover which performance
229 metrics domains and how pmcd should make contact with the agents. An
230 optional section specifying access controls may follow the agent con‐
231 figuration data.
232 Warning: pmcd is usually started as part of the boot sequence and runs
234 initially as root. The configuration file may contain shell commands
235 to create agents, which will be executed by root. To prevent security
236 breaches the configuration file should be writable only by root. The
237 use of absolute path names is also recommended.
238 The case of the reserved words in the configuration file is unimpor‐
240 tant, but elsewhere, the case is preserved.
241 Blank lines and comments are permitted (even encouraged) in the config‐
243 uration file. A comment begins with a ``#'' character and finishes at
244 the end of the line. A line may be continued by ensuring that the last
245 character on the line is a ``\'' (backslash). A comment on a continued
246 line ends at the end of the continued line. Spaces may be included in
247 lexical elements by enclosing the entire element in double quotes. A
248 double quote preceded by a backslash is always a literal double quote.
249 A ``#'' in double quotes or preceded by a backslash is treated liter‐
250 ally rather than as a comment delimiter. Lexical elements and separa‐
251 tors are described further in the following sections.
252
254 Each line of the agent configuration section of the configuration file
255 contains details of how to connect pmcd to one of its agents and speci‐
256 fies which metrics domain the agent deals with. An agent may be
257 attached as a DSO, or via a socket, or a pair of pipes.
258 Each line of the agent configuration section of the configuration file
260 must be either an agent specification, a comment, or a blank line.
261 Lexical elements are separated by whitespace characters, however a sin‐
262 gle agent specification may not be broken across lines unless a back‐
263 slash is used to continue the line.
264 Each agent specification must start with a textual label (string) fol‐
266 lowed by an integer in the range 1 to 510. The label is a tag used to
267 refer to the agent and the integer specifies the domain for which the
268 agent supplies data. This domain identifier corresponds to the domain
269 portion of the PMIDs handled by the agent. Each agent must have a
270 unique label and domain identifier.
271 For DSO agents a line of the form:
273 label domain-no dso entry-point path
275 should appear. Where,
277 label is a string identifying the agent
279 domain-no is an unsigned integer specifying the agent's domain in
280 the range 1 to 510
281 entry-point is the name of an initialization function which will be
282 called when the DSO is loaded
283 path designates the location of the DSO and this is expected
284 to be an absolute pathname. pmcd is only able to load
285 DSO agents that have the same simabi (Subprogram Inter‐
286 face Model ABI, or calling conventions) as it does (i.e.
287 only one of the simabi versions will be applicable). The
288 simabi version of a running pmcd may be determined by
289 fetching pmcd.simabi. Alternatively, the file(1) command
290 may be used to determine the simabi version from the pmcd
291 executable.
292 For a relative path the environment variable PMCD_PATH
294 defines a colon (:) separated list of directories to
295 search when trying to locate the agent DSO. The default
296 search path is $PCP_SHARE_DIR/lib:/usr/pcp/lib.
297 For agents providing socket connections, a line of the form
299 label domain-no socket addr-family address [ command ]
301 should appear. Where,
303 label is a string identifying the agent
305 domain-no is an unsigned integer specifying the agent's domain in
306 the range 1 to 510
307 addr-family designates whether the socket is in the AF_INET, AF_INET6
308 or AF_UNIX domain, and the corresponding values for this
309 parameter are inet, ipv6 and unix respectively.
310 address specifies the address of the socket within the previously
311 specified addr-family. For unix sockets, the address
312 should be the name of an agent's socket on the local host
313 (a valid address for the UNIX domain). For inet and ipv6
314 sockets, the address may be either a port number or a
315 port name which may be used to connect to an agent on the
316 local host. There is no syntax for specifying an agent
317 on a remote host as a pmcd deals only with agents on the
318 same machine.
319 command is an optional parameter used to specify a command line
320 to start the agent when pmcd initializes. If command is
321 not present, pmcd assumes that the specified agent has
322 already been created. The command is considered to start
323 from the first non-white character after the socket
324 address and finish at the next newline that isn't pre‐
325 ceded by a backslash. After a fork(2) the command is
326 passed unmodified to execve(2) to instantiate the agent.
327 For agents interacting with the pmcd via stdin/stdout, a line of the
329 form:
330 label domain-no pipe protocol command
332 should appear. Where,
334 label is a string identifying the agent
336 domain-no is an unsigned integer specifying the agent's domain
337 protocol The value for this parameter should be binary.
338 Additionally, the protocol can include the notready key‐
340 word to indicate that the agent must be marked as not
341 being ready to process requests from pmcd. The agent
342 will explicitly notify the pmcd when it is ready to
343 process the requests by sending a PM_ERR_PMDAREADY PDU.
344 For further details of this protocol, including a
345 description of the IPC parameters that can be specified
346 in a PMDA Install script with the ipc_prot parameter, see
347 the relevant section in PMDA(3).
348 command specifies a command line to start the agent when pmcd
350 initializes. Note that command is mandatory for pipe-
351 based agents. The command is considered to start from
352 the first non-white character after the protocol parame‐
353 ter and finish at the next newline that isn't preceded by
354 a backslash. After a fork(2) the command is passed
355 unmodified to execve(2) to instantiate the agent.
356
358 The access control section of the configuration file is optional, but
359 if present it must follow the agent configuration data. The case of
360 reserved words is ignored, but elsewhere case is preserved. Lexical
361 elements in the access control section are separated by whitespace or
362 the special delimiter characters: square brackets (``['' and ``]''),
363 braces (``{'' and ``}''), colon (``:''), semicolon (``;'') and comma
364 (``,''). The special characters are not treated as special in the
365 agent configuration section. Lexical elements may be quoted (double
366 quotes) as necessary.
367 The access control section of the file must start with a line of the
369 form:
370 [access]
372 In addition to (or instead of) the access section in the pmcd configu‐
374 ration file, access control specifications are also read from a file
375 having the same name as the pmcd configuration file, but with '.access'
376 appended to the name. This optional file must not contain the [access]
377 keyword.
378 Leading and trailing whitespace may appear around and within the brack‐
380 ets and the case of the access keyword is ignored. No other text may
381 appear on the line except a trailing comment.
382 Following this line, the remainder of the configuration file should
384 contain lines that allow or disallow operations from particular hosts
385 or groups of hosts.
386 There are two kinds of operations that occur via pmcd:
388 fetch allows retrieval of information from pmcd. This may be
390 information about a metric (e.g. its description,
391 instance domain, labels or help text) or a value for a
392 metric. See pminfo(1) for further information.
393 store allows pmcd to be used to store metric values in agents
395 that permit store operations. This may be the actual
396 value of the metric (e.g. resetting a counter to zero).
397 Alternatively, it may be a value used by the PMDA to
398 introduce a change to some aspect of monitoring of that
399 metric (e.g. server side event filtering) - possibly
400 even only for the active client tool performing the
401 store operation, and not others. See pmstore(1) for
402 further information.
403 Access to pmcd can be granted in three ways - by user, group of users,
405 or at a host level. In the latter, all users on a host are granted the
406 same level of access, unless the user or group access control mechanism
407 is also in use.
408 User names and group names will be verified using the local /etc/passwd
410 and /etc/groups files (or an alternative directory service), using the
411 getpwent(3) and getgrent(3) routines.
412 Hosts may be identified by name, IP address, IPv6 address or by the
414 special host specifications ``"unix:"'' or ``"local:"''. ``"unix:"''
415 refers to pmcd's unix domain socket, on supported platforms.
416 ``"local:"'' is equivalent to specifying ``"unix:"'' and ``localhost``.
417 Wildcards may also be specified by ending the host identifier with the
419 single wildcard character ``*'' as the last-given component of an
420 address. The wildcard ``".*"'' refers to all inet (IPv4) addresses.
421 The wildcard ``":*"'' refers to all IPv6 addresses. If an IPv6 wild‐
422 card contains a ``::'' component, then the final ``*'' refers to the
423 final 16 bits of the address only, otherwise it refers to the remaining
424 unspecified bits of the address.
425 The wildcard ``*'' refers to all users, groups or host addresses,
427 including ``"unix:"''. Names of users, groups or hosts may not be
428 wildcarded.
429 The following are all valid host identifiers:
431 boing
433 localhost
434 giggle.melbourne.sgi.com
435 129.127.112.2
436 129.127.114.*
437 129.*
438 .*
439 fe80::223:14ff:feaf:b62c
440 fe80::223:14ff:feaf:*
441 fe80:*
442 :*
443 "unix:"
444 "local:"
445 *
446 The following are not valid host identifiers:
448 *.melbourne
450 129.127.*.*
451 129.*.114.9
452 129.127*
453 fe80::223:14ff:*:*
454 fe80::223:14ff:*:b62c
455 fe80*
456 The first example is not allowed because only (numeric) IP addresses
458 may contain a wildcard. The second and fifth examples are not valid
459 because there is more than one wildcard character. The third and sixth
460 contain an embedded wildcard, the fourth and seventh have a wildcard
461 character that is not the last component of the address (the last com‐
462 ponents are 127* and fe80* respectively).
463 The name localhost is given special treatment to make the behavior of
465 host wildcarding consistent. Rather than being 127.0.0.1 and ::1, it
466 is mapped to the primary inet and IPv6 addresses associated with the
467 name of the host on which pmcd is running. Beware of this when running
468 pmcd on multi-homed hosts.
469 Access for users, groups or hosts are allowed or disallowed by specify‐
471 ing statements of the form:
472 allow users userlist : operations ;
474 disallow users userlist : operations ;
475 allow groups grouplist : operations ;
476 disallow groups grouplist : operations ;
477 allow hosts hostlist : operations ;
478 disallow hosts hostlist : operations ;
479 list userlist, grouplist and hostlist are comma separated
481 lists of one or more users, groups or host identifiers.
482 operations is a comma separated list of the operation types
484 described above, all (which allows/disallows all opera‐
485 tions), or all except operations (which allows/disallows
486 all operations except those listed).
487 Either plural or singular forms of users, groups, and hosts keywords
489 are allowed. If this keyword is omitted, a default of hosts will be
490 used. This behaviour is for backward-compatibility only, it is prefer‐
491 able to be explicit.
492 Where no specific allow or disallow statement applies to an operation,
494 the default is to allow the operation from all users, groups and hosts.
495 In the trivial case when there is no access control section in the con‐
496 figuration file, all operations from all users, groups, and hosts are
497 permitted.
498 If a new connection to pmcd is attempted by a user, group or host that
500 is not permitted to perform any operations, the connection will be
501 closed immediately after an error response PM_ERR_PERMISSION has been
502 sent to the client attempting the connection.
503 Statements with the same level of wildcarding specifying identical
505 hosts may not contradict each other. For example if a host named clank
506 had an IP address of 129.127.112.2, specifying the following two rules
507 would be erroneous:
508 allow host clank : fetch, store;
510 disallow host 129.127.112.2 : all except fetch;
511 because they both refer to the same host, but disagree as to whether
513 the fetch operation is permitted from that host.
514 Statements containing more specific host specifications override less
516 specific ones according to the level of wildcarding. For example a
517 rule of the form
518 allow host clank : all;
520 overrides
522 disallow host 129.127.112.* : all except fetch;
524 because the former contains a specific host name (equivalent to a fully
526 specified IP address), whereas the latter has a wildcard. In turn, the
527 latter would override
528 disallow host * : all;
530 It is possible to limit the number of connections from a user, group or
532 host to pmcd. This may be done by adding a clause of the form
533 maximum n connections
535 to the operations list of an allow statement. Such a clause may not be
537 used in a disallow statement. Here, n is the maximum number of connec‐
538 tions that will be accepted from the user, group or host matching the
539 identifier(s) used in the statement.
540 An access control statement with a list of user, group or host identi‐
542 fiers is equivalent to a set of access control statements, with each
543 specifying one of the identifiers in the list and all with the same
544 access controls (both permissions and connection limits). A group
545 should be used if you want users to contribute to a shared connection
546 limit. A wildcard should be used if you want hosts to contribute to a
547 shared connection limit.
548 When a new client requests a connection, and pmcd has determined that
550 the client has permission to connect, it searches the matching list of
551 access control statements for the most specific match containing a con‐
552 nection limit. For brevity, this will be called the limiting state‐
553 ment. If there is no limiting statement, the client is granted a con‐
554 nection. If there is a limiting statement and the number of pmcd
555 clients with user ID, group ID, or IP addresses that match the identi‐
556 fier in the limiting statement is less than the connection limit in the
557 statement, the connection is allowed. Otherwise the connection limit
558 has been reached and the client is refused a connection.
559 Group access controls and the wildcarding in host identifiers means
561 that once pmcd actually accepts a connection from a client, the connec‐
562 tion may contribute to the current connection count of more than one
563 access control statement - the client's host may match more than one
564 access control statement, and similarly the user ID may be in more than
565 one group. This may be significant for subsequent connection requests.
566 Note that pmcd enters a mode where it runs effectively with a higher-
568 level of security as soon as a user or group access control section is
569 added to the configuration. In this mode only authenticated connec‐
570 tions are allowed - either from a SASL authenticated connection, or a
571 Unix domain socket (which implicitly passes client credentials). This
572 is the same mode that is entered explicitly using the -S option.
573 Assuming permission is allowed, one can determine whether pmcd is run‐
574 ning in this mode by querying the value of the pmcd.fea‐
575 ture.creds_required metric.
576 Note also that because most specific match semantics are used when
578 checking the connection limit, for the host-based access control case,
579 priority is given to clients with more specific host identifiers. It
580 is also possible to exceed connection limits in some situations. Con‐
581 sider the following:
582 allow host clank : all, maximum 5 connections;
584 allow host * : all except store, maximum 2 connections;
585 This says that only 2 client connections at a time are permitted for
587 all hosts other than "clank", which is permitted 5. If a client from
588 host "boing" is the first to connect to pmcd, its connection is checked
589 against the second statement (that is the most specific match with a
590 connection limit). As there are no other clients, the connection is
591 accepted and contributes towards the limit for only the second state‐
592 ment above. If the next client connects from "clank", its connection
593 is checked against the limit for the first statement. There are no
594 other connections from "clank", so the connection is accepted. Once
595 this connection is accepted, it counts towards both statements' limits
596 because "clank" matches the host identifier in both statements. Remem‐
597 ber that the decision to accept a new connection is made using only the
598 most specific matching access control statement with a connection
599 limit. Now, the connection limit for the second statement has been
600 reached. Any connections from hosts other than "clank" will be
601 refused.
602 If instead, pmcd with no clients saw three successive connections
604 arrived from "boing", the first two would be accepted and the third
605 refused. After that, if a connection was requested from "clank" it
606 would be accepted. It matches the first statement, which is more spe‐
607 cific than the second, so the connection limit in the first is used to
608 determine that the client has the right to connect. Now there are 3
609 connections contributing to the second statement's connection limit.
610 Even though the connection limit for the second statement has been
611 exceeded, the earlier connections from "boing" are maintained. The
612 connection limit is only checked at the time a client attempts a con‐
613 nection rather than being re-evaluated every time a new client connects
614 to pmcd.
615 This gentle scheme is designed to allow reasonable limits to be imposed
617 on a first come first served basis, with specific exceptions.
618 As illustrated by the example above, a client's connection is honored
620 once it has been accepted. However, pmcd reconfiguration (see the next
621 section) re-evaluates all the connection counts and will cause client
622 connections to be dropped where connection limits have been exceeded.
623
625 Preventing sampling during the life of a PMDA is sometimes desirable,
626 for example if that sampling impacts on sensitive phases of a scheduled
627 job. A temporary ``fence'' can be raised to block all PMAPI client
628 access to one or more agents in this situation. This functionality is
629 provided by the built-in PMCD PMDA and the pmstore(1) command, as in
630 # pmstore -i nfsclient,kvm pmcd.agent.fenced 1
632 If the optional comma-separated list of agent names is omitted, all
634 agents will be fenced. To resume normal operation, the ``fence'' can
635 be lowered as follows
636 # pmstore -i nfsclient,kvm pmcd.agent.fenced 0
638 Lowering the fence for all PMDAs at once is performed using
640 # pmstore pmcd.agent.fenced 0
642 Elevated privileges are required to store to the pmcd.agent.fenced met‐
644 ric. For additional information, see the help text associated with
645 this metric, which can be accessed using the -T, --helptext option to
646 pminfo(1).
647
649 If the configuration file has been changed or if an agent is not
650 responding because it has terminated or the PMNS has been changed, pmcd
651 may be reconfigured by sending it a SIGHUP, as in
652 # pmsignal -a -s HUP pmcd
654 When pmcd receives a SIGHUP, it checks the configuration file for
656 changes. If the file has been modified, it is reparsed and the con‐
657 tents become the new configuration. If there are errors in the config‐
658 uration file, the existing configuration is retained and the contents
659 of the file are ignored. Errors are reported in the pmcd log file.
660 It also checks the PMNS file and any labels files for changes. If any
662 of these files have been modified, then the PMNS and/or context labels
663 are reloaded. Use of tail(1) on the log file is recommended while
664 reconfiguring pmcd.
665 If the configuration for an agent has changed (any parameter except the
667 agent's label is different), the agent is restarted. Agents whose con‐
668 figurations do not change are not restarted. Any existing agents not
669 present in the new configuration are terminated. Any deceased agents
670 are that are still listed are restarted.
671 Sometimes it is necessary to restart an agent that is still running,
673 but malfunctioning. Simply stop the agent (e.g. using SIGTERM from
674 pmsignal(1)), then send pmcd a SIGHUP, which will cause the agent to be
675 restarted.
676
678 Normally, pmcd is started automatically at boot time and stopped when
679 the system is being brought down. Under certain circumstances it is
680 necessary to start or stop pmcd manually. To do this one must become
681 superuser and type
682 # $PCP_RC_DIR/pmcd start
684 to start pmcd, or
686 # $PCP_RC_DIR/pmcd stop
688 to stop pmcd. Starting pmcd when it is already running is the same as
690 stopping it and then starting it again.
691 Sometimes it may be necessary to restart pmcd during another phase of
693 the boot process. Time-consuming parts of the boot process are often
694 put into the background to allow the system to become available sooner
695 (e.g. mounting huge databases). If an agent run by pmcd requires such
696 a task to complete before it can run properly, it is necessary to
697 restart or reconfigure pmcd after the task completes. Consider, for
698 example, the case of mounting a database in the background while boot‐
699 ing. If the PMDA which provides the metrics about the database cannot
700 function until the database is mounted and available but pmcd is
701 started before the database is ready, the PMDA will fail (however pmcd
702 will still service requests for metrics from other domains). If the
703 database is initialized by running a shell script, adding a line to the
704 end of the script to reconfigure pmcd (by sending it a SIGHUP) will
705 restart the PMDA (if it exited because it couldn't connect to the data‐
706 base). If the PMDA didn't exit in such a situation it would be neces‐
707 sary to restart pmcd because if the PMDA was still running pmcd would
708 not restart it.
709 Normally pmcd listens for client connections on TCP/IP port number
711 44321 (registered at http://www.iana.org/). Either the environment
712 variable PMCD_PORT or the -p command line option may be used to specify
713 alternative port number(s) when pmcd is started; in each case, the
714 specification is a comma-separated list of one or more numerical port
715 numbers. Should both methods be used or multiple -p options appear on
716 the command line, pmcd will listen on the union of the set of ports
717 specified via all -p options and the PMCD_PORT environment variable.
718 If non-default ports are used with pmcd care should be taken to ensure
719 that PMCD_PORT is also set in the environment of any client application
720 that will connect to pmcd, or that the extended host specification syn‐
721 tax is used (see PCPIntro(1) for details).
722
724 pmcd does not explicitly terminate its children (agents), it only
725 closes their pipes. If an agent never checks for a closed pipe it may
726 not terminate.
727 The configuration file parser will only read lines of less than 1200
729 characters. This is intended to prevent accidents with binary files.
730 The timeouts controlled by the -t option apply to IPC between pmcd and
732 the PMDAs it spawns. This is independent of settings of the environ‐
733 ment variables PMCD_CONNECT_TIMEOUT and PMCD_REQUEST_TIMEOUT (see
734 PCPIntro(1)) which may be used respectively to control timeouts for
735 client applications trying to connect to pmcd and trying to receive
736 information from pmcd.
737
739 If pmcd is already running the message "Error: OpenRequestSocket bind:
740 Address may already be in use" will appear. This may also appear if
741 pmcd was shutdown with an outstanding request from a client. In this
742 case, a request socket has been left in the TIME_WAIT state and until
743 the system closes it down (after some timeout period) it will not be
744 possible to run pmcd.
745 In addition to the standard PCP debugging flags, see pmdbg(1), pmcd
747 currently uses the options: appl0 for tracing I/O and termination of
748 agents, appl1 for tracing access control and appl2 for tracing the con‐
749 figuration file scanner and parser.
750
752 $PCP_PMCDCONF_PATH
753 default configuration file
754 $PCP_PMCDCONF_PATH.access
756 optional access control specification file
757 $PCP_PMCDOPTIONS_PATH
759 command line options to pmcd when launched from $PCP_RC_DIR/pmcd
760 All the command line option lines should start with a hyphen as
761 the first character.
762 $PCP_SYSCONFIG_DIR/pmcd
764 additional environment variables that will be set when pmcd exe‐
765 cutes. Only settings of the form "PMCD_VARIABLE=value" will be
766 honoured.
767 $PCP_SYSCONF_DIR/labels.conf
769 settings related to labels used globally throughout the PMCS.
770 $PCP_SYSCONF_DIR/labels
772 directory of files containing the global metric labels that will
773 be set for every client context created by pmcd. File names
774 starting with a ``.'' are ignored, and files ending in ``.json''
775 are ``JSONB'' formatted name:value pairs. The merged set can be
776 queried via the pmcd.labels metric. Context labels are applied
777 universally to all metrics.
778 $PCP_SYSCONF_DIR/labels/optional
780 directory of files containing the global metric labels that will
781 be set for every client context created by pmcd, but which are
782 flagged as optional. These labels are exactly the same as other
783 context labels except that they are not used in time series iden‐
784 tifier calculations.
785 ./pmcd.log
787 (or $PCP_LOG_DIR/pmcd/pmcd.log when started automatically)
788 All messages and diagnostics are directed here.
789 $PCP_RUN_DIR/pmcd.pid
791 contains an ascii decimal representation of the process ID of
792 pmcd, when it's running.
793 /etc/pki/nssdb
795 default Network Security Services (NSS) certificate database
796 directory, used for optional Secure Socket Layer connections.
797 This database can be created and queried using the NSS certutil
798 tool, amongst others.
799 /etc/passwd
801 user names, user identifiers and primary group identifiers, used
802 for access control specifications
803 /etc/groups
805 group names, group identifiers and group members, used for access
806 control specifications
807
809 The following variables are set in $PCP_SYSCONFIG_DIR/pmcd.
810 In addition to the PCP environment variables described in the PCP ENVI‐
812 RONMENT section below, the PMCD_PORT variable is also recognised as the
813 TCP/IP port for incoming connections (default 44321), and the
814 PMCD_SOCKET variable is also recognised as the path to be used for the
815 Unix domain socket.
816 If set to the value 1, the PMCD_LOCAL environment variable will cause
818 pmcd to run in a localhost-only mode of operation, where it binds only
819 to the loopback interface. The pmcd.feature.local metric can be
820 queried to determine if pmcd is running in this mode.
821 The PMCD_MAXPENDING variable can be set to indicate the maximum length
823 to which the queue of pending client connections may grow.
824 The PMCD_ROOT_AGENT variable controls whether or not pmcd or pmdaroot
826 (when available), start subsequent pmdas. When set to a non-zero
827 value, pmcd will opt to have pmdaroot start, and stop, PMDAs.
828 The PMCD_RESTART_AGENTS variable determines the behaviour of pmcd in
830 the presence of child PMDAs that have been observed to exit (this is a
831 typical response in the presence of very large, usually domain-induced,
832 PDU latencies). When set to a non-zero value, pmcd will attempt to
833 restart such PMDAS once every minute. When set to zero, it uses the
834 original behaviour of just logging the failure.
835
837 Environment variables with the prefix PCP_ are used to parameterize the
838 file and directory names used by PCP. On each installation, the file
839 /etc/pcp.conf contains the local values for these variables. The
840 $PCP_CONF variable may be used to specify an alternative configuration
841 file, as described in pcp.conf(5).
842 For environment variables affecting PCP tools, see pmGetOptions(3).
844
846 PCPIntro(1), pmdbg(1), pmerr(1), pmgenmap(1), pminfo(1), pmrep(1),
847 pmstat(1), pmstore(1), pmval(1), getpwent(3), getgrent(3),
848 labels.conf(5), pcp.conf(5), pcp.env(5) and PMNS(5).
849Performance Co-Pilot PCP PMCD(1)