Ubuntu Manpage: pmwebd - bridge client PMAPI to HTTP

NAME

       pmwebd - bridge client PMAPI to HTTP

SYNOPSIS

       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] [-?]

DESCRIPTION

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 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 indicates 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 created
or is not writable, output is written to the standard error instead.

-U username
Assume the identity of username before starting to accept incoming 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 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.

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 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 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
              character.  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).