Unix/Linux Go Back    


CentOS 7.0 - man page for pmcd (centos section 1)

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:   man
Select Man Page Set:       apropos Keyword Search (sections above)


PMCD(1) 										  PMCD(1)

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 trace-
       flag] [-t timeout] [-U username] [-x file]

DESCRIPTION
       pmcd is the collector used by the Performance Co-Pilot (see PCPIntro(1)) to gather perfor-
       mance metrics on a system.  As a rule, there must be an instance of pmcd running on a sys-
       tem 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 post-
       gresql 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, con-
	      figuration 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 informa-
	      tion 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 mis-
	      behaving 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 stan-
	      dard 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  inter-
	      face  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 stan-
	      dard  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 names-
	      pace is loaded from the file pmnsfile.

       -N pmnsfile
	      Same  function as -n, except for the handling of duplicate Performance Metric Iden-
	      tifiers (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 Met-
	      rics 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  modi-
	      fied  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 pre-
	      vents 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 speci-
       fies 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 con-
       figuration 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 com-
       ment 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 pre-
       ceded by a backslash is always a literal double quote.  A ``#'' in double quotes  or  pre-
       ceded  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 white-
       space 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 corre-
       sponds 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 white-
       space or the special delimiter characters:  square  brackets  (``[''  and  ``]''),  braces
       (``{''  and ``}''), colon (``:''), semicolon (``;'') and comma (``,'').	The special char-
       acters 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  per-
		      forming 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)  rou-
       tines.

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

       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  wild-
       card.  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-com-
       patibility 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  contra-
       dict  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  per-
       mission	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 connec-
       tion.  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 actu-
       ally accepts a connection from a client, the connection may contribute to the current con-
       nection 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 connec-
       tion, 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 spe-
       cific  host  identifiers.   It is also possible to exceed connection limits in some situa-
       tions.  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 state-
       ment.  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 con-
       nection 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 con-
       tents 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 con-
		 trol specifications
       /etc/groups
		 group names, group identifiers and group members, used for access control speci-
		 fications

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  connec-
       tions  (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 config-
       uration 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  pos-
       sible 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 time-
       outs 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).

Performance Co-Pilot			       PCP					  PMCD(1)
Unix & Linux Commands & Man Pages : ©2000 - 2018 Unix and Linux Forums


All times are GMT -4. The time now is 01:12 AM.