1PMWEBD(1) General Commands Manual PMWEBD(1)
2
6 pmwebd - web access to PCP
7
9 pmwebd [-p port] [-4] [-6] [-t timeout] [-R resdir] [-c number] [-h
10 hostname] [-a archive] [-P] [-L] [-N] [-G] [-i min-interval] [-I [-K
11 spec] [-A archivesdir] [-l logfile] [-U username] [-x file] [-v] [-?]
12
14 pmwebd is a network daemon that binds a subset of the Performance Co-
15 Pilot (PCP) client API (PMAPI(3)) to RESTful web applications using the
16 HTTP (PMWEBAPI(3)) protocol. Web clients request a URI with the prefix
17 /pmapi to access the bindings. pmwebd creates PCP contexts as
18 requested by a dynamic pool of remote clients, and maintains them as
19 long as the clients regularly reconnect to request PMAPI operations.
20 Otherwise, PCP contexts are closed after a timeout. Permanent contexts
21 may be requested on the command line.
22 In addition to the API binding, pmwebd may be optionally configured as
24 a simple HTTP file server, in order to feed the web application itself
25 to a web browser. URIs not matching the /pmapi prefix are mapped to
26 files under the configured resource directory, if the -R option was
27 given.
28 In addition, pmwebd may be optionally configured as a server of a sub‐
30 set of the graphite 0.9.12 web API, for URLs with the /graphite prefix,
31 in order to expose PCP archives to interactive data-graphing web appli‐
32 cations.
33 The options to pmwebd are as follows.
35 -p port
37 Set the TCP port number on which pmwebd will listen for HTTP
38 requests. The default is 44323.
39 -4 or -6
41 Listen only on IPv4 or IPv6. By default, pmwebd will listen on
42 both protocols, if possible.
43 -A archdir
45 Limit remote access to archives to only those beneath the given
46 directory. By default, only files beneath the initial pmwebd
47 working directory may be accessed.
48 -R resdir
50 Activate file serving beneath the given resource directory. All
51 regular files there may be read and transcribed to remote
52 clients. By default, file serving is disabled.
53 -G Activate servicing of a subset of the graphite webapi. This
55 exposes all PCP archives under the -A directory to remote
56 clients. By default, graphite webapi serving is disabled. To
57 use the graphite and/or grafana web applications included with
58 pmwebd, use both -G and -R, and connect your web browser to
59 http://127.0.0.1:43323/
60 -i min-interval
62 Set the minimum sampling interval for graphite time series in
63 seconds. The default is 60. Smaller values give higher preci‐
64 sion (but not necessarily accuracy) data, but may cost extra
65 processing time at pmwebd or the web browser; and vice versa.
66 -I Attempt to open an entire directory as an archive when travers‐
68 ing the -A DIR paths to serve graphite-api metrics. If success‐
69 ful, it can make the metric names much shorter (omitting indi‐
70 vidual encoded file names) and span across time. If the attempt
71 fails, pmwebd will recurse to each individual archive file, just
72 as though -I were not given. The difference is that if the -I
73 attempt succeeds, a subdirectory is not recursed further, so if
74 any other archives or subdirectories are present, they won't be
75 exposed to graphite-api clients.
76 -t timeout
78 Set the maximum timeout (in seconds) after the last operation on
79 a pmapi web context, before it is closed by pmwebd. A smaller
80 timeout may be requested by the web client.
81 -c number
83 Reset the next PMWEBAPI permanent context identifier as given.
84 The default is 1.
85 -h hostname or -a archive or -L
87 Assign the next permanent PMWEBAPI context identifier to a PMAPI
88 connection to the given host (with an extended syntax as given
89 in PCPIntro(1)), or archive file, or the PM_CONTEXT_LOCAL.
90 -P Run in permissive mode (deprecated), allowing Unix domain socket
92 connections and/or local PMDA contexts. By default these are
93 not allowed due to the automatic authentication that is per‐
94 formed on the server in these modes. If enabled, unauthenticat‐
95 ed remote PMWEBAPI(3) clients will be able to access potentially
96 sensitive performance metric values which an unauthenticated
97 PMAPI(3) client usually would not be able to. Only enable this
98 option if you understand the risks involved, and are sure that
99 all remote pmwebd accesses will be from benevolent users.
100 -N Disable creation of new PMWEBAPI contexts via HTTP requests,
102 leaving only permanent ones accessible.
103 -K spec
105 When fetching metrics from a local context, the -K option may be
106 used to control the DSO PMDAs that should be made accessible.
107 The spec argument conforms to the syntax described in __pm‐
108 SpecLocalPMDA(3). More than one -K option may be used.
109 -l logfile
111 By default, logging goes to standard output/error file handles.
112 The verbosity flag -v affects the amount of traffic. The -l op‐
113 tion causes the log file to be written to logfile instead. If
114 the log file cannot be created or is not writable, output is
115 written to the standard error instead.
116 -U username
118 If invoked as root, assume the identity of username before
119 starting to accept incoming requests from web clients.
120 -x file
122 Before the pmwebd logfile can be opened, pmwebd may encounter a
123 fatal error which prevents it from starting. By default, the
124 output describing this error is sent to /dev/tty but it may
125 redirected to file.
126 -v Increase the verbosity of the pmwebd program as it logs to its
128 standard output/error.
129 -? Show pmwebd invocation help and exit.
131
133 The current release of pmwebd is suitable for direct exposure to trust‐
134 ed networks only, due to several security limitations. Most or all of
135 these limitations may be worked around by use of a web application
136 firewall (for example, an Apache HTTPD proxy), which would add the con‐
137 straints and capabilities absent within pmwebd. Such configuration is
138 beyond the scope of this document.
139 encryption/confidentiality
141 The pmwebd program is does not currently support HTTPS
142 (SSL/TLS), so the HTTP traffic is not protected against network-
143 level attacks.
144 authentication
146 The PMAPI layer does not possess a mandatory authentication
147 mechanism, so any remote connection can access any metric ex‐
148 posed by suchly connected PMAPI contexts. However, a new host-
149 context string may use authentication clauses of the longer host
150 URLs, for example pcps://hostname?method=plain&us‐
151 er=userid&pass=password. Use of resulting pmwebapi contexts
152 later requires matching HTTP PLAIN authentication; see below.
153 inbound admission control
155 The pmwebd program does not impose ACLs on the origin or rate of
156 its incoming requests. It may be possible for some clients to
157 starve others.
158 outbound admission control
160 The pmwebd program does not impose ACLs on outbound connections
161 when a new PMAPI context is created for a remote third-party PM‐
162 CD. For an archive type context, the files must be located un‐
163 der the pmwebd current directory, or another directory specified
164 by -A. One may entirely disable remotely specified PMAPI con‐
165 text creation using the -N option; in this case, specify a stat‐
166 ic set of contexts using the -h, -a, and/or -L options. You may
167 assign them arbitrary context numbers with the -c option.
168 context ownership
170 Authenticated PCP contexts are protected by requiring the same
171 HTTP PLAIN/simple userid/password credentials for related /pmapi
172 requests. However, unauthenticated contexts for different web
173 clients are kept distinct only by the assignment of large pseu‐
174 dorandom identifiers. It may be possible to find these by
175 brute-force search or other techniques, thereby letting a web
176 client impersonate another. For more privacy of the permanent
177 contexts, use the -c option to reset their starting web context
178 identifiers to a number much different from 1. On the other
179 hand, context ownership is not that precious, since there exist
180 no state-destructive operations for them, except perhaps metric
181 store or instance profile settings.
182
184 The pmwebd server may be started automatically at boot time and stopped
185 when the system is being brought down. Users may also run customized
186 pmwebd instances (under separate -p PORT numbers), for example for
187 their own archive farms. For management fo the system pmwebd, become
188 superuser and type
189 # $PCP_RC_DIR/pmwebd start
191 to start pmwebd, or
193 # $PCP_RC_DIR/pmwebd stop
195 to stop pmwebd. Starting pmwebd when it is already running is the same
197 as stopping it and then starting it again.
198
200 $PCP_PMWEBDOPTIONS_PATH
201 command line options and environment variable settings for
202 pmwebd when launched from $PCP_RC_DIR/pmwebd This file is inter‐
203 preted as a Bourne Shell script, expecting variable settings of
204 the form "OPTIONS=value" and possibly others.
205 $PCP_LOG_DIR/pmwebd/pmwebd.log
206 Log file for system pmwebd service.
207 $PCP_LOG_DIR
208 Default directory for -A option: a base directory containing PCP
209 archives.
210 $PCP_SHARE_DIR/webapps
211 Default directory for -R option: a base directory containing web
212 applications.
214 Environment variables with the prefix PCP_ are used to parameterize the
215 file and directory names used by PCP. On each installation, the file
216 /etc/pcp.conf contains the local values for these variables. The
217 $PCP_CONF variable may be used to specify an alternative configuration
218 file, as described in pcp.conf(5).
220 PCPIntro(1), PMAPI(3), PMWEBAPI(3), pcp.conf(5), pcp.env(5)
221 http://graphite.readthedocs.org/ and pmns(5).
222Performance Co-Pilot PCP PMWEBD(1)