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 re‐
22 lated 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 $PCP_PM‐
56 CDCONF_PATH, configuration variable in /etc/pcp.conf, or an envi‐
57 ronment variable of the same name. However, these values may be
58 overridden with config using this option. The format of this con‐
59 figuration 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 al‐
65 ready exist, this database can be created using the certutil util‐
66 ity. This process and other certificate database maintenance in‐
67 formation is provided in the PCPIntro(1) manual page and the on‐
68 line 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) ad‐
87 dresses. The -i option is used to specify explicitly an IP ad‐
88 dress that connections should be accepted on. ipaddress should be
89 in the standard dotted form (e.g. 100.23.45.6). The -i option may
90 be used multiple times to define a list of IP addresses. Connec‐
91 tions made to any other IP addresses the host has will be refused.
92 This can be used to limit connections to one network interface if
93 the host is a network gateway. It is also useful if the host
94 takes over the IP address of another host that has failed. In
95 such a situation only the standard IP addresses of the host should
96 be given (not the ones inherited from the failed host). This al‐
97 lows PCP applications to determine that a host has failed, rather
98 than connecting to the host that has assumed the identity of the
99 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 er‐
106 ror 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 port, --port=port
130 Specify port to listen on. By default port 44321 is used.
131 -P passfile, --passfile=passfile
133 Specify the path to a file containing the Network Security Ser‐
134 vices certificate database password for (optional) secure connec‐
135 tions, and for databases that are password protected. Refer also
136 to the -C option. When using this option, great care should be
137 exercised to ensure appropriate ownership ("pcp" user, typically)
138 and permissions on this file (0400, so as to be unreadable by any
139 user other than the user running the pmcd process).
140 -q timeout
142 The pmcd to agent version exchange protocol (new in PCP 2.0 - in‐
143 troduced to provide backward compatibility) uses this timeout to
144 specify how long pmcd should wait before assuming that no version
145 response is coming from an agent. If this timeout is reached, the
146 agent is assumed to be an agent which does not understand the PCP
147 2.0 protocol. The default timeout interval is five seconds, but
148 the -q option allows an alternative timeout interval (which must
149 be greater than zero) to be specified. The unit of time is sec‐
150 onds.
151 -Q, --remotecert
153 Require that all remote client connections provide a certficate.
154 -s sockname, --socket=sockname
156 Specify the path to a local unix domain socket (for platforms sup‐
157 porting this socket family only). The default value is
158 $PCP_RUN_DIR/pmcd.socket.
159 -S, --reqauth
161 Require that all client connections provide user credentials.
162 This means that only unix domain sockets, or authenticated connec‐
163 tions are permitted (requires secure sockets support). If any
164 user or group access control requirements are specified in the
165 pmcd configuration file, then this mode of operation is automati‐
166 cally entered, whether the -S flag is specified or not.
167 -t timeout
169 To prevent misbehaving clients or agents from hanging the entire
170 Performance Metrics Collection System (PMCS), pmcd uses timeouts
171 on PDU exchanges with clients and agents running as processes. By
172 default the timeout interval is five seconds. The -t option al‐
173 lows an alternative timeout interval in seconds to be specified.
174 If timeout is zero, timeouts are turned off. It is almost impos‐
175 sible to use the debugger interactively on an agent unless time‐
176 outs have been turned off for its "parent" pmcd.
177 Once pmcd is running, the timeout may be dynamically modified by
179 storing an integer value (the timeout in seconds) into the metric
180 pmcd.control.timeout via pmstore(1).
181 -T traceflag, --trace=traceflag
183 To assist with error diagnosis for agents and/or clients of pmcd
184 that are not behaving correctly, an internal event tracing mecha‐
185 nism is supported within pmcd. The value of traceflag is inter‐
186 preted as a bit field with the following control functions:
187 1 enable client connection tracing
189 2 enable PDU tracing
190 256 unbuffered event tracing
191 By default, event tracing is buffered using a circular buffer that
193 is over-written as new events are recorded. The default buffer
194 size holds the last 20 events, although this number may be over-
195 ridden by using pmstore(1) to modify the metric pmcd.con‐
196 trol.tracebufs.
197 Similarly once pmcd is running, the event tracing control may be
199 dynamically modified by storing 1 (enable) or 0 (disable) into the
200 metrics pmcd.control.traceconn, pmcd.control.tracepdu and
201 pmcd.control.tracenobuf. These metrics map to the bit fields as‐
202 sociated with the traceflag argument for the -T option.
203 When operating in buffered mode, the event trace buffer will be
205 dumped whenever an agent connection is terminated by pmcd, or when
206 any value is stored into the metric pmcd.control.dumptrace via pm‐
207 store(1).
208 In unbuffered mode, every event will be reported when it occurs.
210 -U username, --username=USER
212 User account under which to run pmcd. The default is the unprivi‐
213 leged "pcp" account in current versions of PCP, but in older ver‐
214 sions the superuser account ("root") was used by default.
215 -v, --verify
217 Verify the pmcd configuration file, reporting on any errors then
218 exiting with a status indicating verification success or failure.
219 -x file
221 Before the pmcd logfile can be opened, pmcd may encounter a fatal
222 error which prevents it from starting. By default, the output de‐
223 scribing this error is sent to /dev/tty but it may redirected to
224 file.
225 -?, --help
227 Display usage message and exit.
228
230 On startup pmcd looks for a configuration file named $PCP_PMCD‐
231 CONF_PATH. This file specifies which agents cover which performance
232 metrics domains and how pmcd should make contact with the agents. An
233 optional section specifying access controls may follow the agent con‐
234 figuration data.
235 Warning: pmcd is usually started as part of the boot sequence and runs
237 initially as root. The configuration file may contain shell commands
238 to create agents, which will be executed by root. To prevent security
239 breaches the configuration file should be writable only by root. The
240 use of absolute path names is also recommended.
241 The case of the reserved words in the configuration file is unimpor‐
243 tant, but elsewhere, the case is preserved.
244 Blank lines and comments are permitted (even encouraged) in the config‐
246 uration file. A comment begins with a ``#'' character and finishes at
247 the end of the line. A line may be continued by ensuring that the last
248 character on the line is a ``\'' (backslash). A comment on a continued
249 line ends at the end of the continued line. Spaces may be included in
250 lexical elements by enclosing the entire element in double quotes. A
251 double quote preceded by a backslash is always a literal double quote.
252 A ``#'' in double quotes or preceded by a backslash is treated liter‐
253 ally rather than as a comment delimiter. Lexical elements and separa‐
254 tors are described further in the following sections.
255
257 Each line of the agent configuration section of the configuration file
258 contains details of how to connect pmcd to one of its agents and speci‐
259 fies which metrics domain the agent deals with. An agent may be at‐
260 tached as a DSO, or via a socket, or a pair of pipes.
261 Each line of the agent configuration section of the configuration file
263 must be either an agent specification, a comment, or a blank line.
264 Lexical elements are separated by whitespace characters, however a sin‐
265 gle agent specification may not be broken across lines unless a back‐
266 slash is used to continue the line.
267 Each agent specification must start with a textual label (string) fol‐
269 lowed by an integer in the range 1 to 510. The label is a tag used to
270 refer to the agent and the integer specifies the domain for which the
271 agent supplies data. This domain identifier corresponds to the domain
272 portion of the PMIDs handled by the agent. Each agent must have a
273 unique label and domain identifier.
274 For DSO agents a line of the form:
276 label domain-no dso entry-point path
278 should appear. Where,
280 label is a string identifying the agent
282 domain-no is an unsigned integer specifying the agent's domain in
283 the range 1 to 510
284 entry-point is the name of an initialization function which will be
285 called when the DSO is loaded
286 path designates the location of the DSO and this is expected
287 to be an absolute pathname. pmcd is only able to load
288 DSO agents that have the same simabi (Subprogram Inter‐
289 face Model ABI, or calling conventions) as it does (i.e.
290 only one of the simabi versions will be applicable). The
291 simabi version of a running pmcd may be determined by
292 fetching pmcd.simabi. Alternatively, the file(1) command
293 may be used to determine the simabi version from the pmcd
294 executable.
295 For a relative path the environment variable PMCD_PATH
297 defines a colon (:) separated list of directories to
298 search when trying to locate the agent DSO. The default
299 search path is $PCP_SHARE_DIR/lib:/usr/pcp/lib.
300 For agents providing socket connections, a line of the form
302 label domain-no socket addr-family address [ command ]
304 should appear. Where,
306 label is a string identifying the agent
308 domain-no is an unsigned integer specifying the agent's domain in
309 the range 1 to 510
310 addr-family designates whether the socket is in the AF_INET, AF_INET6
311 or AF_UNIX domain, and the corresponding values for this
312 parameter are inet, ipv6 and unix respectively.
313 address specifies the address of the socket within the previously
314 specified addr-family. For unix sockets, the address
315 should be the name of an agent's socket on the local host
316 (a valid address for the UNIX domain). For inet and ipv6
317 sockets, the address may be either a port number or a
318 port name which may be used to connect to an agent on the
319 local host. There is no syntax for specifying an agent
320 on a remote host as a pmcd deals only with agents on the
321 same machine.
322 command is an optional parameter used to specify a command line
323 to start the agent when pmcd initializes. If command is
324 not present, pmcd assumes that the specified agent has
325 already been created. The command is considered to start
326 from the first non-white character after the socket ad‐
327 dress and finish at the next newline that isn't preceded
328 by a backslash. After a fork(2) the command is passed
329 unmodified to execve(2) to instantiate the agent.
330 For agents interacting with the pmcd via stdin/stdout, a line of the
332 form:
333 label domain-no pipe protocol command
335 should appear. Where,
337 label is a string identifying the agent
339 domain-no is an unsigned integer specifying the agent's domain
340 protocol The value for this parameter should be binary.
341 Additionally, the protocol can include the notready key‐
343 word to indicate that the agent must be marked as not be‐
344 ing ready to process requests from pmcd. The agent will
345 explicitly notify the pmcd when it is ready to process
346 the requests by sending a PM_ERR_PMDAREADY PDU. For fur‐
347 ther details of this protocol, including a description of
348 the IPC parameters that can be specified in a PMDA In‐
349 stall script with the ipc_prot parameter, see the rele‐
350 vant section in PMDA(3).
351 command specifies a command line to start the agent when pmcd
353 initializes. Note that command is mandatory for pipe-
354 based agents. The command is considered to start from
355 the first non-white character after the protocol parame‐
356 ter and finish at the next newline that isn't preceded by
357 a backslash. After a fork(2) the command is passed un‐
358 modified to execve(2) to instantiate the agent.
359
361 The access control section of the configuration file is optional, but
362 if present it must follow the agent configuration data. The case of
363 reserved words is ignored, but elsewhere case is preserved. Lexical
364 elements in the access control section are separated by whitespace or
365 the special delimiter characters: square brackets (``['' and ``]''),
366 braces (``{'' and ``}''), colon (``:''), semicolon (``;'') and comma
367 (``,''). The special characters are not treated as special in the
368 agent configuration section. Lexical elements may be quoted (double
369 quotes) as necessary.
370 The access control section of the file must start with a line of the
372 form:
373 [access]
375 In addition to (or instead of) the access section in the pmcd configu‐
377 ration file, access control specifications are also read from a file
378 having the same name as the pmcd configuration file, but with '.access'
379 appended to the name. This optional file must not contain the [access]
380 keyword.
381 Leading and trailing whitespace may appear around and within the brack‐
383 ets and the case of the access keyword is ignored. No other text may
384 appear on the line except a trailing comment.
385 Following this line, the remainder of the configuration file should
387 contain lines that allow or disallow operations from particular hosts
388 or groups of hosts.
389 There are two kinds of operations that occur via pmcd:
391 fetch allows retrieval of information from pmcd. This may be
393 information about a metric (e.g. its description, in‐
394 stance domain, labels or help text) or a value for a
395 metric. See pminfo(1) for further information.
396 store allows pmcd to be used to store metric values in agents
398 that permit store operations. This may be the actual
399 value of the metric (e.g. resetting a counter to zero).
400 Alternatively, it may be a value used by the PMDA to in‐
401 troduce a change to some aspect of monitoring of that
402 metric (e.g. server side event filtering) - possibly
403 even only for the active client tool performing the
404 store operation, and not others. See pmstore(1) for
405 further information.
406 Access to pmcd can be granted in three ways - by user, group of users,
408 or at a host level. In the latter, all users on a host are granted the
409 same level of access, unless the user or group access control mechanism
410 is also in use.
411 User names and group names will be verified using the local /etc/passwd
413 and /etc/groups files (or an alternative directory service), using the
414 getpwent(3) and getgrent(3) routines.
415 Hosts may be identified by name, IP address, IPv6 address or by the
417 special host specifications ``"unix:"'' or ``"local:"''. ``"unix:"''
418 refers to pmcd's unix domain socket, on supported platforms. ``"lo‐
419 cal:"'' is equivalent to specifying ``"unix:"'' and ``localhost``.
420 Wildcards may also be specified by ending the host identifier with the
422 single wildcard character ``*'' as the last-given component of an ad‐
423 dress. The wildcard ``".*"'' refers to all inet (IPv4) addresses. The
424 wildcard ``":*"'' refers to all IPv6 addresses. If an IPv6 wildcard
425 contains a ``::'' component, then the final ``*'' refers to the final
426 16 bits of the address only, otherwise it refers to the remaining un‐
427 specified bits of the address.
428 The wildcard ``*'' refers to all users, groups or host addresses, in‐
430 cluding ``"unix:"''. Names of users, groups or hosts may not be wild‐
431 carded.
432 The following are all valid host identifiers:
434 boing
436 localhost
437 giggle.melbourne.sgi.com
438 129.127.112.2
439 129.127.114.*
440 129.*
441 .*
442 fe80::223:14ff:feaf:b62c
443 fe80::223:14ff:feaf:*
444 fe80:*
445 :*
446 "unix:"
447 "local:"
448 *
449 The following are not valid host identifiers:
451 *.melbourne
453 129.127.*.*
454 129.*.114.9
455 129.127*
456 fe80::223:14ff:*:*
457 fe80::223:14ff:*:b62c
458 fe80*
459 The first example is not allowed because only (numeric) IP addresses
461 may contain a wildcard. The second and fifth examples are not valid
462 because there is more than one wildcard character. The third and sixth
463 contain an embedded wildcard, the fourth and seventh have a wildcard
464 character that is not the last component of the address (the last com‐
465 ponents are 127* and fe80* respectively).
466 The name localhost is given special treatment to make the behavior of
468 host wildcarding consistent. Rather than being 127.0.0.1 and ::1, it
469 is mapped to the primary inet and IPv6 addresses associated with the
470 name of the host on which pmcd is running. Beware of this when running
471 pmcd on multi-homed hosts.
472 Access for users, groups or hosts are allowed or disallowed by specify‐
474 ing statements of the form:
475 allow users userlist : operations ;
477 disallow users userlist : operations ;
478 allow groups grouplist : operations ;
479 disallow groups grouplist : operations ;
480 allow hosts hostlist : operations ;
481 disallow hosts hostlist : operations ;
482 list userlist, grouplist and hostlist are comma separated
484 lists of one or more users, groups or host identifiers.
485 operations is a comma separated list of the operation types de‐
487 scribed above, all (which allows/disallows all opera‐
488 tions), or all except operations (which allows/disallows
489 all operations except those listed).
490 Either plural or singular forms of users, groups, and hosts keywords
492 are allowed. If this keyword is omitted, a default of hosts will be
493 used. This behaviour is for backward-compatibility only, it is prefer‐
494 able to be explicit.
495 Where no specific allow or disallow statement applies to an operation,
497 the default is to allow the operation from all users, groups and hosts.
498 In the trivial case when there is no access control section in the con‐
499 figuration file, all operations from all users, groups, and hosts are
500 permitted.
501 If a new connection to pmcd is attempted by a user, group or host that
503 is not permitted to perform any operations, the connection will be
504 closed immediately after an error response PM_ERR_PERMISSION has been
505 sent to the client attempting the connection.
506 Statements with the same level of wildcarding specifying identical
508 hosts may not contradict each other. For example if a host named clank
509 had an IP address of 129.127.112.2, specifying the following two rules
510 would be erroneous:
511 allow host clank : fetch, store;
513 disallow host 129.127.112.2 : all except fetch;
514 because they both refer to the same host, but disagree as to whether
516 the fetch operation is permitted from that host.
517 Statements containing more specific host specifications override less
519 specific ones according to the level of wildcarding. For example a
520 rule of the form
521 allow host clank : all;
523 overrides
525 disallow host 129.127.112.* : all except fetch;
527 because the former contains a specific host name (equivalent to a fully
529 specified IP address), whereas the latter has a wildcard. In turn, the
530 latter would override
531 disallow host * : all;
533 It is possible to limit the number of connections from a user, group or
535 host to pmcd. This may be done by adding a clause of the form
536 maximum n connections
538 to the operations list of an allow statement. Such a clause may not be
540 used in a disallow statement. Here, n is the maximum number of connec‐
541 tions that will be accepted from the user, group or host matching the
542 identifier(s) used in the statement.
543 An access control statement with a list of user, group or host identi‐
545 fiers is equivalent to a set of access control statements, with each
546 specifying one of the identifiers in the list and all with the same ac‐
547 cess controls (both permissions and connection limits). A group should
548 be used if you want users to contribute to a shared connection limit.
549 A wildcard should be used if you want hosts to contribute to a shared
550 connection limit.
551 When a new client requests a connection, and pmcd has determined that
553 the client has permission to connect, it searches the matching list of
554 access control statements for the most specific match containing a con‐
555 nection limit. For brevity, this will be called the limiting state‐
556 ment. If there is no limiting statement, the client is granted a con‐
557 nection. If there is a limiting statement and the number of pmcd
558 clients with user ID, group ID, or IP addresses that match the identi‐
559 fier in the limiting statement is less than the connection limit in the
560 statement, the connection is allowed. Otherwise the connection limit
561 has been reached and the client is refused a connection.
562 Group access controls and the wildcarding in host identifiers means
564 that once pmcd actually accepts a connection from a client, the connec‐
565 tion may contribute to the current connection count of more than one
566 access control statement - the client's host may match more than one
567 access control statement, and similarly the user ID may be in more than
568 one group. This may be significant for subsequent connection requests.
569 Note that pmcd enters a mode where it runs effectively with a higher-
571 level of security as soon as a user or group access control section is
572 added to the configuration. In this mode only authenticated connec‐
573 tions are allowed - either from a SASL authenticated connection, or a
574 Unix domain socket (which implicitly passes client credentials). This
575 is the same mode that is entered explicitly using the -S option. As‐
576 suming permission is allowed, one can determine whether pmcd is running
577 in this mode by querying the value of the pmcd.feature.creds_required
578 metric.
579 Note also that because most specific match semantics are used when
581 checking the connection limit, for the host-based access control case,
582 priority is given to clients with more specific host identifiers. It
583 is also possible to exceed connection limits in some situations. Con‐
584 sider the following:
585 allow host clank : all, maximum 5 connections;
587 allow host * : all except store, maximum 2 connections;
588 This says that only 2 client connections at a time are permitted for
590 all hosts other than "clank", which is permitted 5. If a client from
591 host "boing" is the first to connect to pmcd, its connection is checked
592 against the second statement (that is the most specific match with a
593 connection limit). As there are no other clients, the connection is
594 accepted and contributes towards the limit for only the second state‐
595 ment above. If the next client connects from "clank", its connection
596 is checked against the limit for the first statement. There are no
597 other connections from "clank", so the connection is accepted. Once
598 this connection is accepted, it counts towards both statements' limits
599 because "clank" matches the host identifier in both statements. Remem‐
600 ber that the decision to accept a new connection is made using only the
601 most specific matching access control statement with a connection
602 limit. Now, the connection limit for the second statement has been
603 reached. Any connections from hosts other than "clank" will be re‐
604 fused.
605 If instead, pmcd with no clients saw three successive connections ar‐
607 rived from "boing", the first two would be accepted and the third re‐
608 fused. After that, if a connection was requested from "clank" it would
609 be accepted. It matches the first statement, which is more specific
610 than the second, so the connection limit in the first is used to deter‐
611 mine that the client has the right to connect. Now there are 3 connec‐
612 tions contributing to the second statement's connection limit. Even
613 though the connection limit for the second statement has been exceeded,
614 the earlier connections from "boing" are maintained. The connection
615 limit is only checked at the time a client attempts a connection rather
616 than being re-evaluated every time a new client connects to pmcd.
617 This gentle scheme is designed to allow reasonable limits to be imposed
619 on a first come first served basis, with specific exceptions.
620 As illustrated by the example above, a client's connection is honored
622 once it has been accepted. However, pmcd reconfiguration (see the next
623 section) re-evaluates all the connection counts and will cause client
624 connections to be dropped where connection limits have been exceeded.
625
627 Preventing sampling during the life of a PMDA is sometimes desirable,
628 for example if that sampling impacts on sensitive phases of a scheduled
629 job. A temporary ``fence'' can be raised to block all PMAPI client ac‐
630 cess to one or more agents in this situation. This functionality is
631 provided by the built-in PMCD PMDA and the pmstore(1) command, as in
632 # pmstore -i nfsclient,kvm pmcd.agent.fenced 1
634 If the optional comma-separated list of agent names is omitted, all
636 agents will be fenced. To resume normal operation, the ``fence'' can
637 be lowered as follows
638 # pmstore -i nfsclient,kvm pmcd.agent.fenced 0
640 Lowering the fence for all PMDAs at once is performed using
642 # pmstore pmcd.agent.fenced 0
644 Elevated privileges are required to store to the pmcd.agent.fenced met‐
646 ric. For additional information, see the help text associated with
647 this metric, which can be accessed using the -T, --helptext option to
648 pminfo(1).
649
651 If the configuration file has been changed or if an agent is not re‐
652 sponding because it has terminated or the PMNS has been changed, pmcd
653 may be reconfigured by sending it a SIGHUP, as in
654 # pmsignal -a -s HUP pmcd
656 When pmcd receives a SIGHUP, it checks the configuration file for
658 changes. If the file has been modified, it is reparsed and the con‐
659 tents become the new configuration. If there are errors in the config‐
660 uration file, the existing configuration is retained and the contents
661 of the file are ignored. Errors are reported in the pmcd log file.
662 It also checks the PMNS file and any labels files for changes. If any
664 of these files have been modified, then the PMNS and/or context labels
665 are reloaded. Use of tail(1) on the log file is recommended while re‐
666 configuring pmcd.
667 If the configuration for an agent has changed (any parameter except the
669 agent's label is different), the agent is restarted. Agents whose con‐
670 figurations do not change are not restarted. Any existing agents not
671 present in the new configuration are terminated. Any deceased agents
672 are that are still listed are restarted.
673 Sometimes it is necessary to restart an agent that is still running,
675 but malfunctioning. Simply stop the agent (e.g. using SIGTERM from pm‐
676 signal(1)), then send pmcd a SIGHUP, which will cause the agent to be
677 restarted.
678
680 Normally, pmcd is started automatically at boot time and stopped when
681 the system is being brought down. Under certain circumstances it is
682 necessary to start or stop pmcd manually. To do this one must become
683 superuser and type
684 # $PCP_RC_DIR/pmcd start
686 to start pmcd, or
688 # $PCP_RC_DIR/pmcd stop
690 to stop pmcd. Starting pmcd when it is already running is the same as
692 stopping it and then starting it again.
693 Sometimes it may be necessary to restart pmcd during another phase of
695 the boot process. Time-consuming parts of the boot process are often
696 put into the background to allow the system to become available sooner
697 (e.g. mounting huge databases). If an agent run by pmcd requires such
698 a task to complete before it can run properly, it is necessary to
699 restart or reconfigure pmcd after the task completes. Consider, for
700 example, the case of mounting a database in the background while boot‐
701 ing. If the PMDA which provides the metrics about the database cannot
702 function until the database is mounted and available but pmcd is
703 started before the database is ready, the PMDA will fail (however pmcd
704 will still service requests for metrics from other domains). If the
705 database is initialized by running a shell script, adding a line to the
706 end of the script to reconfigure pmcd (by sending it a SIGHUP) will
707 restart the PMDA (if it exited because it couldn't connect to the data‐
708 base). If the PMDA didn't exit in such a situation it would be neces‐
709 sary to restart pmcd because if the PMDA was still running pmcd would
710 not restart it.
711 Normally pmcd listens for client connections on TCP/IP port number
713 44321 (registered at http://www.iana.org/). Either the environment
714 variable PMCD_PORT or the -p command line option may be used to specify
715 alternative port number(s) when pmcd is started; in each case, the
716 specification is a comma-separated list of one or more numerical port
717 numbers. Should both methods be used or multiple -p options appear on
718 the command line, pmcd will listen on the union of the set of ports
719 specified via all -p options and the PMCD_PORT environment variable.
720 If non-default ports are used with pmcd care should be taken to ensure
721 that PMCD_PORT is also set in the environment of any client application
722 that will connect to pmcd, or that the extended host specification syn‐
723 tax is used (see PCPIntro(1) for details).
724
726 pmcd does not explicitly terminate its children (agents), it only
727 closes their pipes. If an agent never checks for a closed pipe it may
728 not terminate.
729 The configuration file parser will only read lines of less than 1200
731 characters. This is intended to prevent accidents with binary files.
732 The timeouts controlled by the -t option apply to IPC between pmcd and
734 the PMDAs it spawns. This is independent of settings of the environ‐
735 ment variables PMCD_CONNECT_TIMEOUT and PMCD_REQUEST_TIMEOUT (see
736 PCPIntro(1)) which may be used respectively to control timeouts for
737 client applications trying to connect to pmcd and trying to receive in‐
738 formation from pmcd.
739
741 If pmcd is already running the message "Error: OpenRequestSocket bind:
742 Address may already be in use" will appear. This may also appear if
743 pmcd was shutdown with an outstanding request from a client. In this
744 case, a request socket has been left in the TIME_WAIT state and until
745 the system closes it down (after some timeout period) it will not be
746 possible to run pmcd.
747 In addition to the standard PCP debugging flags, see pmdbg(1), pmcd
749 currently uses the options: appl0 for tracing I/O and termination of
750 agents, appl1 for tracing access control and appl2 for tracing the con‐
751 figuration file scanner and parser.
752
754 $PCP_PMCDCONF_PATH
755 default configuration file
756 $PCP_PMCDCONF_PATH.access
758 optional access control specification file
759 $PCP_PMCDOPTIONS_PATH
761 command line options to pmcd when launched from $PCP_RC_DIR/pmcd
762 All the command line option lines should start with a hyphen as
763 the first character.
764 $PCP_SYSCONFIG_DIR/pmcd
766 Environment variables that will be set when pmcd executes. Only
767 settings of the form "PMCD_VARIABLE=value" or "PCP_VARIABLE=value"
768 are honoured.
769 $PCP_SYSCONF_DIR/labels.conf
771 settings related to labels used globally throughout the PMCS.
772 $PCP_SYSCONF_DIR/labels
774 directory of files containing the global metric labels that will
775 be set for every client context created by pmcd. File names
776 starting with a ``.'' are ignored, and files ending in ``.json''
777 are ``JSONB'' formatted name:value pairs. The merged set can be
778 queried via the pmcd.labels metric. Context labels are applied
779 universally to all metrics.
780 $PCP_SYSCONF_DIR/labels/optional
782 directory of files containing the global metric labels that will
783 be set for every client context created by pmcd, but which are
784 flagged as optional. These labels are exactly the same as other
785 context labels except that they are not used in time series iden‐
786 tifier calculations.
787 ./pmcd.log
789 (or $PCP_LOG_DIR/pmcd/pmcd.log when started automatically)
790 All messages and diagnostics are directed here.
791 $PCP_RUN_DIR/pmcd.pid
793 contains an ascii decimal representation of the process ID of
794 pmcd, when it's running.
795 /etc/pki/nssdb
797 default Network Security Services (NSS) certificate database di‐
798 rectory, used for optional Secure Socket Layer connections. This
799 database can be created and queried using the NSS certutil tool,
800 amongst others.
801 /etc/passwd
803 user names, user identifiers and primary group identifiers, used
804 for access control specifications
805 /etc/groups
807 group names, group identifiers and group members, used for access
808 control specifications
809
811 The following variables are set in $PCP_SYSCONFIG_DIR/pmcd.
812 In addition to the PCP environment variables described in the PCP ENVI‐
814 RONMENT section below, the PMCD_PORT variable is also recognised as the
815 TCP/IP port for incoming connections (default 44321), and the
816 PMCD_SOCKET variable is also recognised as the path to be used for the
817 Unix domain socket.
818 If set to the value 1, the PMCD_LOCAL environment variable will cause
820 pmcd to run in a localhost-only mode of operation, where it binds only
821 to the loopback interface. The pmcd.feature.local metric can be
822 queried to determine if pmcd is running in this mode.
823 The PMCD_MAXPENDING variable can be set to indicate the maximum length
825 to which the queue of pending client connections may grow.
826 The PMCD_ROOT_AGENT variable controls whether or not pmcd or pmdaroot
828 (when available), start subsequent pmdas. When set to a non-zero
829 value, pmcd will opt to have pmdaroot start, and stop, PMDAs.
830 The PMCD_RESTART_AGENTS variable determines the behaviour of pmcd in
832 the presence of child PMDAs that have been observed to exit (this is a
833 typical response in the presence of very large, usually domain-induced,
834 PDU latencies). When set to a non-zero value, pmcd will attempt to
835 restart such PMDAS once every minute. When set to zero, it uses the
836 original behaviour of just logging the failure.
837
839 Environment variables with the prefix PCP_ are used to parameterize the
840 file and directory names used by PCP. On each installation, the file
841 /etc/pcp.conf contains the local values for these variables. The
842 $PCP_CONF variable may be used to specify an alternative configuration
843 file, as described in pcp.conf(5).
844 For environment variables affecting PCP tools, see pmGetOptions(3).
846
848 PCPIntro(1), pmdbg(1), pmerr(1), pmgenmap(1), pminfo(1), pmrep(1), pm‐
849 stat(1), pmstore(1), pmval(1), getpwent(3), getgrent(3), la‐
850 bels.conf(5), pcp.conf(5), pcp.env(5) and PMNS(5).
851Performance Co-Pilot PCP PMCD(1)