Provided by: pcp_3.8.12ubuntu1_amd64 bug

NAME

       pmcd - performance metrics collector daemon

SYNOPSIS

       pmcd  [-AfS] [-c config] [-C dirname] [-H hostname] [-i ipaddress] [-l logfile] [-L bytes]
       [-[n|N] pmnsfile] [-p port[,port ...]   [-P  passfile]  [-q  timeout]  [-s  sockname]  [-T
       traceflag] [-t timeout] [-U username] [-x file]

DESCRIPTION

       pmcd  is  the  collector  used  by  the  Performance  Co-Pilot (see PCPIntro(1)) to gather
       performance metrics on a system.  As a rule, there must be an instance of pmcd running  on
       a system for any performance metrics to be available to the PCP.

       pmcd  accepts  connections  from client applications running either on the same machine or
       remotely and provides them with metrics and other related  information  from  the  machine
       that  pmcd is executing on.  pmcd delegates most of this request servicing to a collection
       of Performance Metrics Domain Agents (or just agents), where each agent is responsible for
       a  particular  group  of  metrics,  known  as  the  domain  of the agent.  For example the
       postgresql agent is responsible for  reporting  information  relating  to  the  PostgreSQL
       database,  such  as the transaction and query counts, indexing and replication statistics,
       and so on.

       The agents may be processes started by  pmcd,  independent  processes  or  Dynamic  Shared
       Objects (DSOs, see dlopen(3)) attached to pmcd's address space.  The configuration section
       below describes how connections to agents are specified.

       The options to pmcd are as follows.

       -A     Disable service advertisement.  By default, pmcd will advertise its presence on the
              network  using  any  available  mechanisms (such as Avahi/DNS-SD), assisting remote
              monitoring tools with finding it.  These mechanisms are disabled with this option.

       -c config
              On startup pmcd uses a  configuration  file  from  either  the  $PCP_PMCDCONF_PATH,
              configuration  variable  in  /etc/pcp.conf,  or an environment variable of the same
              name.  However, these values may be overridden with config using this option.   The
              format of this configuration file is described below.

       -C dirname
              Specify  the  path  to  the  Network  Security  Services  certificate database, for
              (optional) secure connections.  The default is /etc/pki/nssdb.  Refer also  to  the
              -P  option.   If  it does not already exist, this database can be created using the
              certutil  utility.   This  process  and  other  certificate  database   maintenance
              information  is  provided  in  the  PCPIntro(1)  manual  page  and  the  online PCP
              tutorials.

       -f     By default pmcd is started as a daemon.  The -f option indicates that it should run
              in  the  foreground.   This  is  most  useful when trying to diagnose problems with
              misbehaving agents.

       -H hostname
              This option can be used to set the hostname that pmcd will use  to  represent  this
              instance  of  itself.  This is used by client tools like pmlogger(1) when reporting
              on the (possibly remote) host.  If this option is not set, the pmcd.hostname metric
              will  match that returned by pmhostname(1).  Refer to the manual page for that tool
              for full details on how the hostname is evaluated.

       -i ipaddress
              This option is usually only used on hosts with more than one network interface.  If
              no  -i  options are specified pmcd accepts connections made to any of its host's IP
              (Internet Protocol) addresses.  The -i option is used to specify explicitly  an  IP
              address  that  connections  should  be  accepted  on.   ipaddress  should be in the
              standard dotted form (e.g. 100.23.45.6).  The -i option may be used multiple  times
              to  define  a list of IP addresses.  Connections made to any other IP addresses the
              host has will be refused.  This can be used to limit  connections  to  one  network
              interface  if  the  host is a network gateway.  It is also useful if the host takes
              over the IP address of another host that has failed.  In such a situation only  the
              standard  IP addresses of the host should be given (not the ones inherited from the
              failed host).  This allows PCP applications to determine that a  host  has  failed,
              rather  than  connecting  to  the  host that has assumed the identity of the failed
              host.

       -l logfile
              By default a log file named pmcd.log is written in the directory $PCP_LOG_DIR/pmcd.
              The  -l option causes the log file to be written to logfile instead of the default.
              If the log file cannot be created or is not writable,  output  is  written  to  the
              standard error instead.

       -L bytes
              PDUs  received  by pmcd from monitoring clients are restricted to a maximum size of
              65536 bytes by default to defend against Denial of Service attacks.  The -L  option
              may be used to change the maximum incoming PDU size.

       -n pmnsfile
              Normally  pmcd  loads  the  default  Performance  Metrics  Name  Space  (PMNS) from
              $PCP_VAR_DIR/pmns/root, however if  the  -n  option  is  specified  an  alternative
              namespace is loaded from the file pmnsfile.

       -N pmnsfile
              Same  function  as  -n,  except  for  the  handling of duplicate Performance Metric
              Identifiers (PMIDs) in pmnsfile - duplicates are  allowed  with  -N  they  are  not
              allowed with -n.

       -P passfile
              Specify  the  path  to  a file containing the Network Security Services certificate
              database password for (optional) secure connections, and  for  databases  that  are
              password  protected.   Refer  also to the -C option.  When using this option, great
              care should be exercised to ensure appropriate ownership  ("pcp"  user,  typically)
              and  permissions  on this file (0400, so as to be unreadable by any user other than
              the user running the pmcd process).

       -q timeout
              The pmcd to agent version exchange protocol (new in PCP 2.0 - introduced to provide
              backward  compatibility)  uses  this  timeout  to specify how long pmcd should wait
              before assuming that no version response is coming from an agent.  If this  timeout
              is  reached,  the agent is assumed to be an agent which does not understand the PCP
              2.0 protocol.  The default timeout interval is five  seconds,  but  the  -q  option
              allows  an  alternative  timeout  interval  (which must be greater than zero) to be
              specified.  The unit of time is seconds.

       -S     Require that all client connections provide user credentials.  This means that only
              unix  domain  sockets,  or authenticated connections are permitted (requires secure
              sockets support).  If any user or group access control requirements  are  specified
              in  the  pmcd  configuration  file,  then  this  mode of operation is automatically
              entered, whether the -S flag is specified or not.

       -s sockname
              Specify the path to a local unix  domain  socket  (for  platforms  supporting  this
              socket family only).  The default value is $PCP_RUN_DIR/pmcd.socket.

       -t timeout
              To  prevent  misbehaving  clients  or  agents  from  hanging the entire Performance
              Metrics Collection System (PMCS), pmcd uses timeouts on PDU exchanges with  clients
              and  agents running as processes.  By default the timeout interval is five seconds.
              The -t option allows an alternative timeout interval in seconds  to  be  specified.
              If  timeout  is  zero, timeouts are turned off.  It is almost impossible to use the
              debugger interactively on an agent unless timeouts have been  turned  off  for  its
              "parent" pmcd.

              Once pmcd is running, the timeout may be dynamically modified by storing an integer
              value (the timeout in seconds) into the metric pmcd.control.timeout via pmstore(1).

       -T traceflag
              To assist with error diagnosis for agents and/or  clients  of  pmcd  that  are  not
              behaving  correctly,  an internal event tracing mechanism is supported within pmcd.
              The value of traceflag is interpreted as a bit field  with  the  following  control
              functions:

              1   enable client connection tracing
              2   enable PDU tracing
              256 unbuffered event tracing

              By  default, event tracing is buffered using a circular buffer that is over-written
              as new events are recorded.  The default buffer size  holds  the  last  20  events,
              although  this  number  may be over-ridden by using pmstore(1) to modify the metric
              pmcd.control.tracebufs.

              Similarly once pmcd is running,  the  event  tracing  control  may  be  dynamically
              modified    by   storing   1   (enable)   or   0   (disable)   into   the   metrics
              pmcd.control.traceconn, pmcd.control.tracepdu and  pmcd.control.tracenobuf.   These
              metrics  map  to  the  bit fields associated with the traceflag argument for the -T
              option.

              When operating in buffered mode, the event trace buffer will be dumped whenever  an
              agent connection is terminated by pmcd, or when any value is stored into the metric
              pmcd.control.dumptrace via pmstore(1).

              In unbuffered mode, every event will be reported when it occurs.

       -U username
              User account under which to run  pmcd.   The  default  is  the  unprivileged  "pcp"
              account  in  current  versions  of PCP, but in older versions the superuser account
              ("root") was used by default.

       -x file
              Before the pmcd logfile can be opened, pmcd  may  encounter  a  fatal  error  which
              prevents it from starting.  By default, the output describing this error is sent to
              /dev/tty but it may redirected to file.

       If a PDU exchange with an agent times out, the agent has violated the requirement that  it
       delivers metrics with little or no delay.  This is deemed a protocol failure and the agent
       is disconnected from pmcd.  Any subsequent requests for information from  the  agent  will
       fail with a status indicating that there is no agent to provide it.

       It  is  possible to specify access control to pmcd based on users, groups and hosts.  This
       allows one to prevent users, groups of users, and certain hosts from accessing the metrics
       provided by pmcd and is described in more detail in the Section on ACCESS CONTROL below.

CONFIGURATION

       On  startup  pmcd  looks  for  a  configuration  file named $PCP_PMCDCONF_PATH.  This file
       specifies which agents cover which performance metrics domains and how  pmcd  should  make
       contact  with  the  agents.  An optional section specifying access controls may follow the
       agent configuration data.

       Warning: pmcd is usually started as part of the boot sequence and runs initially as  root.
       The configuration file may contain shell commands to create agents, which will be executed
       by root.  To prevent security breaches the configuration file should be writable  only  by
       root.  The use of absolute path names is also recommended.

       The  case  of  the reserved words in the configuration file is unimportant, but elsewhere,
       the case is preserved.

       Blank lines and comments are permitted (even encouraged) in  the  configuration  file.   A
       comment  begins with a ``#'' character and finishes at the end of the line.  A line may be
       continued by ensuring that the last character on the  line  is  a  ``\''  (backslash).   A
       comment on a continued line ends at the end of the continued line.  Spaces may be included
       in lexical elements by enclosing the entire element in  double  quotes.   A  double  quote
       preceded  by  a  backslash  is always a literal double quote.  A ``#'' in double quotes or
       preceded by a backslash is treated literally rather than as a comment delimiter.   Lexical
       elements and separators are described further in the following sections.

AGENT CONFIGURATION

       Each line of the agent configuration section of the configuration file contains details of
       how to connect pmcd to one of its agents and specifies  which  metrics  domain  the  agent
       deals with.  An agent may be attached as a DSO, or via a socket, or a pair of pipes.

       Each  line  of the agent configuration section of the configuration file must be either an
       agent specification, a comment, or a  blank  line.   Lexical  elements  are  separated  by
       whitespace characters, however a single agent specification may not be broken across lines
       unless a \ (backslash) is used to continue the line.

       Each agent specification must start with a textual label (string) followed by  an  integer
       in  the  range  1  to  510.  The label is a tag used to refer to the agent and the integer
       specifies  the  domain  for  which  the  agent  supplies  data.   This  domain  identifier
       corresponds to the domain portion of the PMIDs handled by the agent.  Each agent must have
       a unique label and domain identifier.

       For DSO agents a line of the form:

              label domain-no dso entry-point path

       should appear.  Where,

       label         is a string identifying the agent
       domain-no     is an unsigned integer specifying the agent's domain in the range 1 to 510
       entry-point   is the name of an initialization function which will be called when the  DSO
                     is loaded
       path          designates  the  location  of the DSO and this is expected to be an absolute
                     pathname.  pmcd is only able to load DSO agents that have  the  same  simabi
                     (Subprogram  Interface  Model  ABI, or calling conventions) as it does (i.e.
                     only one of the simabi versions will be applicable).  The simabi version  of
                     a  running  pmcd  may be determined by fetching pmcd.simabi.  Alternatively,
                     the file(1) command may be used to determine the  simabi  version  from  the
                     pmcd executable.

                     For  a  relative path the environment variable PMCD_PATH defines a colon (:)
                     separated list of directories to search when trying to locate the agent DSO.
                     The default search path is $PCP_SHARE_DIR/lib:/usr/pcp/lib.

       For agents providing socket connections, a line of the form

              label domain-no socket addr-family address [ command ]

       should appear.  Where,

       label         is a string identifying the agent
       domain-no     is an unsigned integer specifying the agent's domain in the range 1 to 510
       addr-family   designates whether the socket is in the AF_INET, AF_INET6 or AF_UNIX domain,
                     and the corresponding values for this parameter  are  inet,  ipv6  and  unix
                     respectively.
       address       specifies  the  address  of the socket within the previously specified addr-
                     family.  For unix sockets, the address should be  the  name  of  an  agent's
                     socket  on  the  local host (a valid address for the UNIX domain).  For inet
                     and ipv6 sockets, the address may be either a port number  or  a  port  name
                     which  may  be  used  to connect to an agent on the local host.  There is no
                     syntax for specifying an agent on a remote host as a pmcd  deals  only  with
                     agents on the same machine.
       command       is  an  optional parameter used to specify a command line to start the agent
                     when pmcd initializes.  If command is not present,  pmcd  assumes  that  the
                     specified  agent  has  already  been  created.  The command is considered to
                     start from the first non-white character after the socket address and finish
                     at the next newline that isn't preceded by a backslash.  After a fork(2) the
                     command is passed unmodified to execve(2) to instantiate the agent.

       For agents interacting with the pmcd via stdin/stdout, a line of the form:

              label domain-no pipe protocol command

       should appear.  Where,

       label         is a string identifying the agent
       domain-no     is an unsigned integer specifying the agent's domain
       protocol      The value for this parameter should be binary.

                     Additionally, the protocol can include the notready keyword to indicate that
                     the  agent  must be marked as not being ready to process requests from pmcd.
                     The agent will explicitly notify the pmcd when it is ready  to  process  the
                     requests by sending PM_ERR_PMDAREADY PDU.

       command       specifies  a  command  line  to start the agent when pmcd initializes.  Note
                     that command is mandatory for pipe-based agents.  The command is  considered
                     to start from the first non-white character after the protocol parameter and
                     finish at the next newline that isn't preceded  by  a  backslash.   After  a
                     fork(2)  the  command  is  passed unmodified to execve(2) to instantiate the
                     agent.

ACCESS CONTROL CONFIGURATION

       The access control section of the configuration file is optional, but if present  it  must
       follow the agent configuration data.  The case of reserved words is ignored, but elsewhere
       case is preserved.  Lexical elements in  the  access  control  section  are  separated  by
       whitespace  or the special delimiter characters: square brackets (``['' and ``]''), braces
       (``{'' and ``}''), colon (``:''),  semicolon  (``;'')  and  comma  (``,'').   The  special
       characters  are  not  treated  as  special  in  the  agent configuration section.  Lexical
       elements may be quoted (double quotes) as necessary.

       The access control section of the file must start with a line of the form:

       [access]

       Leading and trailing whitespace may appear around and within the brackets and the case  of
       the  access  keyword  is  ignored.  No other text may appear on the line except a trailing
       comment.

       Following this line, the remainder of the configuration file  should  contain  lines  that
       allow or disallow operations from particular hosts or groups of hosts.

       There are two kinds of operations that occur via pmcd:

       fetch          allows retrieval of information from pmcd.  This may be information about a
                      metric (e.g. its description, instance domain or help text) or a value  for
                      a metric.

       store          allows  pmcd  to be used to store metric values in agents that permit store
                      operations.  This may be the actual value of the metric (e.g.  resetting  a
                      counter  to  zero).   Alternatively,  it may be a value used by the PMDA to
                      introduce a change to some aspect of monitoring of that metric (e.g. server
                      side  event  filtering)  -  possibly  even  only for the active client tool
                      performing the store operation, and not others.

       Access to pmcd can be granted in three ways - by user, group of users, or at a host level.
       In  the  latter, all users on a host are granted the same level of access, unless the user
       or group access control mechanism is also in use.

       User names and group names will be verified using the local  /etc/passwd  and  /etc/groups
       files  (or  an  alternative  directory  service),  using  the  getpwent(3) and getgrent(3)
       routines.

       Hosts may be identified by  name,  IP  address,  IPv6  address  or  by  the  special  host
       specifications  ``"unix:"''  or  ``"local:"''.  ``"unix:"''  refers  to pmcd's unix domain
       socket, on supported platforms. ``"local:"'' is equivalent to specifying  ``"unix:"''  and
       ``localhost``.

       Wildcards  may  also  be  specified by ending the host identifier with the single wildcard
       character ``*'' as the last-given component of an address. The wildcard ``".*"'' refers to
       all  inet  (IPv4)  addresses.   The wildcard ``":*"'' refers to all IPv6 addresses.  If an
       IPv6 wildcard contains a ``::'' component, then the final ``*'' refers  to  the  final  16
       bits  of  the  address  only, otherwise it refers to the remaining unspecified bits of the
       address.

       The wildcard ``*'' refers to all users, groups or host addresses,  including  ``"unix:"''.
       Names of users, groups or hosts may not be wildcarded.

       The following are all valid host identifiers:

            boing
            localhost
            giggle.melbourne.sgi.com
            129.127.112.2
            129.127.114.*
            129.*
            .*
            fe80::223:14ff:feaf:b62c
            fe80::223:14ff:feaf:*
            fe80:*
            :*
            "unix:"
            "local:"
            *

       The following are not valid host identifiers:

            *.melbourne
            129.127.*.*
            129.*.114.9
            129.127*
            fe80::223:14ff:*:*
            fe80::223:14ff:*:b62c
            fe80*

       The  first  example  is  not  allowed  because  only  (numeric) IP addresses may contain a
       wildcard.  The second and fifth examples are not valid because  there  is  more  than  one
       wildcard  character.   The  third  and  sixth contain an embedded wildcard, the fourth and
       seventh have a wildcard character that is not the last component of the address (the  last
       components are 127* and fe80* respectively).

       The  name  localhost  is  given special treatment to make the behavior of host wildcarding
       consistent.  Rather than being 127.0.0.1 and ::1, it is mapped to  the  primary  inet  and
       IPv6  addresses  associated with the name of the host on which pmcd is running.  Beware of
       this when running pmcd on multi-homed hosts.

       Access for users, groups or hosts are allowed or disallowed by  specifying  statements  of
       the form:

              allow users userlist : operations ;
              disallow users userlist : operations ;
              allow groups grouplist : operations ;
              disallow groups grouplist : operations ;
              allow hosts hostlist : operations ;
              disallow hosts hostlist : operations ;

       list          userlist,  grouplist  and  hostlist are comma separated lists of one or more
                     users, groups or host identifiers.

       operations    is a comma separated list of the operation types described above, all (which
                     allows/disallows   all   operations),   or   all  except  operations  (which
                     allows/disallows all operations except those listed).

       Either plural or singular forms of users, groups, and hosts keywords are allowed.  If this
       keyword  is  omitted,  a  default  of hosts will be used.  This behaviour is for backward-
       compatibility only, it is preferable to be explicit.

       Where no specific allow or disallow statement applies to an operation, the default  is  to
       allow  the  operation from all users, groups and hosts.  In the trivial case when there is
       no access control section in the  configuration  file,  all  operations  from  all  users,
       groups, and hosts are permitted.

       If a new connection to pmcd is attempted by a user, group or host that is not permitted to
       perform any operations, the connection will be closed immediately after an error  response
       PM_ERR_PERMISSION has been sent to the client attempting the connection.

       Statements  with  the  same  level  of  wildcarding  specifying  identical  hosts  may not
       contradict each other.   For  example  if  a  host  named  clank  had  an  IP  address  of
       129.127.112.2, specifying the following two rules would be erroneous:

            allow host clank : fetch, store;
            disallow host 129.127.112.2 : all except fetch;

       because  they  both refer to the same host, but disagree as to whether the fetch operation
       is permitted from that host.

       Statements containing more  specific  host  specifications  override  less  specific  ones
       according to the level of wildcarding.  For example a rule of the form

            allow host clank : all;

       overrides

            disallow host 129.127.112.* : all except fetch;

       because  the  former  contains  a  specific  host name (equivalent to a fully specified IP
       address), whereas the latter has a wildcard.  In turn, the latter would override

            disallow host * : all;

       It is possible to limit the number of connections from a user,  group  or  host  to  pmcd.
       This may be done by adding a clause of the form

              maximum n connections

       to the operations list of an allow statement.  Such a clause may not be used in a disallow
       statement.  Here, n is the maximum number of connections that will be  accepted  from  the
       user, group or host matching the identifier(s) used in the statement.

       An  access  control statement with a list of user, group or host identifiers is equivalent
       to a set of access control statements, with each specifying one of the identifiers in  the
       list  and  all  with the same access controls (both permissions and connection limits).  A
       group should be used if you want users to contribute to  a  shared  connection  limit.   A
       wildcard should be used if you want hosts to contribute to a shared connection limit.

       When  a  new  client  requests  a  connection, and pmcd has determined that the client has
       permission to connect, it searches the matching list of access control statements for  the
       most  specific  match containing a connection limit.  For brevity, this will be called the
       limiting statement.   If  there  is  no  limiting  statement,  the  client  is  granted  a
       connection.  If there is a limiting statement and the number of pmcd clients with user ID,
       group ID, or IP addresses that match the identifier in the limiting statement is less than
       the  connection  limit  in  the  statement,  the  connection  is  allowed.   Otherwise the
       connection limit has been reached and the client is refused a connection.

       Group access controls and the  wildcarding  in  host  identifiers  means  that  once  pmcd
       actually  accepts a connection from a client, the connection may contribute to the current
       connection count of more than one access control statement - the client's host  may  match
       more  than one access control statement, and similarly the user ID may be in more than one
       group.  This may be significant for subsequent connection requests.

       Note that pmcd enters a mode where it runs effectively with a higher-level of security  as
       soon  as  a  user  or group access control section is added to the configuration.  In this
       mode only authenticated connections  are  allowed  -  either  from  a  SASL  authenticated
       connection, or a Unix domain socket (which implicitly passes client credentials).  This is
       the same mode that is entered explicitly using the  -S  option.   Assuming  permission  is
       allowed,  one  can determine whether pmcd is running in this mode by querying the value of
       the pmcd.feature.creds_required metric.

       Note also that because most specific match semantics are used when checking the connection
       limit,  for  the  host-based  access  control case, priority is given to clients with more
       specific host identifiers.  It is also  possible  to  exceed  connection  limits  in  some
       situations.  Consider the following:

              allow host clank : all, maximum 5 connections;
              allow host * : all except store, maximum 2 connections;

       This  says that only 2 client connections at a time are permitted for all hosts other than
       "clank", which is permitted 5.  If a client from host "boing" is the first to  connect  to
       pmcd,  its  connection  is checked against the second statement (that is the most specific
       match with a connection limit).  As there are no other clients, the connection is accepted
       and contributes towards the limit for only the second statement above.  If the next client
       connects from "clank",  its  connection  is  checked  against  the  limit  for  the  first
       statement.   There  are  no other connections from "clank", so the connection is accepted.
       Once this connection is accepted,  it  counts  towards  both  statements'  limits  because
       "clank"  matches  the  host  identifier in both statements.  Remember that the decision to
       accept a new connection is made using only  the  most  specific  matching  access  control
       statement with a connection limit.  Now, the connection limit for the second statement has
       been reached.  Any connections from hosts other than "clank" will be refused.

       If instead, pmcd with no clients saw three successive connections  arrived  from  "boing",
       the  first  two  would be accepted and the third refused.  After that, if a connection was
       requested from "clank" it would be accepted.  It matches the  first  statement,  which  is
       more  specific  than the second, so the connection limit in the first is used to determine
       that the client has the right to connect.  Now there are 3 connections contributing to the
       second  statement's  connection  limit.   Even  though the connection limit for the second
       statement has been exceeded, the earlier connections from  "boing"  are  maintained.   The
       connection  limit  is  only checked at the time a client attempts a connection rather than
       being re-evaluated every time a new client connects to pmcd.

       This gentle scheme is designed to allow reasonable limits to be imposed on  a  first  come
       first served basis, with specific exceptions.

       As  illustrated  by  the  example above, a client's connection is honored once it has been
       accepted.  However, pmcd reconfiguration (see  the  next  section)  re-evaluates  all  the
       connection  counts and will cause client connections to be dropped where connection limits
       have been exceeded.

RECONFIGURING PMCD

       If the configuration file has been changed or if an agent is not responding because it has
       terminated  or the PMNS has been changed, pmcd may be reconfigured by sending it a SIGHUP,
       as in

            # pmsignal -a -s HUP pmcd

       When pmcd receives a SIGHUP, it checks the configuration file for changes.   If  the  file
       has been modified, it is reparsed and the contents become the new configuration.  If there
       are errors in the configuration file, the  existing  configuration  is  retained  and  the
       contents of the file are ignored.  Errors are reported in the pmcd log file.

       It  also  checks the PMNS file for changes. If the PMNS file has been modified, then it is
       reloaded.  Use of tail(1) on the log file is recommended while reconfiguring pmcd.

       If the configuration for an agent has changed (any parameter except the agent's  label  is
       different),  the  agent  is  restarted.  Agents whose configurations do not change are not
       restarted.  Any existing agents not present in the new configuration are terminated.   Any
       deceased agents are that are still listed are restarted.

       Sometimes  it  is necessary to restart an agent that is still running, but malfunctioning.
       Simply stop the agent (e.g. using SIGTERM from pmsignal(1)),  then  send  pmcd  a  SIGHUP,
       which will cause the agent to be restarted.

STARTING AND STOPPING PMCD

       Normally,  pmcd is started automatically at boot time and stopped when the system is being
       brought down (see rc2(1M) and rc0(1M)).  Under certain circumstances it  is  necessary  to
       start or stop pmcd manually.  To do this one must become superuser and type

            # $PCP_RC_DIR/pcp start

       to start pmcd, or

            # $PCP_RC_DIR/pcp stop

       to  stop  pmcd.   Starting  pmcd when it is already running is the same as stopping it and
       then starting it again.

       Sometimes it may be necessary to restart pmcd during another phase of  the  boot  process.
       Time-consuming  parts  of  the boot process are often put into the background to allow the
       system to become available sooner (e.g. mounting huge databases).  If an agent run by pmcd
       requires such a task to complete before it can run properly, it is necessary to restart or
       reconfigure pmcd after the task completes.  Consider, for example, the case of mounting  a
       database  in  the  background while booting.  If the PMDA which provides the metrics about
       the database cannot function until the database is  mounted  and  available  but  pmcd  is
       started  before the database is ready, the PMDA will fail (however pmcd will still service
       requests for metrics from other domains).  If the database is  initialized  by  running  a
       shell  script, adding a line to the end of the script to reconfigure pmcd (by sending it a
       SIGHUP) will restart the PMDA (if it exited because it couldn't connect to the  database).
       If  the PMDA didn't exit in such a situation it would be necessary to restart pmcd because
       if the PMDA was still running pmcd would not restart it.

       Normally pmcd listens for client connections on TCP/IP port number  44321  (registered  at
       http://www.iana.org/).   Either  the environment variable PMCD_PORT or the -p command line
       option may be used to specify alternative port number(s) when pmcd  is  started;  in  each
       case,  the  specification is a comma-separated list of one or more numerical port numbers.
       Should both methods be used or multiple -p options appear on the command line,  pmcd  will
       listen  on  the  union  of the set of ports specified via all -p options and the PMCD_PORT
       environment variable.  If non-default ports are used with pmcd care  should  be  taken  to
       ensure  that  PMCD_PORT is also set in the environment of any client application that will
       connect to pmcd, or that the extended host specification syntax is used  (see  PCPIntro(1)
       for details).

FILES

       $PCP_PMCDCONF_PATH
                 default configuration file
       $PCP_PMCDOPTIONS_PATH
                 command  line options to pmcd when launched from $PCP_RC_DIR/pcp All the command
                 line option lines should start with a hyphen as the first character.  This  file
                 can also contain environment variable settings of the form "VARIABLE=value".
       ./pmcd.log
                 (or $PCP_LOG_DIR/pmcd/pmcd.log when started automatically)
       $PCP_RUN_DIR/pmcd.pid
                 contains  an  ascii decimal representation of the process ID of pmcd , when it's
                 running.
                 All messages and diagnostics are directed here
       /etc/pki/nssdb
                 default Network Security Services (NSS) certificate database directory, used for
                 optional  Secure  Socket  Layer  connections.   This database can be created and
                 queried using the NSS certutil tool, amongst others.
       /etc/passwd
                 user names, user identifiers and primary  group  identifiers,  used  for  access
                 control specifications
       /etc/groups
                 group  names,  group  identifiers  and  group  members,  used for access control
                 specifications

ENVIRONMENT

       In addition to the PCP environment variables described  in  the  PCP  ENVIRONMENT  section
       below,  the  PMCD_PORT  variable  is  also  recognised  as  the  TCP/IP  port for incoming
       connections (default 44321), and the PMCD_SOCKET variable is also recognised as  the  path
       to be used for the Unix domain socket.

PCP ENVIRONMENT

       Environment variables with the prefix PCP_ are used to parameterize the file and directory
       names used by PCP.  On each installation, the file /etc/pcp.conf contains the local values
       for  these  variables.   The  $PCP_CONF  variable  may  be  used to specify an alternative
       configuration file, as described in pcp.conf(5).

DIAGNOSTICS

       If pmcd is already running the message "Error: OpenRequestSocket bind: Address may already
       be  in  use"  will  appear.  This may also appear if pmcd was shutdown with an outstanding
       request from a client.  In this case, a request socket has  been  left  in  the  TIME_WAIT
       state  and  until  the  system  closes  it down (after some timeout period) it will not be
       possible to run pmcd.

       In addition to the standard  PCP  debugging  flags,  see  pmdbg(1),  pmcd  currently  uses
       DBG_TRACE_APPL0  for  tracing  I/O  and termination of agents, DBG_TRACE_APPL1 for tracing
       access control and DBG_TRACE_APPL2 for tracing the configuration file scanner and parser.

CAVEATS

       pmcd does not explicitly terminate its children (agents), it only closes their pipes.   If
       an agent never checks for a closed pipe it may not terminate.

       The  configuration file parser will only read lines of less than 1200 characters.  This is
       intended to prevent accidents with binary files.

       The timeouts controlled by the -t option apply to  IPC  between  pmcd  and  the  PMDAs  it
       spawns.  This is independent of settings of the environment variables PMCD_CONNECT_TIMEOUT
       and PMCD_REQUEST_TIMEOUT (see PCPIntro(1)) which  may  be  used  respectively  to  control
       timeouts  for  client  applications  trying  to  connect  to  pmcd  and  trying to receive
       information from pmcd.

SEE ALSO

       PCPIntro(1), pmdbg(1), pmerr(1), pmgenmap(1), pminfo(1), pmstat(1), pmstore(1),  pmval(1),
       getpwent(3), getgrent(3), pcp.conf(5), and pcp.env(5).