NAME | SYNOPSIS | DESCRIPTION | CONTEXT CREATION: pmNewContext | CONTEXT CREATION: configurable permanent contexts | PMAPI OPERATIONS | GRAPHITE | 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] [-v] [-?]

DESCRIPTION         top

       Note: this command is deprecated, and will be removed in the next
       major PCP release.  The pmproxy(1) command provides equivalent
       functionality via its time series option.

       pmwebd is a network daemon that binds a subset of the Performance Co-
       Pilot (PCP) client API (PMAPI(3)) to RESTful web applications using a
       subset the PCP REST API (PMWEBAPI(3))asdescribedbelow.

       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.

       -v     Increase the verbosity of pmwebd as it logs to its standard
              output/error.

       -?     Show pmwebd invocation help and exit.

CONTEXT CREATION: pmNewContext         top

       To create a new web context identifier, a web client invokes:

       /pmapi/context?hostname=STRING

       /pmapi/context?hostspec=STRING
              Creates a PM_CONTEXT_HOST PMAPI context with the given host
              name and/or extended specification.  If the host specification
              contains a userid/password combination, then the corresponding
              PMAPI context operations will require HTTP Basic
              authentication credentials with matching userid/password.

       In addition, the web client may add the parameter &polltimeout=MMMM
       for a maximum interval (in seconds) between expected accesses to the
       given context.  This value is limited by pmwebd configuration, and is
       a courtesy to allow pmwebd to free up memory earlier in case of
       sudden web application shutdown.

       If successful, the response from these requests is a JSON document of
       the form:

         { "context" : NNNNN }

       The number (a 32-bit unsigned decimal) is then used in all later op‐
       erations.

CONTEXT CREATION: configurable permanent contexts         top

       In addition, permanent contexts may be created by pmwebd at
       initialization using its -h, -a, -L command line options, so that a
       set of fixed NNNNN numbers may be made available to web clients.

PMAPI OPERATIONS         top

       The general form of the requests is as follows:
       /pmapi/NNNNN/OPERATION where

       /pmapi is the fixed prefix for all PMWEBAPI operations,

       NNNNN  is a PMWEBAPI context number returned from a context-creation
              call, or assigned permanently at pmwebd startup, and

       OPERATION?PARAM1=VALUE2&PARAM2=VALUE2
              identifies the operation and its URL-encoded parameters.  Some
              parameters may be optional.

   METRIC METADATA: pmLookupName, pmLookupDesc, pmLookupText,
       pmTraversePMNS_r
       The general form of the requests is as follows:

       /pmapi/NNNNN/_metric
              Traverse the entire Performance Metrics Name Space (PMNS).

       /pmapi/NNNNN/_metric?prefix=NAME
              Traverse the subtree of PMNS with the prefix NAME.

       The response is a JSON document that provides the metric metadata as
       an array.  For example:

         { "metrics": [
             { "name":"foo.bar", "pmID":PPPP, "indom":DDDD,
               "type":"32", "sem":"instant", "units":"MHz",
               "text-oneline":"foo bar", "text-help":"blah blah blah" },
             { "name":"foo.bar2", ... }
             ...
           ] }

       Most of the fields are self-explanatory.

       name   A name for the metric as defined in the PMNS.  If the PMNS
              contains multiple names associated with the metric's Perfor‐
              mance Metric Identifier (PMID), one of these will be returned
              via name, but there is no way to determine which of the dupli‐
              cate names this will be.

       PPPP   the PMID

       DDDD   the instance domain

       type   from pmTypeStr

       units  from pmUnitsStr

       sem    an abbreviation of the metric semantic:

              PM_SEM_COUNTER  "counter"
              PM_SEM_INSTANT  "instant"
              PM_SEM_DISCRETE "discrete"

   METRIC VALUE: pmFetch
       The general form of the requests is as follows:

       /pmapi/NNNNN/_fetch?names=NAME1,NAME2
              Fetch current values for given named metrics.

       /pmapi/NNNNN/_fetch?pmids=PPPP1,PPPP2
              Fetch current values for given PMIDs.

       If any of the names/pmids are valid, the response is a JSON document
       that provides the values for all requested metrics, for all their in‐
       stances.

         { "timestamp": { "s":SEC, "us":USEC },
           "values": [
                 { "pmid":PPPP1, "name":"NAME1",
                   "instances:" [
                        { "instance":IIII1, "value":VALUE1 }
                        { "instance":IIII2, "value":VALUE2 }
                        ...
                   ] },
                 { "pmid":PPPP2, "name":"NAME2", ... }
                 ...
           ] }

       Most of the fields are self-explanatory.  Numeric metric types are
       represented as JSON integer or floating-point values.  Strings are
       passed verbatim, except that non-ASCII values are replaced with a
       Unicode 0xFFFD REPLACEMENT CHARACTER code.  Event type metrics are
       not currently supported.

   INSTANCE DOMAINS METADATA: pmGetInDom, pmNameInDom, pmLookupInDom
       The general form of the requests is as follows:

       /pmapi/NNNN/_indom?indom=DDDD
              List instances of the given instance domain.

       /pmapi/NNNN/_indom?name=NAME
              List instances of the instance domain belonging to the named
              metric.

       In addition, either query may be suffixed with:

       &instance=IIII,JJJJ
              Restrict listings to given instance code numbers.

       &iname=INAME1,INAME2
              Restrict listings to given instance names.

       The response is a JSON document that provides the metric metadata as
       an array.  For example:

         { "indom":DDDD,
            "instances": [
               { "instance":IIII, "name":"INAME" }
               ...
            ] }

   INSTANCE PROFILE: pmAddProfile, pmDelProfile
       The general form of these requests is as follows:

       /pmapi/NNNN/_profile_reset?indom=DDDD
              These are not currently supported.

       /pmapi/NNNN/_profile_add?indom=DDDD&instance=IIII,JJJJ
              These are not currently supported.

       /pmapi/NNNN/_profile_add?indom=DDDD&iname=IIII,JJJJ
              These are not currently supported.

       /pmapi/NNNN/_profile_del?indom=DDDD&instance=JJJJ
              These are not currently supported.

       /pmapi/NNNN/_profile_del?indom=DDDD&iname=INAME1,INAME2
              These are not currently supported.

   METRIC STORE: pmStore
       The general form of these requests is as follows:

       /pmapi/NNNN/_store?name=NAME&value=VALUE
              Store a new value for given named metrics.

       /pmapi/NNNNN/_store?pmid=PPPP&value=VALUE
              Store a new value for given performance metric identifier
              (PMID).

       In addition, either query may be suffixed with:

       &instance=IIII,JJJJ
              Restrict store to given instance code numbers.

       &iname=INAME1,INAME2
              Restrict store to given instance names.

       If successful, the response from these requests is a JSON document of
       the form:

         { "success" : true }

   DERIVED METRICS: pmRegisterDerived
       /pmapi/NNNNN/_derive?name=NAME&expr=EXPRESSION
              These are not currently supported.

   CONTEXT COPY: pmDupContext
       /pmapi/NNNNN/copy
              These are not currently supported.

   CONTEXT CLOSE: pmDestroyContext
       /pmapi/NNNNN/destroy
              This is not likely to be supported, as it is destructive and
              would offer a tempting target to brute-force attackers.  In‐
              stead, the pmwebd timeout is used to automatically free unused
              contexts.

   PROMETHEUS
       Prometheus exporting of live metrics from a preexisting PMWEBAPI con‐
       text is available:

       The general form of the requests is:

       /pmapi/NNNNN/metrics?target=NAME1,NAME2,...
              Fetch current values for given named metrics.

       For all numeric metrics with the given NAME prefixes, create a
       prometheus text export format giving their current value and related
       metadata.  The response has text/plain type rather than JSON, and is
       designed to be ingested by a Prometheus server, or pcp's own pm‐
       daprometheus.

       The native PCP metric metadata (metric name, semantics and units) are
       first output with the # PCP prefix.  If the units string is empty,
       then none is output.  The units metadata string may contain spaces
       and extends to the end of the line.  Prometheus metric types are
       heuristically inferred from PCP metric types, and units/scales are
       converted to base seconds/bytes/count if possible, with a correspond‐
       ing suffix added to the metric name.  PCP metric names are mapped so
       that . are exchanged with :.  Instance domain instances are repre‐
       sented as Prometheus labels with quoted instance names.

         # PCP proc.nprocs instant none
         # HELP proc:nprocs instantaneous number of processes
         # TYPE proc:nprocs gauge
         proc:nprocs 7

         # PCP kernel.pernode.cpu.intr counter millisec
         # HELP kernel:pernode:cpu:intr_seconds_total total interrupt CPU time from /proc/stat for each node
         # TYPE kernel:pernode:cpu:intr_seconds_total counter
         kernel:pernode:cpu:intr_seconds_total{instance="node0"} 25603.540000000001

         # PCP filesys.blocksize instant byte
         # HELP filesys:blocksize_bytes Size of each block on mounted filesystem (Bytes)
         # TYPE filesys:blocksize_bytes gauge
         filesys:blocksize_bytes{instance="/dev/mapper/docker-253:0-83713-\
         9a130460b46163fcf4443710db3159dea6bb5ec2aaca108515839a7a28c191ce"} 4096
         filesys:blocksize_bytes{instance="/dev/mapper/VolGroup00-root17"} 4096

GRAPHITE         top

       When enabled, pmwebd can emulate a subset of the graphite web-api to
       allow web applications like graphite and grafana to extract data from
       all archives under the configured -A directory.  The graphite
       namespace is constructed from the PCP archives using a simple mapping
       that encodes the Cartesian product of archives, metrics, and
       instance-domain instances into dot-separated strings.  Some
       metacharacter-quoting is employed to encode general strings into
       components.  Only numeric PCP metrics are exposed; COUNTER semantic
       values are rate-converted.

    ┌─────────┬────────┬───────────────────────────────────────────────────────┐
    │position │ number │                        purpose                        │
    ├─────────┼────────┼───────────────────────────────────────────────────────┤
    │   1     │   1    │ encoded pathname of the archive .meta file (default), │
    │         │        │ or canonicalized archive hostname (-J mode)           │
    │   2     │   N    │ the N components of the pcp metric name               │
    │  N+2    │   1    │ instance name of the metric (if any)                  │
    └─────────┴────────┴───────────────────────────────────────────────────────┘
       Since glob wildcarding is supported within metric name components,
       using them in the first component (an encoding of the archive name)
       is a good way to identify machines, or to match multiple archives
       spanning times of interest.

       We list here only the broadest outline of the supported calls.
       pmwebd does not support every graphite web-api option, so many
       querystring parameters may be ignored.  Arithmetic/statistical
       functions on metrics are not supported.

       /graphite/render?format=json&target=FOO&from=TIME&until=TIME
              Return a series of values of the given metrics, between the
              two times, sampled every 60 seconds.

       /graphite/rawdata?target=FOO.BAR&from=TIME&until=TIME
              Same, with a slightly different result encoding.

       /graphite/render?format=png&target=FOO&from=TIME&until=TIME&....
              Same, but render the curves into a PNG image file.  Several
              color- and rendering-control-related parameters are supported.

       /graphite/metrics/find?query=FOO.BAR.*
              Provide incremental metric-tree traversal using wildcards.

       /graphite/graphlot/findmetric?query=FOO+BAR
              Search through metrics with space-separated regular
              expressions.

       /graphite/browser/search?q=FOO+BAR
              Same, with a slightly different result encoding.

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), PCPIntro(3), PMAPI(3), pmSpecLocalPMDA(3), PMWEBAPI(3),
       pcp.conf(5), pcp.env(5), PMNS(5) and
       http://graphite.readthedocs.org/ .

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
       2019-09-26.  (At that time, the date of the most recent commit that
       was found in the repository was 2019-09-26.)  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: pmdiscoverservices(3)