|
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] [-J [-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.
-J When constructing graphite metric names, use the stored host‐
name instead of a archive pathname as the first component.
This virtually unifies all archives found with the same host‐
name into a single time series. The host name is canonical‐
ized: 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 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 pmwebd as it logs to its standard
output/error.
-? Show pmwebd invocation help and exit.
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.
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), pmSpecLocalPMDA(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@groups.io. This page was obtained from the project's upstream
Git repository ⟨https://github.com/performancecopilot/pcp.git⟩ on
2018-02-02. (At that time, the date of the most recent commit that
was found in the repository was 2018-02-02.) 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: pmdaprometheus(1), pmfind(1), pmdiscoverservices(3), pmwebapi(3)
|
HTML rendering created 2018-02-02 by Michael Kerrisk, author of The Linux Programming Interface, maintainer of the Linux man-pages project. For details of in-depth Linux/UNIX system programming training courses that I teach, look here. Hosting by jambit GmbH.
|
|