Definition of the Client Server Protocol

The protocol is a streamed ASCII protocol which is line oriented. Three bytes are special control characters: \n (012) is the line-ending byte which needs to be attached to any line, EOT (004) is the end of transmission sent by the server after any response because server responses can have many (also empty) lines and CAN (030) is the cancel byte which can be sent out-of-band by the client to abort the request or inline in the servers response if during response processing an error occurs.

This defines the full client server protocol including the handshaking with four example commands(first one OK, second cancelled by user, third has an execution error, fourth is cancelled by the server):

    SERVER                                     CLIENT
    Greeting\n
    Protocol <protocol number>\n
    <space sep. list of serv opts>\n
                                               <requested serv option>\n
                                               <more opts>\n
                                               <...>\n
                                               \n
    OK\n
    ----------    SSL handshaking if required  ------------------
    SSL_accept()
                                               SSL_connect()
    -------------------------------------------------------------
                                               <command>
    0  <number of columns>\n
    <line 1 of response>\n
    ...
    <line n of response>\n
    EOT[<session-id>]EOT
                                               <command>
    <error-code> <literal err.>\n
    ...                                        CAN (Out-of-Band!)
    CAN
    <abort error code>\n
    EOT[<session-id>]EOT
                                               <command>
    <err-code> <comment>\n
    EOT[<session-id>]EOT
                                               <command>
    0\n
    <line 1 of response>\n
    ...
    CAN (timeouts, back end-error...)
    <err-code> <comment>\n
    EOT[<session-id>]EOT

Remarks: The greeting is a free-form greeting string sent by the server. The client cannot make any assumptions about the content, apart that it ends in a version number, which may contain dots. The intention is to allow the client to display this greeting. The client should only depend on the protocol version number, which is integer for any assumptions on the protocol or the available calls.

As of protocol version 2 the server options can include "plain", "ssl" and "statistics" giving the possible ways for the connection security/encryption. The statistics option, used for monitoring is explained in the Monitoring support in AMGA section.

The requested server option sent by the client is either "plain" or "ssl", requesting an ssl connection. Alternatively the client may resume a session by responding "resumeSSL<sessionID>" or "resume<sessionID>". The other options sent one by one on a line consist of an integer number and the value for that option:

• 0 <login name>="">
• 1 <Plain text="" full="" name>="">
• 2
• 3 <group mask>="">
• 4 <current directory>="">
• 5 <password> Where the login name is the requested user id string, the full name is entirely optional and should contain the full user name of the user as in the comment field of /etc/passwd. The group and user permission masks are 3 character fields like umask. All of these fields are optional, unless e.g. the server requires that particular user to use a password for authentication.

In case a session is resumed, the server ignores any additional options requested by the client, and will expect a command next if no SSL session is requested, that is the "OK\\n" will only be sent if SSL is being used. This reduces round-trips in case of No-SSL, but the OK is necessary to synchonize SSL startup in case of an SSL session.

Any authentication failure is sent by the server as the response to the first command, to save round-trips in the case of sessions (see below) and because the result of the authentication may only be known after the initialization of the SSL session if the certificate is being used for authentication.

Commands are strings terminated by a newline as explained in the Metadata Access from the Shell section . Sending a wrong command does not violate the protocol, but results in an error "3 Illegal command". Three special commands are part of the protocol:

• quit Asks the server to close the connection.
• exit The same as quit.
• close Ask the server to send a session ID and then close the connection.

Every command is answered by an integer error code, which is 0 in case of everything OK. Error codes are not part of the protocol, but part of the responses to commands.

If sessions are forced on the server, then the server will always send a sessionID at the end of any response to the command and then simply close the connection. This also saves round-trips.

The CAN bytes to interrupt the streaming of a result sent by the server are sent in a TCP out-of-band message. However if the server decides to interrupt the streaming of a response the CAN byte is sent in-band.

---