1PMCD(1)                     General Commands Manual                    PMCD(1)
2
3
4

NAME

6       pmcd - performance metrics collector daemon
7

SYNOPSIS

9       pmcd  [-AfQSv?]   [-c config] [-H hostname] [-i ipaddress] [-l logfile]
10       [-L bytes] [-[n|N] pmnsfile] [-p port[,port  ...]]   [-q  timeout]  [-s
11       sockname] [-t timeout] [-T traceflag] [-U username] [-x file]
12

DESCRIPTION

14       pmcd  is  the  collector  used  by the Performance Co-Pilot (see PCPIn‐
15       tro(1)) to gather performance metrics on a system.  As  a  rule,  there
16       must  be  an  instance  of pmcd running on a system for any performance
17       metrics to be available to the PCP.
18
19       pmcd accepts connections from client applications running either on the
20       same  machine  or remotely and provides them with metrics and other re‐
21       lated information from the machine that pmcd  is  executing  on.   pmcd
22       delegates most of this request servicing to a collection of Performance
23       Metrics Domain Agents (or just agents), where each agent is responsible
24       for  a  particular  group of metrics, known as the domain of the agent.
25       For instance, the postgresql agent is responsible for reporting  infor‐
26       mation relating to the PostgreSQL database, such as the transaction and
27       query counts, indexing and replication statistics, and so on.
28
29       The agents may be processes started by pmcd, independent  processes  or
30       Dynamic Shared Objects (DSOs, see dlopen(3)) attached to pmcd's address
31       space.  The configuration section below describes  how  connections  to
32       agents are specified.
33
34       Note that if a PDU exchange with an agent times out, the agent has vio‐
35       lated the requirement that it delivers metrics with little or no delay.
36       This  is  deemed  a protocol failure and the agent is disconnected from
37       pmcd.  Any subsequent requests for information from the agent will fail
38       with a status indicating that there is no agent to provide it.
39
40       It is possible to specify access control to pmcd based on users, groups
41       and hosts.  This allows one to prevent users, groups of users, and cer‐
42       tain hosts from accessing the metrics provided by pmcd and is described
43       in more detail in the access control section below.
44

OPTIONS

46       The available command line options are:
47
48       -A   Disable service advertisement.  By default,  pmcd  will  advertise
49            its  presence  on the network using any available mechanisms (such
50            as Avahi/DNS-SD), assisting remote monitoring tools  with  finding
51            it.  These mechanisms are disabled with this option.
52
53       -c config, --config=config
54            On startup pmcd uses a configuration file from either the $PCP_PM‐
55            CDCONF_PATH, configuration variable in /etc/pcp.conf, or an  envi‐
56            ronment  variable  of the same name.  However, these values may be
57            overridden with config using this option.  The format of this con‐
58            figuration file is described below.
59
60       -f, --foreground
61            By  default  pmcd is started as a daemon.  The -f option indicates
62            that it should run in the foreground.  This is  most  useful  when
63            trying to diagnose problems with misbehaving agents.
64
65       -H hostname, --hostname=hostname
66            This  option can be used to set the hostname that pmcd will use to
67            represent this instance of itself.  This is used by  client  tools
68            like pmlogger(1) when reporting on the (possibly remote) host.  If
69            this option is not set, the pmcd.hostname metric will  match  that
70            returned by pmhostname(1).  Refer to the manual page for that tool
71            for full details on how the hostname is evaluated.
72
73       -i ipaddress, --interface=ipaddress
74            This option is usually only used on hosts with more than one  net‐
75            work  interface.  If no -i options are specified pmcd accepts con‐
76            nections made to any of its  host's  IP  (Internet  Protocol)  ad‐
77            dresses.   The  -i  option is used to specify explicitly an IP ad‐
78            dress that connections should be accepted on.  ipaddress should be
79            in the standard dotted form (e.g. 100.23.45.6).  The -i option may
80            be used multiple times to define a list of IP addresses.   Connec‐
81            tions made to any other IP addresses the host has will be refused.
82            This can be used to limit connections to one network interface  if
83            the  host  is  a  network  gateway.  It is also useful if the host
84            takes over the IP address of another host  that  has  failed.   In
85            such a situation only the standard IP addresses of the host should
86            be given (not the ones inherited from the failed host).  This  al‐
87            lows  PCP applications to determine that a host has failed, rather
88            than connecting to the host that has assumed the identity  of  the
89            failed host.
90
91       -l logfile, --log=logfile
92            By  default  a log file named pmcd.log is written in the directory
93            $PCP_LOG_DIR/pmcd.  The -l option causes the log file to be  writ‐
94            ten  to logfile instead of the default.  If the log file cannot be
95            created or is not writable, output is written to the standard  er‐
96            ror instead.
97
98       -L bytes
99            PDUs  received by pmcd from monitoring clients are restricted to a
100            maximum size of 65536 bytes by default to defend against Denial of
101            Service  attacks.  The -L option may be used to change the maximum
102            incoming PDU size.
103
104       -n pmnsfile, --namespace=pmnsfile
105            Normally pmcd loads the default  Performance  Metrics  Name  Space
106            (PMNS)  from  $PCP_VAR_DIR/pmns/root,  however if the -n option is
107            specified an alternative namespace is loaded from the  file  pmns‐
108            file.
109
110       -N pmnsfile, --uniqnames=pmnsfile
111            Same  function as -n, except for the handling of duplicate Perfor‐
112            mance Metric Identifiers (PMIDs) in pmnsfile - duplicate names are
113            allowed with -n but they are not allowed with -N.
114
115       -p port, --port=port
116            Specify port to listen on.  By default port 44321 is used.
117
118       -q timeout
119            The  pmcd to agent version exchange protocol (new in PCP 2.0 - in‐
120            troduced to provide backward compatibility) uses this  timeout  to
121            specify  how long pmcd should wait before assuming that no version
122            response is coming from an agent.  If this timeout is reached, the
123            agent  is assumed to be an agent which does not understand the PCP
124            2.0 protocol.  The default timeout interval is five  seconds,  but
125            the  -q  option allows an alternative timeout interval (which must
126            be greater than zero) to be specified.  The unit of time  is  sec‐
127            onds.
128
129       -Q, --remotecert
130            Require that all remote client connections provide a certficate.
131
132       -s sockname, --socket=sockname
133            Specify the path to a local unix domain socket (for platforms sup‐
134            porting  this  socket  family  only).   The   default   value   is
135            $PCP_RUN_DIR/pmcd.socket.
136
137       -S, --reqauth
138            Require  that  all  client  connections  provide user credentials.
139            This means that only unix domain sockets, or authenticated connec‐
140            tions  are  permitted  (requires  secure sockets support).  If any
141            user or group access control requirements  are  specified  in  the
142            pmcd  configuration file, then this mode of operation is automati‐
143            cally entered, whether the -S flag is specified or not.
144
145       -t timeout
146            To prevent misbehaving clients or agents from hanging  the  entire
147            Performance  Metrics  Collection System (PMCS), pmcd uses timeouts
148            on PDU exchanges with clients and agents running as processes.  By
149            default  the  timeout interval is five seconds.  The -t option al‐
150            lows an alternative timeout interval in seconds to  be  specified.
151            If  timeout is zero, timeouts are turned off.  It is almost impos‐
152            sible to use the debugger interactively on an agent  unless  time‐
153            outs have been turned off for its "parent" pmcd.
154
155            Once  pmcd  is running, the timeout may be dynamically modified by
156            storing an integer value (the timeout in seconds) into the  metric
157            pmcd.control.timeout via pmstore(1).
158
159       -T traceflag, --trace=traceflag
160            To  assist  with error diagnosis for agents and/or clients of pmcd
161            that are not behaving correctly, an internal event tracing  mecha‐
162            nism  is  supported within pmcd.  The value of traceflag is inter‐
163            preted as a bit field with the following control functions:
164
165            1   enable client connection tracing
166            2   enable PDU tracing
167            256 unbuffered event tracing
168
169            By default, event tracing is buffered using a circular buffer that
170            is  over-written  as  new events are recorded.  The default buffer
171            size holds the last 20 events, although this number may  be  over-
172            ridden   by  using  pmstore(1)  to  modify  the  metric  pmcd.con‐
173            trol.tracebufs.
174
175            Similarly once pmcd is running, the event tracing control  may  be
176            dynamically modified by storing 1 (enable) or 0 (disable) into the
177            metrics    pmcd.control.traceconn,    pmcd.control.tracepdu    and
178            pmcd.control.tracenobuf.   These metrics map to the bit fields as‐
179            sociated with the traceflag argument for the -T option.
180
181            When operating in buffered mode, the event trace  buffer  will  be
182            dumped whenever an agent connection is terminated by pmcd, or when
183            any value is stored into the metric pmcd.control.dumptrace via pm‐
184            store(1).
185
186            In unbuffered mode, every event will be reported when it occurs.
187
188       -U username, --username=USER
189            User account under which to run pmcd.  The default is the unprivi‐
190            leged "pcp" account in current versions of PCP, but in older  ver‐
191            sions the superuser account ("root") was used by default.
192
193       -v, --verify
194            Verify  the  pmcd configuration file, reporting on any errors then
195            exiting with a status indicating verification success or failure.
196
197       -x file
198            Before the pmcd logfile can be opened, pmcd may encounter a  fatal
199            error which prevents it from starting.  By default, the output de‐
200            scribing this error is sent to /dev/tty but it may  redirected  to
201            file.
202
203       -?, --help
204            Display usage message and exit.
205

CONFIGURATION

207       On  startup  pmcd  looks  for  a  configuration  file  named $PCP_PMCD‐
208       CONF_PATH.  This file specifies which agents  cover  which  performance
209       metrics  domains  and how pmcd should make contact with the agents.  An
210       optional section specifying access controls may follow the  agent  con‐
211       figuration data.
212
213       Warning:  pmcd is usually started as part of the boot sequence and runs
214       initially as root.  The configuration file may contain  shell  commands
215       to  create agents, which will be executed by root.  To prevent security
216       breaches the configuration file should be writable only by  root.   The
217       use of absolute path names is also recommended.
218
219       The  case  of  the reserved words in the configuration file is unimpor‐
220       tant, but elsewhere, the case is preserved.
221
222       Blank lines and comments are permitted (even encouraged) in the config‐
223       uration  file.  A comment begins with a ``#'' character and finishes at
224       the end of the line.  A line may be continued by ensuring that the last
225       character on the line is a ``\'' (backslash).  A comment on a continued
226       line ends at the end of the continued line.  Spaces may be included  in
227       lexical  elements  by enclosing the entire element in double quotes.  A
228       double quote preceded by a backslash is always a literal double  quote.
229       A  ``#''  in double quotes or preceded by a backslash is treated liter‐
230       ally rather than as a comment delimiter.  Lexical elements and  separa‐
231       tors are described further in the following sections.
232

AGENT CONFIGURATION

234       Each  line of the agent configuration section of the configuration file
235       contains details of how to connect pmcd to one of its agents and speci‐
236       fies  which  metrics  domain the agent deals with.  An agent may be at‐
237       tached as a DSO, or via a socket, or a pair of pipes.
238
239       Each line of the agent configuration section of the configuration  file
240       must  be  either  an  agent  specification, a comment, or a blank line.
241       Lexical elements are separated by whitespace characters, however a sin‐
242       gle  agent  specification may not be broken across lines unless a back‐
243       slash is used to continue the line.
244
245       Each agent specification must start with a textual label (string)  fol‐
246       lowed  by an integer in the range 1 to 510.  The label is a tag used to
247       refer to the agent and the integer specifies the domain for  which  the
248       agent  supplies data.  This domain identifier corresponds to the domain
249       portion of the PMIDs handled by the agent.   Each  agent  must  have  a
250       unique label and domain identifier.
251
252       For DSO agents a line of the form:
253
254              label domain-no dso entry-point path
255
256       should appear.  Where,
257
258       label         is a string identifying the agent
259       domain-no     is  an  unsigned integer specifying the agent's domain in
260                     the range 1 to 510
261       entry-point   is the name of an initialization function which  will  be
262                     called when the DSO is loaded
263       path          designates  the  location of the DSO and this is expected
264                     to be an absolute pathname.  pmcd is only  able  to  load
265                     DSO  agents  that have the same simabi (Subprogram Inter‐
266                     face Model ABI, or calling conventions) as it does  (i.e.
267                     only one of the simabi versions will be applicable).  The
268                     simabi version of a running pmcd  may  be  determined  by
269                     fetching pmcd.simabi.  Alternatively, the file(1) command
270                     may be used to determine the simabi version from the pmcd
271                     executable.
272
273                     For  a  relative  path the environment variable PMCD_PATH
274                     defines a colon (:)  separated  list  of  directories  to
275                     search  when trying to locate the agent DSO.  The default
276                     search path is $PCP_SHARE_DIR/lib:/usr/pcp/lib.
277
278       For agents providing socket connections, a line of the form
279
280              label domain-no socket addr-family address [ command ]
281
282       should appear.  Where,
283
284       label         is a string identifying the agent
285       domain-no     is an unsigned integer specifying the agent's  domain  in
286                     the range 1 to 510
287       addr-family   designates whether the socket is in the AF_INET, AF_INET6
288                     or AF_UNIX domain, and the corresponding values for  this
289                     parameter are inet, ipv6 and unix respectively.
290       address       specifies the address of the socket within the previously
291                     specified addr-family.  For  unix  sockets,  the  address
292                     should be the name of an agent's socket on the local host
293                     (a valid address for the UNIX domain).  For inet and ipv6
294                     sockets,  the  address  may  be either a port number or a
295                     port name which may be used to connect to an agent on the
296                     local  host.   There is no syntax for specifying an agent
297                     on a remote host as a pmcd deals only with agents on  the
298                     same machine.
299       command       is  an  optional parameter used to specify a command line
300                     to start the agent when pmcd initializes.  If command  is
301                     not  present,  pmcd  assumes that the specified agent has
302                     already been created.  The command is considered to start
303                     from  the  first non-white character after the socket ad‐
304                     dress and finish at the next newline that isn't  preceded
305                     by  a  backslash.   After a fork(2) the command is passed
306                     unmodified to execve(2) to instantiate the agent.
307
308       For agents interacting with the pmcd via stdin/stdout, a  line  of  the
309       form:
310
311              label domain-no pipe protocol command
312
313       should appear.  Where,
314
315       label         is a string identifying the agent
316       domain-no     is an unsigned integer specifying the agent's domain
317       protocol      The value for this parameter should be binary.
318
319                     Additionally,  the protocol can include the notready key‐
320                     word to indicate that the agent must be marked as not be‐
321                     ing  ready to process requests from pmcd.  The agent will
322                     explicitly notify the pmcd when it is  ready  to  process
323                     the requests by sending a PM_ERR_PMDAREADY PDU.  For fur‐
324                     ther details of this protocol, including a description of
325                     the  IPC  parameters  that can be specified in a PMDA In‐
326                     stall script with the ipc_prot parameter, see  the  rele‐
327                     vant section in PMDA(3).
328
329       command       specifies  a  command  line  to start the agent when pmcd
330                     initializes.  Note that command is  mandatory  for  pipe-
331                     based  agents.   The  command is considered to start from
332                     the first non-white character after the protocol  parame‐
333                     ter and finish at the next newline that isn't preceded by
334                     a backslash.  After a fork(2) the command is  passed  un‐
335                     modified to execve(2) to instantiate the agent.
336

ACCESS CONTROL CONFIGURATION

338       The  access  control section of the configuration file is optional, but
339       if present it must follow the agent configuration data.   The  case  of
340       reserved  words  is  ignored, but elsewhere case is preserved.  Lexical
341       elements in the access control section are separated by  whitespace  or
342       the  special  delimiter  characters: square brackets (``['' and ``]''),
343       braces (``{'' and ``}''), colon (``:''), semicolon  (``;'')  and  comma
344       (``,'').   The  special  characters  are  not treated as special in the
345       agent configuration section.  Lexical elements may  be  quoted  (double
346       quotes) as necessary.
347
348       The  access  control  section of the file must start with a line of the
349       form:
350
351       [access]
352
353       In addition to (or instead of) the access section in the pmcd  configu‐
354       ration  file,  access  control specifications are also read from a file
355       having the same name as the pmcd configuration file, but with '.access'
356       appended to the name.  This optional file must not contain the [access]
357       keyword.
358
359       Leading and trailing whitespace may appear around and within the brack‐
360       ets  and  the case of the access keyword is ignored.  No other text may
361       appear on the line except a trailing comment.
362
363       Following this line, the remainder of  the  configuration  file  should
364       contain  lines  that allow or disallow operations from particular hosts
365       or groups of hosts.
366
367       There are two kinds of operations that occur via pmcd:
368
369       fetch          allows retrieval of information from pmcd.  This may  be
370                      information  about  a  metric (e.g. its description, in‐
371                      stance domain, labels or help text) or  a  value  for  a
372                      metric.  See pminfo(1) for further information.
373
374       store          allows  pmcd to be used to store metric values in agents
375                      that permit store operations.  This may  be  the  actual
376                      value  of the metric (e.g. resetting a counter to zero).
377                      Alternatively, it may be a value used by the PMDA to in‐
378                      troduce  a  change  to some aspect of monitoring of that
379                      metric (e.g. server side  event  filtering)  -  possibly
380                      even  only  for  the  active  client tool performing the
381                      store operation, and not  others.   See  pmstore(1)  for
382                      further information.
383
384       Access  to pmcd can be granted in three ways - by user, group of users,
385       or at a host level.  In the latter, all users on a host are granted the
386       same level of access, unless the user or group access control mechanism
387       is also in use.
388
389       User names and group names will be verified using the local /etc/passwd
390       and  /etc/groups files (or an alternative directory service), using the
391       getpwent(3) and getgrent(3) routines.
392
393       Hosts may be identified by name, IP address, IPv6  address  or  by  the
394       special  host  specifications ``"unix:"'' or ``"local:"''.  ``"unix:"''
395       refers to pmcd's unix domain socket, on  supported  platforms.   ``"lo‐
396       cal:"'' is equivalent to specifying ``"unix:"'' and ``localhost``.
397
398       Wildcards  may also be specified by ending the host identifier with the
399       single wildcard character ``*'' as the last-given component of  an  ad‐
400       dress.  The wildcard ``".*"'' refers to all inet (IPv4) addresses.  The
401       wildcard ``":*"'' refers to all IPv6 addresses.  If  an  IPv6  wildcard
402       contains  a  ``::'' component, then the final ``*'' refers to the final
403       16 bits of the address only, otherwise it refers to the  remaining  un‐
404       specified bits of the address.
405
406       The  wildcard  ``*'' refers to all users, groups or host addresses, in‐
407       cluding ``"unix:"''.  Names of users, groups or hosts may not be  wild‐
408       carded.
409
410       The following are all valid host identifiers:
411
412            boing
413            localhost
414            giggle.melbourne.sgi.com
415            129.127.112.2
416            129.127.114.*
417            129.*
418            .*
419            fe80::223:14ff:feaf:b62c
420            fe80::223:14ff:feaf:*
421            fe80:*
422            :*
423            "unix:"
424            "local:"
425            *
426
427       The following are not valid host identifiers:
428
429            *.melbourne
430            129.127.*.*
431            129.*.114.9
432            129.127*
433            fe80::223:14ff:*:*
434            fe80::223:14ff:*:b62c
435            fe80*
436
437       The  first  example  is not allowed because only (numeric) IP addresses
438       may contain a wildcard.  The second and fifth examples  are  not  valid
439       because there is more than one wildcard character.  The third and sixth
440       contain an embedded wildcard, the fourth and seventh  have  a  wildcard
441       character  that is not the last component of the address (the last com‐
442       ponents are 127* and fe80* respectively).
443
444       The name localhost is given special treatment to make the  behavior  of
445       host  wildcarding  consistent.  Rather than being 127.0.0.1 and ::1, it
446       is mapped to the primary inet and IPv6 addresses  associated  with  the
447       name of the host on which pmcd is running.  Beware of this when running
448       pmcd on multi-homed hosts.
449
450       Access for users, groups or hosts are allowed or disallowed by specify‐
451       ing statements of the form:
452
453              allow users userlist : operations ;
454              disallow users userlist : operations ;
455              allow groups grouplist : operations ;
456              disallow groups grouplist : operations ;
457              allow hosts hostlist : operations ;
458              disallow hosts hostlist : operations ;
459
460       list          userlist,  grouplist  and  hostlist  are  comma separated
461                     lists of one or more users, groups or host identifiers.
462
463       operations    is a comma separated list  of  the  operation  types  de‐
464                     scribed  above,  all  (which  allows/disallows all opera‐
465                     tions), or all except operations (which  allows/disallows
466                     all operations except those listed).
467
468       Either  plural  or  singular forms of users, groups, and hosts keywords
469       are allowed.  If this keyword is omitted, a default of  hosts  will  be
470       used.  This behaviour is for backward-compatibility only, it is prefer‐
471       able to be explicit.
472
473       Where no specific allow or disallow statement applies to an  operation,
474       the default is to allow the operation from all users, groups and hosts.
475       In the trivial case when there is no access control section in the con‐
476       figuration  file,  all operations from all users, groups, and hosts are
477       permitted.
478
479       If a new connection to pmcd is attempted by a user, group or host  that
480       is  not  permitted  to  perform  any operations, the connection will be
481       closed immediately after an error response PM_ERR_PERMISSION  has  been
482       sent to the client attempting the connection.
483
484       Statements  with  the  same  level  of wildcarding specifying identical
485       hosts may not contradict each other.  For example if a host named clank
486       had  an IP address of 129.127.112.2, specifying the following two rules
487       would be erroneous:
488
489            allow host clank : fetch, store;
490            disallow host 129.127.112.2 : all except fetch;
491
492       because they both refer to the same host, but disagree  as  to  whether
493       the fetch operation is permitted from that host.
494
495       Statements  containing  more specific host specifications override less
496       specific ones according to the level of  wildcarding.   For  example  a
497       rule of the form
498
499            allow host clank : all;
500
501       overrides
502
503            disallow host 129.127.112.* : all except fetch;
504
505       because the former contains a specific host name (equivalent to a fully
506       specified IP address), whereas the latter has a wildcard.  In turn, the
507       latter would override
508
509            disallow host * : all;
510
511       It is possible to limit the number of connections from a user, group or
512       host to pmcd.  This may be done by adding a clause of the form
513
514              maximum n connections
515
516       to the operations list of an allow statement.  Such a clause may not be
517       used in a disallow statement.  Here, n is the maximum number of connec‐
518       tions that will be accepted from the user, group or host  matching  the
519       identifier(s) used in the statement.
520
521       An  access control statement with a list of user, group or host identi‐
522       fiers is equivalent to a set of access control  statements,  with  each
523       specifying one of the identifiers in the list and all with the same ac‐
524       cess controls (both permissions and connection limits).  A group should
525       be  used  if you want users to contribute to a shared connection limit.
526       A wildcard should be used if you want hosts to contribute to  a  shared
527       connection limit.
528
529       When  a  new client requests a connection, and pmcd has determined that
530       the client has permission to connect, it searches the matching list  of
531       access control statements for the most specific match containing a con‐
532       nection limit.  For brevity, this will be called  the  limiting  state‐
533       ment.   If there is no limiting statement, the client is granted a con‐
534       nection.  If there is a limiting  statement  and  the  number  of  pmcd
535       clients  with user ID, group ID, or IP addresses that match the identi‐
536       fier in the limiting statement is less than the connection limit in the
537       statement,  the  connection is allowed.  Otherwise the connection limit
538       has been reached and the client is refused a connection.
539
540       Group access controls and the wildcarding  in  host  identifiers  means
541       that once pmcd actually accepts a connection from a client, the connec‐
542       tion may contribute to the current connection count of  more  than  one
543       access  control  statement  - the client's host may match more than one
544       access control statement, and similarly the user ID may be in more than
545       one group.  This may be significant for subsequent connection requests.
546
547       Note  that  pmcd enters a mode where it runs effectively with a higher-
548       level of security as soon as a user or group access control section  is
549       added  to  the  configuration.  In this mode only authenticated connec‐
550       tions are allowed - either from a SASL authenticated connection,  or  a
551       Unix  domain socket (which implicitly passes client credentials).  This
552       is the same mode that is entered explicitly using the -S  option.   As‐
553       suming permission is allowed, one can determine whether pmcd is running
554       in this mode by querying the value of  the  pmcd.feature.creds_required
555       metric.
556
557       Note  also  that  because  most  specific match semantics are used when
558       checking the connection limit, for the host-based access control  case,
559       priority  is  given to clients with more specific host identifiers.  It
560       is also possible to exceed connection limits in some situations.   Con‐
561       sider the following:
562
563              allow host clank : all, maximum 5 connections;
564              allow host * : all except store, maximum 2 connections;
565
566       This  says  that  only 2 client connections at a time are permitted for
567       all hosts other than "clank", which is permitted 5.  If a  client  from
568       host "boing" is the first to connect to pmcd, its connection is checked
569       against the second statement (that is the most specific  match  with  a
570       connection  limit).   As  there are no other clients, the connection is
571       accepted and contributes towards the limit for only the  second  state‐
572       ment  above.   If the next client connects from "clank", its connection
573       is checked against the limit for the first  statement.   There  are  no
574       other  connections  from  "clank", so the connection is accepted.  Once
575       this connection is accepted, it counts towards both statements'  limits
576       because "clank" matches the host identifier in both statements.  Remem‐
577       ber that the decision to accept a new connection is made using only the
578       most  specific  matching  access  control  statement  with a connection
579       limit.  Now, the connection limit for the  second  statement  has  been
580       reached.   Any  connections  from  hosts other than "clank" will be re‐
581       fused.
582
583       If instead, pmcd with no clients saw three successive  connections  ar‐
584       rived  from  "boing", the first two would be accepted and the third re‐
585       fused.  After that, if a connection was requested from "clank" it would
586       be  accepted.   It  matches the first statement, which is more specific
587       than the second, so the connection limit in the first is used to deter‐
588       mine that the client has the right to connect.  Now there are 3 connec‐
589       tions contributing to the second statement's  connection  limit.   Even
590       though the connection limit for the second statement has been exceeded,
591       the earlier connections from "boing" are  maintained.   The  connection
592       limit is only checked at the time a client attempts a connection rather
593       than being re-evaluated every time a new client connects to pmcd.
594
595       This gentle scheme is designed to allow reasonable limits to be imposed
596       on a first come first served basis, with specific exceptions.
597
598       As  illustrated  by the example above, a client's connection is honored
599       once it has been accepted.  However, pmcd reconfiguration (see the next
600       section)  re-evaluates  all the connection counts and will cause client
601       connections to be dropped where connection limits have been exceeded.
602

AGENT FENCING

604       Preventing sampling during the life of a PMDA is  sometimes  desirable,
605       for example if that sampling impacts on sensitive phases of a scheduled
606       job.  A temporary ``fence'' can be raised to block all PMAPI client ac‐
607       cess  to  one  or more agents in this situation.  This functionality is
608       provided by the built-in PMCD PMDA and the pmstore(1) command, as in
609
610            # pmstore -i nfsclient,kvm pmcd.agent.fenced 1
611
612       If the optional comma-separated list of agent  names  is  omitted,  all
613       agents  will  be fenced.  To resume normal operation, the ``fence'' can
614       be lowered as follows
615
616            # pmstore -i nfsclient,kvm pmcd.agent.fenced 0
617
618       Lowering the fence for all PMDAs at once is performed using
619
620            # pmstore pmcd.agent.fenced 0
621
622       Elevated privileges are required to store to the pmcd.agent.fenced met‐
623       ric.   For  additional  information,  see the help text associated with
624       this metric, which can be accessed using the -T, --helptext  option  to
625       pminfo(1).
626

RECONFIGURING PMCD

628       If  the  configuration  file has been changed or if an agent is not re‐
629       sponding because it has terminated or the PMNS has been  changed,  pmcd
630       may be reconfigured by sending it a SIGHUP, as in
631
632            # pmsignal -a -s HUP pmcd
633
634       When  pmcd  receives  a  SIGHUP,  it  checks the configuration file for
635       changes.  If the file has been modified, it is reparsed  and  the  con‐
636       tents become the new configuration.  If there are errors in the config‐
637       uration file, the existing configuration is retained and  the  contents
638       of the file are ignored.  Errors are reported in the pmcd log file.
639
640       It  also checks the PMNS file and any labels files for changes.  If any
641       of these files have been modified, then the PMNS and/or context  labels
642       are  reloaded.  Use of tail(1) on the log file is recommended while re‐
643       configuring pmcd.
644
645       If the configuration for an agent has changed (any parameter except the
646       agent's label is different), the agent is restarted.  Agents whose con‐
647       figurations do not change are not restarted.  Any existing  agents  not
648       present  in  the new configuration are terminated.  Any deceased agents
649       are that are still listed are restarted.
650
651       Sometimes it is necessary to restart an agent that  is  still  running,
652       but malfunctioning.  Simply stop the agent (e.g. using SIGTERM from pm‐
653       signal(1)), then send pmcd a SIGHUP, which will cause the agent  to  be
654       restarted.
655

STARTING AND STOPPING PMCD

657       Normally,  pmcd  is started automatically at boot time and stopped when
658       the system is being brought down.  Under certain  circumstances  it  is
659       necessary  to  start or stop pmcd manually.  To do this one must become
660       superuser and type
661
662            # $PCP_RC_DIR/pmcd start
663
664       to start pmcd, or
665
666            # $PCP_RC_DIR/pmcd stop
667
668       to stop pmcd.  Starting pmcd when it is already running is the same  as
669       stopping it and then starting it again.
670
671       Sometimes  it  may be necessary to restart pmcd during another phase of
672       the boot process.  Time-consuming parts of the boot process  are  often
673       put  into the background to allow the system to become available sooner
674       (e.g. mounting huge databases).  If an agent run by pmcd requires  such
675       a  task  to  complete  before  it  can run properly, it is necessary to
676       restart or reconfigure pmcd after the task  completes.   Consider,  for
677       example,  the case of mounting a database in the background while boot‐
678       ing.  If the PMDA which provides the metrics about the database  cannot
679       function  until  the  database  is  mounted  and  available but pmcd is
680       started before the database is ready, the PMDA will fail (however  pmcd
681       will  still  service  requests for metrics from other domains).  If the
682       database is initialized by running a shell script, adding a line to the
683       end  of  the  script  to reconfigure pmcd (by sending it a SIGHUP) will
684       restart the PMDA (if it exited because it couldn't connect to the data‐
685       base).   If the PMDA didn't exit in such a situation it would be neces‐
686       sary to restart pmcd because if the PMDA was still running  pmcd  would
687       not restart it.
688
689       Normally  pmcd  listens  for  client  connections on TCP/IP port number
690       44321 (registered at  http://www.iana.org/).   Either  the  environment
691       variable PMCD_PORT or the -p command line option may be used to specify
692       alternative port number(s) when pmcd is  started;  in  each  case,  the
693       specification  is  a comma-separated list of one or more numerical port
694       numbers.  Should both methods be used or multiple -p options appear  on
695       the  command  line,  pmcd  will listen on the union of the set of ports
696       specified via all -p options and the  PMCD_PORT  environment  variable.
697       If  non-default ports are used with pmcd care should be taken to ensure
698       that PMCD_PORT is also set in the environment of any client application
699       that will connect to pmcd, or that the extended host specification syn‐
700       tax is used (see PCPIntro(1) for details).
701

CAVEATS

703       pmcd does not explicitly  terminate  its  children  (agents),  it  only
704       closes  their pipes.  If an agent never checks for a closed pipe it may
705       not terminate.
706
707       The configuration file parser will only read lines of  less  than  1200
708       characters.  This is intended to prevent accidents with binary files.
709
710       The  timeouts controlled by the -t option apply to IPC between pmcd and
711       the PMDAs it spawns.  This is independent of settings of  the  environ‐
712       ment   variables  PMCD_CONNECT_TIMEOUT  and  PMCD_REQUEST_TIMEOUT  (see
713       PCPIntro(1)) which may be used respectively  to  control  timeouts  for
714       client applications trying to connect to pmcd and trying to receive in‐
715       formation from pmcd.
716

DIAGNOSTICS

718       If pmcd is already running the message "Error: OpenRequestSocket  bind:
719       Address  may  already  be in use" will appear.  This may also appear if
720       pmcd was shutdown with an outstanding request from a client.   In  this
721       case,  a  request socket has been left in the TIME_WAIT state and until
722       the system closes it down (after some timeout period) it  will  not  be
723       possible to run pmcd.
724
725       In  addition  to  the  standard PCP debugging flags, see pmdbg(1), pmcd
726       currently uses the options: appl0 for tracing I/O  and  termination  of
727       agents, appl1 for tracing access control and appl2 for tracing the con‐
728       figuration file scanner and parser.
729

FILES

731       $PCP_PMCDCONF_PATH
732            default configuration file
733
734       $PCP_PMCDCONF_PATH.access
735            optional access control specification file
736
737       $PCP_PMCDOPTIONS_PATH
738            command line options to pmcd when launched  from  $PCP_RC_DIR/pmcd
739            All  the  command  line option lines should start with a hyphen as
740            the first character.
741
742       $PCP_SYSCONFIG_DIR/pmcd
743            Environment variables that will be set when pmcd  executes.   Only
744            settings of the form "PMCD_VARIABLE=value" or "PCP_VARIABLE=value"
745            are honoured.
746
747       $PCP_SYSCONF_DIR/labels.conf
748            settings related to labels used globally throughout the PMCS.
749
750       $PCP_SYSCONF_DIR/labels
751            directory of files containing the global metric labels  that  will
752            be  set  for  every  client  context  created by pmcd.  File names
753            starting with a ``.'' are ignored, and files ending  in  ``.json''
754            are  ``JSONB''  formatted name:value pairs.  The merged set can be
755            queried via the pmcd.labels metric.  Context  labels  are  applied
756            universally to all metrics.
757
758       $PCP_SYSCONF_DIR/labels/optional
759            directory  of  files containing the global metric labels that will
760            be set for every client context created by  pmcd,  but  which  are
761            flagged  as  optional.  These labels are exactly the same as other
762            context labels except that they are not used in time series  iden‐
763            tifier calculations.
764
765       ./pmcd.log
766            (or $PCP_LOG_DIR/pmcd/pmcd.log when started automatically)
767            All messages and diagnostics are directed here.
768
769       $PCP_RUN_DIR/pmcd.pid
770            contains  an  ascii  decimal  representation  of the process ID of
771            pmcd, when it's running.
772
773       /etc/pcp/tls.conf
774            OpenSSL certificate configuration information file, used  for  op‐
775            tional Secure Socket Layer connections.
776
777       /etc/passwd
778            user  names,  user identifiers and primary group identifiers, used
779            for access control specifications
780
781       /etc/groups
782            group names, group identifiers and group members, used for  access
783            control specifications
784

ENVIRONMENT

786       The following variables are set in $PCP_SYSCONFIG_DIR/pmcd.
787
788       In addition to the PCP environment variables described in the PCP ENVI‐
789       RONMENT section below, the PMCD_PORT variable is also recognised as the
790       TCP/IP   port   for  incoming  connections  (default  44321),  and  the
791       PMCD_SOCKET variable is also recognised as the path to be used for  the
792       Unix domain socket.
793
794       If  set  to the value 1, the PMCD_LOCAL environment variable will cause
795       pmcd to run in a localhost-only mode of operation, where it binds  only
796       to  the  loopback  interface.   The  pmcd.feature.local  metric  can be
797       queried to determine if pmcd is running in this mode.
798
799       The PMCD_MAXPENDING variable can be set to indicate the maximum  length
800       to which the queue of pending client connections may grow.
801
802       The  PMCD_ROOT_AGENT  variable controls whether or not pmcd or pmdaroot
803       (when available), start subsequent  pmdas.   When  set  to  a  non-zero
804       value, pmcd will opt to have pmdaroot start, and stop, PMDAs.
805
806       The  PMCD_RESTART_AGENTS  variable  determines the behaviour of pmcd in
807       the presence of child PMDAs that have been observed to exit (this is  a
808       typical response in the presence of very large, usually domain-induced,
809       PDU latencies).  When set to a non-zero value,  pmcd  will  attempt  to
810       restart  such  PMDAS  once every minute.  When set to zero, it uses the
811       original behaviour of just logging the failure.
812

PCP ENVIRONMENT

814       Environment variables with the prefix PCP_ are used to parameterize the
815       file  and  directory names used by PCP.  On each installation, the file
816       /etc/pcp.conf contains the  local  values  for  these  variables.   The
817       $PCP_CONF  variable may be used to specify an alternative configuration
818       file, as described in pcp.conf(5).
819
820       For environment variables affecting PCP tools, see pmGetOptions(3).
821

SEE ALSO

823       PCPIntro(1), pmdbg(1), pmerr(1), pmgenmap(1), pminfo(1), pmrep(1),  pm‐
824       stat(1),    pmstore(1),   pmval(1),   getpwent(3),   getgrent(3),   la‐
825       bels.conf(5), pcp.conf(5), pcp.env(5) and PMNS(5).
826
827
828
829Performance Co-Pilot                  PCP                              PMCD(1)
Impressum