Provided by: pcp-webapi_4.3.4-1build2_amd64 
NAME
pmwebd - web access to PCP
SYNOPSIS
pmwebd [-p port] [-4] [-6] [-t timeout] [-R resdir] [-c number] [-h hostname] [-a archive]
[-C] [-P] [-L] [-N] [-G] [-X] [-i min-interval] [-J [-K spec] [-A archivesdir] [-S] [-l
logfile] [-U username] [-v] [-?]
DESCRIPTION
Note: this command is deprecated, and will be removed in the next major PCP release. The
pmproxy(1) command provides equivalent functionality via its time series option.
pmwebd is a network daemon that binds a subset of the Performance Co-Pilot (PCP) client
API (PMAPI(3)) to RESTful web applications using a subset the PCP REST API
(PMWEBAPI(3))asdescribedbelow.
Web clients request a URI with the prefix /pmapi to access the bindings. 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.
In addition to the API binding, 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 /pmapi prefix are mapped to files under the configured resource directory, if the -R
option was given.
In addition, pmwebd may be optionally configured as a server of a subset of the graphite
0.9.12 web API, for URLs with the /graphite prefix, in order to expose PCP archives to
interactive data-graphing web applications.
The options to pmwebd are as follows.
-p port
Set the TCP port number on which pmwebd will listen for HTTP requests. The default
is 44323.
-4 or -6
Listen only on IPv4 or IPv6. By default, pmwebd will listen on both protocols, if
possible.
-A archdir
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 pmwebd working directory may be accessed.
-R resdir
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.
-G Activate servicing of a subset of the graphite webapi. This exposes all PCP
archives under the -A directory to remote clients. By default, graphite webapi
serving is disabled. To use the graphite and/or grafana web applications included
with pmwebd, use both -G and -R, and connect your web browser to
http://127.0.0.1:43323/
-X Disable encoding of common characters for metric names, which allows shorter
graphite metric names.
-i min-interval
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 pmwebd or the web browser; and vice versa.
-J When constructing graphite metric names, use the stored hostname instead of a
archive pathname as the first component. This virtually unifies all 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).
-t timeout
Set the maximum timeout (in seconds) after the last operation on a pmapi web
context, before it is closed by pmwebd. A smaller timeout may be requested by the
web client. The default is 300.
-c number
Reset the next PMWEBAPI permanent context identifier as given. The default is 1.
-h hostname or -a archive or -L
Assign the next permanent PMWEBAPI context identifier to a PMAPI connection to the
given host (with an extended syntax as given in PCPIntro(1)), or archive file, or
the PM_CONTEXT_LOCAL.
-C Mandatory authentication mode, where all host specifications at context creation
time must be accompanied by credentials (username and password). These are then
passed to 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.
-P 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 pmwebd accesses will be
from benevolent users. If enabled, unauthenticated remote PMWEBAPI(3) clients will
be able to access potentially sensitive performance metric values which an
unauthenticated PMAPI(3) client usually would not be able to. Refer to
CVE-2012-3419 for additional details.
-N Disable creation of new PMWEBAPI contexts via HTTP requests, leaving only permanent
ones accessible.
-K spec
When fetching metrics from a local context, the -K option may be used to control
the DSO PMDAs that should be made accessible. The spec argument conforms to the
syntax described in pmSpecLocalPMDA(3). More than one -K option may be used.
-l logfile
By default, logging goes to standard output/error file handles. The verbosity flag
-v affects the amount of traffic. The -l option causes the log file to be written
to logfile instead. If the log file cannot be created or is not writable, output
is written to the standard error instead.
-U username
If invoked as root, assume the identity of username before starting to accept
incoming requests from web clients.
-S Disable service advertisement. By default, 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.
-v Increase the verbosity of pmwebd as it logs to its standard output/error.
-? Show pmwebd invocation help and exit.
CONTEXT CREATION: pmNewContext
To create a new web context identifier, a web client invokes:
/pmapi/context?hostname=STRING
/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.
In addition, the web client may add the parameter &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.
If successful, the response from these requests is a JSON document of the form:
{ "context" : NNNNN }
The number (a 32-bit unsigned decimal) is then used in all later operations.
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.
PMAPI OPERATIONS
The general form of the requests is as follows: /pmapi/NNNNN/OPERATION where
/pmapi is the fixed prefix for all PMWEBAPI operations,
NNNNN is a PMWEBAPI context number returned from a context-creation call, or assigned
permanently at pmwebd startup, and
OPERATION?PARAM1=VALUE2&PARAM2=VALUE2
identifies the operation and its URL-encoded parameters. Some parameters may be
optional.
METRIC METADATA: pmLookupName, pmLookupDesc, pmLookupText, pmTraversePMNS_r
The general form of the requests is as follows:
/pmapi/NNNNN/_metric
Traverse the entire Performance Metrics Name Space (PMNS).
/pmapi/NNNNN/_metric?prefix=NAME
Traverse the subtree of PMNS with the prefix NAME.
The response is a JSON document that provides the metric metadata as an array. For
example:
{ "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", ... }
...
] }
Most of the fields are self-explanatory.
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.
PPPP the PMID
DDDD the instance domain
type from pmTypeStr
units from pmUnitsStr
sem an abbreviation of the metric semantic:
PM_SEM_COUNTER "counter"
PM_SEM_INSTANT "instant"
PM_SEM_DISCRETE "discrete"
METRIC VALUE: pmFetch
The general form of the requests is as follows:
/pmapi/NNNNN/_fetch?names=NAME1,NAME2
Fetch current values for given named metrics.
/pmapi/NNNNN/_fetch?pmids=PPPP1,PPPP2
Fetch current values for given PMIDs.
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.
{ "timestamp": { "s":SEC, "us":USEC },
"values": [
{ "pmid":PPPP1, "name":"NAME1",
"instances:" [
{ "instance":IIII1, "value":VALUE1 }
{ "instance":IIII2, "value":VALUE2 }
...
] },
{ "pmid":PPPP2, "name":"NAME2", ... }
...
] }
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.
INSTANCE DOMAINS METADATA: pmGetInDom, pmNameInDom, pmLookupInDom
The general form of the requests is as follows:
/pmapi/NNNN/_indom?indom=DDDD
List instances of the given instance domain.
/pmapi/NNNN/_indom?name=NAME
List instances of the instance domain belonging to the named metric.
In addition, either query may be suffixed with:
&instance=IIII,JJJJ
Restrict listings to given instance code numbers.
&iname=INAME1,INAME2
Restrict listings to given instance names.
The response is a JSON document that provides the metric metadata as an array. For
example:
{ "indom":DDDD,
"instances": [
{ "instance":IIII, "name":"INAME" }
...
] }
INSTANCE PROFILE: pmAddProfile, pmDelProfile
The general form of these requests is as follows:
/pmapi/NNNN/_profile_reset?indom=DDDD
These are not currently supported.
/pmapi/NNNN/_profile_add?indom=DDDD&instance=IIII,JJJJ
These are not currently supported.
/pmapi/NNNN/_profile_add?indom=DDDD&iname=IIII,JJJJ
These are not currently supported.
/pmapi/NNNN/_profile_del?indom=DDDD&instance=JJJJ
These are not currently supported.
/pmapi/NNNN/_profile_del?indom=DDDD&iname=INAME1,INAME2
These are not currently supported.
METRIC STORE: pmStore
The general form of these requests is as follows:
/pmapi/NNNN/_store?name=NAME&value=VALUE
Store a new value for given named metrics.
/pmapi/NNNNN/_store?pmid=PPPP&value=VALUE
Store a new value for given performance metric identifier (PMID).
In addition, either query may be suffixed with:
&instance=IIII,JJJJ
Restrict store to given instance code numbers.
&iname=INAME1,INAME2
Restrict store to given instance names.
If successful, the response from these requests is a JSON document of the form:
{ "success" : true }
DERIVED METRICS: pmRegisterDerived
/pmapi/NNNNN/_derive?name=NAME&expr=EXPRESSION
These are not currently supported.
CONTEXT COPY: pmDupContext
/pmapi/NNNNN/copy
These are not currently supported.
CONTEXT CLOSE: pmDestroyContext
/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.
PROMETHEUS
Prometheus exporting of live metrics from a preexisting PMWEBAPI context is available:
The general form of the requests is:
/pmapi/NNNNN/metrics?target=NAME1,NAME2,...
Fetch current values for given named metrics.
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 # PCP prefix. If the units string is empty, then 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 . are exchanged with :. Instance domain instances are
represented as Prometheus labels with quoted instance names.
# 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-\
9a130460b46163fcf4443710db3159dea6bb5ec2aaca108515839a7a28c191ce"} 4096
filesys:blocksize_bytes{instance="/dev/mapper/VolGroup00-root17"} 4096
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.
┌─────────┬────────┬───────────────────────────────────────────────────────┐
│position │ number │ purpose │
├─────────┼────────┼───────────────────────────────────────────────────────┤
│ 1 │ 1 │ encoded pathname of the archive .meta file (default), │
│ │ │ or canonicalized archive hostname (-J mode) │
│ 2 │ N │ the N components of the pcp metric name │
│ N+2 │ 1 │ instance name of the metric (if any) │
└─────────┴────────┴───────────────────────────────────────────────────────┘
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.
/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.
/graphite/rawdata?target=FOO.BAR&from=TIME&until=TIME
Same, with a slightly different result encoding.
/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.
/graphite/metrics/find?query=FOO.BAR.*
Provide incremental metric-tree traversal using wildcards.
/graphite/graphlot/findmetric?query=FOO+BAR
Search through metrics with space-separated regular expressions.
/graphite/browser/search?q=FOO+BAR
Same, with a slightly different result encoding.
SECURITY
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 pmwebd. Such configuration is beyond the scope of this
document.
encryption/confidentiality
pmwebd does not currently support HTTPS (SSL/TLS), so the HTTP traffic is not
protected against network-level attacks.
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 pcps://hostname?method=plain&user=userid&pass=password. Use
of resulting pmwebapi contexts later requires matching HTTP PLAIN authentication;
see below.
inbound admission control
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.
outbound admission control
pmwebd does not impose access control on outbound connections when a new PMAPI
context is created for a PMCD. (Without the -P option, connections to UNIX-domain
/ local PMCDs are blocked.) This enables hypothetical use of a pmwebd instance to
be used as a network proxy/scanner. For an archive type context, the files must be
located under the pmwebd current directory, or another directory specified by -A.
One may entirely disable remotely specified PMAPI context creation using the -N
option; in this case, specify a static set of contexts using the -h, -a, and/or -L
options. You may assign them arbitrary context numbers with the -c option.
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 -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.
STARTING AND STOPPING PMWEBD
The pmwebd server may be started automatically at boot time and stopped when the system is
being brought down. Users may also run customized pmwebd instances (under separate -p
PORT numbers), for example for their own archive farms. For management fo the system
pmwebd, become superuser and type
# $PCP_RC_DIR/pmwebd start
to start pmwebd, or
# $PCP_RC_DIR/pmwebd stop
to stop pmwebd. Starting pmwebd when it is already running is the same as stopping it and
then starting it again.
FILES
$PCP_PMWEBDOPTIONS_PATH
command line options and environment variable settings for pmwebd when launched
from $PCP_RC_DIR/pmwebd This file is interpreted as a Bourne Shell script,
expecting variable settings of the form "OPTIONS=value" and possibly others.
$PCP_LOG_DIR/pmwebd/pmwebd.log
Log file for system pmwebd service.
$PCP_LOG_DIR
Default directory for -A option: a base directory containing PCP archives.
$PCP_SHARE_DIR/webapps
Default directory for -R option: a base directory containing web applications.
PCP ENVIRONMENT
Environment variables with the prefix PCP_ are used to parameterize the file and directory
names used by PCP. On each installation, the file /etc/pcp.conf contains the local values
for these variables. The $PCP_CONF variable may be used to specify an alternative
configuration file, as described in pcp.conf(5).
SEE ALSO
PCPIntro(1), PCPIntro(3), PMAPI(3), PMWEBAPI(3), pmSpecLocalPMDA(3), pcp.conf(5),
pcp.env(5) http://graphite.readthedocs.org/ and pmns(5).