pmwebd - bridge client PMAPI to HTTP
pmwebd [-p port] [-4] [-6] [-t timeout] [-R resdir] [-c number] [-h hostname] [-a archive]
[-L] [-N] [-K spec] [-A archdir] [-f] [-l logfile] [-U username] [-x file] [-v] [-?]
pmwebd is a long-running network daemon. It binds a subset of the Performance 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 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
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.
Set the TCP port number on which pmwebd will listen for HTTP requests. The default
-4 or -6
Listen only on IPv4 or IPv6. By default, pmwebd will listen on both protocols, if
Activate file serving beneath the given resource directory. All regular files
there may be read & transcribed to remote clients. By default, file serving is
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
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
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
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 indicates that it should
run in the foreground. This is most useful when trying to diagnose problems with
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 created or is not writable, output is written to the standard
Assume the identity of username before starting to accept incoming requests from
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.
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.
The pmwebd program is does not currently support HTTPS (SSL/TLS), so the HTTP traf-
fic is not protected against network-level attacks.
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.
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
specified by -A. One may entirely disable remotely specified PMAPI context cre-
ation 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.
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, con-
text ownership is not that precious, since there exist no state-destructive opera-
tions 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.
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 character. This file can also contain environment variable
settings of the form "VARIABLE=value".
(or $PCP_LOG_DIR/pmwebd/pmwebd.log when started automatically)
All messages and diagnostics are directed here
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 config-
uration file, as described in pcp.conf(5).
PCPIntro(1), PMAPI(3), PMWEBAPI(3), pcp.conf(5), pcp.env(5) and pmns(5).
Performance Co-Pilot PCP PMWEBD(1)