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

NAME

6       pmcd - performance metrics collector daemon
7

SYNOPSIS

9       pmcd  [-AfQSv?]   [-c config] [-C dirname] [-H hostname] [-i ipaddress]
10       [-l logfile] [-L bytes] [-M certname] [-[n|N] pmnsfile] [-p  port[,port
11       ...]]  [-P passfile] [-q timeout] [-s sockname] [-t timeout] [-T trace‐
12       flag] [-U username] [-x file]
13

DESCRIPTION

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
20       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  instance, the postgresql agent is responsible for reporting infor‐
27       mation relating to the PostgreSQL database, such as the transaction and
28       query counts, indexing and replication statistics, and so on.
29
30       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
35       Note that if a PDU exchange with an agent times out, the agent has vio‐
36       lated the requirement that it delivers metrics with little or no delay.
37       This is deemed a protocol failure and the agent  is  disconnected  from
38       pmcd.  Any subsequent requests for information from the agent will fail
39       with a status indicating that there is no agent to provide it.
40
41       It is possible to specify access control to pmcd based on users, groups
42       and hosts.  This allows one to prevent users, groups of users, and cer‐
43       tain hosts from accessing the metrics provided by pmcd and is described
44       in more detail in the access control section below.
45

OPTIONS

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

CONFIGURATION

227       On  startup  pmcd  looks  for  a  configuration  file  named $PCP_PMCD‐
228       CONF_PATH.  This file specifies which agents  cover  which  performance
229       metrics  domains  and how pmcd should make contact with the agents.  An
230       optional section specifying access controls may follow the  agent  con‐
231       figuration data.
232
233       Warning:  pmcd is usually started as part of the boot sequence and runs
234       initially as root.  The configuration file may contain  shell  commands
235       to  create agents, which will be executed by root.  To prevent security
236       breaches the configuration file should be writable only by  root.   The
237       use of absolute path names is also recommended.
238
239       The  case  of  the reserved words in the configuration file is unimpor‐
240       tant, but elsewhere, the case is preserved.
241
242       Blank lines and comments are permitted (even encouraged) in the config‐
243       uration  file.  A comment begins with a ``#'' character and finishes at
244       the end of the line.  A line may be continued by ensuring that the last
245       character on the line is a ``\'' (backslash).  A comment on a continued
246       line ends at the end of the continued line.  Spaces may be included  in
247       lexical  elements  by enclosing the entire element in double quotes.  A
248       double quote preceded by a backslash is always a literal double  quote.
249       A  ``#''  in double quotes or preceded by a backslash is treated liter‐
250       ally rather than as a comment delimiter.  Lexical elements and  separa‐
251       tors are described further in the following sections.
252

AGENT CONFIGURATION

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

ACCESS CONTROL CONFIGURATION

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

AGENT FENCING

625       Preventing  sampling  during the life of a PMDA is sometimes desirable,
626       for example if that sampling impacts on sensitive phases of a scheduled
627       job.   A  temporary  ``fence''  can be raised to block all PMAPI client
628       access to one or more agents in this situation.  This functionality  is
629       provided by the built-in PMCD PMDA and the pmstore(1) command, as in
630
631            # pmstore -i nfsclient,kvm pmcd.agent.fenced 1
632
633       If  the  optional  comma-separated  list of agent names is omitted, all
634       agents will be fenced.  To resume normal operation, the  ``fence''  can
635       be lowered as follows
636
637            # pmstore -i nfsclient,kvm pmcd.agent.fenced 0
638
639       Lowering the fence for all PMDAs at once is performed using
640
641            # pmstore pmcd.agent.fenced 0
642
643       Elevated privileges are required to store to the pmcd.agent.fenced met‐
644       ric.  For additional information, see the  help  text  associated  with
645       this  metric,  which can be accessed using the -T, --helptext option to
646       pminfo(1).
647

RECONFIGURING PMCD

649       If the configuration file has been  changed  or  if  an  agent  is  not
650       responding because it has terminated or the PMNS has been changed, pmcd
651       may be reconfigured by sending it a SIGHUP, as in
652
653            # pmsignal -a -s HUP pmcd
654
655       When pmcd receives a SIGHUP,  it  checks  the  configuration  file  for
656       changes.   If  the  file has been modified, it is reparsed and the con‐
657       tents become the new configuration.  If there are errors in the config‐
658       uration  file,  the existing configuration is retained and the contents
659       of the file are ignored.  Errors are reported in the pmcd log file.
660
661       It also checks the PMNS file and any labels files for changes.  If  any
662       of  these files have been modified, then the PMNS and/or context labels
663       are reloaded.  Use of tail(1) on the  log  file  is  recommended  while
664       reconfiguring pmcd.
665
666       If the configuration for an agent has changed (any parameter except the
667       agent's label is different), the agent is restarted.  Agents whose con‐
668       figurations  do  not change are not restarted.  Any existing agents not
669       present in the new configuration are terminated.  Any  deceased  agents
670       are that are still listed are restarted.
671
672       Sometimes  it  is  necessary to restart an agent that is still running,
673       but malfunctioning.  Simply stop the agent  (e.g.  using  SIGTERM  from
674       pmsignal(1)), then send pmcd a SIGHUP, which will cause the agent to be
675       restarted.
676

STARTING AND STOPPING PMCD

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

CAVEATS

724       pmcd  does  not  explicitly  terminate  its  children (agents), it only
725       closes their pipes.  If an agent never checks for a closed pipe it  may
726       not terminate.
727
728       The  configuration  file  parser will only read lines of less than 1200
729       characters.  This is intended to prevent accidents with binary files.
730
731       The timeouts controlled by the -t option apply to IPC between pmcd  and
732       the  PMDAs  it spawns.  This is independent of settings of the environ‐
733       ment  variables  PMCD_CONNECT_TIMEOUT  and  PMCD_REQUEST_TIMEOUT   (see
734       PCPIntro(1))  which  may  be  used respectively to control timeouts for
735       client applications trying to connect to pmcd  and  trying  to  receive
736       information from pmcd.
737

DIAGNOSTICS

739       If  pmcd is already running the message "Error: OpenRequestSocket bind:
740       Address may already be in use" will appear.  This may  also  appear  if
741       pmcd  was  shutdown with an outstanding request from a client.  In this
742       case, a request socket has been left in the TIME_WAIT state  and  until
743       the  system  closes  it down (after some timeout period) it will not be
744       possible to run pmcd.
745
746       In addition to the standard PCP debugging  flags,  see  pmdbg(1),  pmcd
747       currently  uses  the  options: appl0 for tracing I/O and termination of
748       agents, appl1 for tracing access control and appl2 for tracing the con‐
749       figuration file scanner and parser.
750

FILES

752       $PCP_PMCDCONF_PATH
753            default configuration file
754
755       $PCP_PMCDCONF_PATH.access
756            optional access control specification file
757
758       $PCP_PMCDOPTIONS_PATH
759            command  line  options to pmcd when launched from $PCP_RC_DIR/pmcd
760            All the command line option lines should start with  a  hyphen  as
761            the first character.
762
763       $PCP_SYSCONFIG_DIR/pmcd
764            additional  environment  variables that will be set when pmcd exe‐
765            cutes.  Only settings of the form  "PMCD_VARIABLE=value"  will  be
766            honoured.
767
768       $PCP_SYSCONF_DIR/labels.conf
769            settings related to labels used globally throughout the PMCS.
770
771       $PCP_SYSCONF_DIR/labels
772            directory  of  files containing the global metric labels that will
773            be set for every client  context  created  by  pmcd.   File  names
774            starting  with  a ``.'' are ignored, and files ending in ``.json''
775            are ``JSONB'' formatted name:value pairs.  The merged set  can  be
776            queried  via  the  pmcd.labels metric.  Context labels are applied
777            universally to all metrics.
778
779       $PCP_SYSCONF_DIR/labels/optional
780            directory of files containing the global metric labels  that  will
781            be  set  for  every  client context created by pmcd, but which are
782            flagged as optional.  These labels are exactly the same  as  other
783            context  labels except that they are not used in time series iden‐
784            tifier calculations.
785
786       ./pmcd.log
787            (or $PCP_LOG_DIR/pmcd/pmcd.log when started automatically)
788            All messages and diagnostics are directed here.
789
790       $PCP_RUN_DIR/pmcd.pid
791            contains an ascii decimal representation  of  the  process  ID  of
792            pmcd, when it's running.
793
794       /etc/pki/nssdb
795            default  Network  Security  Services  (NSS)  certificate  database
796            directory, used for  optional  Secure  Socket  Layer  connections.
797            This  database  can  be created and queried using the NSS certutil
798            tool, amongst others.
799
800       /etc/passwd
801            user names, user identifiers and primary group  identifiers,  used
802            for access control specifications
803
804       /etc/groups
805            group  names, group identifiers and group members, used for access
806            control specifications
807

ENVIRONMENT

809       The following variables are set in $PCP_SYSCONFIG_DIR/pmcd.
810
811       In addition to the PCP environment variables described in the PCP ENVI‐
812       RONMENT section below, the PMCD_PORT variable is also recognised as the
813       TCP/IP  port  for  incoming  connections  (default  44321),   and   the
814       PMCD_SOCKET  variable is also recognised as the path to be used for the
815       Unix domain socket.
816
817       If set to the value 1, the PMCD_LOCAL environment variable  will  cause
818       pmcd  to run in a localhost-only mode of operation, where it binds only
819       to the  loopback  interface.   The  pmcd.feature.local  metric  can  be
820       queried to determine if pmcd is running in this mode.
821
822       The  PMCD_MAXPENDING variable can be set to indicate the maximum length
823       to which the queue of pending client connections may grow.
824
825       The PMCD_ROOT_AGENT variable controls whether or not pmcd  or  pmdaroot
826       (when  available),  start  subsequent  pmdas.   When  set to a non-zero
827       value, pmcd will opt to have pmdaroot start, and stop, PMDAs.
828
829       The PMCD_RESTART_AGENTS variable determines the behaviour  of  pmcd  in
830       the  presence of child PMDAs that have been observed to exit (this is a
831       typical response in the presence of very large, usually domain-induced,
832       PDU  latencies).   When  set  to a non-zero value, pmcd will attempt to
833       restart such PMDAS once every minute.  When set to zero,  it  uses  the
834       original behaviour of just logging the failure.
835

PCP ENVIRONMENT

837       Environment variables with the prefix PCP_ are used to parameterize the
838       file and directory names used by PCP.  On each installation,  the  file
839       /etc/pcp.conf  contains  the  local  values  for  these variables.  The
840       $PCP_CONF variable may be used to specify an alternative  configuration
841       file, as described in pcp.conf(5).
842
843       For environment variables affecting PCP tools, see pmGetOptions(3).
844

SEE ALSO

846       PCPIntro(1),  pmdbg(1),  pmerr(1),  pmgenmap(1),  pminfo(1),  pmrep(1),
847       pmstat(1),    pmstore(1),    pmval(1),    getpwent(3),     getgrent(3),
848       labels.conf(5), pcp.conf(5), pcp.env(5) and PMNS(5).
849
850
851
852Performance Co-Pilot                  PCP                              PMCD(1)
Impressum