From c0ab702e2612e910c37cf3eada61e71bf55bac6b Mon Sep 17 00:00:00 2001 From: Timothy Pearson Date: Sat, 9 Mar 2013 23:08:09 -0600 Subject: Add initial README file and initial dependency charts --- README | 12 ++++ .../dependencies/create_dependency_charts.sh | 16 +++++ .../libtdekrb-trinity-dependencies.pdf | Bin 0 -> 10138 bytes .../dependencies/libtqtrla-dependencies.pdf | Bin 0 -> 18589 bytes ...mote-laboratory-client-trinity-dependencies.pdf | Bin 0 -> 22458 bytes .../ulab-adminsysctlserver-dependencies.pdf | Bin 0 -> 22872 bytes .../ulab-adminusermgmtserver-dependencies.pdf | Bin 0 -> 22881 bytes .../dependencies/ulab-authserver-dependencies.pdf | Bin 0 -> 22823 bytes .../ulab-fpgaprogserver-dependencies.pdf | Bin 0 -> 22252 bytes .../dependencies/ulab-fpgaserver-dependencies.pdf | Bin 0 -> 22256 bytes .../dependencies/ulab-gpibserver-dependencies.pdf | Bin 0 -> 23325 bytes .../ulab-sensormonserver-dependencies.pdf | Bin 0 -> 22848 bytes documentation/developers/protocol/rfc.txt | 78 +++++++++++++++++++++ protocol.txt | 78 --------------------- 14 files changed, 106 insertions(+), 78 deletions(-) create mode 100644 README create mode 100755 documentation/developers/dependencies/create_dependency_charts.sh create mode 100644 documentation/developers/dependencies/libtdekrb-trinity-dependencies.pdf create mode 100644 documentation/developers/dependencies/libtqtrla-dependencies.pdf create mode 100644 documentation/developers/dependencies/remote-laboratory-client-trinity-dependencies.pdf create mode 100644 documentation/developers/dependencies/ulab-adminsysctlserver-dependencies.pdf create mode 100644 documentation/developers/dependencies/ulab-adminusermgmtserver-dependencies.pdf create mode 100644 documentation/developers/dependencies/ulab-authserver-dependencies.pdf create mode 100644 documentation/developers/dependencies/ulab-fpgaprogserver-dependencies.pdf create mode 100644 documentation/developers/dependencies/ulab-fpgaserver-dependencies.pdf create mode 100644 documentation/developers/dependencies/ulab-gpibserver-dependencies.pdf create mode 100644 documentation/developers/dependencies/ulab-sensormonserver-dependencies.pdf create mode 100644 documentation/developers/protocol/rfc.txt delete mode 100644 protocol.txt diff --git a/README b/README new file mode 100644 index 0000000..65c5bc7 --- /dev/null +++ b/README @@ -0,0 +1,12 @@ +This is the source repository for the hardware access portion of the uLab remote laboratory system. + +The terminal services components are hosted in a separate GIT repository, available from the uLab project's home page at http://ulab.trinitydesktop.org + +This repository is a hierarchical tree, separating the main components into several related groups. The main groups are: +attic: Old files of any type, provided for historical reasons. These files are not required to build or use the uLab system, but may be of interest to academics who wish to know more about the origins of the uLab system. +clients: uLab clients and client parts for any supported operating systems. Each client part is matched with a server daemon in the "servers" top level directory. +database: Database structure descriptors, which can be used to create the database(s) utilized by the uLab servers. +documentation: Various files providing developer-facing documentation for the uLab system internals. User-facing documentation also included in a subdirectory of this directory. +fpga: FPGA-specific files, utilities, and programming software. This includes the hardware debug module required for FPGA viewer operation, and the various software components utilized by the FPGA Programmer daemon. +lib: Libraries providing core uLab functionality. These libraries are utilized by most uLab software, including both servers and clients. +servers: uLab server daemons for any supported operating systems. Each server daemon is matched with a client part in the "clients" top level directory. diff --git a/documentation/developers/dependencies/create_dependency_charts.sh b/documentation/developers/dependencies/create_dependency_charts.sh new file mode 100755 index 0000000..9b88c65 --- /dev/null +++ b/documentation/developers/dependencies/create_dependency_charts.sh @@ -0,0 +1,16 @@ +#!/bin/bash + +function generate_chart { + debtree --no-recommends --max-depth=2 $1 | dot -Tpdf -o $1-dependencies.pdf +} + +generate_chart libtdekrb-trinity +generate_chart libtqtrla +generate_chart remote-laboratory-client-trinity +generate_chart ulab-adminsysctlserver +generate_chart ulab-adminusermgmtserver +generate_chart ulab-authserver +generate_chart ulab-fpgaprogserver +generate_chart ulab-fpgaserver +generate_chart ulab-gpibserver +generate_chart ulab-sensormonserver diff --git a/documentation/developers/dependencies/libtdekrb-trinity-dependencies.pdf b/documentation/developers/dependencies/libtdekrb-trinity-dependencies.pdf new file mode 100644 index 0000000..fd35842 Binary files /dev/null and b/documentation/developers/dependencies/libtdekrb-trinity-dependencies.pdf differ diff --git a/documentation/developers/dependencies/libtqtrla-dependencies.pdf b/documentation/developers/dependencies/libtqtrla-dependencies.pdf new file mode 100644 index 0000000..db9d2c7 Binary files /dev/null and b/documentation/developers/dependencies/libtqtrla-dependencies.pdf differ diff --git a/documentation/developers/dependencies/remote-laboratory-client-trinity-dependencies.pdf b/documentation/developers/dependencies/remote-laboratory-client-trinity-dependencies.pdf new file mode 100644 index 0000000..a3cc07c Binary files /dev/null and b/documentation/developers/dependencies/remote-laboratory-client-trinity-dependencies.pdf differ diff --git a/documentation/developers/dependencies/ulab-adminsysctlserver-dependencies.pdf b/documentation/developers/dependencies/ulab-adminsysctlserver-dependencies.pdf new file mode 100644 index 0000000..52da25d Binary files /dev/null and b/documentation/developers/dependencies/ulab-adminsysctlserver-dependencies.pdf differ diff --git a/documentation/developers/dependencies/ulab-adminusermgmtserver-dependencies.pdf b/documentation/developers/dependencies/ulab-adminusermgmtserver-dependencies.pdf new file mode 100644 index 0000000..a3f8481 Binary files /dev/null and b/documentation/developers/dependencies/ulab-adminusermgmtserver-dependencies.pdf differ diff --git a/documentation/developers/dependencies/ulab-authserver-dependencies.pdf b/documentation/developers/dependencies/ulab-authserver-dependencies.pdf new file mode 100644 index 0000000..e068d7d Binary files /dev/null and b/documentation/developers/dependencies/ulab-authserver-dependencies.pdf differ diff --git a/documentation/developers/dependencies/ulab-fpgaprogserver-dependencies.pdf b/documentation/developers/dependencies/ulab-fpgaprogserver-dependencies.pdf new file mode 100644 index 0000000..4caaaa9 Binary files /dev/null and b/documentation/developers/dependencies/ulab-fpgaprogserver-dependencies.pdf differ diff --git a/documentation/developers/dependencies/ulab-fpgaserver-dependencies.pdf b/documentation/developers/dependencies/ulab-fpgaserver-dependencies.pdf new file mode 100644 index 0000000..d594e6a Binary files /dev/null and b/documentation/developers/dependencies/ulab-fpgaserver-dependencies.pdf differ diff --git a/documentation/developers/dependencies/ulab-gpibserver-dependencies.pdf b/documentation/developers/dependencies/ulab-gpibserver-dependencies.pdf new file mode 100644 index 0000000..e095761 Binary files /dev/null and b/documentation/developers/dependencies/ulab-gpibserver-dependencies.pdf differ diff --git a/documentation/developers/dependencies/ulab-sensormonserver-dependencies.pdf b/documentation/developers/dependencies/ulab-sensormonserver-dependencies.pdf new file mode 100644 index 0000000..9806eed Binary files /dev/null and b/documentation/developers/dependencies/ulab-sensormonserver-dependencies.pdf differ diff --git a/documentation/developers/protocol/rfc.txt b/documentation/developers/protocol/rfc.txt new file mode 100644 index 0000000..c520be2 --- /dev/null +++ b/documentation/developers/protocol/rfc.txt @@ -0,0 +1,78 @@ +(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 a TQDataStream in printable (7-bit) mode 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. + +Furthermore, to ensure robust command processing, the master server utilizes a frame-based protocol, with a single character of value 255 indicating the end of a frame. The value 255 is therefore reserved and must not appear in data transmitted to or from the master server, except when used to indicate the end of a frame. The three-character abbreviation EOF will be used to refer to this frame termination character within this document. + +================================================================================== +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] +EOF + +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. Each value returned by the server must be followed with an EOF character. + +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. + +Example: LIST EOF + +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. If the specified user is already connected to a laboratory station, the server must return the case-sensitive text "ERRPREVCN", and should block all commands other than QUIT. + +Example: BIND EOF + StationType EOF + +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. If the backend service is not available in the active laboratory workspace, the server should respond with the string "ERRNOSERV" 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 EOF + libremotelab_fpgaviewer EOF + +TSTP: +Returns a long long value containing the termination timestamp, if set +If an administrator has enabled automatic termination of the client's session, a UNIX timestamp with the exact termination time must be returned. If automatic termination has not been enabled, the server must return zero. + +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. + +Example: QUIT EOF + +================================================================================== +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", followed by an EOF character. 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", followed by an EOF character, after which the server should close the client connection. \ No newline at end of file diff --git a/protocol.txt b/protocol.txt deleted file mode 100644 index c520be2..0000000 --- a/protocol.txt +++ /dev/null @@ -1,78 +0,0 @@ -(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 a TQDataStream in printable (7-bit) mode 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. - -Furthermore, to ensure robust command processing, the master server utilizes a frame-based protocol, with a single character of value 255 indicating the end of a frame. The value 255 is therefore reserved and must not appear in data transmitted to or from the master server, except when used to indicate the end of a frame. The three-character abbreviation EOF will be used to refer to this frame termination character within this document. - -================================================================================== -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] -EOF - -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. Each value returned by the server must be followed with an EOF character. - -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. - -Example: LIST EOF - -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. If the specified user is already connected to a laboratory station, the server must return the case-sensitive text "ERRPREVCN", and should block all commands other than QUIT. - -Example: BIND EOF - StationType EOF - -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. If the backend service is not available in the active laboratory workspace, the server should respond with the string "ERRNOSERV" 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 EOF - libremotelab_fpgaviewer EOF - -TSTP: -Returns a long long value containing the termination timestamp, if set -If an administrator has enabled automatic termination of the client's session, a UNIX timestamp with the exact termination time must be returned. If automatic termination has not been enabled, the server must return zero. - -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. - -Example: QUIT EOF - -================================================================================== -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", followed by an EOF character. 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", followed by an EOF character, after which the server should close the client connection. \ No newline at end of file -- cgit v1.2.3