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