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 read-only 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. The file share should be read-only. Otherwise, simultaneous client access may corrupt it.

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.

Manage Turbo Server from the Command Line

The Turbo Server executable, server.exe, is located in the installation directory of Turbo Hub Server (usually C:\Program Files (x86)\Turbo Server). It has many administrative options that are accessible by using command line parameters.

When using the Turbo Server command line administrative tools, it is important to remember the following:

  • Run the command window as Administrator (right-click Run as Administrator).

  • When working in the command window place quotation marks around parameters and paths that include a space.

Server.exe Command Format

Server.exe can be used with the following arguments to manage provisioning, uninstall, upgrade, and service recycling:

Option

Description

Server.exe /provision

    Required parameters:
    [turbo admin email address]

    Optional parameters:
    /dblibrary [library database connection]
    /dbmanager [manager database connection]
    /adminsite [administration site URL]
    /wwwsite   [hub site URL] (creates a new Turbo deployment originating from this server)
    /silent    (installs Turbo without user prompt)

Creates the Turbo Hub Server data and sites.

Server.exe /uninstall

Uninstalls Turbo Hub Server.

Server.exe /restart

    Required parameters:
    [Apache process Id]

Restarts Apache web service gracefully.

Server.exe /?, -?, ?, /help, -help, help

Prints this usage information.


Server.exe admin Command Format

Server.exe can also be used to create and update applications, as well as to manage other server settings. This is done by specifying any of the given topics after the Server.exe admin command.

Server.exe admin --directory-services

Option

Description

print, (none)

Prints the current list of directory services.

new <login prefix>

Creates a new directory service with default settings.

delete <login prefix>

Deletes the given service.

help, h, ?, -?, /?, etc.

Prints help information.


Examples:
  • Print the current directory services:

    Server.exe admin --directory-services

  • Create a new directory service with prefix "loc":

    Server.exe admin --directory-services new loc

  • Delete the "loc" directory service:

    Server.exe admin --directory-services delete loc

Server.exe admin --directory-service

Option

Description

discover-local-ad

Attempts to connect to local Active Directory. If it succeeds, the connection and schema settings are printed.


Server.exe admin --directory-service <login prefix>

Option

Description

print, (none)

Prints the current settings for the directory service.

<property>

Prints the current value of <property>.

<property> <value>

Sets the value of <property> to <value>.

set [<file>]

Imports the settings from a file, or standard input if no file is specified. Settings files are in the same format as the output of the print function.

discover-local-ad

Attempts to connect to local Active Directory. If it succeeds, the connection and schema settings are printed.

discover

Scans the directory service for recommended schema settings.

directories

Prints the subdirectories within this directory service.

groups

Prints the user groups within this directory service.

sync

Synchronizes users and groups from the directory service.

items

Prints the current synchronized items.

items add (Group|Subdirectory) <distinguished name>

Adds an item to be synchronized.

items clear

Deletes all sync items.

help, h, ?, -?, /?, etc.

Prints help information.


An external directory service may have particular configurations which a directory service must accommodate. In addition to standard settings like name and description, there are the following important categories of options:
  • Connection settings: host, port, binding type, username, password

  • Schema settings: user and group attribute names used by the external directory service

  • Synchronized items: if the entire external directory should not be imported, the items commands should be employed to add specific user groups or LDAP directories to include

The following examples describe a typical set of steps to set up a directory service for the local Active Directory.

  • Print the settings of directory service "ad":

    Server.exe admin --directory-service ad

  • Change the name of directory service "ad":

    Server.exe admin --directory-service ad name "Local Active Directory"

  • Dump the settings of directory service "ad" to a file:

    Server.exe admin --directory-service ad print > ad-settings.txt

  • Discover the schema of directory service "ad":

    Server.exe admin --directory-service ad discover

  • Copy/paste the recommended schema from the console to the ad-settings.txt file.

  • Print all the groups found in "ad":

    Server.exe admin --directory-service ad groups

  • Specify a user group to be synchronized:

    Server.exe admin --directory-service ad items add Group "cn=All,dc=acme,dc=com"

  • Set all the settings of "ad" from a file:

    Server.exe admin --directory-service ad set ad-settings.txt

Server.exe admin --global

Option

Description

print, (none)

Prints the current global settings.

<property>

Prints the current value of <property>.

<property> <value>

Sets the value of <property> to <value>.

help, h, ?, -?, /?, etc.

Prints help information.


Examples:

  • Print the current settings:

    Server.exe admin --global

  • Print the OneDrive Client Id settings:

    Server.exe admin --global onedrive-client-id

  • Set the OneDrive Client Id settings:

    Server.exe admin --global onedrive-client-id 9ac73e7d-83aa-425d-8b04-fac64a702f77

Server.exe admin --hub

Option

Description

print, (none)

Prints the current hub settings.

keys

Prints the current set of API keys.

key create <name> <type>

Creates an API key with the given name. Specify "system" or "user" for the type of key to create.

key renew <name>

Regenerates the value of the API key with the given name.

key delete <name>

Deletes the API key with the given name.

configsvc

Prints the launch configuration service settings.

configsvc enable [authentication-key]

Enables the launch configuration web service. The authentication key is required to be passed in the header of all POST requests to the web service. The service is disabled by default.

configsvc disable

Disables the launch configuration service.

configsvc timeout [value]

Sets the length of time (in minutes) that a launch configuration is available after last use. Default is 1-hour.

help, h, ?, -?, /?, etc.

Prints help information.


Examples:
  • Print the current settings:

    Server.exe admin --hub print

  • Add an API key:

    Server.exe admin --hub key create "Test Lab Key" system

  • Enable launch configuration service:

    Server.exe admin --hub configsvc enable C68480F0BD594684A90EEB889118CEB6

Server.exe admin --license

Option

Description

print, (none)

Prints the current license.

set <file>

Sets the license to the contents of the given text file.

help, h, ?, -?, /?, etc.

Prints help information.


Examples:
  • Print the current license:

    Server.exe admin --license print

  • Set the current license:

    Server.exe admin --license set ss-license.txt

Server.exe admin --server

Option

Description

print, (none)

Prints the current primary server settings.

<property>

Prints the current value of <property>.

<property> <value>

Sets the value of <property> to <value>.

help, h, ?, -?, /?, etc.

Prints help information.


Examples:
  • Print the current primary server settings:

    Server.exe admin --server

  • Print the root web address:

    Server.exe admin --server <server-name> web-root

  • Set the root web address:

    Server.exe admin --server <server-name> web-root https://acme/turbo

  • Set the SSL certificate file path:

    Server.exe admin --server <server-name> ssl-certificate-file c:\programdata\acme\cert.txt

Server.exe admin --users

Option

Description

print, (none)

Prints the current users and groups.

authentication-type (Anonymous|Forms)

Changes the current authentication type.

ticket-timeout

Gets or sets the number of minutes that a login ticket is valid when "remember me" is selected. The default is 1-week (10,080 minutes).

help, h, ?, -?, /?, etc.

Prints help information.


Examples:
  • Print information about current users and groups:

    Server.exe admin --users

  • Change the authentication type to "Forms":

    Server.exe admin --users authentication-type Forms

  • Change the login timeout duration to four weeks:

    Server.exe admin --users ticket-timeout 40320

Server.exe admin --user-groups

Option

Description

print, (none)

Prints the current list of user groups.

new <name>

Creates a new user group with default settings.

delete <id>

Deletes the given group.

help, h, ?, -?, /?, etc.

Prints help information.


Examples:
  • Print the current groups:

    Server.exe admin --user-groups

  • Create a new group with name "Power Users":

    Server.exe admin --user-groups new "Power Users"

  • Delete group 2:

    Server.exe admin --user-groups delete 2

Server.exe admin --user-group

Option

Description

print, (none)

Prints the current settings for the user group.

<property>

Prints the current value of <property>.

<property> <value>

Sets the value of <property> to <value>.

set [<file>]

Imports settings from a file, or standard input if no file is specified. Settings files are in the same format as the output of the print function.

clear

Removes all members from the group.

help, h, ?, -?, /?, etc.

Prints help information.


Examples:

  • Print the settings of group 2:

    Server.exe admin --user-group 2

  • Print the properties and members of group 2:

    Server.exe admin --user-group 2 print

  • Remove all members from group 2:

    Server.exe admin --user-group 2 clear

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.

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.

Questions? Talk to us.