Advanced Topics

This section describes advanced topics you may encounter when implementing Turbo Server.

Manually Configure Turbo Hub Server

Turbo Hub Server enables you to manually configure settings during setup. Using this process you can control the database connection strings used by Turbo Hub Server and the domain names for the Administration and Hub Sites. Turbo Hub Server supports the use of any connection string format used by Microsoft SQL Server.

Complete the following steps to install Turbo Server:

  1. Download the Turbo Hub Server setup file and save it locally.

  2. Open a Microsoft Windows Command Prompt and navigate to the directory of the saved setup file.

  3. Enter the following command: Setup.exe /noprovision. This brings up a file installation wizard. Navigate through the prompts until file installation is complete, and then select Finish.

Complete the following steps to manually configure Turbo Server:

  1. Return to the Microsoft Windows Command Prompt and navigate to the directory where the installation files are saved. You specified this location in the previous step; the default location is C:\Program Files\Turbo Server.

  2. To manually configure Turbo Hub Server, type the command: Server.exe /provision [ADMINISTRATOR EMAIL]. Add any of the optional command-line arguments from the following table. Omitting any command-line arguments causes the default setting to apply.

Command Line Argument

Setting

/dblibrary "Integrated Security=true;Data Source=[SERVER];Initial Catalog=Library;"

Configures the connection string for the library database where settings and user information is stored.

/dbmanager "Integrated Security=true;Data Source=[SERVER];Initial Catalog=Manager;"

Configures the connection string for the manager database where usage information is stored.

/wwwsite http://www.[MYSITE].com:[PORT]

Assigns the port and fully qualified domain name for the hub site.

/adminsite http://www.[MYSITE].com:[PORT]

Assigns the port and fully qualified domain name for administration site.


The following is a sample command to set all four settings:
server.exe /provision admin@acme.com /dblibrary "Integrated Security=true;Data Source=acme;Initial Catalog=Library;" /dbmanager "Integrated Security=true;Data Source=acme;Initial Catalog=Manager;" /wwwsite http://www.acme.com /adminsite http://www.acme.com:81

Note: The Microsoft SQL Server connection string will depend on the Microsoft SQL Server configuration. For more information about the connection string, contact the database administrator. Before configuring the Turbo Server, confirm that the running user for the Windows service has appropriate access rights to the database. The service runs under the Local System account by default but the running user can be changed in the Windows services settings.

Select Enter to submit the command and choose Y to proceed.

Fully-qualified domain names can be specified on the Domain page of the Administration Site. For more information about modifying servers refer to Managing the Domain.

Configure Image Streaming from Hub

By default Application Servers download the application images from Hub before running them. It is however possible to stream the images directly from Hub. To configure the streaming, follow the steps listed below.

1. Prepare a file share on Hub

The first step is to create a file share where Hub will store the images. Clients will use it as an image cache. For this document, let's assume we want to use the path D:\image-share. It is available for client machines as a Windows share at an address \hub\share (hub is the name of Hub in the internal network).

2. Configure the image cache on Hub

Now, it’s time to configure Hub. Sign in as an administrator, go to the Server list and click on the server in the hub role. Scroll to the bottom, and there should be an Image Path section. You need to type there the local path of the share folder with images subfolder. In our example, it will be:

Server enable image cache

After saving the settings, Hub will restart, and new images will automatically appear in the image cache.

3. Configure the image path on the clients

To enable streaming, we need to configure the clients to use the hub image cache. It is as simple as running: turbo config --image-path=\\hub\share --all-users.

Side note:

The latest Turbo client (19.12.2108) added new options for configuring the machine-scope client settings. The --all-users flag behavior is inconsistent between various commands. Thus we introduced a TURBOAS environment variable to define the scope of the running commands. For example, to set the image-path globally, you may run the following commands in PowerShell:

$env:TRUBOAS=”all-users”
turbo config --image-path=\\hub\share --as-override (if you want to allow users to change this setting, use --as-inherit)

4. Use the stream (turbo run/installi)

With the image path configured, you may use turbo run or installi on the clients’ machines, and they should directly use the images from the image cache.

Configure Turbo Server Security

This section explains how to manually configure Turbo Server's security settings on common Microsoft Windows platforms. These settings restrict external connections to the Turbo Server sites and services.

To secure the Turbo Server, enable Microsoft Windows Firewall with Advanced Security. The default settings of Microsoft Windows Firewall with Advanced Security block all external connections to the Administration and Portal Sites (assigned to port 80 by default). After Microsoft Windows Firewall with Advanced Security is enabled, add exceptions to the default settings to provide licensed users with access the Hub Site.

Complete the following steps to enable Microsoft Windows Firewall with Advanced Security for access to the Hub Site:

  1. Open the Control Panel and select System and Security.

  2. Open Administrative Tools, then select Windows Firewall with Advanced Security.

  3. Select Inbound Rules and choose New Rule.

  4. Select Port.

  5. Select TCP and Specific local ports. Add the ports required by your server role as described in Firewall and Security.

  6. Select Allow the Connection.

  7. Select the domain, private, and public profiles.

  8. Add a name and description.

Using the Launch Configuration Web Service

The launch configuration web service provides storage for application configurations which may be used to execute applications from a custom web portal using turbo urls. If the Turbo Portal is used as your application portal, this service is not necessary.

Enabling the Launch Configuration Web Service

The launch configuration service may be configured using the API Keys form on the admin site.

Server launch config service

In this example, the authentication key is set to F207AC681BBD40A0BF56ECF95B344EBC. This value is required to be passed to all POST requests to the service in the X-Config-Api-Key HTTP header. The authentication key can be any string value but should be something long and randomly generated.

NOTE: It is important that this authentication key be kept secret to prevent unauthorized users from generating malicious application configurations. Any usage of the key or the code to submit a configuration must be done on the web portal's server side code (not in the browser client where a user can retrieve the key).

Submitting a Custom Application Configuration

To submit a custom application configuration, a simple web POST such as shown in the follow example may be used:

// create a application configuration object. this example assumes that there is a hub image called "test/test".
// this application configuration will result in the turbo command: turbo try test/test --isolate=full
var appConfig = {
   v: 1,
   verb: "try",
   repoId: "test/test",
   isolation: "full"
}

// submit the application configuration to the service
var request = new XMLHttpRequest();
request.open("POST", "http://[hub-server]/start/app");
request.setRequestHeader("Content-Type", "application/json");
request.setRequestHeader("X-Config-Api-Key", "F207AC681BBD40A0BF56ECF95B344EBC");
request.send(JSON.stringify(appConfig));
request.onreadystatechange = function () {
   if(request.readyState === 4) {
      if(request.status === 200) {
         console.log(request.responseText);
      }
      else {
         console.log("request failed with status code: " + request.status);
      }
   }
};

Submit a POST request to the web service with the configuration json string, note the required request headers of Content-Type and X-Config-Api-Key. The response json contains a set of turbo urls that can be used to execute the application from the browser, for example:

{
   "url": "turbo://[hub-server]/start/app?t=config&h=sha256:66a123724dd6f8fb5ee050644a5494795fed2a1901d0c56def4030d8a6a26175&scheme=http&v=2",
   "urlInternal": "turbo://[hub-server]/start/app?t=config&h=sha256:66a123724dd6f8fb5ee050644a5494795fed2a1901d0c56def4030d8a6a26175&scheme=http&v=2"
}

Once submitted, the configuration will be available for the configured timeout period. This can be set on the server administration website (the default is 24-hour). The timeout is reset whenever the configuration is retrieved.

You may also lookup configs from the launch configuration service by performing a GET request on the same URL with an HTTP/S scheme, for example:

http://[hub-server]/start/app?h=sha256:66a123724dd6f8fb5ee050644a5494795fed2a1901d0c56def4030d8a6a26175&scheme=http&v=2

Executing an Application Configuration

// open turbourl to config
var url = "turbo://[hub-server]/start/app?t=config&h=sha256:66a123724dd6f8fb5ee050644a5494795fed2a1901d0c56def4030d8a6a26175&scheme=http&v=2";
window.open(url);

To execute a submitted configuration file, you must use a turbo protocol url. Your web portal can open these turbo urls to attempt to execute the configuration. The turbo protocol is handled by the Turbo Client if installed and will execute the configuration that it points to.

The first time you attempt to open a turbo url, the browser will show a security message like the following (each browser is different). The user can choose to hide future messages for turbo urls.

Server launch config service consent

After the turbo url is allowed by the browser, a security message from the Turbo Client will be shown (see below). This message is to ensure that the user trusts the hub that the container is coming from. It is important that user do not execute containers from untrusted hubs. The user can choose to run this instance or trust all instances from the same hub.

Server launch config service trust

After this the user will be prompted to login if necessary. Once logged in (or if login is not necessary), the container will execute.

Application Configuration JSON Format

{
   // The configuration JSON format version. Must be 1.
   "v":1

   // The turbo command used to execute the application. Possible values are "try", "run", and "new". Required.
   "verb":"try",

   // The repository ID of the image to execute. Required.
   "repoId":"test/test",

   // The isolation mode to run in. These are the same as those that can be passed to turbo run commands with `--isolate` flag. Optional, default is "full".
   "isolation":"full",

   // Allows merge access to special user folders such as documents. Optional, default is false.
   "mergeUser":false,

   // Whether network isolation is enabled in the container. Optional, default is false.
   "isolateNetwork":false,

   // A list of network mappings. Optional, default is empty.
   // Example: routes:[{"rule":"ip","type":"deny"},{"rule":"ip://*.turbo.net","type":"allow"}],
   "routes":[],

   // A list of additional image repository IDs that are permanently layered in to the container. Optional, default is empty.
   // Example: layers: [{"repoId":"npp/notepadplusplus","enabled":true}],
   "layers":[],

   // A list of additional image repository IDs that are temporarily layered in to the container. Optional, default is empty.
   // Example: using: ["gnu/wget"]
   "using":[],

   // Overrides the default startup file. Optional, default is no override.
   //"startupFile":"cmd",

   // Command line parameters that are passed to the startup file of the container. Optional, default is empty.
   // Example: cmdLineArgs: "echo test",
   "cmdLineArgs":"",

   // Automatically synchronizes the application state and settings with the Turbo Hub server. Optional, default is false.
   "sync": true,

   // Enables pre-caching of application DLL and EXE files on the Application Servers’ local disk for faster loading. Optional, default is false.
   "useDllCache": false,

   // Specifies drive visibility in the virtual application using the format: <*|V:|-V:>[,...]. Optional, default is *,-T:.
   "hideDrive":"*,-T:",

   // The VM version is a version string that specifies which Turbo VM version will be used for execution. Optional, default is latest.
   //"vm": "19.6.1427.29"
}

Testing HTTPS (SSL) with a Self-Signed Certificate

Follow these steps to test Turbo Hub Server with SSL enabled using a self-signed certificate.

  1. Configure the container server to use HTTPS/SSL with the Turbo Hub Server command line administration utility.

    # change hub url to use https
    > server.exe admin /server web-address https://[hub-server-host]
    
    # set certificate files
    > server.exe admin /server ssl-certificate-file [path to .crt file]
    > server.exe admin /server ssl-certificate-key-file [path to .key file]
    
    # optionally set the certificate key chain file
    > server.exe admin /server ssl-certificate-chain-file [path to chain file]
    
  2. On the client machine, double-click on your certificate.crt file to install it in the "Trusted Root Certification Authorities for Windows"

  3. Access the hub using the Turbo Client command line tools, Turbo Launcher, or connected Turbo Streaming Server portal.

Disabling TLS/SSL certificate validation on Portal requests

The Portal performs TLS/SSL certificate validation when making TLS connections, rejecting connections with expired or otherwise invalid certificates.

If you wish to disable certificate validation, you may do so manually with the following steps:

  1. RDP onto your Portal server.
  2. Open an administrator command prompt and run the command: <install path>\Server.exe /XShellEx=cmd, replacing <install path> with the install path of your Turbo Server.
  3. In the new command prompt, run the command notepad C:\portal\build\main.js.
  4. At the top of the file, add the line: process.env.NODE_TLS_REJECT_UNAUTHORIZED = '0';.
  5. Save the file, close notepad, and close the command prompts.
  6. Open Services from the start menu and locate Turbo Server. Right-click it and click Restart.
  7. Wait a few minutes for the Turbo service to restart, then load the portal website and confirm the change.

WARNING: Disabling TLS/SSL certificate validation allows the Portal to make insecure HTTPS requests and is strongly discouraged in production environments.

WARNING: This change will be lost when upgrading your Turbo Server. Please reapply the change after upgrade.

Federation

Understanding Federation

Federation feature allows distributing hub servers across different regions to achieve faster streaming for end users and allows higher availability by redundancy. Federation works by assigning a root server from which the child hub servers to copy repositories from.

Federation child communicates with the root server using an API key which is a secret key between the servers. API keys can be disabled and recreated on demand from the admin user interface to ensure repository access to the server is secure. API keys can be configured to grant low privilege tokens which ensure the key is used only to read repository data from the root server.

Federation repositories can be explicitly cached and synchronized on the child hub by adding them from the federation repository page. Federation repositories can also be automatically forwarded to the root server by using request forwarding. Request forwarding is achieved by forwarding https requests to the root hub.

If the root hub is unavailable due to network outage or maintenance, the child hub will continue to service requests against explicitly synchronized repositories without any downtime to the end users. Request forwarding will be temporarily unavailable. If the child hub becomes unavailable, then the end users will only be able to use their locally cached applications.

Configuring Federation

Follow the documentation to setup a Hub Server and your repositories to the hub. The server which will contain the source of the repositories will be called the root server.

  1. Setup an API Key

    On the root server, navigate to https://{root}/admin/hub/keys.aspx. Add an API Key with a descriptive name such as "Federation Key for {child}". Run as system setting is not required. Copy the generated API key.

  2. Add the federation source to child hub

    On the child hub(s), navigate to https://{child}/admin/hub/federationsource.aspx. Change the Hub text box to the root hub host's URL. Add the previously copied API Key and press save.

  3. Add a federated repository

    Navigate to https://{child}/admin/hub/federation.aspx. Add a federated repository by using the repository identifier namespace/name (example: mozilla/firefox), and press save. The repository should begin to synchronize immediately with the status displayed on the federation page.

  4. Use the federated repository

    Once the repository has finished synchronizing, you may begin using the repository on the child server from a workspace.

    You can also install the repository image directly using the turbo cli on the user's machine.

    turbo config --hub={child}
    turbo login {user}
    turbo installi namespace/name
    

    The application should be available from the start menu.

Hub Storage

The Hub Server stores repositories and sessions in a file system based database. The database is located under the path C:\ProgramData\Turbo Server\io (formerly C:\turbo-server\io). Administrators should back up that folder in case of drive failure.

The legacy default folder C:\turbo-server\io is a virtualized folder, which will store files in the Turbo Server installation folder sandbox. In addition, any folder under the installation folder will be virtualized and stored in the sandbox. It is recommended to migrate to a folder outside of any virtualized folders.

The recommended action to migrate the legacy Hub storage is to clear the Hub storage setting field which will migrate the data to the new default folder (C:\ProgramData\Turbo Server\io). Prior to migration, please ensure that the Hub storage has been backed up in case of unexpected failures, and that there is enough room in the destination drive.

Override Single Sign-On Authentication Method

Internal Turbo Servers users may sign in to a Portal configured to use the single sign-on authentication method by appending the ?mode=forms URL parameter to the login page:

http://my-turbo-server/login?mode=forms

This override can be used when testing and troubleshooting the Turbo Server configuration.

Locale Settings

Turbo Server uses the service user's language and region settings to format user-facing dates, times, and other locale-sensitive data.

To update your locale settings:

  1. Login to your Turbo Server host machine as the service user.
  2. Open the Language control panel and confirm that the language pack for your desired language is installed. To install a missing language pack, add the language using Add a language and then click Options on the newly added language.
  3. Open the Region control panel and select your desired Format.
  4. Restart the Turbo Server service to apply your changes.

Change the Turbo Server Service User

The Turbo Server service user is specified during the initial Turbo Server install.

The service user can be set to a different account from the Services management console (services.msc). Locate the Turbo Server service and Right-click > Properties. In the Log On tab, enter the credential of the new account. Note that the service user requires the Log On As a Service right, which is automatically granted when you apply the change.

Switch Turbo Server service user

After changing the service user, update the security settings of the following file to grant Read and Write permissions for the new user and remove the rights of the old user:

  • C:\ProgramData\Turbo Server\Settings.xml

Update the security settings of the following folders to grant the Write permission for the new user and remove the rights of the old user:

  • C:\Windows\Microsoft.NET\Framework64\v4.0.30319\Temporary ASP.NET Files
  • C:\ProgramData\Turbo Server\io (or the Hub Storage Path if set)
  • C:\Program Files (x86)\Turbo Server\Sandbox (or the Turbo Server install directory\Sandbox folder if using a non-default install path)

Update settings.xml to grant permissions to new service user

The service user must also be a member of the Performance Monitor Users group so that it can collect and report server resource loads. For information on adding the service user to this group, see the Performance Counters documentation.

Finally restart the Turbo Server service for the changes to take effect.

Hide System Drives on Application Servers for Cloud Launches

Administrators can hide the application server's system drives to prevent users from accessing them when launching applications using the Run in Cloud launch modes by configuring the Drive Visibility setting in the Workspace Application Settings.

Note that configuring Drive Visibility will prevent PC Native Applications from seeing the binaries on the native filesystem if the setting is configured to hide the drive that the application is installed on. In this case, administrators may configure the following group policy to hide (but still access) the drive icons in the File Explorer dialog: User Configuration > Administrative Templates > Windows Components > File Explorer > Hide these specified drives in My Computer.

Questions? Talk to us.