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