|
NAME | SYNOPSIS | DESCRIPTION | SECURITY | STARTING AND STOPPING PMWEBD | FILES | PCP ENVIRONMENT | SEE ALSO | COLOPHON |
PMWEBD(1) General Commands Manual PMWEBD(1)
pmwebd - web access to PCP
pmwebd [-p port] [-4] [-6] [-t timeout] [-R resdir] [-c number] [-h
hostname] [-a archive] [-C] [-P] [-L] [-N] [-G] [-X] [-i min-
interval] [-I [-K spec] [-A archivesdir] [-S] [-l logfile] [-U
username] [-x file] [-v] [-?]
pmwebd is a network daemon that binds a subset of the Performance Co-
Pilot (PCP) client API (PMAPI(3)) to RESTful web applications using
the HTTP (PMWEBAPI(3)) protocol. 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. 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 pre‐
cision (but not necessarily accuracy) data, but may cost extra
processing time at pmwebd or the web browser; and vice versa.
-I Attempt to open an entire directory as an archive when
traversing the -A DIR paths to serve graphite-api metrics. If
successful, it can make the metric names much shorter (omit‐
ting individual encoded file names) and span across time. If
the attempt fails, pmwebd will recurse to each individual ar‐
chive file, just as though -I were not given. The difference
is that if the -I attempt succeeds, a subdirectory is not re‐
cursed further, so if any other archives or subdirectories are
present, they won't be exposed to graphite-api clients.
-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 de‐
fault 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_LO‐
CAL.
-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 con‐
text 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 connec‐
tions 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 ac‐
cess 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 accessi‐
ble. 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 han‐
dles. The verbosity flag -v affects the amount of traffic.
The -l option causes the log file to be written to logfile in‐
stead. 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 adver‐
tise its presence on the network using any available mecha‐
nisms (such as Avahi/DNS-SD), assisting remote monitoring
tools with finding it. These mechanisms are disabled with
this option.
-x file
Before the pmwebd logfile can be opened, pmwebd may encounter
a fatal error which prevents it from starting. By default,
the output describing this error is sent to /dev/tty but it
may redirected to file.
-v Increase the verbosity of the pmwebd program as it logs to its
standard output/error.
-? Show pmwebd invocation help and exit.
The current release of 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 HTTPD proxy), which
would add the constraints and capabilities absent within pmwebd.
Such configuration is beyond the scope of this document.
encryption/confidentiality
The pmwebd program is 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
The pmwebd program 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
The pmwebd program 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.
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.
$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.
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).
PCPIntro(1), PMAPI(3), PMWEBAPI(3), pcp.conf(5), pcp.env(5)
http://graphite.readthedocs.org/ and pmns(5).
This page is part of the PCP (Performance Co-Pilot) project.
Information about the project can be found at ⟨http://www.pcp.io/⟩.
If you have a bug report for this manual page, send it to
pcp@oss.sgi.com. This page was obtained from the project's upstream
Git repository ⟨git://git.pcp.io/pcp⟩ on 2017-07-05. If you discover
any rendering problems in this HTML version of the page, or you
believe there is a better or more up-to-date source for the page, or
you have corrections or improvements to the information in this
COLOPHON (which is not part of the original manual page), send a mail
to man-pages@man7.org
Performance Co-Pilot PCP PMWEBD(1)
Pages that refer to this page: pmfind(1), pmdiscoverservices(3), pmwebapi(3)