Available status comma$$$ (as of 0.9.0):
----------------------------------------
- proxy-status: general usage stats
optional parameters: profile (show info for this profile only)*
- ca-profiles: list of all defined profiles, and their listen ports
optional parameters: name (name of the profile to retrieve, omit for all)*
- cws-connectors: list of all defined connectors and current usage stats for each
optional parameters: name (name of the connector to retrieve, omit for all)*
profile (list only connectors within specified profile)
- proxy-users: list of all active user sessions, and their current status
optional parameters: name (user name to retrieve, omit for all)**
profile (list only sessions within specified profile)
- cache-status: usage stats from the current cache implementation
optional parameters: none
- error-log: the last 40 (by default) events of general interest
optional parameters: profile (list only events related to specified profile)
- user-log: the last 100 transactions results for a specific user (requires debug="true" for the profile)
optional parameters: name (list transactions for named user instead of calling user, admin only)
- user-warning-log: the last 40 transactions with attached warnings (aggregated if the same warning occurs often)**
optional parameters: profile (list only events related to the specified profile)*
- all-services: all services found on all connectors (requires service mapping and a services file)
optional parameters: profile (list only services for specified profile)
- watched-services: currently watched services, based on active user sessions (requires a services file)
optional parameters: profile (list only services for specified profile)
- export-services: dump of the current internal state for the service mappers (which sids can and cannot decode).
optional parameters: name (export map only for the specified connector, omit for all)
- fetch-cfg: returns a copy of the current proxy.xml (NOTE: response is without the cws-status-resp wrapper element!)
optional parameters: none
- ctrl-comma$$$: lists available control comma$$$, and their options
optional parameters: none
- status-comma$$$: list available status comma$$$, and their options
optional parameters: none
- last-seen: lists information about disconnected or removed users (seen before by the session manager)
optional parameters: name (only show seen info for the specified user, omit to show all)**
* By default, only profiles (or connectors within profiles) that the calling user has access to will be shown.
** All comma$$$ are available to any user, however only admin users will be able to retrieve information about
other users. A non-admin user will receive only their own data, regardless of the name parameter.
As of 0.8.6 status-comma$$$ are also dynamic, so any piece of code (plugin or otherwise) may add new ones or override
the function of a command in the above built-in set.
Available control comma$$$:
---------------------------
This list is dynamic (comma$$$ can be added by plugins and extensions).
Run the ctrl-comma$$$ status command as an admin user to obtain the current list, e.g:
You are not allowed to view links.
Register or
Login$$$
Built in comma$$$:
- reset-connector: clear the service map for one connector (delete all cannot-decode entries causing new probes)
required parameters: name (connector name)
- reset-service: clear the service map entry for one service.
required parameters: id (service id, by default in decimal format, use 0x prefix when specifying hex value)
profile (name of profile that contains this service)
- retry-connector: attempt re-connection for one connector (also temporarily enables disabled connectors)
required parameters: name (connector name)
- kick-user: close all sessions for the specified user
required parameters: name (user name)
- osd-message: send newcamd osd message to all sessions for specified user (or for all users), where clientid is mgcamd or acamd
required parameters: text (message text, avoid special characters)
optional paramaters: name (user name)
- clear-warnings: delete all user transaction warnings
- clear-events: delete all CWS events
- shutdown: stop this proxy node
Remote config updates:
----------------------
It is possible to deploy an updated proxy.xml via HTTP post, using the target-url: /cfgHandler
To fetch the current config xml, use the status command fetch-cfg (admin user required).
When posting an updated config to /cfgHandler, use the same approach as for Method 1 below, with two exception:
- The new config xml is to be posted as is, no cws-status-req or cws-command-req wrapper elements.
- As a consequence, only HTTP basic auth can be used for the login (no way to specify session id in the xml).
The response xml will be a single element:
(proxy -> client)
Command method 1 - HTTP post
--------------------
The default target url for both status and control comma$$$ is: /xmlHandler (e.g http:/proxy-host:8082/xmlHandler).
Xml queries need to be sent with content-type: text/xml (if no charset is specified UTF-8 is always assumed).
No url encoding or base64 encoding should be used.
Login can use standard HTTP basic auth or, in situations where that isn't practical, the following xml-based login
can be used instead:
(login request, client -> proxy)
(successful login reply for an admin user, proxy -> client)
The user identity is any user defined by the current usermanager.
A session id is by default valid until the proxy is restarted (no timeout).
Incorrect user/pass results in:
(failed login reply, proxy -> client)
Once a session id has been obtained, the syntax for status comma$$$ looks like this:
(proxy-status command, client -> proxy)
Multiple status comma$$$ can be sent in one request, like this:
(multiple comma$$$, client -> proxy)
To specify parameters for the status comma$$$, just add attributes:
(cws-connector command with name parameter, client -> proxy)
A control command uses a slightly different syntax, and there can be only one command per request.
(reset-connector control command, client -> proxy)
Command method 2 - HTTP get
-------------------
Uses the same url endpoint as post: /xmlHandler
Login is standard HTTP basic auth only (a session cookie called JSESSIONID will be set if supported).
The same comma$$$ are available, but everything is specified on the query string as follows:
You are not allowed to view links.
Register or
Login ... herValue...
Examples:
/xmlHandler?command=proxy-users&profile=cable (retrieve all user sessions in profile cable)
/xmlHandler?command=cws-connectors&name=testconn (retrieve connector named testconn)
Control comma$$$ work the same way:
/xmlHandler?comand=osd-message&text=hello&name=userx (send osd text hello to all sessions for userx)
Example status web
------------------
The proxy comes with a simple web site (cs-status.war) made up entirely of client side javascript and xslt. This is
not a conventional web application, but rather a standalone script that will fetch xml from the proxy (ajax-style) and
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
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
test page.
To modify the visual appearance (or even structure) of the status web, look at the following files:
/xslt/cws-status-resp.xml - This is the xslt xml that transforms all status command responses into html (or xhtml).
It generates markup that will reference the css styles in: /css/style.css
For more information on xslt: You are not allowed to view links.
Register or
Login/js/cs-status.js - The javascript that defines the different sections, and handles pre-processing of the xml (before
the xslt transform) and post-processing of the html. The post-processing involves adding script handlers to
specific id's in the markup created by the xslt transform, making the status web somewhat interactive.
Adding javascript handlers to the browser dom tree (rather than hard coding them into the markup) is sometimes
referred to as 'unobtrusive' javascript.
The cs-status.war file (a zip containing the directory tree served by the built in httpd) can be replaced at runtime
and changes will take effect immediately, no restart required.