NAME | SYNOPSIS | DESCRIPTION | SECURITY | STARTING AND STOPPING PMWEBD | FILES | PCP ENVIRONMENT | SEE ALSO | COLOPHON

PMWEBD(1)                  General Commands Manual                 PMWEBD(1)

NAME         top

       pmwebd - web access to PCP

SYNOPSIS         top

       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         top

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

SECURITY         top

       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.

STARTING AND STOPPING PMWEBD         top

       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         top

       $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         top

       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 ALSO         top

       PCPIntro(1), PMAPI(3), PMWEBAPI(3), pmSpecLocalPMDA(3), pcp.conf(5),
       pcp.env(5) http://graphite.readthedocs.org/ and pmns(5).

COLOPHON         top

       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-04-30.  (At that time, the date of the most recent commit that
       was found in the repository was 2018-04-30.)  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: pmfind(1)pmdiscoverservices(3)pmwebapi(3)