1PMWEBD(1)                   General Commands Manual                  PMWEBD(1)
2
3
4

NAME

6       pmwebd - web access to PCP
7

SYNOPSIS

9       pmwebd  [-p  port]  [-4]  [-6] [-t timeout] [-R resdir] [-c number] [-h
10       hostname] [-a archive] [-C] [-P] [-L] [-N] [-G] [-X] [-i  min-interval]
11       [-J  [-K  spec]  [-A  archivesdir]  [-S] [-l logfile] [-U username] [-x
12       file] [-v] [-?]
13

DESCRIPTION

15       pmwebd is a network daemon that binds a subset of the  Performance  Co-
16       Pilot (PCP) client API (PMAPI(3)) to RESTful web applications using the
17       HTTP (PMWEBAPI(3)) protocol.  Web clients request a URI with the prefix
18       /pmapi  to  access  the  bindings.   pmwebd  creates  PCP  contexts  as
19       requested by a dynamic pool of remote clients, and  maintains  them  as
20       long  as  the  clients regularly reconnect to request PMAPI operations.
21       Otherwise, PCP contexts are closed after a timeout.  Permanent contexts
22       may be requested on the command line.
23
24       In  addition to the API binding, pmwebd may be optionally configured as
25       a simple HTTP file server, in order to feed the web application  itself
26       to  a  web  browser.  URIs not matching the /pmapi prefix are mapped to
27       files under the configured resource directory, if  the  -R  option  was
28       given.
29
30       In  addition, pmwebd may be optionally configured as a server of a sub‐
31       set of the graphite 0.9.12 web API, for URLs with the /graphite prefix,
32       in order to expose PCP archives to interactive data-graphing web appli‐
33       cations.
34
35       The options to pmwebd are as follows.
36
37       -p port
38              Set the TCP port number on which pmwebd  will  listen  for  HTTP
39              requests.  The default is 44323.
40
41       -4 or -6
42              Listen  only on IPv4 or IPv6.  By default, pmwebd will listen on
43              both protocols, if possible.
44
45       -A archdir
46              Limit remote access to archives to only those beneath the  given
47              directory.  For performance, symbolic links to other directories
48              may not be followed.  By default, only files beneath the initial
49              pmwebd working directory may be accessed.
50
51       -R resdir
52              Activate file serving beneath the given resource directory.  All
53              regular files there  may  be  read  and  transcribed  to  remote
54              clients.  By default, file serving is disabled.
55
56       -G     Activate  servicing  of  a  subset of the graphite webapi.  This
57              exposes all PCP  archives  under  the  -A  directory  to  remote
58              clients.   By  default, graphite webapi serving is disabled.  To
59              use the graphite and/or grafana web applications  included  with
60              pmwebd,  use  both  -G  and  -R, and connect your web browser to
61              http://127.0.0.1:43323/
62
63       -X     Disable encoding of common characters for  metric  names,  which
64              allows shorter graphite metric names.
65
66       -i min-interval
67              Set  the  minimum  sampling interval for graphite time series in
68              seconds.  The default is 60.  Smaller values give higher  preci‐
69              sion  (but  not  necessarily  accuracy) data, but may cost extra
70              processing time at pmwebd or the web browser; and vice versa.
71
72       -J     When constructing graphite metric names, use the stored hostname
73              instead of a archive pathname as the first component.  This vir‐
74              tually unifies all archives found with the same hostname into  a
75              single  time series.  The host name is canonicalized: any symbol
76              characters other than _ (underscore), space, - (hyphen),  and  /
77              (slash) are replaced by _ (underscore).
78
79       -t timeout
80              Set the maximum timeout (in seconds) after the last operation on
81              a pmapi web context, before it is closed by pmwebd.   A  smaller
82              timeout may be requested by the web client. The default is 300.
83
84       -c number
85              Reset  the  next PMWEBAPI permanent context identifier as given.
86              The default is 1.
87
88       -h hostname or -a archive or -L
89              Assign the next permanent PMWEBAPI context identifier to a PMAPI
90              connection  to  the given host (with an extended syntax as given
91              in PCPIntro(1)), or archive file, or the PM_CONTEXT_LOCAL.
92
93       -C     Mandatory authentication mode, where all host specifications  at
94              context  creation time must be accompanied by credentials (user‐
95              name and password).  These are then passed to pmcd(1) when  cre‐
96              ating the context.  In addition, subsequent PMAPI context opera‐
97              tions require matching HTTP  Basic  authentication  credentials.
98              This  setting is incompatible with the permissive mode of opera‐
99              tion.
100
101       -P     Run in permissive mode, allowing Unix domain socket  connections
102              and/or  local  PMDA  contexts.  By default these are not allowed
103              due to the automatic authentication that  is  performed  on  the
104              server  in  these  modes.  Only enable this option if you under‐
105              stand the risks involved, and are sure that  all  remote  pmwebd
106              accesses will be from benevolent users.  If enabled, unauthenti‐
107              cated remote PMWEBAPI(3) clients will be able to  access  poten‐
108              tially  sensitive performance metric values which an unauthenti‐
109              cated PMAPI(3) client usually would not be able  to.   Refer  to
110              CVE-2012-3419 for additional details.
111
112       -N     Disable  creation  of  new  PMWEBAPI contexts via HTTP requests,
113              leaving only permanent ones accessible.
114
115       -K spec
116              When fetching metrics from a local context, the -K option may be
117              used  to  control  the DSO PMDAs that should be made accessible.
118              The spec argument conforms to the syntax described in  pmSpecLo‐
119              calPMDA(3).  More than one -K option may be used.
120
121       -l logfile
122              By  default, logging goes to standard output/error file handles.
123              The verbosity flag -v affects the amount of traffic.  The -l op‐
124              tion  causes  the log file to be written to logfile instead.  If
125              the log file cannot be created or is  not  writable,  output  is
126              written to the standard error instead.
127
128       -U username
129              If  invoked  as  root,  assume  the  identity of username before
130              starting to accept incoming requests from web clients.
131
132       -S     Disable service advertisement.  By default, pmwebd  will  adver‐
133              tise  its presence on the network using any available mechanisms
134              (such as Avahi/DNS-SD), assisting remote monitoring  tools  with
135              finding it.  These mechanisms are disabled with this option.
136
137       -x file
138              Before  the pmwebd logfile can be opened, pmwebd may encounter a
139              fatal error which prevents it from starting.   By  default,  the
140              output  describing  this  error  is  sent to /dev/tty but it may
141              redirected to file.
142
143       -v     Increase the verbosity of pmwebd as it logs to its standard out‐
144              put/error.
145
146       -?     Show pmwebd invocation help and exit.
147

SECURITY

149       pmwebd is suitable for direct exposure to trusted networks only, due to
150       several security limitations.  Most or all of these limitations may  be
151       worked  around  by  use  of a web application firewall (for example, an
152       Apache HTTP proxy), which would add the  constraints  and  capabilities
153       absent  within  pmwebd.  Such configuration is beyond the scope of this
154       document.
155
156       encryption/confidentiality
157              pmwebd does not currently support HTTPS (SSL/TLS), so  the  HTTP
158              traffic is not protected against network-level attacks.
159
160       authentication
161              The  PMAPI  layer  does  not  possess a mandatory authentication
162              mechanism, so any remote connection can access  any  metric  ex‐
163              posed  by suchly connected PMAPI contexts.  However, a new host-
164              context string may use authentication clauses of the longer host
165              URLs,      for      example     pcps://hostname?method=plain&us‐
166              er=userid&pass=password.  Use  of  resulting  pmwebapi  contexts
167              later requires matching HTTP PLAIN authentication; see below.
168
169       inbound admission control
170              pmwebd  does  not impose access control on the origin or rate of
171              its incoming requests.  It may be possible for some  clients  to
172              starve others.
173
174       outbound admission control
175              pmwebd  does  not  impose access control on outbound connections
176              when a new PMAPI context is created for a PMCD.  (Without the -P
177              option,  connections  to UNIX-domain / local PMCDs are blocked.)
178              This enables hypothetical use of a pmwebd instance to be used as
179              a network proxy/scanner.  For an archive type context, the files
180              must be located under the pmwebd current directory,  or  another
181              directory  specified  by  -A.  One may entirely disable remotely
182              specified PMAPI context creation using the -N  option;  in  this
183              case,  specify a static set of contexts using the -h, -a, and/or
184              -L options.  You may assign them arbitrary context numbers  with
185              the -c option.
186
187       context ownership
188              Authenticated  PCP  contexts are protected by requiring the same
189              HTTP PLAIN/simple userid/password credentials for related /pmapi
190              requests.   However,  unauthenticated contexts for different web
191              clients are kept distinct only by the assignment of large  pseu‐
192              dorandom  identifiers.   It  may  be  possible  to find these by
193              brute-force search or other techniques, thereby  letting  a  web
194              client  impersonate  another.  For more privacy of the permanent
195              contexts, use the -c option to reset their starting web  context
196              identifiers  to  a  number  much different from 1.  On the other
197              hand, context ownership is not that precious, since there  exist
198              no  state-destructive operations for them, except perhaps metric
199              store or instance profile settings.
200

STARTING AND STOPPING PMWEBD

202       The pmwebd server may be started automatically at boot time and stopped
203       when  the  system is being brought down.  Users may also run customized
204       pmwebd instances (under separate -p  PORT  numbers),  for  example  for
205       their  own  archive farms.  For management fo the system pmwebd, become
206       superuser and type
207
208       # $PCP_RC_DIR/pmwebd start
209
210       to start pmwebd, or
211
212       # $PCP_RC_DIR/pmwebd stop
213
214       to stop pmwebd.  Starting pmwebd when it is already running is the same
215       as stopping it and then starting it again.
216

FILES

218       $PCP_PMWEBDOPTIONS_PATH
219              command  line  options  and  environment  variable  settings for
220              pmwebd when launched from $PCP_RC_DIR/pmwebd This file is inter‐
221              preted  as a Bourne Shell script, expecting variable settings of
222              the form "OPTIONS=value" and possibly others.
223       $PCP_LOG_DIR/pmwebd/pmwebd.log
224              Log file for system pmwebd service.
225       $PCP_LOG_DIR
226              Default directory for -A option: a base directory containing PCP
227              archives.
228       $PCP_SHARE_DIR/webapps
229              Default directory for -R option: a base directory containing web
230              applications.
231

PCP ENVIRONMENT

233       Environment variables with the prefix PCP_ are used to parameterize the
234       file  and  directory names used by PCP.  On each installation, the file
235       /etc/pcp.conf contains the  local  values  for  these  variables.   The
236       $PCP_CONF  variable may be used to specify an alternative configuration
237       file, as described in pcp.conf(5).
238

SEE ALSO

240       PCPIntro(1), PMAPI(3),  PMWEBAPI(3),  pmSpecLocalPMDA(3),  pcp.conf(5),
241       pcp.env(5) http://graphite.readthedocs.org/ and pmns(5).
242
243
244
245Performance Co-Pilot                  PCP                            PMWEBD(1)
Impressum