Ricci listens on port ??? 11111 ??? and only responds to clients
that connect thru SSL and present SSL certificate.
If presented
certificate (or its signing CA) is stored in ricci's cert database,
client is considered authenticated, otherwise, client can invoke only
“authenticate” function (see bellow). Once authenticated,
presented certificate is saved into cert database, and client has
access to all functions.
All messages are XML based. Client is greeted with hello message on connection establishment, then client submits request and waits for response. Client can make multiple requests in a single session.
Hello message:
<ricci authenticated="true/false" clusteralias="cluster alias" clustername="cluster_name" hostname="hostname.domainname" os="Red Hat Enterprise Linux AS release 4 (Nahant Update 3)" version="1.0"/>
Hello message contains protocol version number, host
information and “authenticated” attribute.
If
“authenticated” attribute is “true” client is authenticated
and can proceed with further calls, otherwise, client can only
invoke “authenticate” function (see bellow). Once authenticated,
client can invoke all functions.
Request:
Tag has to be “ricci”, and “version” and “function” attributes have to be present. Functions, and their arguments are described below.
Function response:
<ricci authenticated="true/false" success="success value – unsigned int" version="1.0"/>
Function response has “ricci” tag, and “authenticated”, “version” and “success” attributes.
Ricci function call successfulness is stored in “success” attr, and can be one of:
General return values:
0 – function call succeeded
1 –
missing “version” attribute
2 – version not supported
3
– missing “function” attribute
4 – function is not
present in selected protocol version
5 – not authenticated, and
function call requires it
6 – internal error (should never
happen)
Function specific return values:
10 – authentication failed
– see “authenticate”
11 – missing <batch/> - see
“process_batch”
12 – no such batch - see “batch_report”
Functions:
authenticate
<ricci function="authenticate" password="root password" version="1.0"/>
Authenticate using root password. If root password is
valid, client's SSL certificate will be saved into certs database.
Subsequent connections that present saved cert will be
auto-authenticated.
If signing CA is listed in
/var/lib/ricci/certs/auth_CAs.pem, certificate is considered valid,
and client needs not call this function at all.
Function takes only “password” argument,
specified as an attribute. It has to be a valid root password of
host ricci is running on.
- If password is not valid, 10 is
returned. Connection is closed after third unsuccessful
authentication attempt.
- If password is valid, client's
certificate is saved into cert database, and function returns 0.
Afterwards, client has access to all functions. If new connection
is initiated using the same certificate, client will have full
access without need to call “authenticate” function.
This is the only function that can be invoked if
“authenticated” attribute of hello message is set to “false”.
Once authenticated, access is allowed to all functions.
unauthenticate
<ricci function="unauthenticate" version="1.0"/>
Mark session as unauthenticated, and remove client's
SSL certificate from cert database.
Access will be allowed to
“authenticate” function only.
New connections, established
using current certificate, will not be auto-authenticated; client
will have to re-authenticate.
Function takes no arguments.
- Function should
always succeed and return 0.
list_modules
<ricci function="list_modules" version="1.0"/>
Returns a list of installed modules,
attached to the response message, in format:
<module
name=”module1”/>
<module name=”module2”/>
Function takes no arguments.
- Function should
always succeed and return 0.
process_batch
<ricci
function="process_batch" async="true/false"
version="1.0">
<batch>
<module
name=”module1”>
... module1 request ...
</module>
<module
name=”module2”>
... module2 request
...
</module>
</batch>
</ricci>
Processes batch request, see below for batch description.
Processing can be synchronous and asynchronous. If synchronous, “process_batch” will return after the whole batch is completed, returning final batch report. There is no way to retrieve report again.
If asynchronous, “process_batch” will return immediately, returning initial batch report (“batch_id” can be extracted from it). Batch report can be retrieved later, using “batch_report” function. Since batch progress is updated for multi-module request, asynchronous processing can be used to implement progress bars.
Function takes two arguments, async attribute (defaults to “false”), and batch.
- Function returns 11, if batch is missing.
-
Otherwise it returns 0.
batch_report
<ricci function="batch_report" batch_id=”batch_id” version="1.0"/>
Retrieve report of batch with id “batch_id”.
Batch report is attached to the function response. If batch is completed (status is either 0 or 4), report will be removed, and won't be accessible any more; otherwise, it can be retrieved again.
Function takes one arguments, “batch_id”, whose report is attached to the function response.
- Function returns 12, if there is no batch with such
“batch_id”.
- It returns 0 otherwise.
Batch description:
Batch is a list of module requests (see respective module
description for request description). It has a “batch_id”
attribute, by which a report can be retrieved.
Modules are
processed sequentially; if one of modules fails, further processing
is aborted, and batch' status is set to 4 – request failure. If all
modules complete successfully, batch' status is set to 0.
Each
module, and batch, has a status attribute, describing its progress.
Status is updated after completion of each module.
<batch batch_id="10271302"
status="2">
<module name="module1"
status="0">
... completed module request
...
</module>
<module name="module2"
status="2"/>
<module name="module3"
status="1"/>
</batch>
Status codes:
0 - completed successfully (batch and module)
1
- scheduled (batch and module)
2 - in progress (batch and module)
3 - module failure (module only)
4 - request failure (batch
and module)
5 - removed from scheduler (module only)