Registering Your Servers
Before you can interact with your dsTest servers you'll need to register them with dsClient Desktop, providing the information necessary for both TCP and SSH connectivity. You'll register your servers in the Server List screen and you can reach it through the Servers>Organize... menu selection. Using this screen you can also "lock" a server, thereby preventing others from using it, access the Status and Operations screen for the selected server, or a terminal window with a server via SSH.
Your server list is stored in the cache directory as servers.xml. Whenever you modify the list the application also writes a servers_backup.xml.
Managing Your Server List
You can use the controls in the server list tool bar to add a server (), to remove a server (), or to kick off a scan of all the servers in your list () and refresh the information downloaded from your servers. You can find out more about what dsClient downloads from dsTest in Data Storage and Management.
The server list itself provides visual clues as to a server's status.
Connectivity: the icon that precedes the server's name indicates whether the application was able to successfully establish a TCP connection with dsTest () or not (). You'll see these symbols used elsewhere in the application to depict connection status. In the example shown the application has active connections with all but one server.
Accessibility: the icon that follows the server's name indicates whether you are locked out of the server () or whether the server is accessible ().
The application's log will indicate the error received if a TCP connection could not be established. Not reachable indicates that dsClient does not have connectivity to the server itself, while connection refused indicates that the server was reached but dsTest was not running. dsClient will not attempt to establish a connection with a locked server until after the lock is joined.
Defining a Server
You can modify a server's parameters at any time by selecting the server in the list and editing the information in the fields displayed. When you add a new server, or when your server list is empty, dsClient will add a server named "New Server" to the list and it's properties will be displayed in the definition pane. The server's parameters are divided into the three sections discussed below.
Unless indicated otherwise, all information is required.
Name your server and describe where and how to connect to it.
Server ID: dsClient creates a unique identifier for each dsTest instance, dst_n, where n simply increments for each server record. You cannot modify this value.
Server Name: The text you enter in this field will be displayed in this screen's server list and throughout the application where a dsTest server is selected or identified.
IP Address/Host Name: The IP address of dsTest's Control Interface, or a host name that will resolve to that address either through a hosts file or DNS.
Communication Method: If dsTest uses SSL on it's Control Interface select XML/SSL/TCP; otherwise the default value, XML/TCP, is appropriate.
Management Ports: These settings specify the TCP ports used for dsTest and for the streaming engines it provides. You can customize these ports as needed for your network. The values you configure for the High Priority Port, the Low Priority Port, and the RESTful API Port will be included in the launch command when you launch dsTest. dsClient launches the streaming engines using the ports configured here. Keep in mind that all of these ports are associated with dsTest's management IP address and therefore must have unique values if used concurrently. The values for dsTest's high and low priority ports as well as the RESTful API port must be unique. You may use the same port number for all of the streaming engines but in that case you will only be able to run one at a time. You can learn more about these ports and their uses in dsTest Management Ports.
From time to time dsClient uses SSH to perform dsTest management tasks such as transferring files, installing a license, upgrading dsTest, or launching dsTest. The application supports both password authentication and key-based authentication. Follow the instructions below to configure the preferred method and credentials to connect to the server.
Authentication Method: Select either Password (default) or Key-Based. If you chose Key-Based you can indicate whether your key file is protected with a passphrase with the Passphrase Required checkbox.
User Name: Enter the user name of the account that will be used for SSH activities. The application will default to the devsol account. When invoking a task that requires root permission, a super user password will be requested separately.
Password: Required for password authentication or when a key file is protected with a passphrase. This value is encrypted when saved to the servers XML file.
Private Key File: Required for key-based authentication, select the appropriate key file for this server. If the file doesn't appear as an option, check the Import New File checkbox and then click the Browse... button to select the file and import it into the application's cache. The newly imported file should then be available to select.
Use the Test button to attempt an SSH connection with the information displayed. Since a server may be configured to not respond to invalid authentication attempts, the request will time out after 60 seconds and you will be notified if that is the case. You will also be notified if the attempt succeeded or was explicitly rejected.
Identify which Developing Solutions products are installed on your server. Use shift-click or Ctrl-click to select multiple products.
After your server has been scanned, the current versions of dsTest and other packages will be displayed in the adjacent panel. These values will be updated when new versions are recognized in subsequent server scans.
Deleting a Server
Select the desired server and click the icon. You will be asked to confirm the deletion before any action is taken. Deleting a server has no effect on any Workspaces or reports you may have associated with that server in the past.
Saving Your List
After you have taken any of the above actions, the Save button at the bottom of the screen will become enabled and clicking it will commit the changes you've made. If you wish to discard those changes you can close the screen without saving. It's usually best to save after each server is defined or modified.
If you have made changes but are unable to save the list, it is due to invalid or missing information in a server configuration. Look for ! next to any text fields or drop-down lists and make sure that every server has at least one product selected.
Scanning Your Servers
dsClient attempts to connect to all of the servers on your list when the application starts. It first attempts to ascertain the accessibility of the servers - which servers are locked, if any and then scans the servers available. During this scan dsClient always downloads the current dsTest license and executes a version command. If the response to the version command contains a hitherto unknown software version, dsClient establishes a new schema cache for that version and proceeds to download the schema files from dsTest.
From time to time you may find it necessary to scan a server while dsClient is running - if you have upgraded a server or installed a new license, or if a new server comes online after dsClient starts, for example. The Refresh icon is available when the list is not being modified or after you have saved your changes. Click the icon to manually trigger the same server scan that runs at startup. You can continue working on other tasks since the scan runs in the background.
A schema is statically assigned to a Workspace at the time it is opened or created. If you perform a scan and download a new schema version, any XML files that are already open will continue to use their assigned schema. You must close and then re-open the files in order for the new version to be applied and for new parameters to become available.
Locking and Unlocking Your Servers
The server lock feature enables you to reserve a dsTest server for exclusive use. The feature provides a mechanism to ensure that your tests cannot be disrupted by other dsTest users unless those users have the password that was used to lock the server. The Lock feature can be engaged from either dsClient Terminal or dsClient Desktop. Instructions for using this feature with the CLI can be found here.
In order to use the lock feature to best advantage, we recommend that you create additional user accounts within the devsol user group that was established when dsTest was installed. We provide a utility, add_devsol_user, that you can use to easily create those accounts.
The Manage Server Locks dialog is accessible from the Servers > Manage menu, from a button at the bottom of the Servers List screen, and is opened automatically at start-up if any of the servers on your list are locked. Action buttons will dynamically enable depending on the states of the selected servers, i.e. if all are unlocked you can choose to lock or disconnect; if all are disconnected you can only connect. Only actions that are suitable for all selections are enabled. Multiple selections can be made by using Ctrl-click or shift-click.
To lock a server, click the Server Locks button at the bottom of the screen. A pop-up window will present the current status of all configured dsTest servers. A server is locked by choosing the server and providing the password for the account that launched dsTest. If the password does not match, the lock request will be refused.
When the correct password is entered, the locked server will be joined, and access to dsTest resources on that server are now possible.
In similar fashion, using the correct password you can click Join Lock on a locked computer to gain access to dsTest or Unlock Server to remove the restriction and allow open access to the server.
Aspects of the Lock Feature
Server lists presented when creating or opening a report will only display connected and accessible (unlocked or lock-joined) servers.
The server list presented for a workspace will include all servers that host the required application. Transmit to Server, however, is disabled if the server is not connected, not available, or if any validation errors are present. The visual indicator at the bottom of the workspace window will dynamically update if the server's status changes.
The Test Connection button checks the connection to the server, queries the lock status, and will update the server status.
The manage actions that appear in the Manage sub-menu will be disabled if the client is locked out of the server, as is the Manage button that appears in the Organize server list properties panel.
The communications infrastructure will trap transaction failure due to server lock and update the server's status. An alert dialog will be shown if an interactive screen that is associated with that server is open.
A fatal error will occur if a live OM chart or report is being run and another user locks the server.
If the server becomes locked with the Server Operations window is open, button actions will be disabled, including SSH actions.