ULab NewServerDameon

Adding a new server daemon to the uLab system

Background

Each uLab server daemon is designed for a specific purpose and runs on one or more servers, with the listening port number of each type of daemon normally being identical across the entire uLab system. Each daemon communicates to its connected client(s) via the master authorization and control server, with communication being established by the master server daemon. The master server daemon reads the uLab instance configuration from its MySQL database, therefore most of the new server daemon installation process involves editing this database.

NOTE: While I have provided example commands for the command line mysql tool to ensure maximum compatibility, you may use any MySQL-compatible database editor (including GUI tools) that you are comfortable with to make the requisite changes. All operations are against the database "remotelab"; the "USE `remotelab`;" command (or an equivalent) must therefore be used to set the database on initial connection and before any subsequent operations are performed.

Process

Adding a new server daemon to the system requires the following actions:

1. Adding the new server daemon(s) to the uLab system
   
   For production servers, this would include transferring binaries and setting up startup scripts
   For a test server, this step can be skipped.
2. Informing the uLab system of the existence of the new type of daemon
   
   Each service type is stored in the table "serviceid", and consists of a unique service type ID (serviceid), short name (name), description (description), client library file name (client_library), version (version), and single instance flag (single_instance). The client library file name is used to load and execute an appropriate client part on connection. For example, the client part of the FPGA viewer is provided by "libremotelab_fpgaviewer.so", therefore "libremotelab_fpgaviewer" would be used in the service type specification for the FPGA access system.
   
   An example MySQL command to set up the remote FPGA viewer service type is:
   

   INSERT INTO `servicetypes`(`serviceid`,`name`,`description`,`client_library`,`version`,`single_instance`) values (123,'Remote FPGA','Remote FPGA access [X3CS200-FT256]','libremotelab_fpgaviewer',1,1);

3. Adding a new workspace (optional)
   
   Workspace information is stored in the "stations" table. This table is only used to notify the uLab of workspace existence and does not directly map available services to any particular workspace. The fields contained in this table are a workspace unique identifier (pk), the workspace short name (name), and the workspace long description (description).
   
   To add an example test workspace, the following MySQL command may be used:
   

   INSERT INTO `stations`(`pk`,`name`,`description`) values (456,'Example Workspace for Testing Purposes','Test Workspace');

4. Informing the uLab system of the existence of the new server daemon(s) for a particular workspace
   
   Server daemon details and daemon workspace membership are both stored in the "services" table. This table maps a particular service type and hostname/port to one or more workspace identifiers, thus adding the referenced server daemon to the indicated workspace. The fields contained in the service table are workspace ID (station), service type ID (servicetype), hostname of the server running the server daemon (hostname), and the listening port of the server daemon (port).
   
   An example command joining an FPGA access daemon to the test workspace given above is:
   

   INSERT INTO `services`(`station`,`servicetype`,`hostname`,`port`) values (465,123,'test-machine.my.domain',4010);

5. Allowing access to the new server(s) and services by editing workspace access controls as needed
   
   Workspace access is controlled by a simple list linking workspace IDs with authorized POSIX groups. This list is contained in the "permissions" database, whose only two fields are the workspace ID (station) and the group name (groupname).
   To allow access to the test workspace by the "developers" POSIX group, the following MySQL command may be used:
   
   

   INSERT INTO `permissions`(`station`,`groupname`) values ('456','developers');

6. Marking the new server(s) online
   
   The uLab system contains mechanisms to detect server faults and seamlessly fail over to working servers. The online/offline status of each server is maintained in the "status" table, whose only two fields are server hostname (hostname) and a binary flag indicating server status (online, 0=offline, 1=online). To mark the new test server above online, the following MySQL command may be used:
   
   

   INSERT INTO `status`(`hostname`,`online`) values ('test-machine.my.domain','1');