1 | CSP HTTP/XML API
|
---|
2 | ----------------
|
---|
3 |
|
---|
4 | The proxy has a simple query api that allows remote monitoring and some limited control/administration features.
|
---|
5 | To use this, rmi and status-web need to be enabled in proxy.xml (see proxy-reference.html).
|
---|
6 |
|
---|
7 | There are two forms of commands: status and control. Each can be executed either via HTTP post containing an xml
|
---|
8 | query or by HTTP get, specifying the command and parameters on the query string. Both methods will produce the
|
---|
9 | same response xml from the proxy, but only post allows multiple commands to be included in one request.
|
---|
10 |
|
---|
11 | These features are designed to be VERY simple to modify and extend, and they're to be considered a default example.
|
---|
12 | One way to make use of this api using only a web browser is included in the form of the status-web (in cs-status.war).
|
---|
13 | This shows an entirely client-side way of building a simple gui on the fly using xslt, js and css (see end of file).
|
---|
14 |
|
---|
15 |
|
---|
16 | Available status commands (as of 0.9.0):
|
---|
17 | ----------------------------------------
|
---|
18 | - proxy-status: general usage stats
|
---|
19 | optional parameters: profile (show info for this profile only)*
|
---|
20 |
|
---|
21 | - ca-profiles: list of all defined profiles, and their listen ports
|
---|
22 | optional parameters: name (name of the profile to retrieve, omit for all)*
|
---|
23 |
|
---|
24 | - cws-connectors: list of all defined connectors and current usage stats for each
|
---|
25 | optional parameters: name (name of the connector to retrieve, omit for all)*
|
---|
26 | profile (list only connectors within specified profile)
|
---|
27 |
|
---|
28 | - proxy-users: list of all active user sessions, and their current status
|
---|
29 | optional parameters: name (user name to retrieve, omit for all)**
|
---|
30 | profile (list only sessions within specified profile)
|
---|
31 |
|
---|
32 | - cache-status: usage stats from the current cache implementation
|
---|
33 | optional parameters: none
|
---|
34 |
|
---|
35 | - error-log: the last 40 (by default) events of general interest
|
---|
36 | optional parameters: profile (list only events related to specified profile)
|
---|
37 |
|
---|
38 | - file-log: the last 40 (by default) events of log level WARNING or SEVERE from the main file log
|
---|
39 |
|
---|
40 | - user-log: the last 100 transactions results for a specific user (requires debug="true" for the profile)
|
---|
41 | optional parameters: name (list transactions for named user instead of calling user, admin only)
|
---|
42 |
|
---|
43 | - user-warning-log: the last 40 transactions with attached warnings (aggregated if the same warning occurs often)**
|
---|
44 | optional parameters: profile (list only events related to the specified profile)*
|
---|
45 |
|
---|
46 | - all-services: all services found on all connectors (requires service mapping and a services file)
|
---|
47 | optional parameters: profile (list only services for specified profile)
|
---|
48 |
|
---|
49 | - watched-services: currently watched services, based on active user sessions (requires a services file)
|
---|
50 | optional parameters: profile (list only services for specified profile)
|
---|
51 |
|
---|
52 | - export-services: dump of the current internal state for the service mappers (which sids can and cannot decode).
|
---|
53 | optional parameters: name (export map only for the specified connector, omit for all)
|
---|
54 |
|
---|
55 | - fetch-cfg: returns a copy of the current proxy.xml (NOTE: response is without the cws-status-resp wrapper element!)
|
---|
56 | optional parameters: none
|
---|
57 |
|
---|
58 | - ctrl-commands: lists available control commands, and their options
|
---|
59 | optional parameters: name (only show command definitions for the specified group name)
|
---|
60 |
|
---|
61 | - status-commands: list available status commands, and their options
|
---|
62 | optional parameters: none
|
---|
63 |
|
---|
64 | - last-seen: lists information about disconnected or removed users (seen before by the session manager)
|
---|
65 | optional parameters: name (only show seen info for the specified user, omit to show all)**
|
---|
66 |
|
---|
67 | - login-failures: lists failed logins and connection attempts per user/ip-address.
|
---|
68 | optional parameters: name (only show details for specified user/ip)**
|
---|
69 |
|
---|
70 | - system-properties: shows all JVM system properties (superuser only)
|
---|
71 |
|
---|
72 | - system-threads: dumps all the JVM threads as strings (superuser only)
|
---|
73 |
|
---|
74 | - export-services: dumps the internal state of the service maps (admin only)
|
---|
75 | optional parameters: format (set to hex or default)
|
---|
76 |
|
---|
77 | * By default, only profiles (or connectors within profiles) that the calling user has access to will be shown.
|
---|
78 |
|
---|
79 | ** All commands are available to any user, however only admin users will be able to retrieve information about
|
---|
80 | other users. A non-admin user will receive only their own data, regardless of the name parameter.
|
---|
81 |
|
---|
82 | As of 0.8.6 status-commands are also dynamic, so any piece of code (plugin or otherwise) may add new ones or override
|
---|
83 | the function of a command in the above built-in set.
|
---|
84 |
|
---|
85 |
|
---|
86 | Available control commands:
|
---|
87 | ---------------------------
|
---|
88 | This list is dynamic (commands can be added by plugins and extensions).
|
---|
89 | Run the ctrl-commands status command as an admin user to obtain the current list, e.g:
|
---|
90 | http://proxy-host:8082/xmlHandler?command=ctrl-commands
|
---|
91 |
|
---|
92 | Built in commands:
|
---|
93 |
|
---|
94 | - reset-connector: clear the service map for one connector (delete all cannot-decode entries causing new probes)
|
---|
95 | required parameters: name (connector name)
|
---|
96 |
|
---|
97 | - reset-service: clear the service map entry for one service.
|
---|
98 | required parameters: id (service id, by default in decimal format, use 0x prefix when specifying hex value)
|
---|
99 | profile (name of profile that contains this service)
|
---|
100 |
|
---|
101 | - retry-connector: attempt re-connection for one connector (also temporarily enables disabled connectors)
|
---|
102 | required parameters: name (connector name)
|
---|
103 |
|
---|
104 | - disable-connector: Temporarily disables a connector (until config reload or manual retry)
|
---|
105 | required parameters: name (connector name)
|
---|
106 |
|
---|
107 | - set-profile-debug: Temporarily changes debug flags (set to false for profile ALL or omit profile to delete ecm logs)
|
---|
108 | required parameters: value (true/false)
|
---|
109 | optional parameters: profile (profile name)
|
---|
110 |
|
---|
111 | - set-user-debug: Temporarily changes debug for a user (enabling/disabling log-ecm, log-emm, log-zap etc)
|
---|
112 | required parameters: value (true/false)
|
---|
113 | optional parameters: name (user name)
|
---|
114 |
|
---|
115 | - kick-user: close all sessions for the specified user
|
---|
116 | required parameters: name (user name)
|
---|
117 |
|
---|
118 | - osd-message: send newcamd osd message to all sessions for specified user (or for all users), where clientid is mgcamd or acamd
|
---|
119 | required parameters: text (message text, avoid special characters)
|
---|
120 | optional parameters: name (user name)
|
---|
121 |
|
---|
122 | - clear-warnings: delete all user transaction warnings
|
---|
123 |
|
---|
124 | - clear-events: delete all CWS events
|
---|
125 |
|
---|
126 | - remove-seen: clear the last-seen log.
|
---|
127 | optional parameters: name (user name, remove only entries for this user)
|
---|
128 |
|
---|
129 | - remove-failed: clear the login-failures log.
|
---|
130 | optional parameters: mask (glob wildcard mask, remove only entries with name matching this mask)
|
---|
131 |
|
---|
132 | - gen-keystore: auto-create a java keystore containing a self-signed certificate for the specified hostname
|
---|
133 | required parameters: password (keystore + key password)
|
---|
134 | host (hostname to use for cn)
|
---|
135 | validity (number of days)
|
---|
136 |
|
---|
137 | - shutdown: stop this proxy node
|
---|
138 |
|
---|
139 |
|
---|
140 | Remote config updates:
|
---|
141 | ----------------------
|
---|
142 | It is possible to deploy an updated proxy.xml via HTTP post, using the target-url: /cfgHandler
|
---|
143 |
|
---|
144 | To fetch the current config xml, use the status command fetch-cfg (admin user required).
|
---|
145 | When posting an updated config to /cfgHandler, use the same approach as for Method 1 below, with two exception:
|
---|
146 | - The new config xml is to be posted as is, no cws-status-req or cws-command-req wrapper elements.
|
---|
147 | - As a consequence, only HTTP basic auth can be used for the login (no way to specify session id in the xml).
|
---|
148 |
|
---|
149 | The response xml will be a single element:
|
---|
150 | (proxy -> client)
|
---|
151 | <cfg-result message="Preformatted result message indicating success or describing the error"/>
|
---|
152 |
|
---|
153 |
|
---|
154 | Command method 1 - HTTP post
|
---|
155 | --------------------
|
---|
156 | The default target url for both status and control commands is: /xmlHandler (e.g http:/proxy-host:8082/xmlHandler).
|
---|
157 | Xml queries need to be sent with content-type: text/xml (if no charset is specified UTF-8 is always assumed).
|
---|
158 | No url encoding or base64 encoding should be used.
|
---|
159 |
|
---|
160 | Login can use standard HTTP basic auth or, in situations where that isn't practical, the following xml-based login
|
---|
161 | can be used instead:
|
---|
162 |
|
---|
163 | (login request, client -> proxy)
|
---|
164 | <cws-status-req ver="1.0">
|
---|
165 | <cws-login>
|
---|
166 | <user name="user" password="password"/>
|
---|
167 | </cws-login>
|
---|
168 | </cws-status-req>
|
---|
169 |
|
---|
170 | (successful login reply for an admin user, proxy -> client)
|
---|
171 | <cws-status-resp ver="1.0">
|
---|
172 | <status state="loggedIn" user="user" admin="true" super-user="true" session-id="fcjrij9z" />
|
---|
173 | </cws-status-resp>
|
---|
174 |
|
---|
175 | The user identity is any user defined by the current usermanager.
|
---|
176 | A session id is by default valid until the proxy is restarted (no timeout).
|
---|
177 | Incorrect user/pass results in:
|
---|
178 |
|
---|
179 | (failed login reply, proxy -> client)
|
---|
180 | <cws-status-resp ver="1.0">
|
---|
181 | <status state="failed" />
|
---|
182 | </cws-status-resp>
|
---|
183 |
|
---|
184 | Once a session id has been obtained, the syntax for status commands looks like this:
|
---|
185 | (proxy-status command, client -> proxy)
|
---|
186 | <cws-status-req ver="1.0">
|
---|
187 | <session session-id="fcjrij9z"/>
|
---|
188 | <proxy-status include="true"/>
|
---|
189 | </cws-status-req>
|
---|
190 |
|
---|
191 | Multiple status commands can be sent in one request, like this:
|
---|
192 | (multiple commands, client -> proxy)
|
---|
193 | <cws-status-req ver="1.0">
|
---|
194 | <session session-id="fcjrij9z"/>
|
---|
195 | <proxy-status include="true"/>
|
---|
196 | <cache-status include="true"/>
|
---|
197 | <ca-profiles include="true"/>
|
---|
198 | <cws-connectors include="true"/>
|
---|
199 | </cws-status-req>
|
---|
200 |
|
---|
201 | To specify parameters for the status commands, just add attributes:
|
---|
202 | (cws-connector command with name parameter, client -> proxy)
|
---|
203 | <cws-status-req ver="1.0">
|
---|
204 | <cws-connectors name="testconn" include="true"/>
|
---|
205 | </cws-status-req>
|
---|
206 |
|
---|
207 | A control command uses a slightly different syntax, and there can be only one command per request.
|
---|
208 | (reset-connector control command, client -> proxy)
|
---|
209 | <cws-command-req ver="1.0">
|
---|
210 | <session session-id="fckivamh"/>
|
---|
211 | <command command="reset-connector" name="test"/>
|
---|
212 | </cws-command-req>
|
---|
213 |
|
---|
214 |
|
---|
215 | Command method 2 - HTTP get
|
---|
216 | -------------------
|
---|
217 | Uses the same url endpoint as post: /xmlHandler
|
---|
218 | Login is standard HTTP basic auth only (a session cookie called JSESSIONID will be set if supported).
|
---|
219 |
|
---|
220 | The same commands are available, but everything is specified on the query string as follows:
|
---|
221 | http://proxy-host:8082/xmlHandler?command=commandName¶mName=paramValue&otherParam=otherValue...
|
---|
222 |
|
---|
223 | Examples:
|
---|
224 | /xmlHandler?command=proxy-users&profile=cable (retrieve all user sessions in profile cable)
|
---|
225 | /xmlHandler?command=cws-connectors&name=testconn (retrieve connector named testconn)
|
---|
226 |
|
---|
227 | Control commands work the same way:
|
---|
228 | /xmlHandler?comand=osd-message&text=hello&name=userx (send osd text hello to all sessions for userx)
|
---|
229 |
|
---|
230 |
|
---|
231 | Example status web
|
---|
232 | ------------------
|
---|
233 | The proxy comes with a simple web site (cs-status.war) made up entirely of client side javascript and xslt. This is
|
---|
234 | not a conventional web application, but rather a standalone script that will fetch xml from the proxy (ajax-style) and
|
---|
235 | format it using xslt directly in the browser. It has been tested in firefox 2/3, ie 6/7/8 and safari 3/4 (and probably
|
---|
236 | won't work in anything else). To get an idea of how the status web works with the xml api, check out the /api-test.html
|
---|
237 | test page.
|
---|
238 |
|
---|
239 | To modify the visual appearance (or even structure) of the status web, look at the following files:
|
---|
240 |
|
---|
241 | /xslt/cws-status-resp.xsl - This is the xslt xml that transforms all status command responses into html (or xhtml).
|
---|
242 | It generates markup that will reference the css styles in: /css/style.css
|
---|
243 | For more information on xslt: http://en.wikipedia.org/wiki/XSL_Transformations
|
---|
244 |
|
---|
245 | /js/cs-status.js - The javascript that defines the different sections, and handles pre-processing of the xml (before
|
---|
246 | the xslt transform) and post-processing of the html. The post-processing involves adding script handlers to
|
---|
247 | specific id's in the markup created by the xslt transform, making the status web somewhat interactive.
|
---|
248 | Adding javascript handlers to the browser dom tree (rather than hard coding them into the markup) is sometimes
|
---|
249 | referred to as 'unobtrusive' javascript.
|
---|
250 |
|
---|
251 | The cs-status.war file (a zip containing the directory tree served by the built in httpd) can be replaced at runtime
|
---|
252 | and changes will take effect immediately, no restart required.
|
---|
253 |
|
---|
254 |
|
---|
255 | Shell script/agent access
|
---|
256 | -------------------------
|
---|
257 | Xslt can also be used to extract live proxy information from the command line, for scripts or monitoring agents like
|
---|
258 | those used by NMS solutions such as nagios or zabbix. This is one example using wget and xsltproc from libxslt:
|
---|
259 |
|
---|
260 | #!/bin/sh
|
---|
261 | echo $(wget --no-check-certificate -q -O - https://admin:passwd@proxy.host.com:8082/xmlHandler?command=proxy-status | xsltproc test.xsl -)
|
---|
262 |
|
---|
263 | Where test.xsl is a snippet from the cws-status-resp.xsl file that handles formatting of the proxy-status + jvm output.
|
---|
264 | In a real use case you would likely extract only specific values, but this shows that any advanced formatting can be used:
|
---|
265 |
|
---|
266 | <?xml version="1.0"?>
|
---|
267 | <xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
|
---|
268 | <xsl:output method="text"/>
|
---|
269 | <xsl:template match="cws-status-resp">
|
---|
270 | <xsl:for-each select="//proxy-status/jvm">
|
---|
271 | CSP <xsl:value-of select="../@version"/>
|
---|
272 | OS: [<xsl:value-of select="@os"/>]
|
---|
273 | JVM: [<xsl:value-of select="@name"/> <xsl:value-of select="@version"/>]
|
---|
274 | Heap: [<xsl:value-of select="@heap-total - @heap-free"/>k/<xsl:value-of select="@heap-total"/>k]
|
---|
275 | TC: [<xsl:value-of select="@threads"/>]
|
---|
276 | <xsl:if test="@filedesc-open"> FD: [<xsl:value-of select="@filedesc-open"/>/<xsl:value-of select="@filedesc-max"/>]</xsl:if>
|
---|
277 | </xsl:for-each>
|
---|
278 | <xsl:for-each select="//proxy-status">
|
---|
279 | Name: <xsl:value-of select="@name"/>
|
---|
280 | Started: <xsl:value-of select="@started"/>
|
---|
281 | Uptime: <xsl:value-of select="@duration"/>
|
---|
282 | Cards: <xsl:value-of select="@connectors"/>
|
---|
283 | Sessions: <xsl:value-of select="@sessions"/> (active: <xsl:value-of select="@active-sessions"/>)
|
---|
284 | Estimated total capacity: <xsl:value-of select="@capacity"/> (ECM->CW transactions per CW-validity-period)
|
---|
285 | Estimated total load: <xsl:value-of select="sum(//connector/@ecm-load)"/> (unique transactions during the last period)
|
---|
286 | ECM total: <xsl:value-of select="@ecm-count"/> (average rate: <xsl:value-of select="@ecm-rate"/>/s)
|
---|
287 | ECM forwards: <xsl:value-of select="@ecm-forwards"/>
|
---|
288 | <xsl:if test="@ecm-count > 0"> (<xsl:value-of select="format-number(@ecm-forwards div @ecm-count, '##.0%')"/>)</xsl:if>
|
---|
289 | ECM cache hits: <xsl:value-of select="@ecm-cache-hits"/>
|
---|
290 | <xsl:if test="@ecm-count > 0"> (<xsl:value-of select="format-number(@ecm-cache-hits div @ecm-count, '##.0%')"/>)</xsl:if>
|
---|
291 | ECM denied: <xsl:value-of select="@ecm-denied"/>
|
---|
292 | <xsl:if test="@ecm-denied > 0"> (<xsl:value-of select="format-number(@ecm-denied div @ecm-count, '##.0%')"/>)</xsl:if>
|
---|
293 | ECM failures: <xsl:value-of select="@ecm-failures"/>
|
---|
294 | EMM total: <xsl:value-of select="@emm-count"/>
|
---|
295 | </xsl:for-each>
|
---|
296 | </xsl:template>
|
---|
297 | </xsl:stylesheet> |
---|