Ubuntu Manpage: pmwebd - web access to PCP

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] [-x file]
       [-v] [-?]

DESCRIPTION

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. 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. Small‐
er 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 sin‐
gle 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 ac‐
companied 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 authen‐
tication 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 addi‐
tional details.

-N Disable creation of new PMWEBAPI contexts via HTTP requests, leaving only permanent ones accessi‐
ble.

-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 pmSpecLo‐
calPMDA(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 us‐
ing any available mechanisms (such as Avahi/DNS-SD), assisting remote monitoring tools with find‐
ing 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.

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 con‐
figuration 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://host‐
name?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 di‐
rectory 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 im‐
personate 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).