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 Leading and trailing whitespace may appear around and within the brack‐
369 ets and the case of the access keyword is ignored. No other text may
370 appear on the line except a trailing comment.
371 Following this line, the remainder of the configuration file should
373 contain lines that allow or disallow operations from particular hosts
374 or groups of hosts.
375 There are two kinds of operations that occur via pmcd:
377 fetch allows retrieval of information from pmcd. This may be
379 information about a metric (e.g. its description,
380 instance domain, labels or help text) or a value for a
381 metric. See pminfo(1) for further information.
382 store allows pmcd to be used to store metric values in agents
384 that permit store operations. This may be the actual
385 value of the metric (e.g. resetting a counter to zero).
386 Alternatively, it may be a value used by the PMDA to
387 introduce a change to some aspect of monitoring of that
388 metric (e.g. server side event filtering) - possibly
389 even only for the active client tool performing the
390 store operation, and not others. See pmstore(1) for
391 further information.
392 Access to pmcd can be granted in three ways - by user, group of users,
394 or at a host level. In the latter, all users on a host are granted the
395 same level of access, unless the user or group access control mechanism
396 is also in use.
397 User names and group names will be verified using the local /etc/passwd
399 and /etc/groups files (or an alternative directory service), using the
400 getpwent(3) and getgrent(3) routines.
401 Hosts may be identified by name, IP address, IPv6 address or by the
403 special host specifications ``"unix:"'' or ``"local:"''. ``"unix:"''
404 refers to pmcd's unix domain socket, on supported platforms.
405 ``"local:"'' is equivalent to specifying ``"unix:"'' and ``localhost``.
406 Wildcards may also be specified by ending the host identifier with the
408 single wildcard character ``*'' as the last-given component of an
409 address. The wildcard ``".*"'' refers to all inet (IPv4) addresses.
410 The wildcard ``":*"'' refers to all IPv6 addresses. If an IPv6 wild‐
411 card contains a ``::'' component, then the final ``*'' refers to the
412 final 16 bits of the address only, otherwise it refers to the remaining
413 unspecified bits of the address.
414 The wildcard ``*'' refers to all users, groups or host addresses,
416 including ``"unix:"''. Names of users, groups or hosts may not be
417 wildcarded.
418 The following are all valid host identifiers:
420 boing
422 localhost
423 giggle.melbourne.sgi.com
424 129.127.112.2
425 129.127.114.*
426 129.*
427 .*
428 fe80::223:14ff:feaf:b62c
429 fe80::223:14ff:feaf:*
430 fe80:*
431 :*
432 "unix:"
433 "local:"
434 *
435 The following are not valid host identifiers:
437 *.melbourne
439 129.127.*.*
440 129.*.114.9
441 129.127*
442 fe80::223:14ff:*:*
443 fe80::223:14ff:*:b62c
444 fe80*
445 The first example is not allowed because only (numeric) IP addresses
447 may contain a wildcard. The second and fifth examples are not valid
448 because there is more than one wildcard character. The third and sixth
449 contain an embedded wildcard, the fourth and seventh have a wildcard
450 character that is not the last component of the address (the last com‐
451 ponents are 127* and fe80* respectively).
452 The name localhost is given special treatment to make the behavior of
454 host wildcarding consistent. Rather than being 127.0.0.1 and ::1, it
455 is mapped to the primary inet and IPv6 addresses associated with the
456 name of the host on which pmcd is running. Beware of this when running
457 pmcd on multi-homed hosts.
458 Access for users, groups or hosts are allowed or disallowed by specify‐
460 ing statements of the form:
461 allow users userlist : operations ;
463 disallow users userlist : operations ;
464 allow groups grouplist : operations ;
465 disallow groups grouplist : operations ;
466 allow hosts hostlist : operations ;
467 disallow hosts hostlist : operations ;
468 list userlist, grouplist and hostlist are comma separated
470 lists of one or more users, groups or host identifiers.
471 operations is a comma separated list of the operation types
473 described above, all (which allows/disallows all opera‐
474 tions), or all except operations (which allows/disallows
475 all operations except those listed).
476 Either plural or singular forms of users, groups, and hosts keywords
478 are allowed. If this keyword is omitted, a default of hosts will be
479 used. This behaviour is for backward-compatibility only, it is prefer‐
480 able to be explicit.
481 Where no specific allow or disallow statement applies to an operation,
483 the default is to allow the operation from all users, groups and hosts.
484 In the trivial case when there is no access control section in the con‐
485 figuration file, all operations from all users, groups, and hosts are
486 permitted.
487 If a new connection to pmcd is attempted by a user, group or host that
489 is not permitted to perform any operations, the connection will be
490 closed immediately after an error response PM_ERR_PERMISSION has been
491 sent to the client attempting the connection.
492 Statements with the same level of wildcarding specifying identical
494 hosts may not contradict each other. For example if a host named clank
495 had an IP address of 129.127.112.2, specifying the following two rules
496 would be erroneous:
497 allow host clank : fetch, store;
499 disallow host 129.127.112.2 : all except fetch;
500 because they both refer to the same host, but disagree as to whether
502 the fetch operation is permitted from that host.
503 Statements containing more specific host specifications override less
505 specific ones according to the level of wildcarding. For example a
506 rule of the form
507 allow host clank : all;
509 overrides
511 disallow host 129.127.112.* : all except fetch;
513 because the former contains a specific host name (equivalent to a fully
515 specified IP address), whereas the latter has a wildcard. In turn, the
516 latter would override
517 disallow host * : all;
519 It is possible to limit the number of connections from a user, group or
521 host to pmcd. This may be done by adding a clause of the form
522 maximum n connections
524 to the operations list of an allow statement. Such a clause may not be
526 used in a disallow statement. Here, n is the maximum number of connec‐
527 tions that will be accepted from the user, group or host matching the
528 identifier(s) used in the statement.
529 An access control statement with a list of user, group or host identi‐
531 fiers is equivalent to a set of access control statements, with each
532 specifying one of the identifiers in the list and all with the same
533 access controls (both permissions and connection limits). A group
534 should be used if you want users to contribute to a shared connection
535 limit. A wildcard should be used if you want hosts to contribute to a
536 shared connection limit.
537 When a new client requests a connection, and pmcd has determined that
539 the client has permission to connect, it searches the matching list of
540 access control statements for the most specific match containing a con‐
541 nection limit. For brevity, this will be called the limiting state‐
542 ment. If there is no limiting statement, the client is granted a con‐
543 nection. If there is a limiting statement and the number of pmcd
544 clients with user ID, group ID, or IP addresses that match the identi‐
545 fier in the limiting statement is less than the connection limit in the
546 statement, the connection is allowed. Otherwise the connection limit
547 has been reached and the client is refused a connection.
548 Group access controls and the wildcarding in host identifiers means
550 that once pmcd actually accepts a connection from a client, the connec‐
551 tion may contribute to the current connection count of more than one
552 access control statement - the client's host may match more than one
553 access control statement, and similarly the user ID may be in more than
554 one group. This may be significant for subsequent connection requests.
555 Note that pmcd enters a mode where it runs effectively with a higher-
557 level of security as soon as a user or group access control section is
558 added to the configuration. In this mode only authenticated connec‐
559 tions are allowed - either from a SASL authenticated connection, or a
560 Unix domain socket (which implicitly passes client credentials). This
561 is the same mode that is entered explicitly using the -S option.
562 Assuming permission is allowed, one can determine whether pmcd is run‐
563 ning in this mode by querying the value of the pmcd.fea‐
564 ture.creds_required metric.
565 Note also that because most specific match semantics are used when
567 checking the connection limit, for the host-based access control case,
568 priority is given to clients with more specific host identifiers. It
569 is also possible to exceed connection limits in some situations. Con‐
570 sider the following:
571 allow host clank : all, maximum 5 connections;
573 allow host * : all except store, maximum 2 connections;
574 This says that only 2 client connections at a time are permitted for
576 all hosts other than "clank", which is permitted 5. If a client from
577 host "boing" is the first to connect to pmcd, its connection is checked
578 against the second statement (that is the most specific match with a
579 connection limit). As there are no other clients, the connection is
580 accepted and contributes towards the limit for only the second state‐
581 ment above. If the next client connects from "clank", its connection
582 is checked against the limit for the first statement. There are no
583 other connections from "clank", so the connection is accepted. Once
584 this connection is accepted, it counts towards both statements' limits
585 because "clank" matches the host identifier in both statements. Remem‐
586 ber that the decision to accept a new connection is made using only the
587 most specific matching access control statement with a connection
588 limit. Now, the connection limit for the second statement has been
589 reached. Any connections from hosts other than "clank" will be
590 refused.
591 If instead, pmcd with no clients saw three successive connections
593 arrived from "boing", the first two would be accepted and the third
594 refused. After that, if a connection was requested from "clank" it
595 would be accepted. It matches the first statement, which is more spe‐
596 cific than the second, so the connection limit in the first is used to
597 determine that the client has the right to connect. Now there are 3
598 connections contributing to the second statement's connection limit.
599 Even though the connection limit for the second statement has been
600 exceeded, the earlier connections from "boing" are maintained. The
601 connection limit is only checked at the time a client attempts a con‐
602 nection rather than being re-evaluated every time a new client connects
603 to pmcd.
604 This gentle scheme is designed to allow reasonable limits to be imposed
606 on a first come first served basis, with specific exceptions.
607 As illustrated by the example above, a client's connection is honored
609 once it has been accepted. However, pmcd reconfiguration (see the next
610 section) re-evaluates all the connection counts and will cause client
611 connections to be dropped where connection limits have been exceeded.
612
614 If the configuration file has been changed or if an agent is not
615 responding because it has terminated or the PMNS has been changed, pmcd
616 may be reconfigured by sending it a SIGHUP, as in
617 # pmsignal -a -s HUP pmcd
619 When pmcd receives a SIGHUP, it checks the configuration file for
621 changes. If the file has been modified, it is reparsed and the con‐
622 tents become the new configuration. If there are errors in the config‐
623 uration file, the existing configuration is retained and the contents
624 of the file are ignored. Errors are reported in the pmcd log file.
625 It also checks the PMNS file and any labels files for changes. If any
627 of these files have been modified, then the PMNS and/or context labels
628 are reloaded. Use of tail(1) on the log file is recommended while
629 reconfiguring pmcd.
630 If the configuration for an agent has changed (any parameter except the
632 agent's label is different), the agent is restarted. Agents whose con‐
633 figurations do not change are not restarted. Any existing agents not
634 present in the new configuration are terminated. Any deceased agents
635 are that are still listed are restarted.
636 Sometimes it is necessary to restart an agent that is still running,
638 but malfunctioning. Simply stop the agent (e.g. using SIGTERM from
639 pmsignal(1)), then send pmcd a SIGHUP, which will cause the agent to be
640 restarted.
641
643 Normally, pmcd is started automatically at boot time and stopped when
644 the system is being brought down. Under certain circumstances it is
645 necessary to start or stop pmcd manually. To do this one must become
646 superuser and type
647 # $PCP_RC_DIR/pmcd start
649 to start pmcd, or
651 # $PCP_RC_DIR/pmcd stop
653 to stop pmcd. Starting pmcd when it is already running is the same as
655 stopping it and then starting it again.
656 Sometimes it may be necessary to restart pmcd during another phase of
658 the boot process. Time-consuming parts of the boot process are often
659 put into the background to allow the system to become available sooner
660 (e.g. mounting huge databases). If an agent run by pmcd requires such
661 a task to complete before it can run properly, it is necessary to
662 restart or reconfigure pmcd after the task completes. Consider, for
663 example, the case of mounting a database in the background while boot‐
664 ing. If the PMDA which provides the metrics about the database cannot
665 function until the database is mounted and available but pmcd is
666 started before the database is ready, the PMDA will fail (however pmcd
667 will still service requests for metrics from other domains). If the
668 database is initialized by running a shell script, adding a line to the
669 end of the script to reconfigure pmcd (by sending it a SIGHUP) will
670 restart the PMDA (if it exited because it couldn't connect to the data‐
671 base). If the PMDA didn't exit in such a situation it would be neces‐
672 sary to restart pmcd because if the PMDA was still running pmcd would
673 not restart it.
674 Normally pmcd listens for client connections on TCP/IP port number
676 44321 (registered at http://www.iana.org/). Either the environment
677 variable PMCD_PORT or the -p command line option may be used to specify
678 alternative port number(s) when pmcd is started; in each case, the
679 specification is a comma-separated list of one or more numerical port
680 numbers. Should both methods be used or multiple -p options appear on
681 the command line, pmcd will listen on the union of the set of ports
682 specified via all -p options and the PMCD_PORT environment variable.
683 If non-default ports are used with pmcd care should be taken to ensure
684 that PMCD_PORT is also set in the environment of any client application
685 that will connect to pmcd, or that the extended host specification syn‐
686 tax is used (see PCPIntro(1) for details).
687
689 $PCP_PMCDCONF_PATH
690 default configuration file
691 $PCP_PMCDOPTIONS_PATH
692 command line options to pmcd when launched from
693 $PCP_RC_DIR/pmcd All the command line option lines should
694 start with a hyphen as the first character.
695 $PCP_SYSCONFIG_DIR/pmcd
696 additional environment variables that will be set when pmcd
697 executes. Only settings of the form "PMCD_VARIABLE=value"
698 will be honoured.
699 $PCP_SYSCONF_DIR/labels
700 directory of files containing the global metric labels that
701 will be set for every client context created by pmcd. File
702 names starting with a ``.'' are ignored, and files ending in
703 ``.json'' are ``JSONB'' formatted name:value pairs. The
704 merged set can be queried via the pmcd.labels metric. Con‐
705 text labels are applied universally to all values.
706 ./pmcd.log
707 (or $PCP_LOG_DIR/pmcd/pmcd.log when started automatically)
708 All messages and diagnostics are directed here.
709 $PCP_RUN_DIR/pmcd.pid
710 contains an ascii decimal representation of the process ID of
711 pmcd, when it's running.
712 /etc/pki/nssdb
713 default Network Security Services (NSS) certificate database
714 directory, used for optional Secure Socket Layer connections.
715 This database can be created and queried using the NSS certu‐
716 til tool, amongst others.
717 /etc/passwd
718 user names, user identifiers and primary group identifiers,
719 used for access control specifications
720 /etc/groups
721 group names, group identifiers and group members, used for
722 access control specifications
723
725 In addition to the PCP environment variables described in the PCP ENVI‐
726 RONMENT section below, the PMCD_PORT variable is also recognised as the
727 TCP/IP port for incoming connections (default 44321), and the
728 PMCD_SOCKET variable is also recognised as the path to be used for the
729 Unix domain socket.
730 If set to the value 1, the PMCD_LOCAL environment variable will cause
732 pmcd to run in a localhost-only mode of operation, where it binds only
733 to the loopback interface. The pmcd.feature.local metric can be
734 queried to determine if pmcd is running in this mode.
735 The PMCD_MAXPENDING variable can be set to indicate the maximum length
737 to which the queue of pending client connections may grow.
738 The PMCD_ROOT_AGENT variable controls whether or not pmcd or pmdaroot
740 (when available), start subsequent pmdas. When set to a non-zero
741 value, pmcd will opt to have pmdaroot start, and stop, PMDAs.
742 The PMCD_RESTART_AGENTS variable determines the behaviour of pmcd in
744 the presence of child PMDAs that have been observed to exit (this is a
745 typical response in the presence of very large, usually domain-induced,
746 PDU latencies). When set to a non-zero value, pmcd will attempt to
747 restart such PMDAS once every minute. When set to zero, it uses the
748 original behaviour of just logging the failure.
749
751 Environment variables with the prefix PCP_ are used to parameterize the
752 file and directory names used by PCP. On each installation, the file
753 /etc/pcp.conf contains the local values for these variables. The
754 $PCP_CONF variable may be used to specify an alternative configuration
755 file, as described in pcp.conf(5).
756
758 If pmcd is already running the message "Error: OpenRequestSocket bind:
759 Address may already be in use" will appear. This may also appear if
760 pmcd was shutdown with an outstanding request from a client. In this
761 case, a request socket has been left in the TIME_WAIT state and until
762 the system closes it down (after some timeout period) it will not be
763 possible to run pmcd.
764 In addition to the standard PCP debugging flags, see pmdbg(1), pmcd
766 currently uses the options: appl0 for tracing I/O and termination of
767 agents, appl1 for tracing access control and appl2 for tracing the con‐
768 figuration file scanner and parser.
769
771 pmcd does not explicitly terminate its children (agents), it only
772 closes their pipes. If an agent never checks for a closed pipe it may
773 not terminate.
774 The configuration file parser will only read lines of less than 1200
776 characters. This is intended to prevent accidents with binary files.
777 The timeouts controlled by the -t option apply to IPC between pmcd and
779 the PMDAs it spawns. This is independent of settings of the environ‐
780 ment variables PMCD_CONNECT_TIMEOUT and PMCD_REQUEST_TIMEOUT (see
781 PCPIntro(1)) which may be used respectively to control timeouts for
782 client applications trying to connect to pmcd and trying to receive
783 information from pmcd.
784
786 PCPIntro(1), pmdbg(1), pmerr(1), pmgenmap(1), pminfo(1), pmrep(1),
787 pmstat(1), pmstore(1), pmval(1), getpwent(3), getgrent(3), pcp.conf(5),
788 and pcp.env(5).
789Performance Co-Pilot PCP PMCD(1)