source: tags/0.9.0/README.HttpXmlApi.txt

Last change on this file was 16, checked in by bowman, 14 years ago

Added a status command and web view showing the latest 40 filelog events with level WARNING or SEVERE (admin users only).

File size: 15.0 KB
Line 
1CSP HTTP/XML API
2----------------
3
4The proxy has a simple query api that allows remote monitoring and some limited control/administration features.
5To use this, rmi and status-web need to be enabled in proxy.xml (see proxy-reference.html).
6
7There are two forms of commands: status and control. Each can be executed either via HTTP post containing an xml
8query or by HTTP get, specifying the command and parameters on the query string. Both methods will produce the
9same response xml from the proxy, but only post allows multiple commands to be included in one request.
10
11These features are designed to be VERY simple to modify and extend, and they're to be considered a default example.
12One 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).
13This 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
16Available 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
80other users. A non-admin user will receive only their own data, regardless of the name parameter.
81
82As of 0.8.6 status-commands are also dynamic, so any piece of code (plugin or otherwise) may add new ones or override
83the function of a command in the above built-in set.
84
85
86Available control commands:
87---------------------------
88This list is dynamic (commands can be added by plugins and extensions).
89Run the ctrl-commands status command as an admin user to obtain the current list, e.g:
90http://proxy-host:8082/xmlHandler?command=ctrl-commands
91
92Built 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
140Remote config updates:
141----------------------
142It is possible to deploy an updated proxy.xml via HTTP post, using the target-url: /cfgHandler
143
144To fetch the current config xml, use the status command fetch-cfg (admin user required).
145When 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
149The 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
154Command method 1 - HTTP post
155--------------------
156The default target url for both status and control commands is: /xmlHandler (e.g http:/proxy-host:8082/xmlHandler).
157Xml queries need to be sent with content-type: text/xml (if no charset is specified UTF-8 is always assumed).
158No url encoding or base64 encoding should be used.
159
160Login can use standard HTTP basic auth or, in situations where that isn't practical, the following xml-based login
161can 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
175The user identity is any user defined by the current usermanager.
176A session id is by default valid until the proxy is restarted (no timeout).
177Incorrect 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
184Once 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
191Multiple 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
201To 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
207A 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
215Command method 2 - HTTP get
216-------------------
217Uses the same url endpoint as post: /xmlHandler
218Login is standard HTTP basic auth only (a session cookie called JSESSIONID will be set if supported).
219
220The same commands are available, but everything is specified on the query string as follows:
221http://proxy-host:8082/xmlHandler?command=commandName&paramName=paramValue&otherParam=otherValue...
222
223Examples:
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
227Control 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
231Example status web
232------------------
233The proxy comes with a simple web site (cs-status.war) made up entirely of client side javascript and xslt. This is
234not a conventional web application, but rather a standalone script that will fetch xml from the proxy (ajax-style) and
235format 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
236won'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
237test page.
238
239To 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
251The cs-status.war file (a zip containing the directory tree served by the built in httpd) can be replaced at runtime
252and changes will take effect immediately, no restart required.
253
254
255Shell script/agent access
256-------------------------
257Xslt can also be used to extract live proxy information from the command line, for scripts or monitoring agents like
258those used by NMS solutions such as nagios or zabbix. This is one example using wget and xsltproc from libxslt:
259
260#!/bin/sh
261echo $(wget --no-check-certificate -q -O - https://admin:passwd@proxy.host.com:8082/xmlHandler?command=proxy-status | xsltproc test.xsl -)
262
263Where test.xsl is a snippet from the cws-status-resp.xsl file that handles formatting of the proxy-status + jvm output.
264In 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-&gt;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 &gt; 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 &gt; 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 &gt; 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>
Note: See TracBrowser for help on using the repository browser.