PMWEBD(1)PMWEBD(1)NAMEpmwebd - bridge client PMAPI to HTTP
SYNOPSISpmwebd [-p port] [-4] [-6] [-t timeout] [-R resdir] [-c number] [-h
hostname] [-a archive] [-L] [-N] [-K spec] [-A archdir] [-f] [-l log‐
file] [-U username] [-x file] [-v] [-?]
DESCRIPTIONpmwebd is a long-running network daemon. It binds a subset of the Per‐
formance Co-Pilot (PCP) client API (PMAPI) to RESTful web applications
using the HTTP (PMWEBAPI) protocol. Web clients request a URI with the
prefix /pmapi to access the bindings. pmwebd creates dynamic PCP con‐
texts as requested by a dynamic pool of remote clients, and maintains
them as long as the clients regularly reconnect to request PMAPI opera‐
tions. 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.
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.
-R resdir
Activate file serving beneath the given resource directory. All
regular files there may be read & transcribed to remote clients.
By default, file serving is disabled.
-t timeout
Set the maximum timeout (in seconds) after the last operation on
a web context, before it is closed by pwmebd. A smaller timeout
may be requested by the web client.
-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.
-A archdir
Limit remote new-context requests for archives to beneath the
given directory. By default, only files beneath the initial
working directory may be accessed.
-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.
-f By default pmwebd is started as a daemon. The -f option indi‐
cates that it should run in the foreground. This is most useful
when trying to diagnose problems with establishing connections.
-l logfile
By default a log file named pmwebd.log is written in the current
directory. The -l option causes the log file to be written to
logfile instead of the default. If the log file cannot be cre‐
ated or is not writable, output is written to the standard error
instead.
-U username
Assume the identity of username before starting to accept incom‐
ing requests from web clients.
-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 error.
-? Show pmwebd invocation help and exit.
SECURITY
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 applica‐
tion 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://host‐
name?method=plain&user=userid&pass=password.
inbound admission control
The pmwebd program does not impose ACLs 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 ACLs on outbound connections
when a new PMAPI context is created for a remote third-party
PMCD. For an archive type context, the files must be located
under the pmwebd current directory, or another directory speci‐
fied 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 pseu‐
dorandom 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
instance profile settings.
STARTING AND STOPPING PMWEBD
Normally, pmwebd is started automatically at boot time and stopped when
the system is being brought down. Under certain circumstances it is
necessary to start or stop pmwebd manually. To do this one must 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 All the command
line option lines should start with a hyphen as the first char‐
acter. This file can also contain environment variable settings
of the form "VARIABLE=value".
./pmwebd.log
(or $PCP_LOG_DIR/pmwebd/pmwebd.log when started automatically)
All messages and diagnostics are directed here
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 ALSOPCPIntro(1), PMAPI(3), PMWEBAPI(3), pcp.conf(5), pcp.env(5) and
pmns(5).
Performance Co-Pilot PCP PMWEBD(1)
