(c) 2012 Timothy Pearson, Raptor Engineering Licensed under the GPL v2 ================================================================================== Overview ================================================================================== The remote laboratory architecture is highly modularized, with the client containing multiple modules, each of which connects directly to a master server. The server similarly consists of a master control server, which manages connections to backend servers, each providing access to a particular laboratory service. Multiple backend servers may be required to access a particular set of laboratory resources, referred to herein as a laboratory station. The client container itself must initiate the first connection and negotiate access to the requested type of laboratory resources, including prompting the user with a list of available resource types. Once the client container has established a connection, the client modules may connect to the master server and will receive stream access to the appropriate backend server daemon. If a client module attempts to connect to the master server when a container connection is not open, the server must reject the connection. Negotation and master control protocols must use TQDataStream to serialize and deserialize commands and responses, while client modules and their associated server daemons may choose to implement any binary or text-based communication protocol required for the specific application. The use of TQDataStream is strongly suggested where possible to maintain codebase consistency. Due to the block encryption used by Kerberos, stream block delimeters are required at the transfer layer. The delimeter must be a single newline character, 0xD ('\n'), and will indicate the end of a block has been reached; therefore, the block is ready for decryption and processing. All block transfers must use Base64 encoding, and the encoded block text must not contain the newline character. ================================================================================== Master Server ================================================================================== The master server acts as a semi-transparent communications relay between the client and any requested backend servers. It must decrypt all incoming client data and reencrypt it for transmission to the appropriate backend server over the backend link. On initial connection from the client container, the master server must negotiate a successful Kerberos connection. Once this connection is established, the server must transmit the following data types: TQ_UINT32 [magic number] TQ_UINT32 [protocol version] The client may terminate the connection at any time, or provide invalid data to the server. If the server loses connection sync with the client or receives invalid data from the client, it must gracefully terminate the connection without interruption to connections from other users. If the client container connection is terminated, all other service connections for that user must also be terminated. After initial negotiation, the server must enter command mode. In this mode the server expects to receive a command string. The following commands are currently supported: LIST BIND SERV QUIT If an invalid command is specified, the server should respond with a string containing the case-sensitive text "ERRINVCMD". The expected actions and/or data transmission/reception on receipt of a valid command are detailed below. LIST: Returns a list of available laboratory stations The server should return a TQValueList, where StationType consists of the following types for each laboratory station: Descriptions should be constructed from station service type flags as known to the master server, and multiple stations with identical resources should be consolidated to one station type ID and description. Station type IDs do not need to be universally unique, but must not conflict with other station type IDs. Subsequent commands may alter the station type ID mappings. BIND : Connects to a specified laboratory station If a station with the specified Service ID list is available, the server must mark that station as in use by the authenticated user, must return the case-sensitive text "OK", and should block all commands other than QUIT. If a station with the specified Service ID list is not available, the server must respond with a string containing the case-sensitive text "ERRUNAVAL" and must re-enter command mode. Example: BIND StationType SERV Requests a connection to the specified backend server on the laboratory station If BIND was previously commanded on this connection, the server must respond with a string containing the case-sensitive text "ERRINVCMD". If no station has been reserved for this user via a call to BIND on an active connection, the server must respond with a string containing the case-sensitive text "ERRNOCONN". If the backend server is not available, i.e. a connection attempt or attempts have failed to establish a connection, the server should respond with the string "ERRNOTAVL" and must close the client connection. Otherwise, the server must return a string containing the case-sensitive text "OK" and then immediately enter binary pass-through mode between the backend server and the client. Example: SERV ServiceType QUIT: Gracefully terminates the connection. The server should return the case-sensitive text "OK" and must immediately close all active connections for the current user. ================================================================================== Backend Server ================================================================================== On initial connection from the client container, the master server must negotiate a successful Kerberos connection. Once this connection is established, the server must transmit a string containing the case-sensitive text "OK". The server has now fully established a secure bidirectional channel to the client and may proceeed to use the channel for any purpose. If the server wishes to reject the connection, for example due to a hardware failure, it must transmit a string containing the case-sensitive text "ERRNOTAVL", after which the server should close the client connection.