Debian 3.9.10debian/3.9.10debian

1 files changed, 1327 insertions, 0 deletions

diff --git a/man/man1/pcpintro.1 b/man/man1/pcpintro.1
new file mode 100644
index 0000000..c82159f
--- /dev/null
+++ b/man/man1/pcpintro.1
@@ -0,0 +1,1327 @@
+'\"macro stdmacro
+.\"
+.\" Copyright (c) 2012-2014 Red Hat.
+.\" Copyright (c) 2008 Aconex, Inc.  All Rights Reserved.
+.\" Copyright (c) 2000 Silicon Graphics, Inc.  All Rights Reserved.
+.\" 
+.\" This program is free software; you can redistribute it and/or modify it
+.\" under the terms of the GNU General Public License as published by the
+.\" Free Software Foundation; either version 2 of the License, or (at your
+.\" option) any later version.
+.\" 
+.\" This program is distributed in the hope that it will be useful, but
+.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
+.\" or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+.\" for more details.
+.\" 
+.\"
+.TH PCPINTRO 1 "PCP" "Performance Co-Pilot"
+.SH NAME
+\f3PCPIntro\f1 \- introduction to the Performance Co-Pilot (PCP)
+.SH INTRODUCTION
+.de CW
+.ie t \f(CW\\$1\f1\\$2
+.el \fI\\$1\f1\\$2
+..
+The Performance Co-Pilot (PCP) is a toolkit designed for monitoring
+and managing system-level performance.
+These services are distributed and scalable 
+to accommodate the most complex system configurations and performance 
+problems.
+.PP
+PCP supports many different platforms, including (but not limited
+to) Linux, MacOSX, Solaris and Windows.
+From a high-level PCP can be considered to contain two classes of
+software utility:
+.IP "\fIPCP Collectors\fR" 8
+These are the parts of PCP that collect and extract
+performance data from various sources, e.g. the operating system kernel.
+.IP "\fIPCP Monitors\fR" 8
+These are the parts of PCP that display data collected from
+hosts (or archives) that have the
+.I "PCP Collector"
+installed.
+Many monitor tools are available as part of the core PCP release,
+while other (typically graphical) monitoring tools are available
+separately in the PCP GUI package.
+.PP
+This manual entry describes the high-level features and
+options common to most PCP utilities available on all platforms.
+.SH OVERVIEW
+The PCP architecture is distributed in the 
+sense that any PCP tool may be executing remotely.  On
+the host (or hosts) being monitored, each domain of performance
+metrics, whether the kernel, a service layer, a database management system, a web server, an application,  etc.
+requires a Performance Metrics Domain Agent (PMDA)
+which is responsible for collecting performance 
+measurements from that domain.
+All PMDAs
+are controlled by the Performance Metrics Collector Daemon
+.RB ( pmcd (1))
+on the same host.
+.PP
+Client applications (the monitoring tools) connect to
+.BR pmcd (1),
+which
+acts as a router for requests, by
+forwarding requests to the appropriate
+PMDA and returning the responses to the clients.
+Clients may also access performance data from a PCP archive
+(created using
+.BR pmlogger (1))
+for retrospective analysis.
+.SS Security philosophy
+PCP redistributes a wealth of performance information within
+a host and across its networks.  The following security
+philosophy underlies the setting of several
+.I defaults
+that control how much information is sent and received.
+.PP
+By default, the information exposed by PMCD about a host is
+approximately of the same level of confidentiality as available
+to a completely unprivileged user on that host.  So, performance
+data that is available to be
+.I read
+completely freely on a machine may be made available by PMCD to
+the network.
+.PP
+However, the host running PMCD and its network is
+.I not
+assumed to run only friendly applications.  Therefore,
+.I write
+type operations, including from the local host, are not
+permitted by default.
+.PP
+These defaults may be overridden (expanded or reduced) in several
+ways, including by specifying network ACLs in
+.BR pmcd.conf ,
+activating non-default PMDAs, or by using PMCD connections
+that pass user credentials.  For example, some PMDAs automatically
+provide greater information for particular credentialed users or groups.
+.PP
+.SS Applications
+The following performance monitoring applications are primarily console
+based, typically run directly from the command line, and are just a
+small subset of the tools available as part of the base PCP package.
+.PP
+Each tool or command is documented completely in its own reference page.
+.TP
+.B pmstat
+Outputs an ASCII high-level summary of system performance.
+.TP
+.B pmie
+An inference engine that can evaluate predicate-action rules to perform
+alarms and automate system management tasks.
+.TP
+.B pminfo
+Interrogate specific performance metrics and the metadata that
+describes them.
+.TP
+.B pmlogger
+Generates PCP
+archives of performance metrics suitable for replay by most
+PCP tools.
+.TP
+.B pmval
+Simple periodic reporting for some or all instances of a performance
+metric, with optional VCR time control.
+.PP
+If the PCP GUI package is installed then
+the following additional tools are available.
+.TP
+.B pmchart
+Displays trends over time of arbitrarily selected performance metrics from
+one or more hosts.
+.TP
+.B pmtime
+Time control utility for coordinating the time between multiple tools
+(including pmchart and pmval).
+.TP
+.B pmdumptext
+Produce ASCII reports for arbitrary combinations of performance
+metrics.
+.SH COMMON COMMAND LINE ARGUMENTS
+There is a set of common command line arguments that are used consistently
+by most PCP tools.
+.TP
+.BI "\-a " archive
+Performance metric information is retrospectively retrieved 
+from the Performance Co-Pilot (PCP)
+.IR archive ,
+previously generated by 
+.BR pmlogger (1).  See
+.BR pcp-archive (5) for format documentation.
+The
+.B \-a
+and
+.B \-h
+options are mutually exclusive.
+.RS
+.PP
+.I archive
+is either the base name common to all of the physical files created
+by an instance of
+.BR pmlogger (1),
+or any one of the physical files, e.g.
+.I myarchive
+(base name) or
+.IB myarchive .meta
+(the metadata file) or
+.IB myarchive .index
+(the temporal index) or
+.IB myarchive .0
+(the first data volume of
+.IR archive )
+or
+.IB myarchive .0.bz2
+or
+.IB myarchive .0.bz
+(the first data volume compressed with
+.BR bzip2 (1))
+or
+.IB myarchive .0.gz
+or
+.IB myarchive .0.Z
+or
+.IB myarchive .0.z
+(the first data volume compressed with
+.BR gzip (1)),
+.IB myarchive .1
+or
+.IB myarchive .3.bz2
+or
+.IB myarchive .42.gz
+etc.
+.RE
+.TP
+.BI "\-a " archive\f1[ , archive , \f1...]
+An alternate form of
+.B \-a
+for applications that are able to handle multiple
+archives.
+.TP
+.BI "\-h " hostname
+Unless directed to another host by the
+.B \-h
+option,
+or to an archive by the
+.B \-a
+option,
+the source of performance metrics will be
+the Performance Metrics Collector Daemon (PMCD)
+on the local host.
+Refer to the
+.B "PMCD HOST SPECIFICATION"
+section later for further details on the many
+options available when forming the
+.I hostname
+specification, as well as a detailed description of
+the default local host connection.
+The
+.B \-a
+and
+.B \-h
+options are mutually exclusive.
+.TP
+.BI "\-s " samples
+The argument
+.I samples
+defines the number of samples to be retrieved and reported.
+If
+.I samples
+is 0 or
+.B \-s
+is not specified, the application
+will sample and report continuously (in real time mode) or until the end
+of the PCP archive (in archive mode).
+.TP
+.B \-z
+Change the reporting timezone to the local timezone at the
+host that is the source of the performance metrics, as identified via
+either the
+.B \-h
+or
+.B \-a
+options.
+.TP
+.BI "\-Z " timezone
+By default, applications
+report the time of day according to the local timezone on the
+system where
+the application is executed.
+The
+.B \-Z
+option changes the timezone to
+.I timezone
+in the format of the environment variable
+.B TZ
+as described in
+.BR environ (5).
+.SH INTERVAL SPECIFICATION AND ALIGNMENT
+Most PCP tools operate with periodic sampling or
+reporting, and the
+.B \-t
+and
+.B \-A
+options may be used to control the duration of the sample interval
+and the alignment of the sample times.
+.TP
+.BI "\-t " interval
+.RS
+Set the update or reporting interval.
+.PP
+The
+.I interval
+argument
+is specified as a sequence of one or more elements of the form
+.nf
+.in +1.0i
+\f2number\f1[\f2units\f1]
+.in
+.fi
+where \f2number\f1 is an integer or floating point constant (parsed using
+.BR strtod (3))
+and the optional \f2units\f1 is one of:
+.BR seconds ,
+.BR second ,
+.BR secs ,
+.BR sec ,
+.BR s ,
+.BR minutes ,
+.BR minute ,
+.BR mins ,
+.BR min ,
+.BR m ,
+.BR hours ,
+.BR hour ,
+.BR h ,
+.BR days ,
+.B day
+and
+.BR d .
+If the
+.I unit
+is empty,
+.B second
+is assumed.
+.PP
+In addition, the upper case (or mixed case) version of any of the
+above is also acceptable.
+.PP
+Spaces anywhere in the
+.I interval
+are ignored, so
+.BR "4 days 6 hours 30 minutes" ,
+.BR "4day6hour30min" ,
+.B "4d6h30m"
+and
+.B "4d6.5h"
+are all equivalent.
+.PP
+Multiple specifications are additive, e.g. ``\fB1hour 15mins 30secs\fR''
+is interpreted as 3600+900+30 seconds.
+.RE
+.TP
+.BI "\-A " align
+.RS
+By default samples are not necessarily aligned on
+any natural unit of time.  The
+.B \-A
+option may be used to force the initial sample to be aligned on the
+boundary of a natural time unit.
+For example
+.BR "\-A 1sec" ,
+.B "\-A 30min"
+and
+.B "-A 1hour"
+specify alignment on whole seconds, half and whole hours respectively.
+.PP
+The
+.I align
+argument follows the syntax for an
+.I interval
+argument described above for the
+.B \-t
+option.
+.PP
+Note that alignment occurs by advancing the time as required, and that
+.B \-A
+acts as a modifier to advance both the start of the time window
+(see the next section)
+and the origin time (if the
+.B \-O
+option is specified).
+.RE
+.SH TIME WINDOW SPECIFICATION
+Many PCP tools are designed to operate in some time window of interest,
+e.g. to define a termination time for real-time monitoring or to
+define a start and end time within a PCP archive log.
+.PP
+In the absence of the
+.B \-O
+and
+.B \-A
+options to specify an initial sample time origin
+and time alignment (see above), the PCP application
+will retrieve the first sample at the start of the time window.
+.PP
+The following options may be used to specify a time window of interest.
+.TP
+.BI "\-S " starttime
+.RS
+By default the time window commences immediately in real-time mode,
+or coincides with time at the start of the PCP archive log
+in archive mode.
+The
+.B \-S
+option may be used to specify a later time
+for the start of the time window.
+.P
+The
+.I starttime
+parameter may be given in one of
+three forms (\c
+.I interval
+is the same as for the
+.B \-t
+option as described above,
+.I datetime
+is described below):
+.TP
+\f2interval\f1
+To specify an offset from the current time (in real-time mode) or
+the beginning of a PCP archive (in archive mode) simply specify the
+interval of time as the argument.  For example
+.B "\-S 30min"
+will set the start of the time window to be exactly 30 minutes from now in
+real-time mode, or
+exactly 30 minutes from
+the start of a PCP archive.
+.TP
+\-\f2interval\f1
+To specify an offset from the end of a PCP archive log, prefix the
+\f2interval\f1 argument with a minus sign.  In this case, the
+start of the time window precedes
+the time at the end of archive by the given interval.
+For example
+.B "\-S \-1hour"
+will set the start of the time window to be exactly one hour before the
+time of the last sample in a PCP archive log.
+.TP
+@\f2datetime\f1
+To specify the calendar date and time (local time in the reporting timezone)
+for the start of the time window, use the datetime
+syntax preceded by an at sign.  Refer to the datetime description below
+for detailed information.
+.RE
+.TP
+.BI "\-T " endtime
+.RS
+By default the end of the time window is unbounded
+(in real-time mode) or aligned with the time at the end of a PCP archive
+log (in archive mode).
+The
+.B \-T
+option may be used to specify an earlier time for
+the end of the time window.
+.PP
+The
+.I endtime
+parameter may be given in one of
+three forms (\c
+.I interval
+is the same as for the
+.B \-t
+option as described above,
+.I datetime
+is described below):
+.TP
+\f2interval\f1
+To specify an offset from the start of the time window
+simply use the interval of time as the argument.  For example
+.B "\-T 2h30m"
+will set the end of the time window to be 2 hours and 30 minutes after
+the start of the time window.
+.TP
+\-\f2interval\f1
+To specify an offset back from the time at the end of a PCP archive log,
+prefix the \f2interval\f1 argument with a minus sign.  For example
+.B "\-T \-90m"
+will set the end of the time window to be 90 minutes before the time of
+the last sample in a PCP archive log.
+.TP
+@\f2datetime\f1
+To specify the calendar date and time (local time in the reporting timezone)
+for the end of the time window, use the datetime
+syntax preceded by an at sign.  Refer to the datetime description below
+for detailed information.
+.RE
+.TP
+.BI "\-O " origin
+.RS
+By default samples are fetched from the start of the
+time window (see description of
+.B \-S
+option) to the end of the time window (see description of
+.B \-T
+option).
+The
+.B \-O
+option allows the specification of an origin within the time window
+to be used as the initial sample time.  This
+is useful for interactive use of a PCP tool with the
+.BR pmtime (1)
+VCR replay facility.
+.PP
+The \f2origin\f1 argument accepted by
+.B \-O
+conforms to the same syntax and semantics as the
+.I starttime
+argument for the
+.B \-T
+option.
+.PP
+For example
+.B "\-O -0"
+specifies that the initial position should be at the end of the
+time window; this is most useful when wishing to replay ``backwards''
+within the time window.
+.RE
+.PP
+The \f2datetime\f1 argument for the
+.BR \-O ,
+.B \-S
+and
+.B \-T
+options consists of: 
+.br
+.ti +1i
+.B "date time zone day relative"
+.br
+A date can be one of:
+YY-MM-DD, MM/DD/YY, DD Month YYYY, or Month DD YYYY.
+A time can be one of: HH:MM:SS, HH:MM.  HH:MM can use either the
+12 hour (via an am or pm suffix) or 24 hour convention.
+A day of the
+week can be a spelled out day of the week, optionally preceded by an
+ordinal number such as second tuesday.  A zone is a time zone value as
+specified by the
+.B tzselect(1)
+command.  A relative time can be a time
+unit that is: preceded by a cardinal number such as 1 year or 2 months,
+preceded by one of the time words this or last, or succeeded by the time word ago.
+A relative time can also be one of the time words: yesterday, today, tomorrow, now.
+Examples of datetime strings are: 
+.BR "1996-03-04 13:07:47 EST Mon" ,
+.BR "1996-03-05 14:07:47 EST -1hour" ,
+.BR "Mon Mar  4 13:07:47 1996" ,
+.BR "Mar 4 1996" ,
+.BR "Mar 4" , 
+.BR "Mar" , 
+.B "13:07:50" 
+or
+.BR "13:08" .
+.PP
+For any missing low order fields, the default value of
+0 is assumed for hours, minutes and seconds, 1 for day of the month and Jan for months.
+Hence, the following are equivalent:
+.B "\-S '@ Mar 1996'"
+and
+.BR "\-S '@ Mar 1 00:00:00 1996'" .
+.PP
+If any high order fields are missing, they are filled in by
+starting with the
+year, month and day from the current time (real-time mode) or
+the time at the beginning of the PCP archive log (archive mode)
+and advancing the
+time until it matches the fields that are specified.
+So, for example if the time window starts by default at
+``Mon Mar 4 13:07:47 1996'',
+then
+.B "\-S @13:10"
+corresponds to 13:10:00 on Mon Mar 4, 1996,
+while
+.B "\-S @10:00"
+corresponds to 10:00:00 on Tue Mar 5, 1996 (note this is the
+following day).
+.PP
+For greater precision than afforded by
+.BR datetime (3),
+the seconds component may be a floating point number.
+.SH "PERFORMANCE METRICS \- NAMES AND IDENTIFIERS"
+The number of performance metric names supported by PCP on most
+platforms ranges from many hundreds to several thousand.
+The PCP libraries and applications use an internal
+identification scheme that unambiguously associates a single
+integer with each known performance metric.
+This integer is known as the Performance Metric Identifier, or PMID.
+Although not a requirement,
+PMIDs tend to have global consistency across
+all systems, so a particular performance metric usually has the same
+PMID.
+.PP
+For all users and most applications, direct use of the PMIDs would be inappropriate
+(e.g. this would limit the range of accessible metrics, make the code
+hard to maintain, force the user interface to be particularly baroque,
+etc.).
+Hence a Performance Metrics Name Space (PMNS)
+is used to provide external names and
+a hierarchic classification for performance metrics.
+A PMNS is
+represented as a tree, with each node having a label, a pointer to
+either a PMID (for leaf nodes) or a set of descendent
+nodes in the PMNS (for non-leaf nodes).
+.PP
+A node label must begin with
+an alphabetic character, followed by zero or more characters drawn
+from the alphabetics, the digits and character \`_\' (underscore).
+For alphabetic characters in a node label, upper and
+lower case are distinguished.
+.PP
+By convention, the name of a performance metric is constructed by
+concatenation of the node labels on a path through the PMNS from the
+root node to a leaf node, with a ``.'' as a separator.
+The root node in
+the PMNS is unlabeled, so all names begin with the label associated
+with one of the descendent nodes below the root node of the PMNS, e.g. \c
+.CW "kernel.percpu.syscall".
+Typically (although this is not a requirement)
+there would be at most one name for each PMID in a PMNS.
+For example
+.CW kernel.all.cpu.idle
+and
+.CW disk.dev.read
+are the unique names for two distinct performance
+metrics, each with a unique PMID.
+.PP
+Groups of related PMIDs may be named
+by naming a non-leaf node in the PMNS tree, e.g. \c
+.CW disk .
+.PP
+The default local PMNS used by
+.B pmcd
+is located at
+.B $PCP_VAR_DIR/pmns/root
+however the environment
+variable
+.B PMNS_DEFAULT
+may be set to the full pathname of a different PMNS which will
+then be used as the default local PMNS.
+.PP
+Most applications do not use the local PMNS directly,
+but rather import parts of the PMNS as required from the
+same place that performance metrics are fetched, i.e. from
+.BR pmcd (1)
+for live monitoring or from a PCP archive for retrospective
+monitoring.
+.PP
+To explore the PMNS
+use
+.BR pminfo (1),
+or if the PCP GUI package is installed the New Chart and Metric Search
+windows within
+.BR pmchart (1).
+.SH PERFORMANCE METRIC SPECIFICATIONS
+In configuration files and (to a lesser extent) command line options,
+metric specifications adhere to the following syntax rules.
+.PP
+If the source of performance metrics is real-time from
+.BR pmcd (1)
+then the accepted
+syntax is
+.br
+.ti +1i
+\fIhost\fB:\fImetric\fB[\fIinstance1\fB,\fIinstance2\fB,\fR...\fB]\fR
+.PP
+If the source of performance metrics is a PCP archive log then the
+accepted syntax
+is
+.br
+.ti +1i
+\fIarchive\fB/\fImetric\fB[\fIinstance1\fB,\fIinstance2\fB,\fR...\fB]\fR
+.PP
+The
+.IB host :\fR,
+.IB archive /
+and
+\fB[\fIinstance1\fB,\fIinstance2\fB,\fR...\fB]\fR
+components are all optional.
+.PP
+The
+.B ,
+delimiter in the list of instance names
+may be replaced by white space.
+.PP
+Special characters in
+.I instance
+names may be escaped by surrounding the name in double quotes or preceding
+the character with a backslash.
+.PP
+White space is ignored everywhere except within a quoted
+.I instance
+name.
+.PP
+An empty
+.I instance
+is silently ignored, and in particular
+``\fB[]\fR'' is the same as no
+.IR instance ,
+while ``\fB[one,,,two]\fR'' is parsed as specifying just
+the two instances ``\fBone\fP'' and ``\fBtwo\fP''.
+.PP
+As a special case, if the
+.B host
+is the single character ``@'' then this refers to a 
+.B PM_CONTEXT_LOCAL
+source, see
+.BR pmNewContext (3).
+.SH SECURE PMCD CONNECTIONS
+Since PCP version 3.6.11, a monitor can explicitly request
+a secure connection to a collector host running
+.BR pmcd (1)
+or
+.BR pmproxy (1)
+using the PM_CTXFLAG_SECURE context flag.
+If the PCP Collector host supports this feature - refer to the
+pmcd.feature.secure metric for confirmation of this - a TLS/SSL
+(Transport Layer Security or Secure Sockets Layer) connection
+can be established which uses public key cryptography and related
+techniques.
+These features aim to prevent eavesdropping and data tampering
+from a malicious third party, as well as providing server-side
+authentication (confident identification of a server by a client)
+which can be used to guard against man-in-the-middle attacks.
+.PP
+A secure
+.B pmcd
+connection requires use of certificate-based authentication.
+The security features offered by
+.B pmcd
+and
+.B pmproxy
+are implemented using the Network Security Services (NSS) APIs and
+utilities.
+The NSS
+.BR certutil
+tool can be used to create certificates suitable for establishing
+trust between PCP monitor and collector hosts.
+.PP
+A complete description is beyond the scope of this document, refer
+to the
+.BR "PCP ENVIRONMENT" ,
+.B "FILES"
+and
+.B "SEE ALSO"
+sections for detailed information.
+This includes links to tutorials on the steps involved in setting up the
+available security features.
+.SH PMCD HOST SPECIFICATION
+In the absence of an explicit host name specification, most tools
+will default to the local host in live update mode.
+In PCP releases since 3.8.4 onward, this results in an efficient
+local protocol being selected \- typically a Unix domain socket.
+If this option is used (which can also be explicitly requested
+via the
+.I unix:
+host specification described below), it is important to note that all
+connections will be automatically authenticated. In other words, the
+credentials of the user invoking a client tool will automatically be
+made available to
+.BR pmcd (1)
+and all of its PMDAs, on the users behalf, such that results can be
+customized to the privilege levels of individual users.
+.PP
+Names of remote hosts running the
+.BR pmcd (1)
+daemon can of course also be provided to request a remote host be used.
+The most basic form of 
+.B pmcd
+host specification is a simple host name, possibly including the
+domain name if necessary.
+However, this can be extended in a number of ways to further refine
+attributes of the connection made to
+.BR pmcd .
+.PP
+The
+.B pmcd
+port number and also optional
+.BR pmproxy (1)
+hostname and its port number, can be given as part of the host
+specification, since PCP version 3.0.
+These supersede (and override) the old-style PMCD_PORT, PMPROXY_HOST
+and PMPROXY_PORT environment variables.
+.PP
+The following are valid hostname specifications that specify connections to
+.B pmcd
+on host
+.I nas1.servers.com
+with/without a list of ports and with/without a
+.BR pmproxy (1)
+connection through a firewall.
+.PP
+.in +0.5i
+.nf
+.ft CW
+$ pcp \-h nas1.servers.com:44321,4321@firewall.servers.com:44322
+$ pcp \-h nas1.servers.com:44321@firewall.servers.com:44322
+$ pcp \-h nas1.servers.com:44321@firewall.servers.com
+$ pcp \-h nas1.servers.com@firewall.servers.com
+$ pcp \-h nas1.servers.com:44321
+.ft R
+.fi
+.in
+.PP
+In addition, security attributes and credentials can also be specified.
+These include username, an optional password (can be given interactively
+and may depend on the authentication mechanism employed), whether to use
+secure (encrypted) or native (naked) protocol, and so on. The previous
+examples all default to native protocol, and use no authentication.
+This can be altered, as in the following examples.
+.PP
+.in +0.5i
+.nf
+.ft CW
+$ pcp \-h pcps://nas1.servers.com:44321?username=tanya&method=gssapi
+$ pcp \-h pcps://nas2.servers.com@firewalls.r.us?method=plain
+$ pcp \-h pcp://nas3.servers.com
+$ pcp \-h unix:
+$ pcp \-h local:
+.ft R
+.fi
+.in
+.PP
+The choice of authentication method, and other resulting parameters like
+username, optionally password, etc, depends on the SASL2 configuration
+used by each (remote)
+.BR pmcd .
+Tutorials are available specifying various aspects of configuring the
+authentication module(s) used, these fine details are outside the scope
+of this document.
+.PP
+The final
+.I local:
+example above is now the default for most tools.
+This connection is an automatically authenticated local host connection
+on all platforms that support Unix domain sockets.  No password is required
+and authentication is automatic.  This is also the most efficient (lowest
+overhead) communication channel available.
+.PP
+The difference between
+.I unix:
+and
+.I local:
+is that the former is a strict Unix domain socket specification (connection
+fails if it cannot connect that way),
+whereas the latter has a more forgiving fallback to using
+.I localhost
+(i.e. a regular Inet socket connection is used when Unix domain socket
+connections are unavailable).
+.SH ENVIRONMENT
+In addition to the PCP run-time environment and configuration variables
+described in the 
+.B "PCP ENVIRONMENT"
+section below,
+the following environment variables apply to all installations.
+.TP
+.B PCP_CONSOLE
+When set, this changes the default console from
+.I /dev/tty
+(on Unix)
+or
+.I CON:
+(on Windows)
+to be the specified console.
+The special value of
+.I none
+can be used to indicate no console is available for use.
+This is used in places where console-based tools need to interact
+with the user, and in particular is used when authentication is
+being performed.
+.TP
+.B PCP_DERIVED_CONFIG
+When set, this variable defines the path to a file that contains
+definitions of derived metrics as per the syntax described in
+.BR pmLoadDerivedConfig (3).
+Derived metrics may be used to extend the available metrics with
+new (derived) metrics using simple arithmetic expressions.
+.RS
+.PP
+If 
+.B PCP_DERIVED_CONFIG
+is set, the derived metric definitions are processed automatically
+as each new source of performance metrics is established (i.e. each
+time a
+.BR pmNewContext (3)
+is called) or when requests are made against the PMNS.
+.RE
+.TP
+.B PCP_SECURE_SOCKETS
+When set, this variable forces any monitor tool connections to be
+established using the certificate-based secure sockets feature.
+If the connections cannot be established securely, they will fail.
+.TP
+.B PCP_SECURE_DB_METHOD
+With secure socket connections, the certificate and key database is
+stored using the
+.B sql:
+method by default.  Use
+.B PCP_SECURE_DB_METHOD
+to override the default, most usually setting the value to the empty
+string (for the older database methods).
+.TP
+.B PCP_STDERR
+Many PCP tools support the environment variable
+.BR PCP_STDERR ,
+which can be used to
+control where error messages are sent.
+When unset, the default behavior is that
+``usage'' messages and option parsing errors are
+reported on standard error, other messages after
+initial startup are sent to the default destination for the tool,
+i.e. standard error for ASCII tools, or a dialog for GUI tools.
+.RS
+.PP
+If
+.B PCP_STDERR
+is set to the literal value
+.B DISPLAY
+then all messages will be displayed in a dialog.
+This is used for any tools launched from the a Desktop environment.
+.PP
+If
+.B PCP_STDERR
+is set to any other value, the value is assumed to
+be a filename, and all messages will be written there.
+.RE
+.TP
+.B PMCD_CONNECT_TIMEOUT
+When attempting to connect to a remote
+.BR pmcd (1)
+on a machine that is booting,
+the connection attempt
+could potentially block for a long time until the remote machine
+finishes its initialization.
+Most PCP applications and some of the PCP library routines
+will abort and return an error if the connection has not been established after
+some specified interval has elapsed.  The default interval is 5
+seconds.  This may be modified by setting
+.B PMCD_CONNECT_TIMEOUT
+in the environment to a real number of seconds for the
+desired timeout.
+This is most useful in cases where the remote host is at
+the end of a slow network, requiring longer latencies to
+establish the connection correctly.
+.TP
+.B PMCD_RECONNECT_TIMEOUT
+When a monitor or client application loses a connection to a
+.BR pmcd (1),
+the connection may be re-established by calling
+a service routine in the PCP library.
+However, attempts to reconnect are controlled by a back-off
+strategy to avoid flooding the network with reconnection
+requests.
+By default, the back-off delays are 5, 10, 20, 40 and 80
+seconds for consecutive reconnection requests from a client
+(the last delay will be repeated for any further
+attempts after the fifth).
+Setting the environment variable
+.B PMCD_RECONNECT_TIMEOUT
+to a comma separated list of positive integers will re-define
+the back-off delays, e.g. setting
+.B PMCD_RECONNECT_TIMEOUT
+to ``1,2'' will back-off for 1 second, then attempt another
+connection request every 2 seconds thereafter.
+.TP
+.B PMCD_REQUEST_TIMEOUT
+For monitor or client applications connected to
+.BR pmcd (1),
+there is a possibility of the application "hanging" on a request
+for performance metrics or metadata or help text.
+These delays may become severe if the system
+running
+.B pmcd
+crashes, or the network connection is lost.  By setting the environment
+variable
+.B PMCD_REQUEST_TIMEOUT
+to a number of seconds, requests to
+.B pmcd
+will timeout after this number of seconds.  The default behavior is
+to be willing to wait 10 seconds for a response from every
+.B pmcd
+for all applications.
+.TP
+.B PMCD_WAIT_TIMEOUT
+.br
+When
+.BR pmcd (1)
+is started from
+.B $PCP_RC_DIR/pcp
+then the primary instance of
+.BR pmlogger (1)
+will be started if the configuration flag
+.B pmlogger
+is
+.BR chkconfig (8)
+enabled and
+.B pmcd
+is running and accepting connections.
+.RS
+.PP
+The check on
+.BR pmcd 's
+readiness will wait up to
+.B PMCD_WAIT_TIMEOUT
+seconds.
+If
+.B pmcd
+has a long startup time (such as on a very large
+system), then 
+.B PMCD_WAIT_TIMEOUT
+can be set to provide a maximum wait longer than the default 60 seconds.
+.RE
+.TP
+.B PMNS_DEFAULT
+If set, then interpreted as the
+full pathname to be used as the default local PMNS for
+.BR pmLoadNameSpace (3).
+Otherwise, the default local PMNS is located at
+.B $PCP_VAR_DIR/pcp/pmns/root
+for base PCP installations.
+.TP
+.B PCP_COUNTER_WRAP
+Many of the performance metrics exported from PCP agents have the
+semantics of
+.I counter
+meaning they are expected to be monotonically increasing.
+Under some circumstances, one value of these metrics may smaller
+than the previously fetched value.
+This can happen when a counter of finite precision overflows, or
+when the PCP agent has been reset or restarted, or when the
+PCP agent is exporting values from some
+underlying instrumentation that is subject to some asynchronous
+discontinuity.
+
+The environment variable
+.B PCP_COUNTER_WRAP
+may be set to indicate that all such cases of a decreasing ``counter''
+should be treated
+as a counter overflow, and hence the values are assumed to have
+wrapped once in the interval between consecutive samples.
+This ``wrapping'' behavior was the default in earlier PCP versions, but
+by default has been disabled in PCP release from version 1.3 on.
+.TP
+.B PMDA_PATH
+The
+.B PMDA_PATH
+environment variable
+may be used to modify the search path used by
+.BR pmcd (1)
+and
+.BR pmNewContext (3)
+(for
+.B PM_CONTEXT_LOCAL
+contexts) when searching for a daemon or DSO PMDA.
+The syntax follows that for
+.B PATH
+in
+.BR sh (1),
+i.e. a colon separated list of directories,
+and the default search path is ``/var/pcp/lib:/usr/pcp/lib'',
+(or ``/var/lib/pcp/lib'' on Linux, depending on the value
+of the $PCP_VAR_DIR environment variable).
+.TP
+.B PMCD_PORT
+The TPC/IP port(s) used by
+.BR pmcd (1)
+to create the socket for incoming connections and requests, was
+historically 4321 and more recently the officially registered port
+44321; in the current release,
+.B both
+port numbers are used by default as a transitional arrangement.
+This may be over-ridden by setting
+.B PMCD_PORT
+to a different port number, or a comma-separated list of port numbers.
+If a non-default port is used when
+.B pmcd
+is started, then
+every monitoring application connecting to that
+.B pmcd
+must also have
+.B PMCD_PORT
+set in their environment before attempting a connection.
+.PP
+The following environment variables are relevant to installations
+in which 
+.BR pmlogger (1),
+the PCP archive logger, is used.
+.TP
+.B PMLOGGER_PORT
+The environment variable
+.B PMLOGGER_PORT
+may be used to change the base TCP/IP port number used by
+.BR pmlogger (1)
+to create the socket to which
+.BR pmlc (1)
+instances will try and connect.
+The default base port number is 4330.
+When used,
+.B PMLOGGER_PORT
+should be set in the environment before
+.B pmlogger
+is executed.
+.TP
+.B PMLOGGER_REQUEST_TIMEOUT
+When
+.BR pmlc (1)
+connects to
+.BR pmlogger (1),
+there is a remote possibility of
+.BR pmlc
+\&"hanging" on a request
+for information as a consequence of a failure of the network or
+.BR pmlogger .
+By setting the environment
+variable
+.B PMLOGGER_REQUEST_TIMEOUT
+to a number of seconds, requests to
+.B pmlogger
+will timeout after this number of seconds.  The default behavior is
+to be willing to wait forever for a response from each request to a
+.BR pmlogger .
+When used,
+.B PMLOGGER_REQUEST_TIMEOUT
+should be set in the environment before
+.B pmlc
+is executed.
+.PP
+If you have the PCP product installed, then the following
+environment variables are relevant to the Performance Metrics
+Domain Agents (PMDAs).
+.TP
+.B PMDA_LOCAL_PROC
+Use this variable has been deprecated and it is now ignored.
+If the ``proc'' PMDA is configured as a DSO for use with
+.BR pmcd (1)
+on the local host then all of the ``proc'' metrics will be
+available to applications using a
+.B PM_CONTEXT_LOCAL
+context.
+.RS
+.PP
+The previous behaviour was that
+if this variable was set, then a context established with the
+.I type
+of
+.B PM_CONTEXT_LOCAL
+will have access to the ``proc'' PMDA to retrieve performance metrics
+about individual processes.
+.RE
+.TP
+.B PMDA_LOCAL_SAMPLE
+Use this variable has been deprecated and it is now ignored.
+If the ``sample'' PMDA is configured as a DSO for use with
+.BR pmcd (1)
+on the local host then all of the ``sample'' metrics will be
+available to applications using a
+.B PM_CONTEXT_LOCAL
+context.
+.RS
+.PP
+The previous behaviour was that
+if this variable was set, then a context established with the
+.I type
+of
+.B PM_CONTEXT_LOCAL
+will have access to the ``sample'' PMDA if this optional PMDA has
+been installed locally.
+.RE
+.TP
+.B PMIECONF_PATH
+If set,
+.BR pmieconf (1)
+will form its
+.BR pmieconf (5)
+specification (set of parameterized
+.BR pmie (1)
+rules) using all valid
+.B pmieconf
+files found below each subdirectory in this
+colon-separated list of subdirectories.  If not set, the default is
+.BR $PCP_VAR_DIR/config/pmieconf .
+.SH FILES 
+.PD 0
+.TP 10
+.B /etc/pcp.conf
+Configuration file for the PCP runtime environment,
+see
+.BR pcp.conf (5).
+.TP
+.B /etc/pki/nssdb
+Optionally contains a Network Security Services database with a
+"PCP Collector" certificate providing trusted identification for
+the collector host.
+.TP
+.B $HOME/.pcp
+User-specific directories containing configuration files for
+customisation of the various monitor tools, such as
+.BR pmchart (1).
+.TP
+.B $HOME/.pki/nssdb
+A shared Network Security Services (NSS) database directory
+containing per-user certificates identifying known valid remote
+.B pmcd
+collector hosts.
+The NSS
+.B certutil
+tool is one of several that can be used to maintain this database.
+.TP
+.B $PCP_RC_DIR/pcp
+Script for starting and stopping
+.BR pmcd (1).
+.TP
+.B $PCP_PMCDCONF_PATH
+Control file for
+.BR pmcd (1).
+.TP
+.B $PCP_PMCDOPTIONS_PATH
+Command line options passed to
+.BR pmcd (1)
+when it is started from
+.BR $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".
+.TP
+.B $PCP_BINADM_DIR
+Location of PCP utilities for collecting and maintaining PCP archives, PMDA
+help text, PMNS files etc.
+.TP
+.B $PCP_PMDAS_DIR
+Parent directory of the installation directory for Dynamic Shared Object (DSO) PMDAs.
+.TP
+.B $PCP_RUN_DIR/pmcd.pid
+If pmcd is running, this file contains an ascii decimal representation of its
+process ID.
+.TP
+.B $PCP_LOG_DIR/pmcd
+Default location of log files for
+.BR pmcd (1),
+current directory for running PMDAs.
+Archives generated by
+.BR pmlogger (1)
+are generally below
+.BR $PCP_LOG_DIR/pmlogger .
+.TP
+.B $PCP_LOG_DIR/pmcd/pmcd.log
+Diagnostic and status log for the current running
+.BR pmcd (1)
+process.
+The first place to look when there are problems associated
+with
+.BR pmcd .
+.TP
+.B $PCP_LOG_DIR/pmcd/pmcd.log.prev
+Diagnostic and status log for the previous
+.BR pmcd (1)
+instance.
+.TP
+.B $PCP_LOG_DIR/NOTICES
+Log of 
+.BR pmcd (1)
+and 
+PMDA starts, stops, additions and removals.
+.TP
+.B $PCP_VAR_DIR/config
+Contains directories of configuration files for several PCP tools.
+.TP
+.B $PCP_SYSCONF_DIR/pmcd/rc.local
+Local script for controlling PCP boot, shutdown and restart actions.
+.TP
+.B $PCP_VAR_DIR/pmns
+Directory containing the set of PMNS files for all installed PMDAs.
+.TP
+.B $PCP_VAR_DIR/pmns/root
+The ASCII
+.BR pmns (5)
+exported by
+.BR pmcd (1)
+by default.  This PMNS is be the super set of all other PMNS files
+installed in
+.BR $PCP_VAR_DIR/pmns .
+.PP
+In addition, if the PCP product is installed the following
+files and directories are relevant.
+.TP
+.B $PCP_LOG_DIR/NOTICES
+In addition to the 
+.BR pmcd (1)
+and PMDA activity, may be used to log alarms and notices from
+.BR pmie (1)
+via
+.BR pmpost (1).
+.TP
+.B $PCP_PMLOGGERCONTROL_PATH
+Control file for
+.BR pmlogger (1)
+instances launched from
+.B $PCP_RC_DIR/pcp
+and/or managed by
+.BR pmlogger_check (1)
+and
+.BR pmlogger_daily (1)
+as part of a production PCP archive collection setup.
+.PD
+.SH "PCP ENVIRONMENT"
+Environment variables with the prefix
+.B PCP_
+are used to parameterize the file and directory names
+used by PCP.
+On each installation, the file
+.B /etc/pcp.conf
+contains the local values for these variables.
+The
+.B $PCP_CONF
+variable may be used to specify an alternative
+configuration file,
+as described in
+.BR pcp.conf (5).
+.SH SEE ALSO
+.BR pmcd (1),
+.BR pmie (1),
+.BR pmie_daily (1),
+.BR pminfo (1),
+.BR pmlc (1),
+.BR pmlogger (1),
+.BR pmlogger_daily (1),
+.BR pmstat (1),
+.BR pmval (1),
+.BR pcp (1),
+.BR pcp.conf (5),
+.BR pcp.env (5),
+.BR pmns (5)
+and
+.BR chkconfig (8).
+.PP
+If the PCP GUI package is installed, then the
+following entries are also relevant:
+.br
+.BR pmchart (1),
+.BR pmtime (1),
+and
+.BR pmdumptext (1).
+.PP
+If the secure sockets extensions have been enabled, then the
+following references are also relevant:
+.br
+.I "http://www.performancecopilot.org/pcp-gui.git/man/html/index.html"
+.br
+.I "http://www.mozilla.org/projects/security/pki/nss/#documentation"
+.br
+.I "http://www.mozilla.org/projects/security/pki/nss/tools/certutil.html"
+.PP
+Also refer to the books
+.I "Performance Co-Pilot User's and Administrator's Guide"
+and
+.IR "Performance Co-Pilot Programmer's Guide"
+which can be found at http://www.performancecopilot.org/