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