'\"macro stdmacro
.\"
.\" Copyright (c) 2013-2018 Red Hat.
.\" 
.\" 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 PMWEBD 1 "PCP" "Performance Co-Pilot"
.SH NAME
\f3pmwebd\f1 \- web access to PCP

.de SAMPLE
.br
.RS 2n
.nf
.nh
..
.de ESAMPLE
.hy
.fi
.RE
..

.SH SYNOPSIS
\f3pmwebd\f1
[\f3\-p\f1 \f2port\f1]
[\f3\-4\f1]
[\f3\-6\f1]
[\f3\-t\f1 \f2timeout\f1]
[\f3\-R\f1 \f2resdir\f1]
[\f3\-c\f1 \f2number\f1]
[\f3\-h\f1 \f2hostname\f1]
[\f3\-a\f1 \f2archive\f1]
[\f3\-C\f1]
[\f3\-P\f1]
[\f3\-L\f1]
[\f3\-N\f1]
[\f3\-G\f1]
[\f3\-X\f1]
[\f3\-i\f1 \f2min-interval\f1]
[\f3\-J\f1
[\f3\-K\f1 \f2spec\f1]
[\f3\-A\f1 \f2archivesdir\f1]
[\f3\-S\f1]
[\f3\-l\f1 \f2logfile\f1]
[\f3\-U\f1 \f2username\f1]
[\f3\-v\f1]
[\f3\-?\f1]
.SH DESCRIPTION
.P
.B Note: this command is deprecated, and will be removed in the next
.B major PCP release.
.B The pmproxy(1) command provides equivalent functionality via its
.B time series option.
.P
.B pmwebd
is a network daemon that binds a subset of the
Performance Co-Pilot (PCP) client API (\c
.BR PMAPI (3))
to RESTful web
applications using a subset the PCP REST API (\c
.BR PMWEBAPI (3)) as described below.
.PP
Web clients request a URI with the prefix
.B /pmapi
to access the bindings.
.B pmwebd
creates PCP contexts as requested
by a dynamic pool of remote clients, and maintains them as long as the
clients regularly reconnect to request PMAPI operations.  Otherwise,
PCP contexts are closed after a timeout.  Permanent contexts may be
requested on the command line.
.PP
In addition to the API binding,
.B pmwebd
may be optionally configured as a
simple HTTP file server, in order to feed the web application itself
to a web browser.  URIs not matching the 
.B /pmapi
prefix are mapped to files under the configured resource directory, if
the \f3\-R\f1 option was given.
.PP
In addition,
.B pmwebd
may be optionally configured as a server of a subset
of the graphite 0.9.12 web API, for URLs with the
.B /graphite
prefix, in order to expose PCP archives to interactive data-graphing web
applications.
.PP
The options to
.B pmwebd
are as follows.
.TP
\f3\-p\f1 \f2port\f1
Set the TCP port number on which
.B pmwebd
will listen for HTTP requests.
The default is 44323.
.TP
\f3\-4\f1 or \f3\-6\f1
Listen only on IPv4 or IPv6.  By default,
.B pmwebd
will listen on both
protocols, if possible.
.TP
\f3\-A\f1 \f2archdir\f1
Limit remote access to archives to only those beneath the given directory.
For performance, symbolic links to other directories may not
be followed.
By default, only files beneath the initial
.B pmwebd
working directory may
be accessed.
.TP
\f3\-R\f1 \f2resdir\f1
Activate file serving beneath the given resource directory.  All regular
files there may be read and transcribed to remote clients.  By default,
file serving is disabled.
.TP
\f3\-G\f1
Activate servicing of a subset of the graphite webapi.  This exposes all
PCP archives under the \f3\-A\f1 directory to remote clients.  By default,
graphite webapi serving is disabled.  To use the graphite and/or grafana
web applications included with
.BR pmwebd ,
use both \f3\-G\f1 and \f3\-R\f1, and connect your web browser to
.nh
.B http://127.0.0.1:43323/
.hy
.TP
\f3\-X\f1
Disable encoding of common characters for metric names, which allows
shorter graphite metric names.
.TP
\f3\-i\f1 \f2min-interval\f1
Set the minimum sampling interval for graphite time series in seconds.
The default is 60.  Smaller values give higher precision (but not
necessarily accuracy) data, but may cost extra processing time at
.B pmwebd
or the web browser; and vice versa.
.TP
\f3\-J\f1
When constructing graphite metric names, use the stored \f2hostname\f1
instead of a archive pathname as the first component.  This virtually
unifies \f2all\f1 archives found with the same hostname into a single
time series.  The host name is canonicalized: any symbol
characters other than _ (underscore), space, - (hyphen), and / (slash)
are replaced by _ (underscore).
.TP
\f3\-t\f1 \f2timeout\f1
Set the maximum timeout (in seconds) after the last operation on a pmapi web
context, before it is closed by
.BR pmwebd .
A smaller timeout may be requested
by the web client. The default is 300.
.TP
\f3\-c\f1 \f2number\f1
Reset the next PMWEBAPI permanent context identifier as given.
The default is 1.
.TP
\f3\-h\f1 \f2hostname\f1 or \f3\-a\f1 \f2archive\f1 or \f3\-L\f1
Assign the next permanent PMWEBAPI context identifier to a PMAPI connection
to the given host (with an extended syntax as given in 
.BR PCPIntro (1)),
or archive file, or the PM_CONTEXT_LOCAL.
.TP
\f3\-C\f1
Mandatory authentication mode, where all host specifications at context
creation time must be accompanied by credentials (username and password).
These are then passed to
.BR pmcd (1)
when creating the context.
In addition, subsequent PMAPI context operations require matching
HTTP Basic authentication credentials.
This setting is incompatible with the permissive mode of operation.
.TP
\f3\-P\f1
Run in permissive mode, allowing Unix domain socket connections and/or
local PMDA contexts.
By default these are not allowed due to the automatic authentication that
is performed on the server in these modes.
Only enable this option if you understand the risks involved, and are sure
that all remote
.B pmwebd
accesses will be from benevolent users.
If enabled, unauthenticated remote
.BR PMWEBAPI (3)
clients will be able to access
potentially sensitive performance metric values which an unauthenticated
.BR PMAPI (3)
client usually would not be able to.
Refer to CVE-2012-3419 for additional details.
.TP
\f3\-N\f1
Disable creation of new PMWEBAPI contexts via HTTP requests, leaving only
permanent ones accessible.
.TP
\f3\-K\f1 \f2spec\f1
When
fetching metrics from a local context, the \f3\-K\f1
option may be used to control the DSO PMDAs that should be
made accessible.  The
.I spec
argument conforms to the syntax described in
.BR pmSpecLocalPMDA (3).
More than one
.B \-K
option may be used.
.TP
\f3\-l\f1 \f2logfile\f1
By default, logging goes to standard output/error file handles.
The verbosity flag \f3\-v\f1 affects the amount of traffic.  The
.B \-l
option causes the log file to be written to
.I logfile
instead.
If the log file cannot be created or is not writable, output is
written to the standard error instead.
.TP
\f3\-U\f1 \f2username\f1
If invoked as root, assume the identity of
.I username
before starting to accept incoming requests from web clients.
.TP
\f3\-S\f1
Disable service advertisement.
By default,
.B pmwebd
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.
.TP
\f3\-v\f1
Increase the verbosity of
.B pmwebd
as it logs to its standard output/error.
.TP
\f3\-?\f1
Show
.B pmwebd
invocation help and exit.

.SH CONTEXT CREATION: pmNewContext

To create a new web context identifier, a web client invokes:
.TP
.B /pmapi/context?hostname=STRING
.TP
.B /pmapi/context?hostspec=STRING
Creates a PM_CONTEXT_HOST PMAPI context with the given host name and/or extended
specification.  If the host specification contains a userid/password combination,
then the corresponding PMAPI context operations will require HTTP Basic authentication
credentials with matching userid/password.
.PP
In addition, the web client may add the parameter
.B &polltimeout=MMMM
for a maximum interval (in seconds) between expected accesses to the
given context.  This value is limited by pmwebd configuration, and is
a courtesy to allow pmwebd to free up memory earlier in case of sudden
web application shutdown.
.PP
If successful, the response from these requests is a JSON document of the form:

.SAMPLE
{ "context" : NNNNN }
.ESAMPLE

The number (a 32-bit unsigned decimal) is then used in all later
operations.

.SH CONTEXT CREATION: configurable permanent contexts

In addition, permanent contexts may be created by pmwebd at
initialization using its \-h, \-a, \-L command line options, so that a
set of fixed NNNNN numbers may be made available to web clients.

.SH PMAPI OPERATIONS

The general form of the requests is as follows:
.B /pmapi/NNNNN/OPERATION
where
.TP
.B /pmapi
is the fixed prefix for all PMWEBAPI operations,
.TP
.B NNNNN
is a PMWEBAPI context number returned from a context-creation call, or
assigned permanently at pmwebd startup, and
.TP
.B OPERATION?PARAM1=VALUE2&PARAM2=VALUE2
identifies the operation and its URL-encoded parameters.  Some
parameters may be optional.

.SS METRIC METADATA: pmLookupName, pmLookupDesc, pmLookupText, pmTraversePMNS_r

The general form of the requests is as follows:
.TP
.B /pmapi/NNNNN/_metric
Traverse the entire Performance Metrics Name Space (PMNS).
.TP
.B /pmapi/NNNNN/_metric?prefix=NAME
Traverse the subtree of PMNS with the prefix NAME.
.PP
The response is a JSON document that provides the metric metadata
as an array.  For example:

.SAMPLE
{ "metrics": [ 
    { "name":"foo.bar", "pmID":PPPP, "indom":DDDD,
      "type":"32", "sem":"instant", "units":"MHz",
      "text-oneline":"foo bar", "text-help":"blah blah blah" },
    { "name":"foo.bar2", ... }
    ...
  ] }
.ESAMPLE

Most of the fields are self-explanatory.
.TP
name
A name for the metric as defined in the PMNS.
If the PMNS contains multiple names associated with the metric's
Performance Metric Identifier (PMID),
one of these will be returned via name, but there is no way to
determine which of the duplicate names this will be.
.TP
PPPP
the PMID
.TP
DDDD
the instance domain
.TP
type
from pmTypeStr
.TP
units
from pmUnitsStr
.TP
sem
an abbreviation of the metric semantic:
.TS
l l.
PM_SEM_COUNTER  "counter"
PM_SEM_INSTANT  "instant"
PM_SEM_DISCRETE "discrete"
.TE

.SS METRIC VALUE: pmFetch

The general form of the requests is as follows:
.TP
.B /pmapi/NNNNN/_fetch?names=NAME1,NAME2
Fetch current values for given named metrics.
.TP
.B /pmapi/NNNNN/_fetch?pmids=PPPP1,PPPP2
Fetch current values for given PMIDs.
.PP
If any of the names/pmids are valid, the response is a JSON document that
provides the values for all requested metrics, for all their instances.

.SAMPLE
{ "timestamp": { "s":SEC, "us":USEC },
  "values": [
        { "pmid":PPPP1, "name":"NAME1",
          "instances:" [
               { "instance":IIII1, "value":VALUE1 }
               { "instance":IIII2, "value":VALUE2 }
               ...
          ] },
        { "pmid":PPPP2, "name":"NAME2", ... }
        ...
  ] }
.ESAMPLE

Most of the fields are self-explanatory.  Numeric metric types
are represented as JSON integer or floating-point values.  Strings
are passed verbatim, except that non-ASCII values are replaced
with a Unicode 0xFFFD REPLACEMENT CHARACTER code.  Event type metrics
are not currently supported.

.SS INSTANCE DOMAINS METADATA: pmGetInDom, pmNameInDom, pmLookupInDom

The general form of the requests is as follows:
.TP
.B /pmapi/NNNN/_indom?indom=DDDD
List instances of the given instance domain.
.TP
.B /pmapi/NNNN/_indom?name=NAME
List instances of the instance domain belonging to the named metric.
.PP
In addition, either query may be suffixed with:
.TP
.B &instance=IIII,JJJJ
Restrict listings to given instance code numbers.
.TP
.B &iname=INAME1,INAME2
Restrict listings to given instance names.
.PP

The response is a JSON document that provides the metric metadata
as an array.  For example:

.SAMPLE
{ "indom":DDDD,
   "instances": [
      { "instance":IIII, "name":"INAME" }
      ...
   ] }
.ESAMPLE

.SS INSTANCE PROFILE: pmAddProfile, pmDelProfile

The general form of these requests is as follows:
.TP
.B /pmapi/NNNN/_profile_reset?indom=DDDD
These are not currently supported.
.TP
.B /pmapi/NNNN/_profile_add?indom=DDDD&instance=IIII,JJJJ
These are not currently supported.
.TP
.B /pmapi/NNNN/_profile_add?indom=DDDD&iname=IIII,JJJJ
These are not currently supported.
.TP
.B /pmapi/NNNN/_profile_del?indom=DDDD&instance=JJJJ
These are not currently supported.
.TP
.B /pmapi/NNNN/_profile_del?indom=DDDD&iname=INAME1,INAME2
These are not currently supported.

.SS METRIC STORE: pmStore

The general form of these requests is as follows:
.TP
.B /pmapi/NNNN/_store?name=NAME&value=VALUE
Store a new value for given named metrics.
.TP
.B /pmapi/NNNNN/_store?pmid=PPPP&value=VALUE
Store a new value for given performance metric identifier (PMID).
.PP
In addition, either query may be suffixed with:
.TP
.B &instance=IIII,JJJJ
Restrict store to given instance code numbers.
.TP
.B &iname=INAME1,INAME2
Restrict store to given instance names.
.PP
If successful, the response from these requests is a JSON document of the form:

.SAMPLE
{ "success" : true }
.ESAMPLE

.SS DERIVED METRICS: pmRegisterDerived

.TP
.B /pmapi/NNNNN/_derive?name=NAME&expr=EXPRESSION
These are not currently supported.

.SS CONTEXT COPY: pmDupContext

.TP
.B /pmapi/NNNNN/copy
These are not currently supported.

.SS CONTEXT CLOSE: pmDestroyContext

.TP
.B /pmapi/NNNNN/destroy
This is not likely to be supported, as it is destructive and would offer
a tempting target to brute-force attackers.  Instead, the pmwebd timeout
is used to automatically free unused contexts. 

.SS PROMETHEUS

Prometheus exporting of live metrics from a preexisting PMWEBAPI context
is available:

The general form of the requests is:
.TP
.B /pmapi/NNNNN/metrics?target=NAME1,NAME2,...
Fetch current values for given named metrics.
.PP
For all numeric metrics with the given NAME prefixes, create a
prometheus text export format giving their current value and related
metadata.  The response has text/plain type rather than JSON, and is
designed to be ingested by a Prometheus server, or pcp's own
pmdaprometheus.

The native PCP metric metadata (metric name, semantics and units) are first output with the
.B # PCP
prefix.
If the units string is empty, then
.B none
is output.
The units metadata string may contain spaces and extends to the end of the line.
Prometheus metric types are heuristically inferred from PCP
metric types, and units/scales are converted to base
seconds/bytes/count if possible, with a corresponding suffix added to
the metric name.
PCP metric names are mapped so that \fB.\fP are exchanged with
\fB:\fP.  Instance domain instances are represented as Prometheus labels
with quoted instance names.

.SAMPLE
# PCP proc.nprocs instant none
# HELP proc:nprocs instantaneous number of processes
# TYPE proc:nprocs gauge
proc:nprocs 7

# PCP kernel.pernode.cpu.intr counter millisec
# HELP kernel:pernode:cpu:intr_seconds_total total interrupt CPU time from /proc/stat for each node
# TYPE kernel:pernode:cpu:intr_seconds_total counter
kernel:pernode:cpu:intr_seconds_total{instance="node0"} 25603.540000000001

# PCP filesys.blocksize instant byte
# HELP filesys:blocksize_bytes Size of each block on mounted filesystem (Bytes)
# TYPE filesys:blocksize_bytes gauge
filesys:blocksize_bytes{instance="/dev/mapper/docker-253:0-83713-\e
9a130460b46163fcf4443710db3159dea6bb5ec2aaca108515839a7a28c191ce"} 4096
filesys:blocksize_bytes{instance="/dev/mapper/VolGroup00-root17"} 4096
.ESAMPLE

.SH GRAPHITE

When enabled, pmwebd can emulate a subset of the graphite web-api to
allow web applications like graphite and grafana to extract data from
all archives under the configured \-A directory.  The graphite
namespace is constructed from the PCP archives using a simple mapping
that encodes the Cartesian product of archives, metrics, and
instance-domain instances into dot-separated strings.  Some
metacharacter-quoting is employed to encode general strings into
components.  Only numeric PCP metrics are exposed; COUNTER semantic
values are rate-converted.

.TS
box,center;
c | c | c
c | c | l.
position	number	purpose
_
1	1	encoded pathname of the archive .meta file (default),
		or canonicalized archive hostname (\f2-J\f1 mode)
2	N	the N components of the pcp metric name
N+2	1	instance name of the metric (if any)
.TE

Since glob wildcarding is supported within metric name components,
using them in the first component (an encoding of the archive name) is
a good way to identify machines, or to match multiple archives
spanning times of interest.

We list here only the broadest outline of the supported calls.  pmwebd
does not support every graphite web-api option, so many querystring
parameters may be ignored.  Arithmetic/statistical functions on
metrics are not supported.

.TP
.B /graphite/render?format=json&target=FOO&from=TIME&until=TIME
Return a series of values of the given metrics, between the two times, sampled every 60 seconds.
.TP
.B /graphite/rawdata?target=FOO.BAR&from=TIME&until=TIME
Same, with a slightly different result encoding.
.TP
.B /graphite/render?format=png&target=FOO&from=TIME&until=TIME&....
Same, but render the curves into a PNG image file.  Several color- and
rendering-control-related parameters are supported.
.TP
.B /graphite/metrics/find?query=FOO.BAR.*
Provide incremental metric-tree traversal using wildcards.
.TP
.B /graphite/graphlot/findmetric?query=FOO+BAR
Search through metrics with space-separated regular expressions.
.TP
.B /graphite/browser/search?q=FOO+BAR
Same, with a slightly different result encoding.

.SH SECURITY
.PP
.B pmwebd
is suitable for direct exposure to
trusted networks only, due to several security limitations.  Most or
all of these limitations may be worked around by use of a web
application firewall (for example, an Apache HTTP proxy), which would
add the constraints and capabilities absent within
.BR pmwebd .
Such configuration is beyond the scope of this document.
.TP
encryption/confidentiality
.BR pmwebd
does not currently support HTTPS (SSL/TLS), so
the HTTP traffic is not protected against network-level attacks.
.TP
authentication
The PMAPI layer does not possess a mandatory authentication mechanism,
so any remote connection can access any metric exposed by suchly connected
PMAPI contexts.  However, a new host-context string may use
authentication clauses of the longer host URLs, for example
.IR pcps://hostname?method=plain&user=userid&pass=password .
Use of resulting pmwebapi contexts later requires matching HTTP PLAIN
authentication; see below.
.TP
inbound admission control
.B pmwebd
does not impose access control on the origin or rate of its incoming requests.
It may be possible for some clients to starve others.
.TP
outbound admission control
.B pmwebd
does not impose access control on outbound connections
when a new PMAPI context is created for a PMCD.
(Without the
.BR \-P
option, connections to UNIX-domain / local PMCDs are blocked.)
This enables hypothetical use of a
.B pmwebd
instance to be used as a network proxy/scanner.
For an archive type context, the files must be located under the
.B pmwebd
current directory, or another directory specified by 
.BR \-A .
One may entirely disable remotely specified PMAPI context creation using the 
.B \-N
option; in this case, specify a static set of contexts using the
.BR \-h ,
.BR \-a ,
and/or
.B \-L
options.
You may assign them arbitrary context numbers with the
.B \-c
option.
.TP
context ownership 
Authenticated PCP contexts are protected by requiring the same HTTP
PLAIN/simple userid/password credentials for related /pmapi requests.
However, unauthenticated contexts for different web clients are kept
distinct only by the assignment of large pseudorandom identifiers.  It
may be possible to find these by brute-force search or other
techniques, thereby letting a web client impersonate another.  For
more privacy of the permanent contexts, use the
.B \-c
option to reset their starting web context identifiers to a number
much different from 1.  On the other hand, context ownership is not
that precious, since there exist no state-destructive operations for
them, except perhaps metric store or instance profile settings.
.SH "STARTING AND STOPPING PMWEBD"
The
.B pmwebd
server may be started automatically at boot time and
stopped when the system is being brought down.  Users may also run
customized
.B pmwebd
instances (under separate \f3\-p\f1 PORT numbers), for
example for their own archive farms.
.B
For management fo the system
.BR pmwebd ,
become superuser and type
.PP
.ft CS
# $PCP_RC_DIR/pmwebd start
.ft
.PP
to start
.BR pmwebd ,
or
.PP
.ft CS
# $PCP_RC_DIR/pmwebd stop
.ft
.PP
to stop
.BR pmwebd .
Starting
.B pmwebd
when it is already running is the same as stopping
it and then starting it again.
.SH FILES
.PD 0
.TP
.B $PCP_PMWEBDOPTIONS_PATH
command line options
and environment variable settings for
.B pmwebd
when launched from
.B $PCP_RC_DIR/pmwebd
This file is interpreted as a Bourne Shell script, expecting
variable settings of the form "OPTIONS=value" and possibly others.
.TP
.B $PCP_LOG_DIR/pmwebd/pmwebd.log
Log file for system
.B pmwebd
service. 
.TP
.B $PCP_LOG_DIR
Default directory for \f3\-A\f1 option: a base directory containing PCP archives.
.TP
.B $PCP_SHARE_DIR/webapps
Default directory for \f3\-R\f1 option: a base directory containing web applications.
.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
.I /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 PCPIntro (1),
.BR PCPIntro (3),
.BR PMAPI (3),
.BR PMWEBAPI (3),
.BR pmSpecLocalPMDA (3),
.BR pcp.conf (5),
.BR pcp.env (5)
.nh
.BR http://graphite.readthedocs.org/
.hy
and
.BR pmns (5).