1PMCD(1) General Commands Manual PMCD(1)
2
6 pmcd - performance metrics collector daemon
7
9 pmcd [-AfS] [-c config] [-C dirname] [-H hostname] [-i ipaddress] [-l
10 logfile] [-L bytes] [-[n|N] pmnsfile] [-p port[,port ...] [-P pass‐
11 file] [-q timeout] [-s sockname] [-T traceflag] [-t timeout] [-U user‐
12 name] [-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 -n pmnsfile
102 Normally pmcd loads the default Performance Metrics Name Space
103 (PMNS) from $PCP_VAR_DIR/pmns/root, however if the -n option is
104 specified an alternative namespace is loaded from the file pmns‐
105 file.
106 -N pmnsfile
108 Same function as -n, except for the handling of duplicate Per‐
109 formance Metric Identifiers (PMIDs) in pmnsfile - duplicate
110 names are allowed with -n they are not allowed with -N.
111 -P passfile
113 Specify the path to a file containing the Network Security Ser‐
114 vices certificate database password for (optional) secure con‐
115 nections, and for databases that are password protected. Refer
116 also to the -C option. When using this option, great care
117 should be exercised to ensure appropriate ownership ("pcp" user,
118 typically) and permissions on this file (0400, so as to be
119 unreadable by any user other than the user running the pmcd
120 process).
121 -q timeout
123 The pmcd to agent version exchange protocol (new in PCP 2.0 -
124 introduced to provide backward compatibility) uses this timeout
125 to specify how long pmcd should wait before assuming that no
126 version response is coming from an agent. If this timeout is
127 reached, the agent is assumed to be an agent which does not
128 understand the PCP 2.0 protocol. The default timeout interval
129 is five seconds, but the -q option allows an alternative timeout
130 interval (which must be greater than zero) to be specified. The
131 unit of time is seconds.
132 -S Require that all client connections provide user credentials.
134 This means that only unix domain sockets, or authenticated con‐
135 nections are permitted (requires secure sockets support). If
136 any user or group access control requirements are specified in
137 the pmcd configuration file, then this mode of operation is
138 automatically entered, whether the -S flag is specified or not.
139 -s sockname
141 Specify the path to a local unix domain socket (for platforms
142 supporting this socket family only). The default value is
143 $PCP_RUN_DIR/pmcd.socket.
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.
149 By default the timeout interval is five seconds. The -t option
150 allows an alternative timeout interval in seconds to be speci‐
151 fied. If timeout is zero, timeouts are turned off. It is
152 almost impossible to use the debugger interactively on an agent
153 unless timeouts 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 met‐
157 ric pmcd.control.timeout via pmstore(1).
158 -T traceflag
160 To assist with error diagnosis for agents and/or clients of pmcd
161 that are not behaving correctly, an internal event tracing mech‐
162 anism is supported within pmcd. The value of traceflag is
163 interpreted 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
170 that is over-written as new events are recorded. The default
171 buffer size holds the last 20 events, although this number may
172 be over-ridden by using pmstore(1) to modify the metric
173 pmcd.control.tracebufs.
174 Similarly once pmcd is running, the event tracing control may be
176 dynamically modified by storing 1 (enable) or 0 (disable) into
177 the metrics pmcd.control.traceconn, pmcd.control.tracepdu and
178 pmcd.control.tracenobuf. These metrics map to the bit fields
179 associated 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
183 when any value is stored into the metric pmcd.control.dumptrace
184 via pmstore(1).
185 In unbuffered mode, every event will be reported when it occurs.
187 -U username
189 User account under which to run pmcd. The default is the
190 unprivileged "pcp" account in current versions of PCP, but in
191 older versions the superuser account ("root") was used by
192 default.
193 -x file
195 Before the pmcd logfile can be opened, pmcd may encounter a
196 fatal error which prevents it from starting. By default, the
197 output describing this error is sent to /dev/tty but it may
198 redirected to file.
199 If a PDU exchange with an agent times out, the agent has violated the
201 requirement that it delivers metrics with little or no delay. This is
202 deemed a protocol failure and the agent is disconnected from pmcd. Any
203 subsequent requests for information from the agent will fail with a
204 status indicating that there is no agent to provide it.
205 It is possible to specify access control to pmcd based on users, groups
207 and hosts. This allows one to prevent users, groups of users, and cer‐
208 tain hosts from accessing the metrics provided by pmcd and is described
209 in more detail in the Section on ACCESS CONTROL below.
210
212 On startup pmcd looks for a configuration file named $PCP_PMCD‐
213 CONF_PATH. This file specifies which agents cover which performance
214 metrics domains and how pmcd should make contact with the agents. An
215 optional section specifying access controls may follow the agent con‐
216 figuration data.
217 Warning: pmcd is usually started as part of the boot sequence and runs
219 initially as root. The configuration file may contain shell commands
220 to create agents, which will be executed by root. To prevent security
221 breaches the configuration file should be writable only by root. The
222 use of absolute path names is also recommended.
223 The case of the reserved words in the configuration file is unimpor‐
225 tant, but elsewhere, the case is preserved.
226 Blank lines and comments are permitted (even encouraged) in the config‐
228 uration file. A comment begins with a ``#'' character and finishes at
229 the end of the line. A line may be continued by ensuring that the last
230 character on the line is a ``\'' (backslash). A comment on a continued
231 line ends at the end of the continued line. Spaces may be included in
232 lexical elements by enclosing the entire element in double quotes. A
233 double quote preceded by a backslash is always a literal double quote.
234 A ``#'' in double quotes or preceded by a backslash is treated liter‐
235 ally rather than as a comment delimiter. Lexical elements and separa‐
236 tors are described further in the following sections.
237
239 Each line of the agent configuration section of the configuration file
240 contains details of how to connect pmcd to one of its agents and speci‐
241 fies which metrics domain the agent deals with. An agent may be
242 attached as a DSO, or via a socket, or a pair of pipes.
243 Each line of the agent configuration section of the configuration file
245 must be either an agent specification, a comment, or a blank line.
246 Lexical elements are separated by whitespace characters, however a sin‐
247 gle agent specification may not be broken across lines unless a \
248 (backslash) is used to continue the line.
249 Each agent specification must start with a textual label (string) fol‐
251 lowed by an integer in the range 1 to 510. The label is a tag used to
252 refer to the agent and the integer specifies the domain for which the
253 agent supplies data. This domain identifier corresponds to the domain
254 portion of the PMIDs handled by the agent. Each agent must have a
255 unique label and domain identifier.
256 For DSO agents a line of the form:
258 label domain-no dso entry-point path
260 should appear. Where,
262 label is a string identifying the agent
264 domain-no is an unsigned integer specifying the agent's domain in
265 the range 1 to 510
266 entry-point is the name of an initialization function which will be
267 called when the DSO is loaded
268 path designates the location of the DSO and this is expected
269 to be an absolute pathname. pmcd is only able to load
270 DSO agents that have the same simabi (Subprogram Inter‐
271 face Model ABI, or calling conventions) as it does (i.e.
272 only one of the simabi versions will be applicable). The
273 simabi version of a running pmcd may be determined by
274 fetching pmcd.simabi. Alternatively, the file(1) command
275 may be used to determine the simabi version from the pmcd
276 executable.
277 For a relative path the environment variable PMCD_PATH
279 defines a colon (:) separated list of directories to
280 search when trying to locate the agent DSO. The default
281 search path is $PCP_SHARE_DIR/lib:/usr/pcp/lib.
282 For agents providing socket connections, a line of the form
284 label domain-no socket addr-family address [ command ]
286 should appear. Where,
288 label is a string identifying the agent
290 domain-no is an unsigned integer specifying the agent's domain in
291 the range 1 to 510
292 addr-family designates whether the socket is in the AF_INET, AF_INET6
293 or AF_UNIX domain, and the corresponding values for this
294 parameter are inet, ipv6 and unix respectively.
295 address specifies the address of the socket within the previously
296 specified addr-family. For unix sockets, the address
297 should be the name of an agent's socket on the local host
298 (a valid address for the UNIX domain). For inet and ipv6
299 sockets, the address may be either a port number or a
300 port name which may be used to connect to an agent on the
301 local host. There is no syntax for specifying an agent
302 on a remote host as a pmcd deals only with agents on the
303 same machine.
304 command is an optional parameter used to specify a command line
305 to start the agent when pmcd initializes. If command is
306 not present, pmcd assumes that the specified agent has
307 already been created. The command is considered to start
308 from the first non-white character after the socket
309 address and finish at the next newline that isn't pre‐
310 ceded by a backslash. After a fork(2) the command is
311 passed unmodified to execve(2) to instantiate the agent.
312 For agents interacting with the pmcd via stdin/stdout, a line of the
314 form:
315 label domain-no pipe protocol command
317 should appear. Where,
319 label is a string identifying the agent
321 domain-no is an unsigned integer specifying the agent's domain
322 protocol The value for this parameter should be binary.
323 Additionally, the protocol can include the notready key‐
325 word to indicate that the agent must be marked as not
326 being ready to process requests from pmcd. The agent will
327 explicitly notify the pmcd when it is ready to process
328 the requests by sending PM_ERR_PMDAREADY PDU.
329 command specifies a command line to start the agent when pmcd
331 initializes. Note that command is mandatory for pipe-
332 based agents. The command is considered to start from
333 the first non-white character after the protocol parame‐
334 ter and finish at the next newline that isn't preceded by
335 a backslash. After a fork(2) the command is passed
336 unmodified to execve(2) to instantiate the agent.
337
339 The access control section of the configuration file is optional, but
340 if present it must follow the agent configuration data. The case of
341 reserved words is ignored, but elsewhere case is preserved. Lexical
342 elements in the access control section are separated by whitespace or
343 the special delimiter characters: square brackets (``['' and ``]''),
344 braces (``{'' and ``}''), colon (``:''), semicolon (``;'') and comma
345 (``,''). The special characters are not treated as special in the
346 agent configuration section. Lexical elements may be quoted (double
347 quotes) as necessary.
348 The access control section of the file must start with a line of the
350 form:
351 [access]
353 Leading and trailing whitespace may appear around and within the brack‐
355 ets and the case of the access keyword is ignored. No other text may
356 appear on the line except a trailing comment.
357 Following this line, the remainder of the configuration file should
359 contain lines that allow or disallow operations from particular hosts
360 or groups of hosts.
361 There are two kinds of operations that occur via pmcd:
363 fetch allows retrieval of information from pmcd. This may be
365 information about a metric (e.g. its description,
366 instance domain or help text) or a value for a metric.
367 store allows pmcd to be used to store metric values in agents
369 that permit store operations. This may be the actual
370 value of the metric (e.g. resetting a counter to zero).
371 Alternatively, it may be a value used by the PMDA to
372 introduce a change to some aspect of monitoring of that
373 metric (e.g. server side event filtering) - possibly
374 even only for the active client tool performing the
375 store operation, and not others.
376 Access to pmcd can be granted in three ways - by user, group of users,
378 or at a host level. In the latter, all users on a host are granted the
379 same level of access, unless the user or group access control mechanism
380 is also in use.
381 User names and group names will be verified using the local /etc/passwd
383 and /etc/groups files (or an alternative directory service), using the
384 getpwent(3) and getgrent(3) routines.
385 Hosts may be identified by name, IP address, IPv6 address or by the
387 special host specifications ``"unix:"'' or ``"local:"''. ``"unix:"''
388 refers to pmcd's unix domain socket, on supported platforms.
389 ``"local:"'' is equivalent to specifying ``"unix:"'' and ``localhost``.
390 Wildcards may also be specified by ending the host identifier with the
392 single wildcard character ``*'' as the last-given component of an
393 address. The wildcard ``".*"'' refers to all inet (IPv4) addresses.
394 The wildcard ``":*"'' refers to all IPv6 addresses. If an IPv6 wild‐
395 card contains a ``::'' component, then the final ``*'' refers to the
396 final 16 bits of the address only, otherwise it refers to the remaining
397 unspecified bits of the address.
398 The wildcard ``*'' refers to all users, groups or host addresses,
400 including ``"unix:"''. Names of users, groups or hosts may not be
401 wildcarded.
402 The following are all valid host identifiers:
404 boing
406 localhost
407 giggle.melbourne.sgi.com
408 129.127.112.2
409 129.127.114.*
410 129.*
411 .*
412 fe80::223:14ff:feaf:b62c
413 fe80::223:14ff:feaf:*
414 fe80:*
415 :*
416 "unix:"
417 "local:"
418 *
419 The following are not valid host identifiers:
421 *.melbourne
423 129.127.*.*
424 129.*.114.9
425 129.127*
426 fe80::223:14ff:*:*
427 fe80::223:14ff:*:b62c
428 fe80*
429 The first example is not allowed because only (numeric) IP addresses
431 may contain a wildcard. The second and fifth examples are not valid
432 because there is more than one wildcard character. The third and sixth
433 contain an embedded wildcard, the fourth and seventh have a wildcard
434 character that is not the last component of the address (the last com‐
435 ponents are 127* and fe80* respectively).
436 The name localhost is given special treatment to make the behavior of
438 host wildcarding consistent. Rather than being 127.0.0.1 and ::1, it
439 is mapped to the primary inet and IPv6 addresses associated with the
440 name of the host on which pmcd is running. Beware of this when running
441 pmcd on multi-homed hosts.
442 Access for users, groups or hosts are allowed or disallowed by specify‐
444 ing statements of the form:
445 allow users userlist : operations ;
447 disallow users userlist : operations ;
448 allow groups grouplist : operations ;
449 disallow groups grouplist : operations ;
450 allow hosts hostlist : operations ;
451 disallow hosts hostlist : operations ;
452 list userlist, grouplist and hostlist are comma separated
454 lists of one or more users, groups or host identifiers.
455 operations is a comma separated list of the operation types
457 described above, all (which allows/disallows all opera‐
458 tions), or all except operations (which allows/disallows
459 all operations except those listed).
460 Either plural or singular forms of users, groups, and hosts keywords
462 are allowed. If this keyword is omitted, a default of hosts will be
463 used. This behaviour is for backward-compatibility only, it is prefer‐
464 able to be explicit.
465 Where no specific allow or disallow statement applies to an operation,
467 the default is to allow the operation from all users, groups and hosts.
468 In the trivial case when there is no access control section in the con‐
469 figuration file, all operations from all users, groups, and hosts are
470 permitted.
471 If a new connection to pmcd is attempted by a user, group or host that
473 is not permitted to perform any operations, the connection will be
474 closed immediately after an error response PM_ERR_PERMISSION has been
475 sent to the client attempting the connection.
476 Statements with the same level of wildcarding specifying identical
478 hosts may not contradict each other. For example if a host named clank
479 had an IP address of 129.127.112.2, specifying the following two rules
480 would be erroneous:
481 allow host clank : fetch, store;
483 disallow host 129.127.112.2 : all except fetch;
484 because they both refer to the same host, but disagree as to whether
486 the fetch operation is permitted from that host.
487 Statements containing more specific host specifications override less
489 specific ones according to the level of wildcarding. For example a
490 rule of the form
491 allow host clank : all;
493 overrides
495 disallow host 129.127.112.* : all except fetch;
497 because the former contains a specific host name (equivalent to a fully
499 specified IP address), whereas the latter has a wildcard. In turn, the
500 latter would override
501 disallow host * : all;
503 It is possible to limit the number of connections from a user, group or
505 host to pmcd. This may be done by adding a clause of the form
506 maximum n connections
508 to the operations list of an allow statement. Such a clause may not be
510 used in a disallow statement. Here, n is the maximum number of connec‐
511 tions that will be accepted from the user, group or host matching the
512 identifier(s) used in the statement.
513 An access control statement with a list of user, group or host identi‐
515 fiers is equivalent to a set of access control statements, with each
516 specifying one of the identifiers in the list and all with the same
517 access controls (both permissions and connection limits). A group
518 should be used if you want users to contribute to a shared connection
519 limit. A wildcard should be used if you want hosts to contribute to a
520 shared connection limit.
521 When a new client requests a connection, and pmcd has determined that
523 the client has permission to connect, it searches the matching list of
524 access control statements for the most specific match containing a con‐
525 nection limit. For brevity, this will be called the limiting state‐
526 ment. If there is no limiting statement, the client is granted a con‐
527 nection. If there is a limiting statement and the number of pmcd
528 clients with user ID, group ID, or IP addresses that match the identi‐
529 fier in the limiting statement is less than the connection limit in the
530 statement, the connection is allowed. Otherwise the connection limit
531 has been reached and the client is refused a connection.
532 Group access controls and the wildcarding in host identifiers means
534 that once pmcd actually accepts a connection from a client, the connec‐
535 tion may contribute to the current connection count of more than one
536 access control statement - the client's host may match more than one
537 access control statement, and similarly the user ID may be in more than
538 one group. This may be significant for subsequent connection requests.
539 Note that pmcd enters a mode where it runs effectively with a higher-
541 level of security as soon as a user or group access control section is
542 added to the configuration. In this mode only authenticated connec‐
543 tions are allowed - either from a SASL authenticated connection, or a
544 Unix domain socket (which implicitly passes client credentials). This
545 is the same mode that is entered explicitly using the -S option.
546 Assuming permission is allowed, one can determine whether pmcd is run‐
547 ning in this mode by querying the value of the pmcd.fea‐
548 ture.creds_required metric.
549 Note also that because most specific match semantics are used when
551 checking the connection limit, for the host-based access control case,
552 priority is given to clients with more specific host identifiers. It
553 is also possible to exceed connection limits in some situations. Con‐
554 sider the following:
555 allow host clank : all, maximum 5 connections;
557 allow host * : all except store, maximum 2 connections;
558 This says that only 2 client connections at a time are permitted for
560 all hosts other than "clank", which is permitted 5. If a client from
561 host "boing" is the first to connect to pmcd, its connection is checked
562 against the second statement (that is the most specific match with a
563 connection limit). As there are no other clients, the connection is
564 accepted and contributes towards the limit for only the second state‐
565 ment above. If the next client connects from "clank", its connection
566 is checked against the limit for the first statement. There are no
567 other connections from "clank", so the connection is accepted. Once
568 this connection is accepted, it counts towards both statements' limits
569 because "clank" matches the host identifier in both statements. Remem‐
570 ber that the decision to accept a new connection is made using only the
571 most specific matching access control statement with a connection
572 limit. Now, the connection limit for the second statement has been
573 reached. Any connections from hosts other than "clank" will be
574 refused.
575 If instead, pmcd with no clients saw three successive connections
577 arrived from "boing", the first two would be accepted and the third
578 refused. After that, if a connection was requested from "clank" it
579 would be accepted. It matches the first statement, which is more spe‐
580 cific than the second, so the connection limit in the first is used to
581 determine that the client has the right to connect. Now there are 3
582 connections contributing to the second statement's connection limit.
583 Even though the connection limit for the second statement has been
584 exceeded, the earlier connections from "boing" are maintained. The
585 connection limit is only checked at the time a client attempts a con‐
586 nection rather than being re-evaluated every time a new client connects
587 to pmcd.
588 This gentle scheme is designed to allow reasonable limits to be imposed
590 on a first come first served basis, with specific exceptions.
591 As illustrated by the example above, a client's connection is honored
593 once it has been accepted. However, pmcd reconfiguration (see the next
594 section) re-evaluates all the connection counts and will cause client
595 connections to be dropped where connection limits have been exceeded.
596
598 If the configuration file has been changed or if an agent is not
599 responding because it has terminated or the PMNS has been changed, pmcd
600 may be reconfigured by sending it a SIGHUP, as in
601 # pmsignal -a -s HUP pmcd
603 When pmcd receives a SIGHUP, it checks the configuration file for
605 changes. If the file has been modified, it is reparsed and the con‐
606 tents become the new configuration. If there are errors in the config‐
607 uration file, the existing configuration is retained and the contents
608 of the file are ignored. Errors are reported in the pmcd log file.
609 It also checks the PMNS file for changes. If the PMNS file has been
611 modified, then it is reloaded. Use of tail(1) on the log file is rec‐
612 ommended while reconfiguring pmcd.
613 If the configuration for an agent has changed (any parameter except the
615 agent's label is different), the agent is restarted. Agents whose con‐
616 figurations do not change are not restarted. Any existing agents not
617 present in the new configuration are terminated. Any deceased agents
618 are that are still listed are restarted.
619 Sometimes it is necessary to restart an agent that is still running,
621 but malfunctioning. Simply stop the agent (e.g. using SIGTERM from
622 pmsignal(1)), then send pmcd a SIGHUP, which will cause the agent to be
623 restarted.
624
626 Normally, pmcd is started automatically at boot time and stopped when
627 the system is being brought down. Under certain circumstances it is
628 necessary to start or stop pmcd manually. To do this one must become
629 superuser and type
630 # $PCP_RC_DIR/pmcd start
632 to start pmcd, or
634 # $PCP_RC_DIR/pmcd stop
636 to stop pmcd. Starting pmcd when it is already running is the same as
638 stopping it and then starting it again.
639 Sometimes it may be necessary to restart pmcd during another phase of
641 the boot process. Time-consuming parts of the boot process are often
642 put into the background to allow the system to become available sooner
643 (e.g. mounting huge databases). If an agent run by pmcd requires such
644 a task to complete before it can run properly, it is necessary to
645 restart or reconfigure pmcd after the task completes. Consider, for
646 example, the case of mounting a database in the background while boot‐
647 ing. If the PMDA which provides the metrics about the database cannot
648 function until the database is mounted and available but pmcd is
649 started before the database is ready, the PMDA will fail (however pmcd
650 will still service requests for metrics from other domains). If the
651 database is initialized by running a shell script, adding a line to the
652 end of the script to reconfigure pmcd (by sending it a SIGHUP) will
653 restart the PMDA (if it exited because it couldn't connect to the data‐
654 base). If the PMDA didn't exit in such a situation it would be neces‐
655 sary to restart pmcd because if the PMDA was still running pmcd would
656 not restart it.
657 Normally pmcd listens for client connections on TCP/IP port number
659 44321 (registered at http://www.iana.org/). Either the environment
660 variable PMCD_PORT or the -p command line option may be used to specify
661 alternative port number(s) when pmcd is started; in each case, the
662 specification is a comma-separated list of one or more numerical port
663 numbers. Should both methods be used or multiple -p options appear on
664 the command line, pmcd will listen on the union of the set of ports
665 specified via all -p options and the PMCD_PORT environment variable.
666 If non-default ports are used with pmcd care should be taken to ensure
667 that PMCD_PORT is also set in the environment of any client application
668 that will connect to pmcd, or that the extended host specification syn‐
669 tax is used (see PCPIntro(1) for details).
670
672 $PCP_PMCDCONF_PATH
673 default configuration file
674 $PCP_PMCDOPTIONS_PATH
675 command line options to pmcd when launched from
676 $PCP_RC_DIR/pmcd All the command line option lines should
677 start with a hyphen as the first character.
678 $PCP_SYSCONFIG_DIR/pmcd
679 additional environment variables that will be set when pmcd
680 executes. Only settings of the form "PMCD_VARIABLE=value"
681 will be honoured.
682 ./pmcd.log
683 (or $PCP_LOG_DIR/pmcd/pmcd.log when started automatically)
684 $PCP_RUN_DIR/pmcd.pid
685 contains an ascii decimal representation of the process ID of
686 pmcd , when it's running.
687 All messages and diagnostics are directed here
688 /etc/pki/nssdb
689 default Network Security Services (NSS) certificate database
690 directory, used for optional Secure Socket Layer connections.
691 This database can be created and queried using the NSS certu‐
692 til tool, amongst others.
693 /etc/passwd
694 user names, user identifiers and primary group identifiers,
695 used for access control specifications
696 /etc/groups
697 group names, group identifiers and group members, used for
698 access control specifications
699
701 In addition to the PCP environment variables described in the PCP ENVI‐
702 RONMENT section below, the PMCD_PORT variable is also recognised as the
703 TCP/IP port for incoming connections (default 44321), and the
704 PMCD_SOCKET variable is also recognised as the path to be used for the
705 Unix domain socket.
706 If set to the value 1, the PMCD_LOCAL environment variable will cause
708 pmcd to run in a localhost-only mode of operation, where it binds only
709 to the loopback interface. The pmcd.feature.local metric can be
710 queried to determine if pmcd is running in this mode.
711 The PMCD_MAXPENDING variable can be set to indicate the maximum length
713 to which the queue of pending client connections may grow.
714
716 Environment variables with the prefix PCP_ are used to parameterize the
717 file and directory names used by PCP. On each installation, the file
718 /etc/pcp.conf contains the local values for these variables. The
719 $PCP_CONF variable may be used to specify an alternative configuration
720 file, as described in pcp.conf(5).
721
723 If pmcd is already running the message "Error: OpenRequestSocket bind:
724 Address may already be in use" will appear. This may also appear if
725 pmcd was shutdown with an outstanding request from a client. In this
726 case, a request socket has been left in the TIME_WAIT state and until
727 the system closes it down (after some timeout period) it will not be
728 possible to run pmcd.
729 In addition to the standard PCP debugging flags, see pmdbg(1), pmcd
731 currently uses DBG_TRACE_APPL0 for tracing I/O and termination of
732 agents, DBG_TRACE_APPL1 for tracing access control and DBG_TRACE_APPL2
733 for tracing the configuration file scanner and parser.
734
736 pmcd does not explicitly terminate its children (agents), it only
737 closes their pipes. If an agent never checks for a closed pipe it may
738 not terminate.
739 The configuration file parser will only read lines of less than 1200
741 characters. This is intended to prevent accidents with binary files.
742 The timeouts controlled by the -t option apply to IPC between pmcd and
744 the PMDAs it spawns. This is independent of settings of the environ‐
745 ment variables PMCD_CONNECT_TIMEOUT and PMCD_REQUEST_TIMEOUT (see
746 PCPIntro(1)) which may be used respectively to control timeouts for
747 client applications trying to connect to pmcd and trying to receive
748 information from pmcd.
749
751 PCPIntro(1), pmdbg(1), pmerr(1), pmgenmap(1), pminfo(1), pmrep(1),
752 pmstat(1), pmstore(1), pmval(1), getpwent(3), getgrent(3), pcp.conf(5),
753 and pcp.env(5).
754Performance Co-Pilot PCP PMCD(1)