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.

  1. 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.

  2. Request:

    Tag has to be “ricci”, and “version” and “function” attributes have to be present. Functions, and their arguments are described below.

  3. 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:



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)



Links:
Modules
Variables