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] [-I [-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.  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.

       -I     Attempt to open an entire directory as an archive when
              traversing the -A DIR paths to serve graphite-api metrics.  If
              successful, it can make the metric names much shorter (omit‐
              ting individual encoded file names) and span across time.  If
              the attempt fails, pmwebd will recurse to each individual ar‐
              chive file, just as though -I were not given.  The difference
              is that if the -I attempt succeeds, a subdirectory is not re‐
              cursed further, so if any other archives or subdirectories are
              present, they won't be exposed to graphite-api clients.

       -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 the pmwebd program as it logs to its
              standard output/error.

       -?     Show pmwebd invocation help and exit.

SECURITY         top

       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.  Use
              of resulting pmwebapi contexts later requires matching HTTP
              PLAIN authentication; see below.

       inbound admission control
              The pmwebd program 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
              The pmwebd program 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), 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@oss.sgi.com.  This page was obtained from the project's upstream
       Git repository ⟨https://github.com/performancecopilot/pcp.git⟩ on
       2017-09-15.  If you discover any rendering problems in this HTML ver‐
       sion 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 man‐
       ual 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)