1.1 Getting Started

Signing In

To get started, sign in to your Turbo.net Portal. The Portal is a web site where you can access all of your organization's applications, files, and other resources.

Your system administrator will provide with the URL of your organization's Turbo.net Portal. Once you open the URL, you can sign in with your organization credentials.

If you have a Workspace hosted on Turbo.net, press the Sign In button in the top right and sign in with your Turbo.net credentials. If you don't already have a Turbo.net account, you will need to create a Turbo.net account and ask your administrator to add you as a member of the Workspace.

Clients

For the best experience, it is recommended to install and use one of the native Turbo.net clients on your device. Turbo.net provides an app for all major desktop and mobile platforms.

If you do not use one of Turbo.net client applications, you can still use Turbo.net via the HTML5 interface in any major web browser.

• Turbo.net for PC
• Turbo.net for Mac
• Turbo.net for iOS
• Turbo.net for Android

If you are on a device issued by your organization, your system administrator may already have installed the necessary Turbo.net client on your device.

Running Applications

Turbo.net applications can be opened using the Portal or, if configured by your administrator, directly from the Start Menu or Applications folder.

Portal

To open an application or file, go to the Turbo.net Portal and click on the item you want to open.

By default, items will open and stream inside the web browser. For a better experience, you can open items in one of the Turbo.net native applications by right-clicking on the icon and selecting Run in Cloud (Windowed).

If you are on a PC that meets the application requirements, you also have the option of running the application on your own device. There are no separate installation steps required to run applications once the Turbo.net for PC application is installed.

To select a specific way to run the application, right-click on the application and select one of the following:

1. Run in Cloud (HTML5): The application will run in the cloud and stream to your device inside the web browser.
2. Run in Cloud (Windowed): The application will run in the cloud and stream to your device via the Turbo.net native application.
3. Run on My PC (Local): The application will be downloaded and run on your device.
4. Install on My PC: The application will be installed on your device.

You can select a preferred default method of running an application by clicking on the gear icon in the top right of the application list:

1.2 Using Files

Turbo.net let you use files located on your device or on popular online storage providers such as OneDrive and Dropbox.

Local File System

Users may access files on their local system when launching an application in the Cloud or on a local container instance.

Access local files with Run in Cloud (Turbo.net for PC)

You can access files on your device when an application is launched using a Turbo.net native client. On the Portal, this mode is referred to as Run in Cloud (Windowed):

Applications running in this mode will show files from the local device as Home on My PC or Home on My Mac in the File Open and Save dialogs.

Files from the local system may also be accessed using the \\\\tsclient\\\{drive\} remote path.

Access local files with Run On My PC (Turbo.net for PC)

Users who run Turbo applications on their local Windows Desktop may access the local file system directly. Open the Settings dialog from Turbo Launcher and check the Access to local user folders setting.

User folders such as Desktop, Downloads, Documents, Music, Pictures, and Videos are now accessible in the Turbo application that are launched on the machine. Non-system drives are also directly accessible.

Access local file system files with Turbo.net for Mac

Users may access files from their local system when they launch an application in the cloud and stream it to their device via Turbo for Mac.

Applications running in this mode will show files from the local system under the Home on My Mac mapped drive in the File Open and Save dialogs.

Files from the local system may also be accessed using the \\TSCLIENT\Home remote path.

Cloud Storage Services

Connecting a cloud storage service, such as OneDrive or Dropbox, to your applications on Turbo.net is a seamless way to access your files quickly.

From your Portal, click on Files to access the storage services for your account.

Then, click on the Connect button to link the storage service to your account, allowing Turbo applications to load and save data to the storage service.

You will be asked to authenticate your account with the storage service to link it with your applications.

When the authentication succeeds, the storage service status will show as connected and give you the option to Disconnect.

Files from the storage service will be available under the T:\ drive for applications running in the cloud.

1.3 Printing

Turbo supports printing both from the HTML5 and native client interfaces.

For the best experience, we recommend installing a Turbo native client to allow direct use of local printers.

From a Web Browser

To print from the HTML5 client, select the Print to PDF printer:

The printer will download a PDF file through the browser. Open the PDF and print using your local printer.

From Native Clients

If the Turbo application is executing on the local machine, the printer should automatically be visible to the application.

If the application is running in the cloud, local printers will be automatically redirected and visible to the application.

1.4 Networking

Turbo.net allows applications to access the local network of the client device even when running from the cloud when using the Turbo for PC or Turbo for Mac client.

The HTML5 and mobile clients do not support local network access without a separate network tunnel setup.

Applications launched on the local device, eg Run on My PC will automatically interact with the local network.

Enabling Local Network Access

For security purposes, local network access must be enabled in the Turbo for PC or Turbo for Mac settings before network sharing can be used.

To enable local network access, open the Turbo for PC or Turbo fro Mac application and check the Allow access to local network setting.

Once the setting is enabled, subsequent launches of cloud-based applications will be able to reference local URLs.

Accessing localhost

When network sharing is enabled, a potential ambiguity exists when referencing the special localhost device name, depending on whether the client device or cloud host is the intended target.

To resolve this ambiguity, Turbo.net uses the following address convention:

• The localhost name references the server running the application in the cloud.
• The special host name localhost.turbo.net references the client device.

For example:

1.5 Advanced Settings

Turbo for Windows

Click on Settings at the bottom right of the Turbo Launcher to bring up the Settings dialog.

1. Open on startup: starts Turbo Launcher on Windows startup.
2. Disable proxy autodetection: do not use the Windows Internet Explorer proxy settings to access the internet.
3. Show launcher in the taskbar: shows Turbo Launcher on the Windows taskbar.
4. Allow access to local network: allow cloud launched applications to connect to the local network.
5. Allow access to local user folders: allows applications launched on my machine to have full read write access to special user folders including the OneDrive folder.
6. Launch: controls where the applications will execute for your left-click launches.
7. Cloud: the application will execute in the cloud and stream to the user’s device.
8. Machine: the application will execute locally on the user’s device.

Turbo for Mac

Click on the gear (⚙) icon at the top-right of the Launcher to access the settings.

1. Synchronize with Turbo.net: save application settings to the cloud.
2. Open on startup: open the Turbo Launcher when the system starts.
3. Use Extended RAIL: improve visual appearance of streamed application.
4. Use H.264: use codec to decrease bandwidth usage for streaming (requires Extended RAIL).
5. Cloud Region: select the region where the application will execute and stream from.

FAQ

How do I save passwords in a browser on Turbo to share with team members?

This can be achieved by creating an image with the credentials set using the Turbo CLI

# Run a browser
>turbo new firefox
Using VM 18.7.1306 from local
Using image clean:26 from local
Using image firefox:61 from local
Running new container firefox#9afe83e2

# Go to a website and log in, saving your credentials, then exit the application
Process exited with status 0

# Save the container into an image
> turbo commit firefox#9afe83e2 ffpassword
Using image firefox:61 from local
Committing container firefox:3.5#a524349c to image ffpassword
Commit complete

# Push to hub
> turbo push ffpassword mynamespace/ffpassword
Pushing image ffpassword to mynamespace/ffpassword
Push complete
Image is private

1.6 Administrators

Creating Images

In the previous section, we used several ready-to-use images from the Turbo.net Hub. But what if we want to create or customize our own images?

Customizing applications

Recall that in the previous section we launched several Firefox containers from the Turbo.net Hub. Applications in the Hub are configured with installer defaults. Let’s see how to customize images with our own preferred settings.

Launch a new Firefox container as before:

> turbo new firefox

In this example, we modify the Firefox container by setting the homepage to a new URL from the Options menu:

Close the browser window to stop the container.

We suggest restarting the container to verify the all of the settings are configured as desired. This will be the same experience as your users when they launch the final image:

> turbo start e4a84281
Using VM 11.8.960 from local
Using image vcredist:2008 from local
Using image clean:25 from local
Using image firefox:47.0.1 from local
Using image firefox-base:47.0.1 from local
Running existing container firefox#e4a84281 with visibility private

Notice that if we use the new command to start a new Firefox container, the default home page still appears.

> turbo new firefox
Using VM 11.8.960 from local
Using image vcredist:2008 from local
Using image clean:25 from local
Using image firefox:47.0.1 from local
Using image firefox-base:47.0.1 from local
Running new container firefox#b05176b2 with visibility private

To publish our modified Firefox container, we must create a new image. To create an image from a container, use the turbo commit command:

> turbo commit e4a8 firefox-turbo

The first argument to commit is the identifier of the container being committed. Observe again that we used prefix matching to shorten the container identifier. The second argument is the name of the new image. By convention, modifications to a base image are named following the pattern -.

Finally, we can launch a new instance of our custom image!

> turbo new firefox-turbo

Notice that a new container identifier has been assigned. Even though the configuration is the same as our initial container e4a84281, the container we just launched is a new instance of a container instantiated off the firefox-turbo image.

Removing images

Since we only created the firefox-turbo image for testing purposes, we’d like to remove it to keep our local repository clean.

Images can be removed using the rmi (remove image) command:

> turbo rmi turbo-clean
Image firefox-turbo was removed

The rmi command also accepts wildcards. For example, all images can be removed from a device with the command turbo rmi *.

Installing custom applications

So far we have been using applications that were already available in the Turbo.net Hub. But what if we want to install completely custom applications into our containers?

In this example, we’ll install Sublime Text editor into a container. (Sublime Text is a popular text editor.) To follow along with this demo, you’ll need to download the Sublime Text installer:

Download Sublime Text 2.0.2a Setup.exe

We assume in this example that the installer is downloaded to the folder C:\Installers.

You can install applications into containers just like you would a normal desktop. However notice we have a small problem — how do we get the installer binary into the container?

The --mount flag causes the specified directory to be mounted within the container. Mounted directories on the host device are accessible from within the container context exactly as they would be on the host device.

# Mount a host folder into the container that contains the setup file 
> turbo new clean --mount="C:\Installers"

# The native C:\Installers folder is now accessible from the container command prompt
(clean#94d6338f) C:\>cd "C:\Installers"
(clean#94d6338f) C:\Installers>dir
 Volume in drive C has no label.
 Volume Serial Number is DADA-BCA1

 Directory of C:\Installers

07/01/2016 01:58 PM <DIR> .
07/01/2016 01:58 PM <DIR> ..
07/01/2016 01:58 PM 5,601,488 Sublime Text 2.0.2a Setup.exe
 1 File(s) 5,601,488 bytes
 2 Dir(s) 114,467,921,920 bytes free

Notice that unlike a normal clean image, this container has a C:\Installers directory visible that contains the Sublime Text setup file.

Next, launch the setup and click through the installer as you would normally. Once it’s complete, you can navigate to the C:\Program Files (x86)\Sublime Text 2 folder to confirm that Sublime Text has been installed in the container:

# Run the installer to install the program into the container
(clean#94d6338f) C:\Installers>"Sublime Text 2.0.2a Setup.exe"

# Verify the install
(clean#94d6338f) C:\>cd "Program Files (x86)\Sublime Text 2"
(clean#94d6338f) C:\Program Files (x86)\Sublime Text 2>dir
 Volume in drive C has no label.
 Volume Serial Number is DADA-BCA1

 Directory of C:\Program Files (x86)\Sublime Text 2

07/01/2016 02:01 PM <DIR> .
07/01/2016 02:01 PM <DIR> ..
09/15/2010 10:06 PM 71,680    bz2.pyd
09/15/2010 10:06 PM 1,852     Microsoft.VC90.CRT.manifest
09/15/2010 10:06 PM 572,928   msvcp90.dll
09/15/2010 10:06 PM 653,136   msvcr90.dll
07/31/2012 09:54 PM 4,206     PackageSetup.py
07/01/2016 02:01 PM <DIR>     Pristine Packages
09/15/2010 10:06 PM 153,088   pyexpat.pyd
09/15/2010 10:06 PM 2,145,280 python26.dll
09/15/2010 10:06 PM 1,484,587 python26.zip
09/15/2010 10:06 PM 11,776    select.pyd
03/10/2012 08:23 AM 10,838    sublime_plugin.py
07/08/2013 11:25 AM 3,921,408 sublime_text.exe
09/15/2010 10:06 PM 585,728   unicodedata.pyd
07/01/2016 02:01 PM 13,381    unins000.dat
07/01/2016 02:01 PM 1,179,960 unins000.exe
07/01/2016 02:01 PM 20,903    unins000.msg
09/15/2010 10:06 PM 73,728    _ctypes.pyd
09/15/2010 10:06 PM 86,016    _elementtree.pyd
09/15/2010 10:06 PM 286,208   _hashlib.pyd
09/15/2010 10:06 PM 40,448    _socket.pyd
09/15/2010 10:06 PM 665,600   _ssl.pyd
 20 File(s) 11,982,751 bytes
 3 Dir(s) 114,456,604,672 bytes free

Finally we can launch the sublime_text.exe executable!

Take note of the full path to the startup file as we’ll need it later.

# Run the program inside of the container
(clean#94d6338f) C:\Program Files (x86)\Sublime Text 2>sublime_text.exe

Saving new images

Now we have a useful container that has Sublime Text installed.

As before, we’ll use the commit command to create an image that we can distribute. But in this case we do not want the command prompt to open by default. An alternate startup file can be specified at commit time using the --startup-file flag.

Here we commit the container to a new image using the startup file path we noted previously:

# Save changes to the container to an image.
# The startup-file flag allows the image to automatically run an executable instead of opening a command prompt.
> turbo commit 94d6338f sublimetext --startup-file="C:\Program Files (x86)\Sublime Text 2\sublime_text.exe"
Committing container clean#94d6338f to image sublimetext
Commit complete

Now launch a fresh sublimetext container using the image we just created:

# Run the new image, the run command is similar to the new command but instead runs an existing container of the same image name if they exist
> turbo run sublimetext

Desktop Integration

Sometimes we want containers to behave as isolated environments. Other times, we want the container to interact (in a managed way) with the host desktop.

Turbo lets you to control the level and types of integration with the host desktop.

Accessing local files

You may have noticed in previous examples that you could not access the My Documents or My Downloads file when using containerized applications. This is because the container has its own instance of the filesystem by default. In many cases, we may want to allow access to these built-in folders.

Turbo allows you to selectively de-isolate individual folders between the container and host device. We saw an example of this earlier with the --mount flag. But explicitly mounting all of the user folders would be tedious. Also, user folder names vary between operating system variants.

To solve this, Turbo provides a built-in isolation mode that de-isolates all major user folders:

> turbo run notepadplusplus --isolate=full+merge-user

When Notepad++ starts, notice that you can view and edit files in your user folders.

Shell integration

Full desktop integration extends beyond just the ability to access the host filesystem. For example, we may want the application’s Start Menu shortcuts, file associations, and other shell integrations to work as if the application was natively installed.

Turbo lets you “install” images via the installi (install image) command. Installed images are “wired up” to the shell and behave as if they are installed on the host device. But note that these applications are not actually installed — they are still running in the Turbo container environment, just with shell interactions and different isolation settings.

To install an image, we use the command:

> turbo installi 7-zip
Shortcut 7-zip created in Start Menu

>turbo installi notepadplusplus
Shortcut notepadplusplus created in Start Menu

If you press the Windows key, you will notice that 7-Zip and Notepad++ appear in the Start Menu! You can launch these applications through the normal Windows application launch experience.

Also, notice that if you right-click on a file in the Windows Explorer, you see the shell extensions normally associated with installed versions of 7-Zip and Notepad++:

Installing a container does not automatically cause the image contents to download. The contents will download automatically when the application is first run. Container installation is intentionally designed this way so that many applications can be registered on the desktop very quickly.

To remove the applications, use the uninstalli command:

> turbo uninstalli 7-zip
Shortcut for 7-zip removed from Start Menu

> turbo uninstalli notepadplusplus
Shortcut for notepadplusplus removed from Start Menu

You can check that the Start Menu shortcuts, file associations, and shell extensions have been removed.

Installed containers can also be removed through the Add/Remove Programs section of the Control Panel.

Networking

Turbo containers have a virtual networking stack that can be customized on a per-container basis. You can also connect containers with one another and with the host device’s network adapters.

Site whitelisting

The route-block and route-add flags control which domains and protocols are allowed to interact with the container.

A nice application of container networking is to block all IP addresses except specified websites in a browser.

> turbo new firefox --route-block=ip --route-add=ip://yahoo.com

This will launch a new Firefox browser with all IP addresses blocked except for the IP address associated with yahoo.com. To verify this, try navigating to a a few websites and notice that only Yahoo’s site is accessible!

Routing rules are applied in left-to-right order. The first rule blocks all IP traffic. Subsequent rules can then add back specific routes. In our example, we could have added additional --route-add arguments to allow access to additional web sites. The ip:// prefix indicates that all IP traffic, including both TCP and UDP protocols, should be affected by the routing rule.

Virtual networks

Suppose we want to run multiple containers on an isolated virtual network such that the containers can communicate with one another.

In this example, we’ll create a WordPress server and then access it with a Firefox web browser.

# Launch a WordPress server in a virtual network environment
> turbo run wordpress -d --network=wp --name=web 

# Run a Firefox browser instance in the same virtual network
# environment and connect to the WordPress server
> turbo run --network=wp firefox http://web:8080

The --network flag creates a named virtual network. Containers started in the same virtual network can communicate with one another. The --name flag assigns a friendly name to the container which is also used to reference the container via virtual DNS resolution.

Notice that the Firefox browser is able to connect to the WordPress server at the http://web:8080 address. You may also confirm that the WordPress server is not externally accessible on the device.

Container linking

It is also possible to connect individual containers together via container linking.

We can repeat the example above using the --link command:

# Launch a WordPress server in a virtual network environment
> turbo run -d --network=wp --name=web wordpress

# It is also possible to map a different domain name than
# the container name by setting up a container-to-container link
> turbo run --link=web:mywordpress.com firefox http://mywordpress.com:8080

Container linking provides more fine grained control over container interactions but may be more complicated to use than named virtual networks.

This example also demonstrates the use of container name remapping. In this case, we mapped Firefox to the web container as before but modified its DNS entry to mywordpress.com.

Network layering

Network configurations can be stored in images and layered just like any other image. This is very useful when applying the same set of routing rules to multiple images. The Turbo.net Hub also provides pre-configured network routing images.

For example, the following command creates a Firefox browser with social media websites blocked:

> turbo run firefox,block-social-routes

The block-social-routes is a layer provided by the Turbo.net Hub that has route blocking rules defined for popular social media sites.

Notice that the Firefox browser will not navigate to sites like facebook.com and twitter.com.

Automation

When operating in a developer environment, the recommended practice is to automate creation of Turbo images.

Turbo supports a flexible scripting language called TurboScript. In this section, we’ll see how to use TurboScript in conjunction with different external tools to automate container builds.

Building images with TurboScript

In this example, we’ll use TurboScript to automatically build VLC Media Player, a popular media player for Windows.

To execute a TurboScript build, we use the turbo build command. The script reference can be either a local path or a URL.

> turbo build https://raw.githubusercontent.com/turboapps/turbome/master/vlc/stable/turbo.me

We have provided the build script for this application at that URL. (More on this later.) Notice that by convention the TurboScript name is turbo.me.

If you have run this script before, you should add the --overwrite flag to the command to allow the build to overwrite the previously created image.

After a couple minutes, a new vlc image should be created. Try running it to confirm it works!

> turbo run vlc

Inside TurboScript

Let’s look at what this script does. It starts by defining the namespace, name and title of the container image that will be created.

meta title="VLC stable"
meta namespace="videolan"
meta name="vlc"

Next we want to fetch the VLC homepage, parse the contents and extract the download link and version number for the latest release. The tools we chose for the job are wget and Python. Both of these tools are available in the Turbo.net Hub.

We bring these into the script’s scope as transient dependencies. Transient layers are available while the script is executing but are automatically removed when the final image is saved. Transient layers are applied with the using command.

# we'll use wget to download files and python to fetch and parse VLC homepage
using gnu/wget,python/python:3.4.1

# we'll need the 'requests' python module
cmd pip install requests --quiet

The cmd verb executes the given command. Here we use the Python pip package manager to install additional components.

With our tools ready we parse the download URL from the homepage and fetch the VLC setup file:

batch
 echo import requests >> getUrl.py
 echo import re >> getUrl.py
 echo host = "http://www.videolan.org/vlc" >> getUrl.py
 echo headers = {'User-Agent': 'Mozilla/5.0 (Windows NT 6.3; WOW64; rv:41.0) Gecko/20100101 Firefox/41.0'} >> getUrl.py
 echo r = requests.get(host , headers=headers, timeout=10) >> getUrl.py
 echo url = ''.join(list(re.findall('(get.videolan.org\/vlc\/.*exe)', r.text)[0])) >> getUrl.py
 echo print(url) >> getUrl.py

cmd python getUrl.py
 var url = last

# Download
 cmd "wget --no-check-certificate --no-verbose -O VlcSetup.exe %url%"

Notice another great TurboScript trick here — the batch block! The batch verb lets us inline script files within the script itself, avoiding the need to pull in an external .py file and allowing us to keep our script self contained. Scopes in TurboScript are determined by whitespace alignment, similar to Python.

Also notice the last keyword. This special variable is substituted by TurboScript with the return value from the previous command. Here it is used to capture the output from the Python script and place it into a TurboScript variable.

The next step is to install VLC. When using automation, be sure to use silent install options (the /S flag in this case).

# Install
 cmd VlcSetup.exe /S

With VLC installed the container image is ready. We do some final Python scripting to parse out the version number and set that as the container version tag:

batch
 echo import requests >> getVersion.py
 echo import re >> getVersion.py
 echo host = "http://www.videolan.org/vlc" >> getVersion.py
 echo headers = {'User-Agent': 'Mozilla/5.0 (Windows NT 6.3; WOW64; rv:41.0) Gecko/20100101 Firefox/41.0'} >> getVersion.py
 echo r = requests.get(host , headers=headers, timeout=10) >> getVersion.py
 echo version = ''.join(list(re.findall('(get.videolan.org\/vlc\/(.*)\/win.*exe)', r.text)[0][1])) >> getVersion.py
 echo print(version) >> getVersion.py

cmd python getVersion.py
 var version = last

We were only able to cover some TurboScript basics here. To learn more, view the TurboScript Reference Guide.

Scripting builds

Now that we have our TurboScript and a command to run the build, we need to automate the rest of the build process.

Add the follow commands to your automated CI build script:

# Log in to your Turbo.net account
turbo login <username> <password>

# Execute the TurboScript and build a new image
turbo build -n=<name> C:\path\to\turbo.me

# Push the image to our repo
turbo push <name>

(You may want to use an API key instead of your password for automated logins. We'll discuss API keys in just a moment.)

Once the image is pushed, other users and processes can pull and run it instantly!

Integrating with MSBuild and Visual Studio

Now let's integrate our container build step with MSBuild, Visual Studio's build system. (The same basic steps will work with any IDE.)

The easiest way to integrate with Visual Studio/MSBuild is to add a Post-build event to your project.

Right-click on your project in Visual Studio and select Build Events from the left-hand menu.

In the Post-build event command line box, add the line:

turbo build -n=$(SolutionName) $(SolutionDir)\turbo.me

For solutions with multiple projects, we recommend only triggering a post-build event for the last project in the build chain. This may require customizing your TurboScript to also pull in the build outputs from these other projects.

As before, you could also optionally add a turbo push event to automatically generate a repository version on each build. This is the recommended practice for continuous integration style development.

Automating with Jenkins

Jenkins is a popular and free open source continuous integration (CI) system. Turbo directly integration with Jenkins that allows container images to be built as part of the CI process.

To follow along with this section, you'll need to install the TurboScript plugin for Jenkins into your Jenkins environment. Install it by opening the Jenkins Plugin Manager and install the latest TurboScript plugin.

First we need to setup the Jenkins job. Save the script file on the Jenkins host machine. Change line #15 to use your own Turbo.net username.

From the Jenkins Dashboard create a new Jenkins job of type Turbo Project. Add an Execute TurboScript build step and connect it to the script just saved.

We want to push the container image created to the Hub, so we add a Push Turbo Image build step:

Save the new Jenkins job and trigger a run to see your automated build in action!

Automating Turbo with Chocolatey

Chocolatey is a package manager for Windows desktop applications. We can use TurboScript to leverage Chocolatey to create Turbo images. This is powerful since any application with a Chocolatey package can be used to create a Turbo container. As of this writing there are nearly 3,000 distinct Chocolatey packages available.

Let's repeat our VLC example using Chocolatey instead of a native TurboScript:

> turbo new --name=choco-vlc clean --using=chocolatey/chocolatey

This command creates a new container named choco-vlc. The --using flag lets applies Chocolatey as a transient layer within the container. Recall that this will allow us to use Chocolatey within the container but remove it from the final image. We saw this earlier in the TurboScript but here we see how to apply using from the command line.

In some cases other dependencies may be required to install the chocolate package such as PowerShell. In this case, just add additional transient layers: --using=chocolatey/chocolatey,microsoft/powershell.

In the command window that opens run:

choco install vlc -y

The VLC package should start to download and install successfully within the container.

When the install has completed, close the command window.

> exit

In the original command window used to create the container, we commit our image.

> turbo commit choco-vlc my-vlc --startup-file="@PROGRAMFILESX86@\VideoLAN\VLC\vlc.exe"

Note we set the appropriate startup file using the --startup-file flag so the container runs VLC on startup (rather than a command prompt containing VLC).

We can now test the image by launching it in a new container. In a command window, enter:

> turbo new my-vlc

VLC should launch:

Sample TurboScripts on GitHub

TurboScripts for many popular applications have been open sourced and are available in the turboapps GitHub repository.

Looking at examples is a quick way to pick up the basics of TurboScript. Pull these down, customize your builds -- and remember to contribute your own TurboScripts back to the community by sending a pull request!

API keys for scripting and authentication

To allow authentication in the context of scripting and automation, Turbo supports authentication via API keys. API keys eliminate the need to hard code passwords or pass them as parameters to your scripts.

The first step is to create an API key. To do this, go to your organization settings, and then select Devices & API Keys on the right menu. (You can also generate and manage API keys for an individual account on the Account Settings page.)

Once here, click Add API Key to generate a new key.

Notice that when you hover your mouse over an API key a Remove button is shown. Use this button to remove the key and revoke its access to your organization.

There is no limit to the number of keys you can generate. You may decide to create and manage different keys for different teams or for different user access, allowing you the flexibility to revoke them independently without disrupting all key users.

Click Copy Key and head back to the command line.

Using the API key is easy -- just include the key in the turbo login command using the --api-key flag:

> turbo login --api-key=9ZoKH_336g0MqP2yptwfrv9B1XUm8YFPnCZNugVQNr4
testorg logged in at 2/26/2016 3:53:31 PM

The session is now authenticated in the organization account context. The account will stay logged in until the API key is revoked or the session is closed with the turbo logout command.

Turbo on Citrix and RDS

System administrators can use Turbo to quickly deploy applications and custom containerized environments on Citrix, Parallels RAS, Workspot, Windows Remote Desktop Services (RDS), and other remote desktop systems.

Prerequisites

To get started, you will need to download and install Turbo for Windows for all users on the system.

If users will be streaming the application window rather than the whole desktop, we recommend hiding the Turbo GUI using the --hide-gui flag.

> start /wait turbo-client.exe --all-users --silent --hide-gui

Adding Applications to the Start Menu

Turbo application desktop integration, including Start Menu, desktop shortcuts, and file associations, can be enabled with the turbo installi command along with the --all-users flag. If you omit the version from the application identifier, then the latest version will be used.

# Sign in to Turbo.net (sign up at https://turbo.net/signup)
> turbo login 

# Add the latest Firefox ESR browser to the Start Menu
> turbo installi --all-users mozilla/firefox-esr

# Add the latest Google Chrome browser to the Start Menu
> turbo installi --all-users google/chrome

# Add Internet Explorer 8 with Java 6.45 to the Start Menu
> turbo installi --all-users microsoft/ie:8,jre:6.45

The Firefox ESR, Chrome,and IE8 with Java6 applications will appear in the Start Menu of the server.

Adding Applications to the Delivery Platform

Depending on the delivery platform in use, you may also need to add the applications in the delivery system’s administration interface.

In this example, we will add applications to Citrix XenApp using Citrix Studio.

Start Citrix Studio and go to Applications > Add Applications.

Select the option to Add applications From Start Menu…

Then select the Firefox ESR, Chrome, and IE8 with Java6 applications.

Click through to Finish to complete the process.

Running the Applications

Once added to Citrix Studio users can access the applications from the Citrix StoreFront website or the Citrix Receiver application.

Click on an application to launch it.

Note that because applications are executed in isolated Turbo container environments, any combination of browsers, plugins, and runtimes can run side-by-side on the same server.

For example, an Internet Explorer 8 with Java 6 environment can run alongside an Internet Explorer 10 with Java 7 environment or another Internet Explorer 8 with Java 7 environment:

This allows elimination of Citrix siloing and consolidation of servers to a single version of Citrix using a single base image.

Advanced Topics

Turbo.net has many capabilities that we didn’t discuss in other sections. Here are a few:

Synchronizing state across machines

Turbo.net optionally supports state synchronization. This allows application state to be saved and continue automatically on a different device.

To enable state synchronization, launch the container with the --enable-sync flag:

# Begin work in container on device A
> turbo run --enable-sync python
(python#a37b20f9) C:\> exit

Saving state of container python#a37b20f9
Container python#a37b20f9 stopped in state cc525b1b
 `start python#a37b20f9` to restart execution locally
 `continue cc525b1b` to continue execution remotely

Notice that when state synchronization is enabled, a state identifier is generated when the container is stopped. The state identifier includes information about the state of the container as it existed upon termination and is used to identify a point at which continuation of execution should occur on another device. In this example, the state identifier is cc525b1b.

If you have another device available, login and use the command:

# Continue execution on device B
> turbo continue cc525b1b
Continuing execution of container python#a37b20f9 in state cc525b1b
(python#a37b20f9) C:\>

(You should use the state identifier you received when you closed your version of the container.)

Turbo.net uses efficient differential synchronization techniques that only transmit information on changes across devices. The entire container does not need to be copied across devices if the other machine already has some of the container information. This makes it much faster to migrate state across devices.

Importing third party package formats

Turbo.net supports importing of several application package formats directly into Turbo container images. This is useful if investment has already been made in packaging applications in a third party package format.

In this example, we import a virtual application package from ThinApp into a Turbo containers:

# Import the ThinApp package described by package.ini into the appname image
> turbo import -n=appname thinapp C:\thinapp-project\package.ini

Container Skinning

When many container instances are running it can be difficult to distinguish between applications, particularly if they are subtle variants of a single base application. Skinning makes it easy to visually distinguish between container contexts.

Turbo currently supports a skinning driver that surrounds visible container windows with a specified color:

# Identify different Java versions by window skin
> turbo run jre:8.0,firefox+skin(green)
> turbo run jre:7.51,firefox+skin(red)
> turbo run jre:6.45,firefox+skin(0x0000ff)

Organization Dashboard

To access the dashboard in an administrator mode, you need to sign in to your turbo.net account on the https://turbo.net page. After accessing your personal dashboard, click on the profile icon in the upper right corner and switch to your organization's dashboard:

You can now search for new applications and add them to the dashboard (or remove the ones that are already there):

Being an admin of the organization, allows you to also publish images under the organization namespace. After adding a new image, it will appear on the dashboard, but the only way to run it would be using the “My PC” mode. To enable custom applications to run in the cloud please contact support@turbo.net.

Running Applications Using a Shareable URL

Turbo allows organization administrators to create a URL for end users to run applications without having to log into the dashboard.

First create an API key under the organization. Log into your organization's administrator or owner account and navigate to your organizations Devices & API Keys page. The Devices & API Keys page can be found through the Profile and Account link on your organization's dashboard, or directly through the URL https://turbo.net/orgs/{org-name}/settings/devices-and-api-keys. Click Add API Key to create an API key which will be embed in the Turbo URL as a query parameter. Give it a name you can remember (and possibly revoke later).

Next, we will obtain a URL to launch an application under the organizations namespace. Navigate to your organization's dashboard (click on your profile dropdown). The organization's dashboard should be at the url https://turbo.net/orgs/{org-name}. Right click on the application you would like to run using an anonymous url. Select Share Application. A new dialog will open, with the option to select the API key from the previous step. The Launch Location dropdown allows the URL to specify whether the application will launch directly in the HTML5 client, or attempt to launch using the native Turbo.net client via the Turbo Protocol. Click Create Link, then copy the Share URL to a text editor.

To test your link, open an incognito browser window without logging into Turbo.net and paste the URL into the browser address bar. The application should run without requiring a login. Please be aware that the Share URLs use an API Key that allows access to your organization's applications and should be kept secure within the organization.

A list of all of your organization's Share URLs can be found by visiting the the Sharing tab on your organization's dashboard. If you wish to modify or revoke your Share URL, you may do so by clicking ... options dropdown on the appropriate Share URL.

1.7 Developers

.NET and Java

Containers let you deploy applications built on frameworks such as .NET and Java without requiring users to install the .NET Framework or Java runtime.

Containerizing also assures that your application will run reliably regardless of what runtimes may already be installed on the endpoint.

Getting Started

We will begin by downloading the sample applications from GitHub. A nice trick to do this without installing Git is to create a temporary container with turbo try that is only used to clone the repository. The --mount=%CD%\samples flag is used to poke a hole in the container to the samples directory on the native file system so that the containerized Git application can write to it. (The %CD% special path variable represents the current directory.)

# Create a samples folder
> mkdir samples

# Download the sample applications from GitHub
> turbo try --mount=%CD%\samples git -- /c git clone https://github.com/turboapps/samples

.NET

This example shows how to make an image for a .NET Framework application using TurboScript, an automated way to build application images.

The script copies the application binaries from the cloned repository to a new container and commits it to an image. The --mount=%CD%\samples flag is used to poke a hole in the container isolation so that the cloned repository can be accessed. The --no-base flag just marks microsoft/dotnet:4.5 as a dependency rather than copying it into the image. This greatly reduces the size of the final image.

# Build an image using the application binaries from the cloned repository

> turbo build --mount=%CD%\samples --name=dotNetApp --no-base turbo.me

Below is the TurboScript used for this example project. You should copy and paste this code into an empty text file named turbo.me:

# Layer in the required version of the .NET Framework
layer microsoft/dotnet:4.5

# Create a new directory for your application
cmd mkdir C:\myApp

# Copy the application from the mounted path to the application folder
cmd copy %CD%\samples\dotnet-helloworld\DotNetHelloWorld.exe c:\myApp

# Set the startup file for the image to the application executable
startup file c:\myApp\DotNetHelloWorld.exe

Java

Instead of using TurboScript automation, we will demonstrate a different and more interactive process for containerizing the Java sample application.

First, create a new container with the Java Development Kit, specified with the turbo new jdk:7 command. We will do all of our work in this container, such as copying and running the application. When everything is ready, the container state will be committed to an image.

The --mount=%CD%\samples flag is used to poke a hole in the container isolation so that the Java application can be copied from the host file system. The --detach flag specifies that the turbo command should not wait for the container to finish.

# Start a new Java Development Kit container
> turbo new jdk:7 --detach --mount=%CD%\samples

# Create a folder for the Java application
(3df234f3) > mkdir C:\javaApp

# Copy the Java application from the host file system to the container
(3df234f3) > xcopy /s samples\java-simple-webserver C:\javaApp

# Set the working directory to C:\javaApp
(3df234f3) > pushd C:\javaApp

# Run the server from within the container
(3df234f3) C:\javaApp> "%java_home%\bin\java.exe" -jar SimpleWebServer.jar

The Java application is now running on your local machine using port 80, which can be confirmed by opening a web browser to http://localhost. You should see a listing of all the files in the C:\javaApp folder of the container.

Now that the Java application has been copied to the container and is running correctly, we can proceed to the final step of committing the container state to an image. To do that, shutdown the container using the turbo stop command with the container identifier.

# Stop the container
> turbo stop 3df234ff3

Commit the container state to an image using the turbo commit command.

# Commit the container
> turbo commit 3df234f3 simple-java-webserver

By default, committing will generate a final image that also contains the base oracle/jdk:7 dependency. This may be desirable for portability if you plan on exporting the image for use with Turbo Studio or Server, or if the base dependency may get deleted later on. However, it will also increase the size of the image. Instead, you may want to soft-link the oracle/jdk:7 dependency by using the --no-base flag. A soft-linked dependency will be pulled automatically and added to the container by our layering mechanism on startup.

# Commit with a soft-linked dependency
> turbo commit --no-base 3df234f3 simple-java-webserver

Creating releases

Each time an image is pushed a new version is generated. But usually only certain versions are released to end users. These images can be marked as releases using the turbo release command.

To illustrate this idea, we’ll create a 1.0 release from our newly created image.

# Create a new release version 1.0 for the image
> turbo release simple-java-webserver 1.0

When turbo images is executed, you should now see a new entry for simple-java-webserver:1.0.

> turbo images
ID            Name                   Release   Created                Size
--            ----                   -------   -------                ----
7a85fe8f7ad1  oracle/jdk             7.65      8/22/2014 11:34:19 AM  74.3 MB
9iejrk2a34hd  git/git                1.94      8/21/2014 11:32:00 AM  50.4 MB
3a24fade3ea4  simple-java-webserver            8/22/2014 11:52:32 AM  20.2 MB
3a24fade3ea4  simple-java-webserver  1.0       8/22/2014 11:59:59 AM  20.2 MB

Deploying to the Turbo.net Hub

Now that we have built our image, we can deploy it to end users by pushing it to the Turbo Hub.

> turbo push simple-java-webserver

This will create a new repository in your Turbo.net account called simple-java-webserver where the image will be placed.

Note that if you tagged your image in the previous section, use the command:

>turbo push simple-java-webserver:1.0.

Web Applications

Turbo can also be used to containerize web applications. Let’s see how to use Turbo with two popular web frameworks — ASP.NET and Node.

Creating an ASP.NET application container

# Create a new container with .NET, ASP.NET, and git
> turbo run microsoft/dotnet,microsoft/aspnet --using=git/git

Downloading dotnet from https://turbo.net/users/microsoft
Downloading aspnet from https://turbo.net/users/microsoft
Downloading git from https://turbo.net/users/git
Running container 249c4f3e with visibility private

Inside the container session, use the git clone command to move the application into the container.

(249c4f3e) > cd c:\
(249c4f3e) > git clone https://github.com/turboapps/samples

We use IIS Express to launch the ASP.NET application:

# Start the ASP.NET application console
(249c4f3e) > start "MiniBlog" "C:\Program Files (x86)\IIS Express\iisexpress.exe" /path:C:\samples\aspnet-MiniBlog\Website

We can see the ASP.NET application start up as the IIS output is logged in the new console window.

Copied template config file 'C:\Program Files (x86)\IIS Express\AppServer\applicationhost.config' to 'C:\Users\Administrator\appdata\local\temp\iisexpress\applicationhost2014112420457848.config'
Updated configuration file 'C:\Users\Administrator\appdata\local\temp\iisexpress\applicationhost2014112420457848.config' with given cmd line info.
Starting IIS Express ...
Successfully registered URL "http://localhost:8080/" for site "Development Web Site" application "/"
Registration completed
IIS Express is running.
Enter 'Q' to stop IIS Express

Let’s confirm the application is running by opening http://localhost:8080 in a browser.

Login using username demo and password demo.

And finally create a new post!

Creating a Node.js container

In this example we’ll containerize aIRChat, an open source IRC client built on the popular Node.js framework.

Start a new container using the turbo run command specifying the Node.js image to be included and applying as before a transient Git layer:

> turbo run node --using=git

In the container, first create a folder where we can clone the aIRChat project from GitHub.

> mkdir projects
> cd projects

Use the git clone command again to copy the application contents into the container.

> git clone https://github.com/redwire/airchat.git
Cloning into 'airchat'...
remote: Reusing existing pack: 2983, done.
remote: Counting objects: 21, done.
remote: Compressing objects: 100% (18/18), done.
Receiving objects:  99% (remote: Total 3004 (delta 9), reused 0 (delta 0)
Receiving objects: 100% (3004/3004), 8.84MiB | 948.00 KiB/s, done.
Resolving deltas: 100% (1302/1302), done.
Checking connectivity... done.

Once the application files are present, we can use the standard npm package manager to install the aIRChat application:

> cd .\airchat\Content
> npm install

We are now ready to launch the application!

# Launch a Node.js server
> node app.js

connect.multipart() will be removed in connect 3.0
visit https://github.com/senchalabs/connect/wiki/Connect-3.0 for alternatives
connect.limit() will be removed in connect 3.0
Express server listening on port 3000

aIRChat is now running on port 3000. You can confirm this by opening a browser to http://localhost:3000. Once you’ve verified that aIRChat is running, stop the Node.js server by entering Ctrl+C. At the command prompt type exit to shut down the container session. When you’re finished configuring the container, committing it will create a new merged image.

# Specify a name for the new image
> turbo commit 1be755fcfafc4cf0b8e1c0667f6d13f0 aIRChat

Servers

Turbo.net supports both desktop and server applications. For the most part, server application images behave in the same way as desktop application images. However, special configuration considerations often arise with server applications.

Multiple database server versions

Turbo can be used to run database servers such as SQL Server, MySQL, ElasticSearch, MongoDB, and others.

In this example, we will use Turbo to run multiple versions of the free SQL Server Express database and access them from the database management client.

> turbo run sqlserver/sqlserver2012-express -d --route-block=tcp,udp -n=sql1
> turbo run sqlserver/sqlserver2014-express -d --route-block=tcp,udp -n=sql2
> turbo run sqlserver/ssms2012 -d --link=sql1:sql1 --link=sql2:sql2

Note that we have used container linking and naming to connect the SSMS management client to the two database instances, and route blocking to prevent the database ports from being accessible on the host device’s network.

Login using the username sa and password password1 to the database servers sql1 and sql2. You can confirm the two databases are manageable through the client and are two distinct versions.

Multiple instances of a single server

In this example, we’ll use TCP port mapping, a special case of network routing, to run multiple instances of the Ghost blogging engine on the same host.

By default, Ghost uses port 2368 to listen to requests. Since only one server can listen on a given port at a time, we need to remap this port to allow multiple Ghost instances to run simultaneously:

# Create a container that maps port 8080 on the host to port 2368 on the container.
C:\> turbo new -d --route-add=tcp://2368:8080 ghost

# Create a container that maps port 8081 on the host to port 2368 on the container.
C:\> turbo new -d --route-add=tcp://2368:8081 ghost

# Create a container that maps port 8082 on the host to port 2368 on the container.
C:\> turbo new -d --route-add=tcp://2368:8082 ghost

The tcp:// prefix indicates that the routing rule should apply to TCP traffic. The rule 2368:8080 causes the container’s port 2368 to be mapped to the host device port 8080. We can then launch a second and third instance by mapping 2368 to host port 8081 and 8082.

You can check that three distinct Ghost instances are accessible by browsing to localhost:8080, localhost:8081, and localhost:8082. You can also test what happens if you try to launch instances without applying the routing rules!

Factoring a database into a layer

A useful practice when constructing container architectures is to use layering to factor data from the underlying server application.

For example, suppose that we have a Ghost blog that’s been populated with some data. We would like to move the data into a separate layer. This will allow us to layer in just the database contents on top of any compatible base Ghost image. Saving the database in a distinct layer can help you test different application versions against the same data, back up database contents, or quickly rollback a database to a fixed base state during development.

First, we need to create a blank container that will hold the database:

# Create a clean container
> turbo new clean --no-run

We do not want to actually run the new container so we used the --no-run flag.

Next, use the turbo cp command to copy the database from the Ghost container (bc53e584 in our example) to the blank container:

> turbo cp bc53e584:c:\ghost\content\data d65260ad:c:\ghost\content\data

Note the d65260ad: prefix used for the target folder. This tells the copy command to place the contents into a particular folder. If no container prefix is used, the host device is assumed. The c:\ghost\content\data folder is the location for the database contents in this example.

Now that the database container is ready, we commit it into a new image called ghost-db:

# Commit the container to a new image
> turbo commit d65260ad ghost-db

Finally, we can layer ghost-db into any base Ghost server container and to pre-populate it with our content:

# Create a ghost container with the ghost-db content layered on top of it
> turbo run ghost,ghost-db

2.1 Overview

The Turbo.net Hub is a public Hub server hosted on app.turbo.net that maintains thousands of publicly available applications. Users may pull and run public applications on their local machine or publish their own private applications.

On-premises Hub servers are also available with Turbo Server, which allows enterprises to deploy and manage their own applications.

Users may browse the applications available on the Turbo.net Hub by clicking on the Hub link at the top of the Turbo.net homepage.

For more information on running applications from the Turbo.net Hub, see Running Applications.

2.2 Working with Images

Creating Images

There are four ways to create an image:

1. Commit a container
2. Automatically create with a build script
3. Build images from XAPPL configuration files created with Turbo Studio
4. Import and convert various file types to images

Commit a Container

# Before committing a container check that it is stopped
> turbo containers

# Then create a new image from the container
> turbo commit <container-id> <image-name>

See a more detailed example here.

Automatic Builds

You can automatically build images using a TurboScript, which is a set of instructions that recreate the steps of configuring a container. See more information on TurboScript verbage and syntax.

# Example script to automatically build a 7-Zip image

# Pull dependency images
layer gnu/wget

# Prepare environmnet
cmd mkdir c:\7zip

# Download installation media
workdir C:\7zip
cmd wget http://downloads.sourceforge.net/sevenzip/7z920.exe

# Install 7-Zip
cmd 7z920.exe /S /D=C:\7zip

Save the script as a .me file and then use turbo build command:

# Build the script and specify a name for the new image
> turbo build -n=7-zip:9.20 C:\path\to\build.me

# New image is now saved in the local registry
> turbo images

Name   Tag   ID            Created               Size
7-zip  9.20  95sdf1245239  8/18/2014 2:21:32 PM  25.4MB

Building from a XAPPL File

XAPPL files are static configuration files originally created using Turbo Studio that specify the files, registry keys, and virtual machine settings for an image. The command-line interface can also build images based on XAPPL configuration files using turbo build command.

# Build an image and specify a name
> turbo build -n=firefox:30 C:\path\to\firefox30.xappl

Import

If you have an existing image (file type .svm) on your local machine or a network drive (perhaps built with Turbo Studio or a legacy version of Turbo Studio), you can import it to your local registry.

# Specify the new name, file type, and path to the image
> turbo import -n=newimage svm C:\path\to\image.svm

If the image is not explicitly named, its ID will be used as a default.

The import command also supports building from 2 external file types:

1. Microsoft Software Installer (.msi)
2. ThinApp Configuration (package.ini)

Use the appropriate file type parameter:

# MSI
> turbo import msi <path to .msi>

# ThinApp configuration
> turbo import thinapp <path to package.ini> 

Forking, Renaming, and Tagging

Images can be forked using the turbo fork command. This creates a link to the specified image with a new name and tag. It does not affect the original image.

# Pull an image
> turbo pull account/image

# Check the image
> turbo images

Name            Tag  ID            Created               Size
account/image        14wed2165141  8/18/2014 1:55:23 PM  1.9MB

# Fork to a new image name and tag
> turbo fork account/image tester/test1:1.0

# New image is added
> turbo images

Name            Tag  ID            Created               Size
account/image        14wed2165141  8/18/2014 1:55:23 PM  1.9MB
tester/test1    1.0  14wed2165141  8/18/2014 1:55:23 PM  1.9MB

The turbo tag command can also retag images.

# Specify the image you want to tag and the new tag
> turbo tag tester/test1:1.0 2.0

# Check the tag
> turbo images

Name            Tag  ID            Created               Size
account/image        14wed2165141  8/18/2014 1:55:23 PM  1.9MB
tester/test1    2.0  14wed2165141  8/18/2014 1:55:23 PM  1.9MB

Push to a Remote Repository

Images in a local registry can be copied to a remote repository on the Turbo.net Hub or an on-premises Turbo Server with the turbo push command. Images pushed to a Turbo Server can be made available to your team members and end-users.

# Specify the image you want to push
> turbo push sample

# Or push to a specific namespace and tag
> turbo push turbotest/sample:latest

If unspecified, the image will be pushed to the logged-in user's namespace with the tag head.

Images pushed to the Turbo.net Hub are private by default. For more information on sharing images with your enterprise, see Turbo Server.

See more information on using the hub.

Creating Layers

Creating a layer on top of an existing image is used to apply special settings, files, or registry entries without having to maintain and deploy a duplicated image. A common use case is to layer a brower image with different browser plugins, change the default homepage, or have it launch in kiosk mode.

Using TurboScript

Turboscript allows creating layers in an interable and repeatable fashion. In this example we will create a layer which modifies the startup file for Python in order to launch Python's built in ide IDLE.

First, create a a turbo.me file and open it in a text editor. Begin the file with the meta data section:

###################################
# Meta tags
###################################

# User friendly title which will be displayed on the hub
meta title="Python IDLE"

# Namespace should be your username or organization (https://turbo.net/hub/namespace/name)
meta namespace="python"
meta name="pythonidle"

# Version of the application
meta release="3.7.3"

Include the base image by using the layer command:

###################################
# Pull dependency images
###################################

layer python/python:3.7.3

Finally, set the startup file to the start menu .lnk used by Python to launch IDLE:

###################################
# Startup File
###################################

startup file ("c:\ProgramData\Microsoft\Windows\Start Menu\Programs\Python 3.7\IDLE (Python 3.7 32-bit).lnk")

Run turbo build turbo.me to build the image. Try it out using turbo try python/pythonidle:3.7.3.

See the TurboScript reference page for advanced details.

Customizing Layer Using TurboScript

In the previous example we simply set the startup file from the base image to create a layer that behaved in a different way. If the user wanted to change files within the base image in the layer, it is achievable by using TurboScript copy command.

Lets say the user wants to change the default working directory for the Python IDLE layer, so that the application's open/save dialogs will look into the T: (TurboDrive) drive. A solution will be to change the lnk file's Start in field. We must edit this file and extract it for rebuilding.

This can be achieved by starting a python container and manually editing the lnk file using Windows File Explorer:

1. turbo run --isolate=merge-user --startup-file=explorer.exe python/python:3.7.3
2. Navigate to C:\ProgramData\Microsoft\Windows\Start Menu\Programs\Python 3.7
3. Right click on the file IDLE (Python 3.7 32-bit).lnk
4. Edit the Start in to T:, or any other folder of your choice.
5. Open another instance of File Explorer, this will be outside of the Turbo Virtual Machine.
6. Copy the IDLE (Python 3.7 32-bit).lnk you just edited using the virtual File Explorer instance, and paste it to the native File Explorer folder where you've created the turbo.me file.
7. Close the virtual File Explorer to shutdown the container. If the container does not shutdown, press ctrl+c in the command line to force kill.

Next we modify the TurboScript to replace the startup file with the modifed file:

###################################
# Startup File
###################################

copy "IDLE (Python 3.7 32-bit).lnk" "c:\ProgramData\Microsoft\Windows\Start Menu\Programs\Python 3.7\IDLE (Python 3.7 32-bit).lnk"
startup file ("c:\ProgramData\Microsoft\Windows\Start Menu\Programs\Python 3.7\IDLE (Python 3.7 32-bit).lnk")

Run turbo build --overwrite turbo.me to rebuild the image. This time, turbo try python/pythonidle:3.7.3 should launch Python IDLE with the working directory set to the specified directory.

2.3 Command Line Interface

The Turbo Command Line Interface allows advanced users and administrators to execute, modify, and create Turbo applications in an automated manner. Install the Turbo for Windows to get started.

Creating Containers

A container is an instance of a Turbo Application. The new command creates and starts a new container.

The clean image represents a clean OS image. A container is an instance of an image — in other words, you can start up multiple containers that start off in the state specified by a given image. The container holds all of the data and other state changes that occur as the user performs actions in the container.

To create a new container from the clean image, we use the command turbo new clean:

> turbo new clean
Using VM 11.8.960 from local
Using image vcredist:2008 from local
Using image clean:25 from local
Running new container clean#8104e501 with visibility private

# A new console running in a container will appear. Consoles running inside a
# Turbo container display the name and first 8 characters of the randomly
# assigned container ID in the prompt.
(clean#8104e501) C:\>

# Verify the clean container is a clean OS instance
(clean#8104e501) C:\>dir
 Volume in drive C has no label.
 Volume Serial Number is DADA-BCA1

 Directory of C:\

07/01/2016 01:14 PM <DIR> .
07/01/2016 01:14 PM <DIR> ..
12/31/1999 05:00 PM <DIR> Users
12/31/1999 05:00 PM <DIR> ProgramData
12/31/1999 05:00 PM <DIR> Program Files
12/31/1999 05:00 PM <DIR> Program Files (x86)
12/31/1999 05:00 PM <DIR> Windows
12/31/1999 05:00 PM <DIR> $Recycle.Bin
12/31/1999 05:00 PM <DIR> Documents and Settings
12/31/1999 05:00 PM <DIR> PerfLogs
12/31/1999 05:00 PM <DIR> Recovery
12/31/1999 05:00 PM <DIR> System Volume Information
 0 File(s) 0 bytes
 12 Dir(s) 113,578,422,272 bytes free

Take a moment to compare the directory listing inside the container from the corresponding listings on your host device. Notice there will likely be many files on the host device that don’t appear in the container command prompt. This is because the container has its own version of the filesystem that reflects the settings of the clean image!

To exit a container, exit all processes that were started in the container. In our case, only the command prompt process is running in the container.

(clean#8104e501) C:\> exit

# The container exit code will be printed
Process exited with status 0

Starting Existing Containers

The container still exists even though we exited all processes and it was shut down.

We can restart an existing container using the start command:

> turbo start 8104e501
Using VM 11.8.960 from local
Using image vcredist:2008 from local
Using image clean:25 from local
Running existing container clean#8104e501 with visibility private

# Command prompt to the existing container appears
(clean#8104e501) C:\>

In this example, we used the full container identifier. If there is no danger of ambiguity, you can use any prefix of a container identifier to specify the container. For example, we could have used turbo start 810 so long as there were no other containers with identifiers starting in 810.

Deleting Containers

Suppose we are done with our container. We can remove it from our local repository using the rm command.

> turbo rm clean#8104e501 
Container clean#8104e501 has been removed

This is especially useful when creating and tearing down test environments or performing other transient tasks where we’d like to leave our host device in a clean state.

We can remove all containers in the local repository using the -a flag:

# Remove all containers
> turbo rm -a
All containers have been removed

This restores us to a nice clean desktop!

Running Hub Images

Creating an empty container is nice, but really we want to run real applications.

While you can install your own applications into containers, many popular applications now such as Mozilla Firefox.

# Run the latest version of Firefox
> turbo run firefox

In a few seconds, you will see the Firefox browser window appear!

Take a moment to look at the Start Menu and observe that Firefox has not been installed on the desktop! If you are on a desktop with limited permissions, you may also have noticed that no permissions were required to launch Firefox.

Since no specific version of Firefox was specified, this command runs the latest version of Firefox.

How did the turbo command know how to run Firefox? By default, it will connect to the Turbo.net Hub to resolve any image names that are not present in the local repository. (We’ll see how to add images to the local repository later.)

The Turbo.net Hub provides thousands of images for popular applications, runtimes, and layers that will automatically configure and run on demand. You can also publish images into a private repository. Enterprises can deploy and manager an on-premises Turbo Hub with Turbo Server.

Version Management

In the example above, no version was specified. In this case the container is called evergreen — the latest image version is always run and the container is automatically updated if a new version becomes available. This is a powerful and easy method to keep devices up to date with the latest patches.

We can also run a specific version of an application. To specify an image version, use the : operator:

# Run version 40 of Firefox
> turbo run firefox:40

Because containers are isolated from the host desktop, Turbo can run legacy applications even if newer versions are installed locally or the host is running a newer operating system than the application was originally designed for.

Turbo versions are also based on prefix matching. For example, if versions 8.77 and 8.91 of the jre image exist, then the image specifier jre:8 refers the latest among the versions prefixed with major version 8 — 8.91 in this example. This behavior allows the latest update or patch of a previous major version branch to be applied to an evergreen image.

Layering

We can also combine together multiple images into a single container using the layering operator.

For example, suppose we want to run Firefox with the Java runtime enabled:

# Run Firefox with Java enabled
> turbo run firefox:35,jre

Note that if you navigate to the Options / Plugins menu in Firefox, the Java plugin is installed!

The layering operator applies each image’s configuration on top of the existing container configuration sequentially from left to right.

We can combine the versioning and layering operators to achieve more combinations:

# Run two different Firefox versions with multiple Java versions enabled
> turbo run firefox:35,jre:7.51 --detach
> turbo run firefox:38,jre:8 --detach

Notice that we are able to run multiple versions of Firefox — with multiple versions of Java! — side by side on a single desktop.

In this example, we used the --detach flag to allow another command to be executed immediately before the container session closed. The default behavior is often preferred when using the turbo command in scripting.

Since detach is a common option, it is also available as a short form argument -d. We’ll use the short form in the future, and also note other frequent commands that have short forms available.

Using

A container's layered images is an immutable property. This means if you were to create a container using > turbo run firefox:35,jre, then the container must always run with the firefox and jre image.

To make enable a layer temporarily, use the --using flag:

> turbo run firefox:35 --using=jre

Commit

Commiting a container will create a new image with all layers and changes to the container. A commited container will not include any using images.

# Creates a new image with both firefox and jre included
> turbo new firefox,jre
> turbo commit <cid> firefoxjre

A dependency is created if you commit with the flag --no-base. A dependency must be pushed to the hub before the dependant image is pushed.

# Creates a new image with firefox. The image `jre` is referenced as a dependency
> turbo new firefox,jre
> turbo commit --no-base <cid> firefox2
> turbo push jre
> turbo push firefox2

Images that are ran with the --using flag are not included in the new image or as a dependency.

# Creates a new firefox image, temprorarily allowing usage of jre but commiting without
> turbo new firefox --using=jre
> turbo commit <cid> firefox2

2.4 Repositories

Repositories are the units that make up the Hub. A repository contains the image and version histories of a project, and it may be public or private.

The Hub is where you can browse and search for repositories for popular applications and components, upload your own projects, and run them online with a single click.

If a repository is public, it will appear in search results, and any Turbo user can pull or run it. Only the repository owner (or members of the owning organization) can push to the repository.

Private repositories are not searchable, and they can only be accessed, pulled, or changed by their named owner(s).

A repository can be owned by a user or an organization. Anywhere in this documentation that mentions the repository owner or profile, it could be used interchagably between a single user or an organization. Users belonging to the organization can access the repositories in the organization if they belong to the organization. Write access to an organizations repository is granted to the administrators and owner of the organization.

The homepage for a repository is located at https://app.turbo.net/run/[profile]/[repo], where profile is the username of the repository owner and repo is the name of the repository. The homepage contains 3 sections:

1. About - Provides an overview of the repository.
2. Releases - Lists all tagged versions of the image.
3. History - Lists the full version history of the image.

On your repository's About page, you can edit the description, Readme, icon, URL, and steps for getting started with your project.

Other users viewing the repository details page can run the repository in a variety of ways.

They can Run your image in a new container through the command-line interface:

# Run the image in a container
> turbo run [profile]/[repo]

They can Pull the image to their local registry. This button will execute this command as if entered via the command-line interface:

# Pull an image down from the Hub
> turbo pull [profile]/[repo]

They can Open a console window in a fresh container with your image as the base. These same actions can also be completed from the command-line interface:

# Open a console window with your image as base
> turbo run [profile]/[repo] cmd

You can create a new repository from the command-line interface by pushing it to the Hub from your local registry:

# First run a container
> turbo run clean

# Then commit the container to an image
> turbo commit 125ee2932 <image>

# Push an image to the Hub
> turbo push <image>

# The image is now pushed to the logged-in profile

To push a repository to an organization, include the name of the organization you are pushing to:

# Push image to organization
> turbo push <image> <org>/<reponame>

Repository Settings

This section will describe the different settings you can apply to the repository. Any workspace application created from a repository will inherit these settings. If an organization dashboard has a direct reference to launch a repository, the session will inherit these settings as well.

Sessions are persistent

Persistent sessions automatically synchronize the application state and settings with Turbo.net. This allows your state and settings to be preserved automatically across multiple sessions and devices.

Typically this setting should be enabled in order to prevent loss of data.

Access local user folders

This setting allows the application to access the host device's local user folders. This includes user folders such as Desktop, Downloads, Documents, Music, Pictures, and Videos.

For applications executing on a remote host, it is recommend that you access your files by connecting a Cloud Storage Service.

Enable URL redirection

When enabled, users using the Turbo URL Redirector Extension will automatically be routed to this virtual application when a accessing certain websites from their native browser.

For more information on installing and configuring the URL redirection extension, see Browser Redirector.

Isolate network

Network isolation runs applications in a virtualized network environment. This environment is unique per application, and is isolated from the host's network.

If you expect multiple users to be running on the same host, it is recommended that you disable this setting to prevent cross-session network access.

For more granular network isolation settings, see Virtual Networks.

Use DLL Cache

This setting enables pre-caching of application DLL and EXE files on the Application Servers’ local disk for faster loading.

Typically this setting will be disabled, in which case the DLL and EXE files are embedded in the SVM and loaded from the Image Cache Server.

Access local network

Local network access allows a remote application to access the local host's network. The local host's network can be accessed by using the special hostname localhost.turbo.net.

Enable: Enables remote access to the local network.
Disable: Disables remote access to the local network.
None: Uses the client's settings to control local network access.

Using

Images added to the using field are included as temporary dependencies during application execution. These images are not committed to the final image, and are not included when continuing a session unless specified.

You may add multiple images by using a comma delimiter: example/using-1,example/using-2.

Components

Components are added to the base image as layers. These layers will be committed to the final image, and are included when continuing a session.

Components must be enabled to be included during execution. Disabled components are for display purposes only, they are shown on the repo settings page and application settings dialog.

VM version

The VM version is a version string that specifies which Turbo VM version will be used for execution.

Typically this field should be left empty so that you are automatically updated to the latest VM version. This should only be used for known VM incompatibilities.

If the specified version is lower than the minimum version that is required by turbo.exe, then the minimum version will be used instead.

2.5 Templates

Templates provide a way to build your own application environment. Tell Turbo what type of application you're building and the dependencies it needs, and we'll deliver a base container embedded with the proper images.

For example, let's say you've written a JavaScript web application on Node.js and MongoDB. Instead of installing these and forcing your testers or end-users to install these dependencies as well, you can build a portable container for your project by adding your application to a template with Node.js and MongoDB images pre-packaged.

Once you package your application into that container, you can deploy it to any Windows environment for testing or use without installers, missing dependencies, or breaks.

3.1 Overview

Turbo.net embraces a "Package Once, Publisher Anywhere" philosophy.

Once an application has been containerized in Turbo, it can be deployed directly to desktops; streamed from an on-premises Turbo Application Server or the cloud; or pushed or streamed via major device management platforms.

This section provides instructions for deploying Turbo applications over major delivery modes.

Additional delivery methods can be implemented using the Turbo APIs.

Note that when using the Turbo HTML5 client for delivery, no client deployment steps are required -- applications launch directly within any HTML5-enabled web browser.

3.2 To Turbo.net

Turbo supports deploying containers as standalone executables, MSIs and Turbo Virtual Machines (SVMs). Read this section to find out more about which deployment option and tools best fit your needs.

The Hub

The Hub is an online registry of Turbo images and provides a central location to archive and distribute applications. Once an application is packaged into a Turbo image using Turbo Studio or the command-line interface, the image can be uploaded to the Hub and accessed privately.

Images are pushed to the Hub using the command-line interface. The most common scenario is to create a container via the command line, commit the container to your local registry and then push the image to the Hub. However, it's also possible to start with an SVM output from Turbo Studio and push that to the Hub. Read below for details on each scenario.

Containers

Before pushing a container to the Hub, it needs to be committed to the local registry and converted into an image. Here is an example of the process of creating a container and publishing it on the Turbo Hub.

# Create a container with Java, Node.js and Git support
> turbo run oracle/jdk,nodejs/nodejs,git/git

# Shut down the container by typing exit into the new command window
> exit

# Get the container id for the last container
> turbo containers -l

# Commit the container to your local registry
> turbo commit 922e myimage

# Verify that the image is now in your local registry
> turbo images

# Push the image to the Hub
> turbo push myimage

To push a repository to an organization, include the name of the organization you are pushing to:

# Push image to organization myorg
> turbo push myimage orgname/reponame

Once the push is complete you can verify that the image is available on the Hub by going to the app.turbo.net/settings/repos or app.turbo.net/orgs/orgname/settings/repos in your browser.

SVMs

Here is an example of how you would deploy an SVM to the Hub.

# Import the SVM into your local registry with the name "myimage"
> turbo import -n=myimage svm \path\to\app.svm

# Verify that the image is now in your local registry
> turbo images

# Push the image to the Hub
> turbo push myimage

Once the push is complete you can verify that the image is available on the Hub by going to the app.turbo.net/settings/repos in your browser.

Using Turbo Studio

Turbo Studio provides a feature to deploy applications directly to your Turbo.net account. After completing the build process, see the Build section for details, click on the Publish to Server option on the ribbon menu.

You will be prompted to log in with your Turbo.net account information and then application will be added to your profile. Once the application has been added to your Turbo.net account, it will be accessible from any Turbo enabled device.

3.3 To Turbo Server

Turbo supports deploying container images as standalone executables, MSIs, and Turbo Virtual Machines (SVMs) to Turbo Server using Turbo Studio or the Turbo Client command line tools. Images added to the Hub can then be added to Workspaces as PC Applications, making the applications available to end-users.

Turbo Server also supports other application types, such as Web Applications and Native Applications, which can be added directly from the Turbo Server administration site.

Adding Images to the Hub

Using Turbo Studio

Turbo Studio provides a feature to deploy applications directly to your Turbo Server. After completing the build process, see the Build section for details, click on the Publish to Server option on the ribbon menu.

From the publish dialog, click change next to the publish server and login to the your Turbo Server. Once you have published the application it will be added to your Turbo Server Hub.

You will now see your application in your hub list in the administration site. Follow the Adding Applications to a Workspace instructions to add the application to a workspace and make it available to end-users.

Using Command Line

Complete the following steps to add a new application image to Turbo Hub Server:

1. Install the Turbo Client for Windows platform.

2. Connect the client to your hub server using the turbo config command. See Config Command for more information.

> turbo config --hub=http://[hubserver]

3. Log in as a hub administrator account or use a system API key. This is done using the turbo login command. See Login Command for more information.

> turbo login admin-user
-OR-
> turbo login --api-key=6g8BwsIlU7ezl_CMIZ_0PYBwK6WVAUZdx1mxYO1WFOg

4. Create your container image. See Working with Containers for more information on ways to create container images.

As an example, we will make a create an empty container that executes the native notepad.exe application.

> turbo new clean -n=test-container
(exit the container window that is shown)
> turbo commit test-container test/notepad:1.0 --no-base --startup-file=notepad.exe
> turbo push test/notepad:1.0

You will now see your test image in your hub list in the administration site. Follow the Adding PC Applications to a Workspace instructions to add the application to a workspace and make it available to end-users.

NOTE: If you do not specify a namespace in the image name (ex, "test" in "test/notepad") then the image will be pushed to the user's private namespace. This image will only be accessible by the user who pushed it and it will not show in the hub list on the administration site.

Troubleshooting

The push command is denied with following error message:

> turbo push mozilla/firefox-base:68.0.1
Pushing image mozilla/firefox-base:68.0.1 to mozilla/firefox-base:68.0.1
Error: Push failed. This user may not be authorized to push to the mozilla repository.

The current logged in user may not be an administrator of the Hub server. Add the user to the administrators group. For more information refer to Managing Users and Authentication.

NOTE: If you add the user to the administrators group after already attempting to push an image to the Hub server, you may have to wait up to 5 minutes for the permissions to propagate to the Hub server. Either switch to an API key based login, or restart the Hub server process and try again.

Adding PC Applications to a Workspace

A workspace is a list of applications that is shown on the Turbo Portal and on the Turbo Clients to users with sufficient permissions. From this workspace, users will be able to run applications using any Turbo enabled device (Windows, MacOS, iOS, Android, or any HTML5 browser).

Applications must first be added to the Turbo Server Hub before they can be added to a Workspace, see Adding Images to the Hub.

If you have not yet created a workspace, you may do so by accessing the Turbo Server administration site at: https://[server]/admin. Navigate to the Workspaces tab, click Add Workspace, and submit your desired workspace settings.

Then open the Workspace administration site by clicking on the Manage link. Navigate to the Applications tab, click Add > PC Application, and select your application.

The application will now be available on the Turbo Server Portal and on the Turbo Clients to users with sufficient permissions.

3.4 To a Desktop

Turbo supports deploying containers from the Turbo Hub to your desktop using the subscribe and installi features. Add the latest version of an application to enable auto-patching of that application. This ensures you get the latest updates to the selected applications as they are released.

Virtual desktop infrastructure (VDI) / Windows Virtual Desktop (WVD)

The turbo subscribe command allows administrators to register desktops to workspaces. A desktop registered to a workspace provides end users access to all workspace applications, application updates, and Active Directory based permissions.

• Add an API key for a workspace.
• Give the API key Read Only Admin Permissions to the workspace.
• Configure applications in the workspace with the appropriate permissions under Application Settings.
• Install Turbo Client for all users on the VDI base image.
• Login with the API key which will be used to update the workspace and grant end users access turbo login --all-users --api-key=<apiKey>.
• Subscribe to the workspace: turbo subscribe --all-users <workspace>. The workspace applications will be cached to the local all-users repository location. Application updates and settings are updated periodically.
• Configure a login script to register the workspace subscription to the user turbo subscription register <subscription>.

Single Repository Shell Registration

Containers can also be integrated with the Windows shell. The install or installi command will create Start Menu shortcuts, file associations, and shell extensions in the shell for the image so that it behaves similar to an installed application.

# Install the VLC container to the shell
> turbo installi --name=vlc videolan/vlc --register-extensions

Configuring shortcuts and file associations for an image is done in Turbo Studio. See the reference section for more details.

3.5 AWS AppStream

Turbo supports deploying applications to Amazon AppStream 2.0. AppStream 2.0 provides cloud-based Windows desktops hosted in the AWS cloud.

AppStream 2.0 offers two deployment models: Always-On/On-Demand and Elastic fleets.

With Always-On and On-Demand fleets, one creates a golden image that includes the Turbo client configured as you would any other VDI environment. In this case, Turbo allows applications to be dynamically deployed without modifications to the base image.

With Elastic fleets, it is necessary to have a way to rapidly provision applications on the clean base image provided by AWS as well as run applications that may not originally be designed for portable use or for execution in the specific Windows environment provided by AWS. Turbo containers address all of these issues in a single, efficient solution.

Before Starting

Before starting the AppStream 2.0 setup, please note the following information:

• URL of the Turbo Hub Server
• API Key to access the Hub Server

The API key can be generated from the Turbo Server administration console under Hub / API Keys. Press Add Key and enter a key name such as aws-appstream. Leave the Run as system option unselected.

It is strongly recommended that a dedicated API key be used for the AppStream 2.0 fleet.

For the best performance, it is recommended that the Hub Server run in the same AWS Availability Zone as the AppStream 2.0 fleet. This also minimizes costs associated with data transfer. If necessary, the AWS Hub instance can federate respositories from an external Turbo Hub such as an on-premises Hub.

AppStream 2.0 Setup

Turbo AppStream 2.0 setup consists of:

1. Configuring an AppStream 2.0 Stack and Fleet
2. Setting up the Turbo App Block
3. Adding applications

Stack and Fleet Setup

Prior to configuring Turbo in AppStream, it is necessary to create an AppStream 2.0 Stack and Fleet. These provide the computate infrastructure that will run applications.

Instructions on configuration can be found in the AWS AppStream 2.0 documentation:

Create an AppStream 2.0 Fleet and Stack

AppStream 2.0 includes the ability to use Elastic Fleets which are a very cost effective way to launch and stream Turbo applications to end users. Since elastic fleet VMs are provisioned from a ready-to-use pool of instances, provisioning is fast, yet customers are only charged for actual time used, exclusive of "standby" time.

App Block

An AppStream App Block provides shared setup for a set of AppStream applications. When using Turbo to deploy on AppStream, a single App Block is used to deploy the Turbo Client, which can then run any Turbo-packaged application.

For convenience, the Turbo Client is available in VHD form from the Turbo Downloads page:

Turbo Client Downloads

A setup script is provided that handles mounting of the VHD and setup of the Turbo Client. The setup script is available in the Turbo GitHub repository:

Turbo VHD Setup Script

The setup script accepts a single parameter indicating the Hub server to be used.

The Turbo Client VHD and setup script must be copied into an S3 bucket in the same zone as the AppStream 2.0 fleet. AppStream 2.0 must also have permissions to access the S3 bucket.

For more information on S3 bucket configuration, see the document:

Store Application Icon, Setup Script, and VHD in S3 Bucket

The following App Block settings should be used:

Adding Applications

Once the App Block is configured, any Turbo application can be launched within the AppStream 2.0 interface.

Prior to adding the application, the application icon should be added to the connected S3 bucket.

The following Application settings should be used:

Note that each application must be associated to a fleet before the application will be available.

Launching Applications

To test applications, select the applicable AppStream 2.0 Stack and press Action / Create Streaming URL. This creates a one-time URL that will launch AppStream as the specified user.

3.6 Citrix

System administrators can use Turbo to quickly deploy applications and custom containerized environments on Citrix, Parallels RAS, Workspot, Windows Remote Desktop Services (RDS), and other remote desktop systems.

Using Turbo Command Line

Turbo containers can be deployed to Citrix XenApp servers using the Turbo command line interface. Below are the steps required.

Prerequisites

To get started, you will need to download and install Turbo for Windows for all users on the system.

If users will be streaming the application window rather than the whole desktop, we recommend hiding the Turbo GUI using the --hide-gui flag.

> start /wait turbo-client.exe --all-users --silent --hide-gui

Adding Applications to the Start Menu

Turbo application desktop integration, including Start Menu, desktop shortcuts, and file associations, can be enabled with the turbo installi command along with the --all-users flag. If you omit the version from the application identifier, then the latest version will be used.

# Sign in to Turbo.net
> turbo login 

# Add the latest Firefox ESR browser to the Start Menu
> turbo installi --all-users mozilla/firefox-esr

# Add the latest Google Chrome browser to the Start Menu
> turbo installi --all-users google/chrome

# Add Internet Explorer 8 with Java 6.45 to the Start Menu
> turbo installi --all-users microsoft/ie:8,jre:6.45

The Firefox ESR, Chrome,and IE8 with Java6 applications will appear in the Start Menu of the server.

Adding Applications to the Delivery Platform

Depending on the delivery platform in use, you may also need to add the applications in the delivery system's administration interface.

In this example, we will add applications to Citrix XenApp using Citrix Studio.

Start Citrix Studio and go to Applications > Add Applications.

Select the option to Add applications From Start Menu...

Then select the Firefox ESR, Chrome, and IE8 with Java6 applications.

Click through to Finish to complete the process.

Running the Applications

Once added to Citrix Studio users can access the applications from the Citrix StoreFront website or the Citrix Receiver application.

Click on an application to launch it.

Since applications are executed in isolated Turbo container environments, any combination of browsers, plugins, and runtimes can run side-by-side on the same server.

For example, an Internet Explorer 8 with Java 6 environment can run alongside an Internet Explorer 10 with Java 7 environment or another Internet Explorer 8 with Java 7 environment.

This allows elimination of Citrix siloing and consolidation of servers to a single version of Citrix using a single base image.

Using Turbo Citrix Scripts

Turbo containers can also be deployed to XenApp using powershell helper scripts to automate the deployment.

XenApp 7

For XenApp 7, use the turbocitrix/xa7-subscribe container image to add turbo applications to your XenApp server and publish them automatically.

# install the turbo client for all users on the machine (this is only necessary once)
> Turbo-Plugin.exe --all-users --silent

# login to your account or org using the defined API key
> turbo login --api-key=WvUjfpjqtx0as1CczTX5mPZ5pdXgc1w2t91HRzVc3Qc 
Logged in as turboorg

# run the container image that contains the powershell helper script
> turbo try turbocitrix/xa7-subscribe -- turboorg -deliveryGroup Default -apikey WvUjfpjqtx0as1CczTX5mPZ5pdXgc1w2t91HRzVc3Qc -waitonexit
Using VM 11.8.817.5 from local
Using image clean:25 from local
Using image vcredist:2008 from local
Using image xa7-subscribe:2016.02.26 from local
Running new container xa7-subscribe#3d2a1d9f with visibility private
Checking if Turbo client is installed...
Subscribe to turboorg...
Aptana Studio subscribed
Mozilla Firefox subscribed
7-Zip subscribed
Atom subscribed
Audacity subscribed
Dia subscribed
LibreOffice Writer subscribed
LibreOffice Base subscribed
Beyond Compare subscribed
NPP Notepad++ subscribed
Google Chrome subscribed
LibreOffice Calc subscribed

Aptana Studio published
Mozilla Firefox published
Atom published
Dia published
LibreOffice Writer published
LibreOffice Base published
Beyond Compare published
NPP Notepad++ published
Google Chrome published
LibreOffice Calc published
Deployment successful

After those easy commands, we have applications deployed to our XenApp farm!

Go to Subscribe for XenApp7 for more information and full documentation of the script parameters.

XenApp 6.5

For XenApp 6.5, use the turbocitrix/xa6-subscribe container image to add turbo applications to your XenApp server and publish them automatically.

> Turbo-Plugin.exe --all-users --silent

> turbo login --api-key=WvUjfpjqtx0as1CczTX5mPZ5pdXgc1w2t91HRzVc3Qc 
Logged in as turboorg

> turbo try turbocitrix/xa6-subscribe -- turboorg -users domain\users -apikey WvUjfpjqtx0as1CczTX5mPZ5pdXgc1w2t91HRzVc3Qc -waitonexit
Using VM 11.8.817.5 from local
Using image clean:25 from local
Using image vcredist:2008 from local
Using image xa6-subscribe:2016.02.26 from local
Running new container xa6-subscribe#4fa191d9f with visibility private
Checking if Turbo client is installed...
Subscribe to turboorg...
Aptana Studio subscribed
Mozilla Firefox subscribed
7-Zip subscribed
Atom subscribed
Audacity subscribed
Dia subscribed
LibreOffice Writer subscribed
LibreOffice Base subscribed
Beyond Compare subscribed
NPP Notepad++ subscribed
Google Chrome subscribed
LibreOffice Calc subscribed

Aptana Studio published
Mozilla Firefox published
Atom published
Dia published
LibreOffice Writer published
LibreOffice Base published
Beyond Compare published
NPP Notepad++ published
Google Chrome published
LibreOffice Calc published
Deployment successful

You can find more information and full documentation at Subscribe for XenApp6.5.

3.7 System Center (SCCM)

Microsoft System Center Configuration Manager (SCCM) is a wonderful tool to deploy application containers to desktops in your enterprise. Below shows several methods that SCCM can be used to deploy containers.

Distribute Standalone Executables

The easiest solution is to deploy a shortcut to a standalone executable container. Standalone executable containers are single .exe files that have the full virtual machine built in. With them you can get the full application experience without installing anything to the machine. You can either point your application shortcut to a copy of the .exe in a local machine location or at shared network location. See building standalone executables for more information.

Distribute MSIs

Turbo MSIs can be used as an alternative to deploy standalone executables. The benefits are that you have full control over what shortcuts get created as well as the ability to add file associations to your application. See building MSIs for more information.

Use application images (.svm files)

This option is the most versatile but also requires some configuration effort. Instead of embedding all the application files in the SCCM package, we may use the .svm files hosted either on Hub or a file share. Below, you can find a description of the file share deployment. Firstly, we need to configure the file share server.

1. Configure the file share server

There are two configuration steps for the file share server:

• Install the Turbo.net client: turbo-client-19.9.2054.0.exe --silent --all-users
• Make the path C:\ProgramData\Turbo\Containers\repo a shared folder, giving read-access to all the user accounts which will run Turbo applications
• Download the base images:
  • turbo pull --all-users xvm
  • turbo pull --all-users clean

2. Prepare Turbo.net Client Runtime installation package in SCCM

From https://turbo.net/download download the .msi Turbo.net Client installer and create an Application in SCCM with the .msi deployment type:

Next, create a custom Application that configures the newly installed Turbo.net Client. For this purpose, we need a simple install.bat file with the following content (replace {file-share} with the shared folder path from the previous point):

"C:\Program Files (x86)\Turbo\Cmd\turbo.exe" config --all-users --image-path {file-share}
echo ok > "C:\Program Files (x86)\Turbo\configured.txt"

** Note about the file share address **

When you have multiple sites configured in SCCM, you may want to use a separate file share for each one of them. For instance, the right place for a Turbo file share would be the SCCM Distribution Point. However, that complicates the above script, as we need to discover the nearest share dynamically. One option to do so is by querying the SCCM WMI objects.

Next, we create a custom Application:

Create the 'Script Installer' deployment type:

Specify the path to the batch file:

And the detection rules:

Finally, on the User Experience tab, make sure the script installs for the system and run the deployment.

3. Prepare and publish the application image

It's time to create the application .svm file. We can do that by using either Studio or Turbo Script. Both methods are covered in other sections of the documentation, so let's focus only on the publishing part. With the .svm file ready, we need to import it by running turbo import svm --name {app-name} {path-to-svm-file} on the file share server(s).

4. Prepare the SCCM application package

We are now ready to prepare the SCCM package for our application. We start again by creating a .bat file with a simple command:

"C:\Program Files (x86)\Turbo\Cmd\turbo.exe" installi --skip-installed --offline {app-name}

And use it in a 'Script Installer' deployment:

The turbo installi command adds keys to the Uninstaller key, so you may use the app key in a Detection Rule configuration:

In the User Experience tab, select 'Install for user' and finish the Application wizard. We are now ready to deploy the package to Distribution Points and client devices.

** Note **

When you use a hub instead of the file share, it is possible to install all the organization images published to a hub with the subscribe command, for example:

# Add shortcuts to all the dashboard apps from the 'turbo-user' user account
> turbo subscribe turbo-user

# Add shortcuts to all the dashboard apps from the 'turbo-org' org
> turbo subscribe turbo-org

See installi, install, and subscribe for more information.

3.8 Intune

Intune is an Azure-based device management solution by Microsoft.

This section describes the process for deploying the Turbo client to Intune-managed devices.

Deploying Turbo for PC

1. Download the latest Turbo Client MSI installer at https://start.turbo.net/install?msi=
2. Sign in to the Intune portal
3. In the Intune pane select Client Apps > Apps > Add
4. In the App type list select Line-of-business app and select the Turbo Client MSI installer
5. Select Configure and provide the following information:
   • Name: Enter the name of the app as it is to be displayed in the company portal
   • Description: Enter a description for the app as it is to be displayed in the company portal
   • Publisher: Enter Turbo.net as the publisher.
6. Under the Command-line arguments section, enter the text CMDLINE="params" where params are the desired setup parameters. Any parameters valid for the Turbo EXE client install and turbo config command may be provided here.
   • Recomended: Use the --image-path=allusers flag to have all users on the device use a shared image cache. This prevents redownload of the application when different users on the same device run the same application.
   • (Optional) Use the --add-trusted-source=https://myhub.start.turbo.net flag to have the device automatically trust applications from your Hub. If this is not done at client setup time, the user will be prompted to trust applications published by your organization before an application can execute on the device.
   • For example, to use a shared image cache and add a trusted source, the command-line argument would be CMDLINE="--image-path=allusers --add-trusted-source=https://myhub.start.turbo.net"
7. Optional: Select Scope and select any desired tags
8. Select Add
9. Under Manage, click Assignments and assign the app to the necessary groups

Deploying Turbo for iOS

1. Sign in to the Intune portal
2. In the Intune pane select Client Apps > Apps > Add
3. In the App type list select iOS
4. In the Search the App Store pane search for Turbo.net, select the Turbo.net iOS app, and press Select
5. (Optional) Select App information to edit the auto-populated fields
6. (Optional) Select Scope and select any desired tags
7. Select Add
8. Under Manage, click Assignments and assign the app to the necessary groups.

Deploying Turbo for Android

To deploy Turbo.net for Android via InTune:

1. Sign in to the Intune portal
2. In the Intune pane select Client Apps > Apps > Add
3. In the App type list select Android
4. Select Configure and provide the following information:
   • Name: Enter the name of the app as it is to be displayed in the company portal. Usually this would be Turbo.net.
   • Description: Enter a description for the app as it is to be displayed in the company portal.
   • Publisher: Enter Turbo.net as the publisher.
   • Appstore URL: Enter https://play.google.com/store/apps/details?id=net.turbo.android.launcher
   • Minimum operating system: Select Android 5.0 (Lollipop)
5. Select OK and Add
6. Under Manage, click Assignments and assign the app to the necessary groups.

3.9 Parallels RAS

Parallels Remote Application Server (RAS) is a comprehensive virtual application and desktop delivery solution that allows your employees to access and use applications and data from any device.

By integrating Turbo.net technology, Parallels Remote Application Server allows IT administrators to package applications and their dependencies into an isolated virtual environments. Containerized applications can be run on any Windows server, no matter the underlying OS. This eliminates installs, conflicts, breaks, and missing dependencies.

Application Provisioning

Turbo.net is integrated into Parallels RAS, allowing application provisioning directly from the Turbo.net Hub to any server in the farm. Administrators can just select the required application directly from the RAS Console; applications are automatically installed and ready to be published to the users.

Effortless Delivery

Turbo.net has teamed up with Parallels RAS to further simplify the process of delivering applications and desktops. Completely transparent to the administrator and without any extra configurations required, the applications in the Turbo.net Hub are available for delivery in the Parallels RAS Console like any application already installed in the farm. As soon as a user requests first-time access to an application published, Parallels RAS automatically installs and configures Turbo.net runtime and the application on the RDSH servers, reducing IT staff's manual tasks.

Run Legacy Applications and Multiple Versions Simultaneously

Some applications (and very often legacy applications) were not designed for publishing, since they may fail to launch if there is another instance of the application already running on the server. Parallels RAS integrated with Turbo.net allows you to bypass such limitations, because a running application wouldn’t be able to detect that there is another instance of the application already running on the computer. Application containerization enables administrators to run different versions of the same application on the same server. For instance, on a webpage, testers may test the page on different browsers and also different versions of the same browser, ensuring the same face is shown on each.

Learn More

For more information on Turbo.net on Parallels RAS, take a look at the demo video above or visit https://www.parallels.com/products/ras/features/turbo-net.

3.10 Turbo Client

In the following pages you will learn about how to use the Turbo Client and Turbo Launcher.

Install the Plugin

End-users must download and install the Turbo Client prior to launching Turbo applications for the first time.

If you already have the Turbo Client and are installing an update Turbo automatically uninstalls older versions if they have been idle for more than 30 days.

Command line flags

When installing the Turbo Client for a managed environment, there are command line flags that may be useful.

Turbo-plugin.exe [Option]

Proxy Settings

The Turbo Client uses the proxy settings of the local device by default. End-users using Microsoft Internet Explorer can change proxy settings from within the browser. Users of other browsers must change proxy settings on the host device itself.

Complete the following steps to change system proxy settings on the host device:

1. Navigate to the Control Panel in your windows Start Menu.

2. Select the Internet Options icon.

3. Select the Connections tab, then LAN Settings.

4. Enter the proxy settings specified by your network administrator.

Using the Turbo Launcher

The Turbo Launcher

The Turbo Launcher is what end-users see when they select the Turbo icon from the system tray. Users are able to launch applications from the Hub they are connected to.

• Turbo Launcher automatically runs on Microsoft Windows startup and runs in the background until manually shut-down. The process is represented in the Microsoft Windows systray by a Turbo icon. Select the icon brings up a more detailed window from which all other settings are available. Closing this window does not end the background activity; only choosing Shut Down from the Options menu shuts down background activity.

• Any Turbo user can sign in to a host using the Turbo Launcher. This includes users with turbo.net accounts and users with accounts on private Turbo Hub Servers.

• To be "signed in" means that applications will run without prompting for a username and a password, application settings data are saved, and settings for that user can be viewed and edited.

• Multiple Turbo users can be signed in on the same machine.

• Only one Turbo user per host can be signed in at the same time.

Advanced Plugin Topics

Install location

If the Turbo Client was installed for all users, the install location is in one of the following locations.

• For x86 platforms: C:\Program Files\Turbo

• For x64 platforms: C:\Program Files (x86)\Turbo

If the plugin is installed for a single user profile, the install location is in the following locations: C:\Users<profile>\AppData\Local\Turbo

Command line flags

The Turbo Client installs an application called Turbo Service that runs on startup. This application can be found in the install directory of the Turbo Client. There is a command line interface for this application.

TurboService.exe [Option]

Mobile Device Management Configuration

Mobile Device Management (MDM) software is used to monitor, manage, and secure employee mobile devices. Below is the configuration XML necessary for iOS and Android devices.

iOS

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>serverURL</key>
    <string>https://turbo.net/</string>
    <key>username</key>
    <string>example@domain.com</string>
    <key>rememberMe</key>
    <true/>
    <key>password</key>
    <string>userpassword</string>
</dict>
</plist>

serverURL is URL of Turbo Server. username and password are the user's Turbo Server credentials. rememberMe indicates that user credentials are stored on the device.

If username and password are provided then the application tries to login the user automatically.

Android

<restrictions xmlns:android="http://schemas.android.com/apk/res/android">
    <restriction
        android:defaultValue=""
        android:key="login"
        android:restrictionType="string"
        android:title="User login" />

    <restriction
        android:defaultValue=""
        android:key="password"
        android:restrictionType="string"
        android:title="User password" />

    <restriction
        android:defaultValue=""
        android:key="server"
        android:restrictionType="string"
        android:title="Turbo server" />

    <restriction
        android:defaultValue="true"
        android:key="rememberme"
        android:restrictionType="bool"
        android:title="Remember me" />
</restrictions>

server is URL of Turbo Server. login and password are the user's Turbo Server credentials. rememberme indicates that user credentials are stored on the device.

If login and password are provided then the application tries to login the user automatically.

3.11 Portable EXEs and MSIs

Turbo Studio can be used to package virtual applications as portable EXEs and MSIs.

EXE

A popular option for organizations that have an existing endpoint management solution like LANDesk Management Suite ®, Microsoft System Center, or Novell ZENworks is to deploy containerized applications as standalone executables. These executables are built on the SVM architecture and work just like a container.

Deploying applications within containers is convenient for running different versions of applications like Internet Explorer 8 and 11 side-by-side on the same system.

To produce an executable output, set the Project Type to ISV Application in Turbo Studio. Executables can be deployed directly to the users device or to a network share and do not have any dependency requirements.

An enterprise license for Turbo Studio is required to enable executable outputs. Contact our sales team for more information.

MSI

MSI outputs simply wrap the standalone application exe into an MSI package to add support for shell integrations such as file associations, Start Menu shortcuts and ProgIds. MSIs are a common deployment option for organizations that are using AdminStudio or for integrating with existing desktop management solutions.

To build an MSI, go to the Setup section of Turbo Studio, enter the MSI details and click Build MSI. MSIs can be deployed with existing desktop management tools or directly by the end users. See the reference for details on MSI settings.

An enterprise license for Turbo Studio is required to enable MSI outputs. Contact our sales team for more information.

Turbo EXE

A Turbo EXE is a portable executable that packages the application with the Turbo client. When an application is published as a Turbo EXE, the application is pushed to the Hub which enables features such as deploying application updates to users. See the hub docs for additional features.

To produce a Turbo exe, set the Project Type to Portable Application in Turbo Studio. A Turbo.net account is required.

3.12 Integration Tools

Turbo has tools to enhance the deployment process and integrate containerized applications with existing deployment tools. For example, Browser Redirector enables administrators to automatically direct users to a supported browser based on a URL that is entered. This solves compatibility issues for organizations that have legacy web applications that rely on non-standard browser configurations.

Redirector Walkthrough

The Turbo URL Redirector is a native browser extension that assists in web navigation by processing clicked hyperlinks and URLs entered in the navigation bar. The extension can be configured to open specified domains using a browser available on Turbo.net or a local Turbo Server.

The Turbo URL Redirector for Internet Explorer is implemented in the Turbo.net Browser Helper Object (Turbo-IEBrowserHelper.dll or Turbo-IEBrowserHelper-x64.dll depending on the processor architecture of the host machine) and supports IE versions 8, 9, 10 and 11. The Turbo.net Extension provides the same experience for users of Chrome 42 and above. To try the Turbo URL Redirector feature for yourself, follow this step-by-step guide.

Enabling Turbo URL Redirection

The Turbo URL Redirector is disabled by default, because its installation requires elevated permissions to copy IE Browser Helper binaries to %ProgramFiles(x86)%.

To enable the Turbo URL Redirector, execute the following command:

> turbo config --enable-redirector
Hub server: https://turbo.net/
Browser redirection is enabled

Enabling Turbo URL Redirection in Internet Explorer

Launch Internet Explorer.

You may see an Internet Explorer Security alert explaining that the Turbo Sandbox Manager will be opened outside of Protected mode. (Turbo Sandbox Manager is the service responsible for integration of Turbo applications with the Turbo.net website.) Ignore this warning by checking Do not show me the warning for this program again and then clicking Allow.

Go to Tools (Alt + X) and Manage add-ons (M).

The Turbo.net Browser Helper will be displayed in the list of currently loaded add-ons. Change the status of the add-on to Enabled if required and close the dialog.

Enabling Turbo URL Redirection in Chrome

Install and enable the Turbo.net Extension.

For information how to enable the extension for all users see Deploying Turbo URL Redirection via Group Policy.

Defining Redirection Rules in the Windows Registry

Redirection rules can also be set in the Windows registry in cases where Turbo.net subscriptions are not used.

Rules are added to the "HKLM\Software\Code Systems\Turbo\Redirector" hive ("HKLM\Software\Wow6432node\Code Systems\Turbo\Redirector" for 64-bit operating systems).

Create a key under the Redirector hive, setting the name of the new key to the url pattern to match. In the example above, the pattern is "yahoo.com" which matches any url that contains "yahoo.com".

Within the new rule key, registry values are used to describe the command to execute if a url is encountered which matches the pattern. There are two ways to describe the redirection response, with Command or TurboCommand string values. A Command value is set to the full path to the command to execute. In the example above, the command is set to "c:\turbo\ie8-win10.exe". A TurboCommand value is set to the command to execute via turbo.exe. An example value would be "run ie8" which would execute "turbo.exe run ie8". For either of these command types, the url which matched the pattern is appeneded to the end of the command to be passed as a parameter.

Deploying Turbo URL Redirection via Group Policy

This section explains how to enable the Turbo URL Redirector for all users of Internet Explorer and Chrome.

Before following the step-by-step guide for each browser ensure that the Turbo URL Redirector is enabled.

> turbo config
Hub server: https://turbo.net/
Browser redirection is enabled

If the browser redirection feature is disabled, see enabling Turbo URL Redirection.

Enable the Turbo Browser Helper Object for All IE Users

Microsoft Internet Explorer can be configured for all users through Local Group Policy. This section explains how to specify the GPO to silently load and enable the Turbo.net Browser Helper Object. Depending on the policy settings the user may be allowed to disable the add-on afterwards.

First open the Local Group Policy Editor:

> gpedit.msc

Select the Add-on Management node under Computer Configuration/Administrative Templates/Windows Components/Internet Explorer/Security Features in the Local Computer Policy panel.

Double click Add-on List in the detailed view.

Select Enabled and click the Show button in the Options panel.

Add a new entry with Value name {DEC8F2AC-A81F-4BC9-A973-41EE4C4AF116} and Value 1. The Value name corresponds to the class identifier (CLSID) of the Browser Helper Object. The Value is a number indicating whether Internet Explorer should deny or allow the add-on to be loaded. Setting Value to 1 means that an add-on should be allowed. Enter a 2 to allow the add-on to be loaded and permit the user to manage the add-on through Add-on Manager. We recommend using 1 for most administration scenarios.

Click OK to save options and close the dialog.

Press the Apply button to update the policy settings and OK to close the dialog.

Launch the native IE to verify settings.

If the Turbo Sandbox Manager is not running you may see an Internet Explorer Security alert explaining the process will be opened outside of Protected mode. (Turbo Sandbox Manager is the service responsible for integration of Turbo applications with the Turbo.net website.) You can ignore this warning by checking Do not show me the warning for this program again and then clicking Allow.

Go to Tools (Alt + X) and open Manage Add-ons (M).

Turbo.net Browser Helper should be included in the list of currently loaded add-ons and be enabled. Note that actions to change the status of the Turbo.net Browser Helper are disabled.

Enable the Turbo.net Extension for All Chrome Users

Google Chrome configuration for all Windows domain users can also be defined using Local Group Policy. This section provides step-by-step instructions on adding the Turbo.net Extension to force-install extensions in Chrome. The extension will be installed silently, without user interaction and cannot be uninstalled by the user. All permissions requested by the extension will be granted implicitly, without user interaction.

As of this writing the Turbo.net Extension requires permissions to read and change all data on the visited websites and communicate with cooperating native applications. The extension supports Chrome 42 and above.

First, Download the IP archive with policy templates from the Chrome website.

(For more information about the policy templates and other supported configuration settings refer to the documentation for Chrome administrators.)

Unpack the archive to and install templates on the local machine by copying them to %SystemRoot%\PolicyDefinitions directory.

Copy .\policy_templates\windows\admx\chrome.admx to %SystemRoot%\PolicyDefinitions.

Copy .\policy_templates\windows\admx\locale\chrome.adml to the %SystemRoot%\PolicyDefinitions\locale directory, where the locale alias corresponds to the locale name (en-US for United States) of the Windows display language used on the host machine.

Run the Local Group Policy Editor:

> gpedit.msc

Select Extensions node under Computer Configuration/Administrative Templates/Google/Google Chrome in the Local Computer Policy panel.

Double click on the Configure the list of force-installed apps and extensions in the detailed view.

Select Enabled and click the Show button in the Options panel.

Add the following entry to the list of Extension/app ids and update URLs to be silently installed.

ldibmiofagdkgiphkcokpooepankmacl;https://clients2.google.com/service/update2/crx

The first component is the Id of the Turbo.net Extension. The URL points to the standard Chrome Web Store update service.

Click OK to save options and close the dialog.

Press the Apply button to update the policy settings and OK to close the dialog.

To verify that local policy settings are applied correctly launch Google Chrome and go to chrome://extensions URL.

The Turbo.net Extension should be listed on the page with the Enabled checkbox set, but not available for user interaction and a badge informing that the extension was installed by enterprise policy.

The Local Group Policies presented in this article apply equally well to browsers launched with merge or write-copy isolation using Turbo:

> turbo try google/chrome --isolate=merge
> turbo try microsoft/ie --isolate=write-copy

3.13 Tips

API Keys

API keys allow you to login to the Turbo.net or Turbo Server hub without the use of a password. This is important for scripting and automation as it eliminates the need to hard code passwords or pass them in as parameters to your scripts. API keys can be revoked or regenerated in case they have been compromised.

Manage Your Keys

The first step is to create an API key. To do this, go to your account or organization settings page by clicking on the account dropdown on the top right of the page, and then select Device and API Keys on the right menu.

Once here, click Add API Key to generate a new key. Press the Remove button to remove the key and revoke its access to your organization. There is no limit to the number of keys you can generate.  You may decide to create and manage different keys for different teams or for different user access, allowing you the flexibility to revoke them independently without disrupting all key users.

Click Copy Key and head back to the command line.

Turbo Login with an API Key

Using the API key is easy -- just include the key in the turbo login command using the --api-key flag.

> turbo login --api-key=9ZoKH_336g0MqP2yptwfrv9B1XUm8YFPnCZNugVQNr4
turboorg logged in at 7/26/2018 3:53:31 PM

The session is now authenticated in the account context. The account will stay logged in until the API key is revoked or the session is closed with the turbo logout command.

Windows Firewall

Sometimes it is necessary to add Windows Firewall rules to allow container applications access to network ports. Below are some suggestions when configuring these rules.

Using the StubExe Path

If creating a rule that applies to a program path, you will need to use the path to the stubexe. The stubexe is a small .exe stub that is written to the sandbox when an application inside the container is launched. It is required by the Windows operating system in order to execute an application.

If I run Mozilla Firefox in a container:

> turbo run firefox -d
Using VM 18.7.1306 from local
Using image clean:26 from local
Using image firefox:61.0.1 from local
Using image firefox-base:61.0.1 from local
Running existing container firefox#d9011823

I will find the sandbox for this container at C:\Users\turbouser\AppData\Local\Turbo\Containers\sandboxes\d9011823384b4cbeac39e7d430892fe4, where d9011823384b4cbeac39e7d430892fe4 is the container ID. You can find the container ID using the turbo containers command or by looking for a directory which matches the container name, in this case firefox#d9011823.

> tree /f C:\Users\turbouser\AppData\Local\Turbo\Containers\sandboxes\d9011823384b4cbeac39e7d430892fe4\local\stubexe
Folder PATH listing
Volume serial number is 000000FB 5ABB:3E17
C:\USERS\TURBOUSER\APPDATA\LOCAL\TURBO\CONTAINERS\SANDBOXES\D9011823384B4CBEAC39E7D430892FE4\LOCAL\STUBEXE
└───0xBD0FFFB5401D3815
        firefox.exe
        firefox.exe.manifest

The folder 0xBD0FFFB5401D3815 is a hash of the file configuration settings so that that the same launch again in the future does not require a new file to be written unnecessarily.

Note, there will be a stubexe for each .exe that is spawned from the container. You will need to make rules for each .exe that it should apply to.

If you are using a standalone executable, the stubexe is also used and will be in the application sandbox in the same folder structure. If your environment has upgraded from using a Spoon Client, then you may need to use the spoon directory rather than the one which using a turbo link.

Creating a New Outbound Rule

In Windows Firewall, an Outbound Rule is used to control how an application can access outside resources.

Open the Windows Firewall from the Control Panel.

Click on Advanced Settings link.

Click on Outbound Rules and then New Rule....

Select the Program rule type and then next.

Enter the path to the application stubexe and then next.

For our example we will block all connections from the application. Then press next.

Apply to all networks then press next.

Give the rule a name and description, then press next.

Now your new rule will be added to those that Windows adds by default.

Running firefox again from the same container yields a different result this time.

Customizing the StubExe Path

By default the stubexe path is inside the sandbox. However, this can make it difficult to configure network rules that apply across your enterprise since it will be a different path for every user. For this case, you can configure where the stubexe is cached using Turbo Studio when you build your container images.

You can set the Application stub cache location to any local path.

Now the application stubexe will always be cached in a well known location that you can set your universal rules to point to.

Adding Rules Programatically

You can use either the PowerShell New-NetFirewallRule cmdlet or call the Windows netsh command directly.

4.1 Overview

Turbo Studio is a desktop application that allows you to convert any Windows application into a self-contained virtual application container. Virtual applications can be delivered as Turbo images to be used by the Turbo Client or Turbo Server as well as standalone executables.

The GUI allows users to easily edit complex configurations for applications that may require complicated settings. Whereas Turbo's command line tool builds images from containers, Turbo Studio uses static XML files (.xappl) to build images. More information about the XAPPL file format is available in the XAPPL reference.

Once created with Turbo Studio, the command-line interface builds these XAPPL files into images that you can push to the Turbo Hub. Click here for a specific example.

Turbo Studio provides three methods for creating images and virtual applications:

1. Setup Capture: In this method, file and registry changes are recorded during the installation process of an application and these changes are applied to the configuration. This is the recommended method of image creation.

2. Snapshot an application or component: In this method, snapshots capture the system state before and after an application is installed. Based on the observed system changes, the virtual application settings are automatically configured.

3. Install application into a container: With this method, you would run the application installer in a clean container environment. When the installer completes, the contents of the container will be used to generate the application configuration.

Turbo Studio offers a user interface to manage custom images and virtual applications as well as additional creation methods not available in the command-line interface.

System Requirements

Turbo Studio runs on on Windows Vista and higher, including systems running within VMware and Microsoft hardware virtualization and hypervisor environments.

Turbo Studio supports both 32- and 64-bit applications. Both 32-bit (under 32-bit mode) and 64-bit executables can be run on x64-based platforms.

Turbo Studio has limited support for the Windows Preinstallation Environment (WinPE), though certain applications (depending on operating system features unavailable in WinPE) may not function properly.

Note: Turbo Studio does not support virtualization of 16-bit executables. To run 16-bit DOS applications, virtualize an appropriate emulator with the application and launch the application through the emulator.

Note: For legacy applications that install only on Windows XP or Windows Server 2003, use Turbo Studio 19 to capture the application and generate a XAPPL+Files configuration, then use the latest version of Turbo Studio to build the configuration into an application SVM or EXE package.

4.2 Working with Turbo Studio

Getting Started

Using Turbo Studio enables you to configure the filesystem and registry of a container, embed external runtimes and components, take application snapshots, and create Turbo Virtual Machine (SVM) or executable files. The primary interface consists of a ribbon bar along the top and several panes accessed by buttons on the left.

Menu Bar

• The File menu enables container configurations to be created, opened, and saved. Turbo Studio configuration settings like the license certificate, proxy settings, troubleshooting options, etc can also be found here.
• The Home ribbon bar provides access to common Turbo Studio features. Details below.
• The Advanced ribbon bar provides access to advanced Turbo Studio features. Details below.

Options

• License settings button is to set the turbo.net account or license certificate used for licensing purposes.
• Proxy settings button is to configure network proxy settings.
• Play sound on build completion sets whether an audible chime is played to notify the user that the build is complete. This can be useful for long builds that are running in the background. The default is enabled.
• Enable capture diagnostic logging sets whether exhaustive diagnostic logs are collected during a system capture or snapshot. These can be useful in troubleshooting why a capture or snapshot failed to collect some information. The default is disabled.
• Copy added files to the configuration folder sets whether files that are added to a configuration are sourced from their current location or copied into the configuration's "Files" folder. Sourcing from their location can be useful if adding files from a network share or from system folders where the files may change between builds. However, if the configuration is built from a different location or by a different user, Studio may not have access to the files. To make a configuration portable, enable this setting so that all files necessary to build are in the same location. The default is disabled.
• Show virtual filesystem drives sets whether virtual drives (from 'A:' to 'Z:') are shown. This allows configuration of files on non-system drives.
• Internet Explorer snapshot compatibility mode sets whether special configuration settings should be used when taking a snapshot of Microsoft Internet Explorer. The default is disabled.
• Use hardware acceleration to optimize rendering sets whether Turbo Studio is rendered using hardware acceleration. This will increase the rendering performance but in some cases this may result in rendering defects. The default is enabled.
• Use dark color scheme sets wether Turbo Studio uses a dark or light color scheme. The default is dark color scheme.

Home Ribbon Bar

Capture

• Start Capture button is to start a real-time capture of your application installation. This is the recommended method of creating container configurations. The feature is only available on Windows 10+ and Windows Server 2016+ and does not support applications that are required to reboot the machine during the installation process.

Snapshot

• Capture Before button is to capture the machine state before you install your application for a snapshot.
• Capture and Diff button is to capture the machine state after you install your application for a snapshot.

For more information on the snapshot process, see Snapshot documentation.

Build

• Build button is to build your container image output.
• Build and Run button is to build your container image output and then execute it for testing purposes.
• Run and Merge button builds your container image and then executes it within the Turbo Client Runtime environment. Any changes made while inside the container environment will be added back to the configuration after the application is shutdown. This can be used to quickly set defaults in your container image.

Startup

• Startup File button shows the Startup File dialog where paths to applications can be set to be executed when the container starts.

Output

• Output File field is the name of the file that is created when your container image configuration is built. The Browse... button allows this field to be set.

• Project Type dropdown allows you to set the type of output to generate. The following values are possible:

  • Layer (SVM) is a bare Turbo container image file that can be pushed to Turbo.net Hub, used in Turbo Server, imported into the Turbo.net Client Runtime environment, or used as a dependency in another project.
  • Standalone/ISV Application (EXE) is a standalone executable file with no dependence on the Turbo.net Client Runtime or Turbo.net Hub. This output type requires an Enterprise or ISV license for Turbo Studio.
  • Portable Application (EXE) is a packaged executable file which contains the Turbo.net Client Runtime components and integrates with the Turbo.net Hub or an on-premise Turbo Server.

  At runtime, you may see different behavior between Standalone and Portable applications. This is because they use a different set of default runtime settings which can change how the application behaves.

  • The default isolation settings will be different. This will change how the application can interact with the software on the native machine. Standalone executables will have the isolation settings exactly as you see it in the xappl and in Turbo Studio. Since Portal applications are built to run on the Turbo.net Client Runtime, its isolation settings will be a combination of the image configuration and the isolation mode which can be dynamically assigned at runtime. The default mode is full isolation which will override merge or writecopy isolation settings in the image configuration. You can change the isolation mode for a Portable application with the --isolate parameter. Setting the isolation mode to merge will defer isolation settings to those assigned in the image configuration. There is no way to change the base isolation mode in Standalone applications.
  • The default VM settings flags are also different between the two application types. Standalone executables will only have those that are defined in the image configuration. Portable application will additionally contain these settings: ExeOptimization, SpawnComServers, IsolateWindowClasses, SuppressPopups, ForceWriteCopyIsolation, MergePathEnvVars, MergeVmSettings, DumpStdStreams, InheritFolderMaps, and ForceEnvironmentVariablesWriteCopyIsolation. See xappl reference for more information on these flags.

Publish

• Publish to Turbo Server button allows an output container image to be pushed directly to the Turbo.net Hub or a Turbo Server instance.
• Publish to Local Repository button allows an output container image to be pushed to the local Turbo.net Client Runtime repository.

Advanced Ribbon Bar

Tools

• Platform Merge button allows a configuration to be quickly created which merges different configurations that were built for specific platforms (ex: Windows 7, Window 10, etc). The merged configuration is optimized by putting files and registry keys which are shared across platforms into a shared layer.
• Architecture Merge button allows a configuration to be quickly created which merged different configurations that were built for different platform architectures (ex: x86, x64).
• Debugger button opens the Turbo Studio Debugger tool.
• Factor Configuration button splits a standalone executable configuration into two configurations, a launcher configuration and a data configuration. The launcher configuration only contains metadata and settings while the data configuration contains all the file and registry references. This is useful for large applications which generate large executable files (.exe) in order to mitigate performance consequence of Windows scanning the .exe on launch.

Import

• Import Configuration button allows an application package to be imported from a file (.ini, .msi, .axt, .appv), the turbo.net hub, or the local image repository. For more information, see Import Configuration.
• Import Registry File button allows a registry file (.reg) to be imported into the current layer of the configuration. The registry file can be generated by exporting a key from the Windows Registry Editor (regedit).

Side Navigation

• The layers dropdown list shows all the layers that are defined in the configuration. Edit... to create, remove, modify the order in which they are applied, and define conditions on layers.
• The Filesystem pane displays the application virtual filesystem and enables addition and removal of virtual files and directories.
• The Registry pane displays the application virtual registry and enables addition and removal of virtual registry keys and data values.
• The Settings pane enables configuration of container metadata, startup image, startup/shutdown shims, and process configuration options.
• The Layers pane enables configuration of external container components. This is for use with the Standalone Executable project type. Layers which are to be used with the Turbo Client or Turbo Server should define dependencies using those platforms.
• The Desktop pane enables configuration of the MSI setup package, shortcuts, and other shell integration options.
• The Licensing pane enables configuration of application expiration options.
• The Security panel enables configuration of application security options.
• The Network pane enables you to configure container proxy and DNS settings.

Note: Turbo Studio users are responsible for any third-party licensing compliance for redistributable components included using virtualization.

Filesystem

Turbo Studio enables you to embed a virtual filesystem into your executable. Embedded files are accessible by your Turbo-processed application as if they were present in the actual filesystem. Virtual files are isolated from the host device. Virtual files do not require security privileges on the host device regardless of whether the virtual files reside in a privileged directory. Because virtual files are embedded in the application executable, shared DLLs do not interfere with those installed by other applications on the host device.

In the event of a conflict between a file in the virtual filesystem and a file present on the host device, the file in the virtual filesystem takes precedence.

Note: When running a container on Windows 7, the All Users Directory\Application Data and All Users Directory root folders will map to the same folder at runtime. To prevent one setting from overriding another, verify that the isolation settings for these folders are the same.

Isolation Modes

Folders may be containerized in Full, Merge, Write Copy, or Hide mode.

• Full: Full mode is used when the directory is required to be completely isolated from the host device. Only files in the virtual filesystem are visible to the application even if a corresponding directory exists on the host device. Any writes to files are redirected to the sandbox data area.
• Merge: Merge mode is used when the directory is required to have some level of interaction with the host device. Files will be visible from both the virtual filesystem and the host device. Any writes to files which are new or already exist on the host device will pass through and be written to the host device. Any writes to files that are in the virtual filesystem will be written to the sandbox data area.
• Write Copy: Write Copy mode is used when the directory is required to have visibility to files on the host device but cannot change them. Files will be visible from both the virtual filesystem and the host device. Any writes to files are redirected to the sandbox data area.
• Hide: Hide mode is used when a directory on the host device could interfere with the application's ability to run properly. The application will receive a File Not Found error code whenever an attempt is made to read from or write to files in the directory even if the files exist on the host device.

Tip: To apply selected isolation modes to all subfolders, right-click on the folder, choose Isolation, select the checkbox for Apply to Subfolders, then select OK.

File Attributes

• Hidden: Files and folders can be hidden from shell browse dialogs and other applications. This is used to prevent internal components and data files from being displayed to the user. To hide a file or folder, select the checkbox in the Hidden column adjacent to the desired file or folder. Note: The Hidden Flag is NOT the same as the Hide isolation mode. Enabling the Hidden Flag prevents a file or folder from displaying in browse dialogs or from directory enumeration APIs; it does not prevent the application (and potentially the end-user) from accessing the folder or file contents by direct binding. To prevent the file or folder from being found by the application, enable Hide isolation mode.
• No Sync: This feature only applies to containers that are delivered and managed by Turbo Virtual Desktop Server. By default, files in the virtual filesystem can be synchronized to a user's Turbo account. This enables the application state to be maintained across different devices that are Turbo enabled. If there are folders in the virtual filesystem that should not be synchronized and remain only on the local device, select the checkbox in the No Sync column next to the desired file or folder. This setting is managed on a folder level and applies to all files within that folder.
• Read Only: Flagging files and folders as read-only prevents the application from modifying the file or folder contents. To make a file or folder read-only, select the checkbox in the Read Only column next to the desired file or folder.
• No Upgrade: By default, files in the virtual filesystem can be upgraded with patches (refer to "Updating Registration Settings" in the Register containers in the Windows Shell section for more information). If there are files in the virtual filesystem that should not be upgraded, such as user data files, select the checkbox in the No Upgrade column next to the desired file or folder.

Registry

Turbo Studio enables you to embed a virtual registry into your executable. Embedded registry keys are accessible by your Turbo-processed application as if they were present in the actual registry. Virtual registry keys are isolated from the host device. Virtual registry keys do not require security privileges on the host device regardless of whether the virtual files reside in a privileged directory. Because virtual registry entries are embedded in the application executable, other applications are unable to disrupt application execution by inadvertent modification of registry entries.

The Classes root, Current User root, Local Machine root, and Users root folders correspond to the HKEY_CLASSES_ROOT, HKEY_CURRENT_USER, HKEY_LOCAL_MACHINE, and HKEY_USERS keys on the host machine.

Registry string values can include well-known variables such as @WINDIR@, @SYSWOW64@, @PROGRAMFILESX86@ and @PROGRAMFILES@.

In the event of a conflict between a key or value in the virtual registry and data present on the host device registry, information in the virtual registry takes precedence.

Isolation Modes

Keys may be containerized in Full, Merge, Write Copy, or Hide mode.

• Full: Full mode is used when the key is required to be completely isolated from the host device. Only values in the virtual registry are visible to the application even if a corresponding key exists on the host device. Any writes to values are redirected to the sandbox data area.

• Merge: Merge mode is used when the key is required to have some level of interaction with the host device. Values will be visible from both the virtual registry and the host device. Any writes to values which are new or already exist on the host device will pass through and be written to the host device. Any writes to values that are in the virtual registry will be written to the sandbox data area.

• Write Copy: Write Copy mode is used when the key is required to have visibility to values on the host device but cannot change them. Values will be visible from both the virtual registry and the host device. Any writes to values are redirected to the sandbox data area.

• Hide: Hide mode is used when a key on the host device could interfere with the application's ability to run properly. The application will receive a Key Not Found error code whenever an attempt is made to read from or write to values in the key even if the values exist on the host device.

  Tip: To apply selected isolation modes to all subkeys, right-click on the key, choose Isolation, select the checkbox for Apply to Subkeys, then OK.

Key Attributes

• No Sync: This feature only applies to containers that are delivered and managed by Turbo Virtual Desktop Server. By default, keys and values in the virtual registry can be synchronized to a user's Turbo account. This enables the application state to be maintained across different devices that are Turbo enabled. If there are keys in the virtual registry that should not be synchronized and remain only on the local device, select the checkbox in the No Sync column next to the desired key. This setting is managed on a key level and applies to all values within that folder.

Setup Capture

The Setup Capture allows an application install to be recorded in order to create the container configuration. This is the recommended method of creating container configurations. The feature is only available on Windows 10+ and Windows Server 2016+ and does not support applications that are required to reboot the machine during the installation process. Use Snapshot if these requirements cannot be met for your application.

Note that Setup Capture does not capture changes to drives other than the system drive.

Below is a walkthrough of the steps required to setup capture ShareX.

Using Setup Capture to Capture the Application Install

Launch Turbo Studio and open a blank configuration by clicking File > New.

Click Start Capture and select an empty folder to store the application files and configuration file.

Perform the ShareX installation as normal.

ShareX requires .NET 4.7. Add a .NET 4.7 layer to this application using one of the following methods:

• Install .NET 4.7 during the Setup Capture
• Add a .NET 4.7 layer to the application as a Component in Turbo Server

Once the installation is complete click Stop on the recording dialog in Turbo Studio.

The Setup Capture process records all running process on the system. Therefore it will likely record processes that are not necessary for this application image. Right-clicking on a process name and selecting Copy Captured Paths will copy all the paths that will be captured on the clipboard. This can be used to confirm that a process is necessary. For ShareX, select only the ShareX.exe and ShareX-13.2.1-setup.exe processes on the progress selection dialog and click OK.

After the recording and process selection steps are complete Turbo Studio will gather the necessary files and registry settings into the selected folder.

Click Browse next to the Output File field and select a folder and filename to save the build output. The Output File is generally saved in the same folder as the application files and registry settings that was selected above. Click File > Save to save the application configuration.

Click Build and Run to build the application at the Output File location selected above and do a test launch of the application.

See Deploying for information about deploying containers on the Turbo platform.

Snapshots

Many applications require combinations of filesystem and registry entries. To facilitate containerization of these applications, Turbo Studio can snapshot application installations and automatically configure them based on modifications made to the host system during setup.

If possible, the Setup Capture method of container creation should be used instead of snapshotting.

Note that Snapshot does not capture changes to drives other than the system drive.

Process

Snapshots use before and after images of the host machine to determine configuration:

• Before: This snapshot is taken prior to installing the application and captures the state of the host device without the target application installed.

• After: This snapshot is taken after installing the application and captures all changes to the host device during application installation. Turbo Studio then computes the changes between the before and after snapshots, and inserts these changes into the configuration.

Complete the following steps to use the Snapshot feature:

1. Prepare the host device: Install Turbo Studio onto a clean machine. IMPORTANT: Taking a snapshot on a base OS image with application components already installed will result in an unreliable snapshot capture.

2. Capture the before image: Select Capture Before on the Virtual Application tab on the ribbon bar. This may take several minutes to complete.

3. (Optional) Save the Before Snapshot: Saving the before snapshot enables you to skip this step in subsequent applications from the same clean machine. Select the down arrow underneath Capture Before and choose Save Snapshot. Turbo Studio automatically saves the most recently captured before snapshot. This snapshot is reset once the Capture and Diff is complete.

4. Install your application: Install the appication as you would normally. If the application setup requests a reboot, save the Before Snapshot, then proceed with the reboot.

5. Capture the after image: On the Virtual Application tab on the ribbon bar, select Capture and Diff. This captures the After Snapshot, computes the deltas between the two snapshots, and populates the image with the delta entries.

6. Review the filesystem and registry entries: Remove any files or settings not required for proper execution. Removing unused entries will reduce image size. Be careful to avoid removal of required resources, as it will cause your image to fail to function properly.

Capture Application Updates via Snapshot

Container updates can be captured within Turbo Studio via snapshots.

Complete the following steps to capture an update via snapshots:

1. Install the native version of the application on a clean machine.

2. Select Capture Before.

3. Install necessary updates to the native application.

4. Select Capture and Diff to create the after snapshot. This captures the deltas between the original and updated versions.

5. Set the Project Type to Component, then select Build to create the SVM.

This process only captures changes between the original executable and installed updates. You can then apply the resulting SVM to the original virtual package.

Best Practices

• Performing the snapshot on a clean machine ensures that all dependencies are installed by the application setup. Installing on a machine with existing components can inadvertently include dependencies in the before snapshot and exclude them from the final output.

• If you configure a clean machine using whole-machine virtualization tools such as Microsoft Virtual PC and save a before snapshot based on this image you can snapshot many distinct containers in rapid succession by reverting the whole-machine virtual state and using the same before snapshot.

• Most applications should be configured by performing the snapshot on the earliest (least common denominator) target operating system. A small number of applications may require multi-platform merge for successful deployment across all operating system variants.

• When selecting a folder to save the Capture and Diff snapshot, select Make New Folder in Turbo Studio. This folder will not be included in the snapshot. If the folder is included in the Capture and Diff snapshot, remove it using the Filesystem tab.

• Before beginning the pruning process, save a backup of the Capture and Diff snapshot (snapshot.xappl). Revert to the original Capture and Diff snapshot in the event of an error.

• Run and use the native application to understand what registry keys and folders are updated at runtime. This will help determine the proper isolation settings for folders and registry keys.

• To determine if a folder should be set to full isolation or merge isolation, decide if the user would want access to files created within that folder outside the container environment. If yes, the folder should be set to merge, if no, full.

• Remove uninstall shortcuts during the pruning process.

Configuration

The following discusses the many configuration features available in Turbo Studio. These features allow you to edit and customize the settings for an image or virtual application configuration.

Process Settings

• Command line arguments will be passed to the startup file when the container is executed by default. You can override and specify a fixed set of command line arguments to pass to the startup executable for Standalone Executable project types. Command line arguments can also be assigned directly to the startup files in the Startup Files dialog.
• Working directory allows you to specify what the default working directory of startup files will be. Options include the directory that the startup file is in (default), the directory that the container was executed from (useful for tooling that might take relative paths to files as parameters), or a specific location.
• Target architecture controls how wow64 redirection functions inside the virtual environment. If the configuration file was generated from a snapshot of an x86 machine then this should be set to x86. Otherwise this should be left as x64.
• Minimum required OS specifies the minimum required version of the Windows Operating System where the container will be allowed to run. If the requirements are not met then an error dialog is shown on container start.
• Application type specified which Windows subsystem is used for executable project types. This can either be GUI, Console, or Inherit. Inherit will determine the value for this field from the startup file executable.
• Spawn child processes within virtualized environment sets the default behavior for how native executables (those that are not inside the container configuratino) are handled in the container. They can either be spawned inside the container and therefore be subject to the configuration of the container environment, or they can be spawned outside the container and therefore not have access to files or registry inside the container.
• Spawn COM servers within virtualized environment specifies whether COM servers in the container are isolated from the native environment.
• Child process exception list is a list of executable files that will be excluded from the default spawn behavior. This is useful if certain system processes need to be spawned outside the container while everything else is kept inside (ie. print spooler, etc).
• Compress payload makes it so that the files stored in the container at build time will be compressed. This can greatly reduce the size of the container image or executable file. Enabling this setting will decrease performance as files must be decompressed at runtime and those over 1MB will be copied into the sandbox, even for read operations.
• Use Windows DLL loader allows the container runtime environment to use the Windows loader for executable file types (.dll and .exe). This has the advantage of increased compatibility but increases the filesystem usage requirements as all executable files must be faulted into the sandbox before they can be loaded rather than loading directly from the container image.
• Trace process starts in debug output will display a message in the debug output stream whenever a process is started. The debug output stream can be viewed with dbgview.
• Enable Turbo command line arguments makes it so that the container runtime parameters can be used (ie /XEnable, /XShellEx, etc). See building standalone executables for more information.
• Enable startup executable optimization makes it so that if there is a single startup file, then it will be run directly rather than being spawned from the virtual machine boostrap executable. This will reduce the number of processes that are required to start the container.
• Shutdown process tree on root process exit makes is so that all child processes of the startup file will automatically be killed when the startup file exists.
• Enable Chromium suport allows support for the Chromium sandbox used by Google Chrome, Microsoft Edge, and other applications and components.

Sandbox Settings

• Sandbox location field specifies where the container's runtime sandbox will be stored during execution. This only applies to Standalone Executables and containers which are started using the Turbo Client Runtime will override this with its own behavior. This path can use the folder root tokens (ie @DESKTOP@, @APPDATA@, etc) as well as the following metadata variables: @TITLE@, @PUBLISHER@, @VERSION@, @WEBSITE@, and @BUILDTIME@. The container build time is in a format similar to 2008.02.01T08.00. With the exception of the @BUILDTIME@ variable (which is set automatically), these variables are based on the values specified in the Properties tab of Settings panel.
• Stubexe cache location field specifies where the container stubexe files are stored. By default this is blank and they are stored in the sandbox. Stubexe files are generated .exe files that map to executables which are launched inside the container. In some environment, stubexe files require exclusions for security or anti-virus software so it can be convenient to store them in the same place to reduce the exposure and complexity of exception rules.
• Cache location allows you to specify a location to store temporary container files. By default thse are stored in the user's temp directory.
• Environment variables allows to define custom environment variables that will be seen by applications inside the container. Options exist to control how variables are merged or overridden inside the container.
• Virtual services allow Windows services to be defined inside the container. Windows services are specialized applications that run in the background. They are typically responsible for providing system services such as database services, network traffic handling, web request processing, and other server functionality. Many applications install and require specific services in order to function properly.
• Delete sandbox on application shutdown makes it so that the sandbox folder is removed once the container stops. Enabling this setting will increase startup time as there are many files that are cached in the sandbox between runs.
• Enable window class isolation enables isolation for window classes. Window classes are a fundamental set of attributes that are assigned to an application window in the Windows operating system. These are often used to detect the presence of applications that are already running.
• Enable clipboard isolation enables isolation of the clipboard, preventing copy/paste operations from crossing container boundaries.
• Enable process name isolation augments process names with the sandbox hash. This can be used for some applications which look for process names to enforce side-by-side constraints.
• Enable non-system drive isolation hides local drives other than the system drive where the operating system is installed.
• Enable network share isolation hides network shares on the system.
• Enable DDE message isolation prevents Dynamic Data Exchange (DDE) messages from crossing container boundaries.
• Force read-share files makes it so that all files in the container are opened in a way that doesn't block other processes from opening for read.

Metadata Settings

• Standard Metadata fields include information such as product title, publisher, description, icon, web site URL, and version. By default these values are inherited by the startup file and will be displayed here. To override any of the values, uncheck the Inherit checkbox. Leave the value as @INHERIT@ for any values that should continue to be inherited.
• Custom Metadata can be used by specialized external executable viewer applications, inventory scanners, and other asset and licensing management systems. For information on custom executable metadata, consult the Microsoft Windows Software Development Kit.

Startup Settings

• Splash Image can assign an image that is displayed while the container is loading. Startup images improve application branding and are useful when the application requires several seconds to initialize.
• Transparency key enables the splash image to contain transparent regions which can improve the visual effectiveness of your splash.
• Display splash until assigns how the splash will be shown, either for a specific amount of time or until the first application window appears. The splash image can always be dismissed by clicking it with the mouse.
• Shims and Scripts settings allow you to run custom code to configure or clean up environments before and after a container is executed. See Startup/Shutdown Scripts and Shims for more information.
• Startup script assigns a path to a script that is executed when the container starts.
• Shutdown script assigns a path to a script that is executed when the container stops.
• Terminate container with non-zero exit code sets whether the exit code from the startup script is honored. If enabled, any non-zero exit code from the startup script will abort the container start (ex: exit /b 1). If disabled, the exit code from the script will be ignored. The default is disabled.
• Run scripts as admin user sets whether the scripts are to be executed in an administrator context. If enabled, the container startup will show a UAC prompt if the user is not already an administrator. The default is disabled.
• Startup shim DLL assigns a path to a shim DLL that is executed when the container starts.
• OnInitialize parameter is a string value which is passed to the startup shim.
• Shutdown shim DLL assigns a path to a shim DLL that is executed when the container stops.
• OnShutdown parameter is a string value which is passed to the shutdown shim.

Layers Settings

The Layers panel allows external image layers (SVMs) to be merged into the configuration at build time. While this can be used for any of the project types, it is primarily used for standalone executable projects.

If the image output from the configuration is being used with the Turbo Client or Turbo Server then dependencies should be managed through those platforms directly and not by using external layer settings here.

External layers which are imported for use as build-time dependencies are copied to a local dependency cache. If the configuration is to be built on another machine or by a different user on the same machine, then the external layers must be imported again before the build will succeed.

External layers in the local dependency cache are loosely matched by name and version. If the external layer changes in any way (ex: isolation setting, new files, etc) but the name or version are not updated, then the new version will not be used unless it has been re-imported in all build environments.

For standalone executable project types, runtime patch layer dependencies can be set by clicking the Patches... button.

Desktop Integration Settings

The Desktop panel allows shortcuts and file associations to be defined which are used when the container is installed to the machine via Turbo Client install, installi, or subscribe commands, from the Turbo Server portal, or with MSI deployments.

See Desktop Integration for more information on shortcut and file association configuration.

Licensing Settings

• Disallow execution after number of days sets a hard limit on how many days the container can be executed. Useful for applications for trials or proof-of-concept.
• Disallow execution after date sets the date at which point the container no longer executes.
• Expiration message is the error message which is displayed when the container expires.
• Display warning with number of days left sets the number of days prior to expiration that a warning message is shown when the container starts.
• Warning message sets the message that is displayed when the warning is shown.
• System clock uses the machine time to determine expiration. If the machine time is modified then the expiration time can be affected.
• Web server clock uses the URL specified in the Web server URL field to determine the time used for expiration settings. This removes the possibility of the end-user changing their system time settings to extend the expiration but requires a network connection to the specified web server.
• Disallow execution if unreachable will prevent the container from executing if the web server clock URL cannot be reached.
• Warning message sets the message that is displayed when the unreachable warning is shown.

Security Settings

• Required domain specifies the name of an Active Directory domain where the container must be executed. If the container is attempted to be executed off the domain then an error message will be displayed.
• Required group membership is a list of Active Directory groups to which the user executing the container must belong. Group names are semi-colon delimited.
• Emulate elevated security privileges makes it so that the processes in the container think they are running as admin when they are not. Since processes are running in a sandbox, writes to secure locations won't require administrative access.
• Trim elevation from manifests removes application manifest entries which result in UAC prompts. Useful if the elevation is no longer necessary because write operations to system locations are only in the container sandbox.
• Always launch child processes as current user makes it so that any processes spawn inside the container will inherit the current user's account privileges rather than any custom privileges that the parent process might assign.
• Virtual environment is read-only makes it so that all write attempts to files inside the container will return access denied errors.
• Enable DRM compatibility allows some DRM software (ie Armadillo variants) to function inside the container.
• Enable DEP compatibility hides Data Execution Prevention (DEP) settings on modern operating systems which can allow older applications to run in a container. Be aware of your company security policies before enabling this setting.
• Enable FIPS compatibility hides the container from any FIPS rules enforced on the machine. Useful for legacy applications which cannot be made FIPS compliant. The application security must be ensured by other means.
• Enable AppLocker DLL rules compatibility disables AppLocker DLL rules for the container applications. The application security must be ensured by other means.

Proxy Settings

• Proxy TCP connections enables proxy settings for all TCP network traffic.
• Proxy UDP connections enables proxy settings for all UDP network traffic.
• Proxy server sets the proxy server to use for the specific protocols.
• Protocol specifies the proxy protocol to use. Valid options are SOCKS5, SOCKS4, HTTPS, and HTTP.
• Authentication specifies how the container authenticates with the proxy server. This can either be anonymous or plain-text username/password.

DNS Settings

• Hostname or IP Address specifies the source name/address to map to another location.
• Redirect specified the target IP address where the source address is mapped to. Redirecting to IP 0.0.0.0 will make the source name/address unreachable.

IP Restriction Settings

• Route is the hostname, IP address (v4 or v6 format, CIDR notation for subnet mask), or pattern to which the rule applies.
• Type sets whether the matching routes will be allowed or denied. All routes are allowed by default. To change this default add a route for "*" set to Deny.

Desktop Integration

A container image can be configured for integration into your desktop environment using custom shortcuts or file associations. Container images can be deployed to a desktop with the Turbo Client using install, installi, or subscribe commands or through the Turbo Server portal. Standalone executables can be deployed using a Microsoft Installer (MSI) file.

If the configuration was created using Setup Capture or Snapshot then shortcuts and file associations will automatically be defined from the values that were discovered.

MSI Configuration

The MSI panel allows configuration of Microsoft Installer output files. This is only visible for standalone executable project types. The MSI will only install the standalone executable and execute it via the shortcuts and file associations that were defined.

• Output location specifies the location where the MSI file will be saved when built.
• Automatically generate MSI after successful application build will cause Turbo Studio to automatically build a new MSI whenever a new EXE is built.
• Product Info properties will be applied to the installation record in Programs and Features or Add/Remove Programs list.
• Install application for All Users controls whether the application is installed to a user's Application Data directory or Program Files. If enabled, the MSI will require administrative privileges to install.
• Application folder allows customization of the location where application files will be installed.
• Automatically upgrade earlier application versions will update the installation record, shortcuts, and file associations that were created with previous versions of the MSI. The Product Version field must be updated for this to be applied.
• Allow side-by-side versions of the same application will append to the installation record, shortcuts, and file associations that were created with previous versions of the MSI. The Product Version field must be updated for this to be applied.
• Extended Properties specifies additional property values that are displayed in the installation record.

Shortcuts

Defines that shortcuts that are created when the container is installed to a device. Shortcuts can be created on the desktop, in the programs menu, or in the SendTo folder.

• Name specifies the name of the shortcut that is created.
• Target specifies the application from the startup file list that is executed when the shortcut is clicked.
• Edit List... button brings up the startup file dialog to edit the available startup files.
• Arguments specifies that command-line parameters that are passed to the target.
• Show As specifies how the application is shown on launch. Options are Normal, Minimized, and Maximized.
• Description specifies the description of the shortcut that is displayed on hover.
• Browse button allows the selection of an icon file to be assigned.

ProgIDs

A ProgID (short for PROgrammatic IDentifier) is the mechanism in Microsoft Windows where actions (known as verbs) can be defined for specific file types.

• ProgID specifies the name of the ProgID (ex: "txtfile").
• Description specifies the friendly name of the ProgID (ex: "Text Document").
• Icon... assigns the associated icon file.

Verbs

Verbs define that actions that can be performed on a file type associated with a ProgID. These verbs will show in the context menu when right-clicking on a file.

• Verb specified the name of the verb. Common verbs include Open, Edit, and Print.
• Default indicates that this verb is the default action if the file type is opened (double-clicked or pressed enter key).
• Command is the friendly name of the verb that will be seen in the context menu for the file.
• Inherit uses the behavior defined in the virtual registry for the verb. If unchecked then can set the behavior manually.
• Target is the application from the startup file list that is executed.
• Arguments is the additional parameters to pass to the target application. The "%1" token is replaced by the path to the file being acted upon. Take care to quote this token appropriately so that paths that contain spaces will be handled correctly.

Extensions

The Extensions list defines file types and their associated ProgIDs.

• Extension specifies the file extension (ex: ".txt").
• ProgID specifies the name of the ProgID that was defined with associated verbs to act on the file type.
• MIME Type specifies the MIME type label to apply to the file extension. This field is optional.

MSI Example

Here we will show the steps required to configure a simple container to be deployed via MSI with shortcuts and file associations.

Start by creating an empty container configuration file. Add "c:\windows\syswow64\notepad.exe" from your machine to the @SYSWOW64@ directory in the Filesystem panel. Set the startup file to @SYSWOW64@\notepad.exe, set the project type to Standalone/ISV Application, and set the output file location. Save the configuration file.

Go to the Settings panel. By default the metadata will be inherited automatically from the startup file.

In our case, we will want to change some of these values to something more appropriate. Unselect the Inherit properties checkbox. Set the Product Title field to "Notepad Container".

Note that the custom value of the Product Title field is shown in the Open With... menu in Windows when file associations are configured. If you choose to inherit metadata then the value shown may not be what you want. To override what is displayed in the Open With... menu while still inheriting the other values, click the Custom Metadata... button and add the FileDescription field.

Go to the Install panel. Set the location where the MSI output will be written. Assign Product Info values. These values affect where the container files will be deployed on the machine and will show up in the uninstall entry on the machine where the MSI is installed.

If the container is to be installed for all users on the machine, then select the Install application for All Users checkbox. Note that this will require administrative privileges to install.

You can control how different versions of the same container MSI are handled. They can either be allowed to run versions of the container side-by-side or upgrade existing versions. Note that this is controlled by the Product Version field on this panel and not by the container version metadata on the Settings panel. Also note that for this to work properly, the MSI version must be changed inside Turbo Studio and not updated in an external editor.

Now we will add a shortcut that gets created on the desktop. Click on Desktop in the Shortcuts tree. Click Add Shortcut.... Set the name of the shortcut as it will appear on the desktop, in our example we will use "Notepad Container". The Target dropdown list will show all available startup files that can be executed by the shortcut. If there is something that is not included here, click the Edit List... button to add a new startup file for it. Select the icon to use for the shortcut and press ok.

Next we will add a file assocation to allow this container to be easily used to open .txt files from the Windows shell. Click on ProgIds and then Add ProgId.... A ProgId is a programatic identifier that the Windows Shell uses to associate an application with a file type. We will add one here for textfile which is the ProgId for all text file types. You can also assign an icon which will be used by associated files.

Next we will define actions that are available for the file type from the Windows context menu (when you right-click on a file). Common verbs include "open", "edit", or "print" but you can define any that you wish. Click on the newly added textfile ProgId and click the Add Verb... button. Set the verb name to "open" and check the Default box. Default verbs will be used when a user double-click the file. Set the Command field to what the user will see in the context menu.

If you created your container from a snapshot or otherwise defined the file association settings in the virtual registry, then you can select the Inherit checkbox to use that configuration. Otherwise, set the Target to a startup file and specify the arguments. In most cases you will want to pass the selected file as a parameter to the application so that it can be opened. Use %1 as a placeholder for the selected file path. Make note to properly quote this value as paths can contain spaces that may be incorrectly parsed by your application.

The final step is to define a file extension that will use this new ProgId. Click on Extensions and then on Add Extension.... Set the Extension to ".txt" and ProgId to "textfile". MIME Type is optional.

Now you're done. Save the configuration file and build the container. When the build completes, go to the Install panel and click the Build MSI button to produce the MSI package for the container. Copy the MSI to a test machine and run it.

After installation is complete, you will notice that the shortcut that we configured is now on the desktop.

You will notice, however, that the file icon is the default and not what we assigned. This is because Windows 10+ doesn't allow file associations to be changed except by direct user input to prevent malware attacks. Since there were changes to the system file associations, Windows will prompt you the next time the file type is opened to confirm which application should be used. You will notice that "Notepad Container" is now in the list.

Select Notepad Container from the list and check Always use this app to open .txt files. Press OK. Now the file will be permenantly linked to your container. You will notice also that the icon is now updated to that of the ProgId icon that we selected earlier. In addition, you will now see all your defined verbs in the file's context menu.

In the Windows Programs and Features panel, you will find an entry for our Notepad Container deployment. Uninstalling it from here will remove all shortcuts and file associations that were added.

Import Configuration

The following section details the Import Configuration feature available in Turbo Studio. Import Configuration is used to import application packages in various formats into a Turbo Studio configuration that can be built and deployed to your endpoints.

Supported application package formats are: Microsoft App-V package (.appv), ThinApp configuration (.ini), Microsoft Installer (.msi), and ZENworks application package (.axt).

Import Wizard

To import an application package into Turbo Studio, please follow these steps:

1. Open Turbo Studio and click on the Advanced tab in the task bar
2. Click the Import Configuration button
3. Select File import type and then click Next
4. Browse to the Configuration file to import and then click Next
5. Browse to the Destination folder to where the output will be stored and then click Next
6. Wait for the import process to complete. This may take a few minutes.
7. Review the import summary for any warnings and then click Finish

Once the import is complete, the configuration will be saved to your destination folder and opened in the Turbo Studio editor.

App-V Import

Support for App-V packages is currently in beta and is available in Turbo Studio 22.9+.

To import an App-V package, follow the import wizard to the Select source configuration file step and select an .appv file. Once the import completes, the import summary will display a list of Turbo configuration files that were created as part of the import process. These Turbo configration files include:

• MyApp.xappl: The base configuration file that contains all virtual files, virtual registry objects, application entry points, and metadata from the App-V package.
• MyApp_Config.xappl: The extensions configuration file that contains all extension points from App-V package. This include shortcuts, shell extensions, file assocations, and other extension points contained in the App-V package manifest.

Next it is recommended to open each .xappl file in Turbo Studio and click Build to create the Turbo images. You may also Build and Run the base configuration to confirm that the application launches correctly.

The following sections describe how to import dynamic configurations and how to deploy the newly built Turbo images to users.

Dynamic Configurations

Support for App-V dynamic configurations is currently in beta and is available in Turbo Studio 22.11+.

Dynamic configurations allows package publishers to customize how their packages run for users or machines without rebuilding the entire package. Turbo supports this same functionality through layering.

When importing an App-V package, the importer will look for any .xml files in the same directory that are valid dynamic configurations by checking their root element tag name and xmlns. Any valid dynamic configurations will be imported and the following Turbo configuration files will be output:

• MyApp_UserConfig.xappl: A user configuration file corresponding to each user configuration file located in the App-V package folder.
• MyApp_DeploymentConfig_User.xappl: A deployment user configuration file corresponding to each deployment configuration file located in the App-V package folder. This includes all user configurations from the deployment configuration.
• MyApp_DeploymentConfig_Machine.xappl A deployment machine configuration file corresponding to each deployment configuration file located in the App-V package folder. This includes all machine configurations from the deployment configuration.

It is recommended to open each .xappl file in Turbo Studio and click Build to create the Turbo images.

Deploying imported App-V images

Turbo images created from the App-V import process can be deployed by running the installi command. Different user and machine configurations can be achieved through the use of layering.

For example to deploy an imported App-V package with default extensions to the current user, the extensions image can be layered on top of the base image:

turbo installi MyApp,MyApp_Config

Once installed, the current user will see shortcuts, file assocations, shell extensions, and other extension points defined in the extensions image. Opening a shortcut, clicking a file with an matching file assocation, or clicking a shell extension will launch the application in the Turbo virtual environment.

We recommend using the following layer combinations to simulate App-V deployments:

• __MyApp,MyApp_Config__: Layers the base image with the default extensions. Equivalent to publishing the App-V package without dynamic configs
  

• __MyApp,MyApp_UserConfig__: Layers the base image with user extensions. Equivalent to publishing the App-V package a dynamic user configuration.
  

• __MyApp,MyApp_DeploymentConfig_Machine,app_DeploymentConfig_User__: Layers the base image with machine extensions. Equivalent to publishing the App-V package a dynamic deployment configuration.
  

• __MyApp,MyApp_DeploymentConfig_Machine,app_UserConfig__: Layers the base image with user and machine extensions. Equivalent to publishing the App-V package a dynamic user configuration and a dynamic deployment configuration.
  

For more information on deploying applications with Turbo, see Deploying to a Desktop.

App-V Import Known Issues

App-V packages may define multiple application entry points rather than a single startup file. If the App-V package defines a single application entry point then it will be set as the startup file in the Turbo configuration, otherwise no default startup file will be set and the user should select one manually in Turbo Studio after import.

Dynamic configurations registry key deletions are implemented in the Turbo configuration with Hide isolation. Any registry keys with Hide isolation will also hide native registry key of the same name. This differs from the App-V dynamic configuration which will only remove the registry key from the virtual registry.

UserScripts and MachineScripts are not imported automatically. Scripts with application startup and shutdown triggers may be added manually in Turbo Studio from the Settings > Startup > Scripts menu.

Known Issues

Some application package formats may include settings that are not available in the Turbo Studio configuration or vice versa. After importing application packages, the Turbo Studio configuration should be reviewed and tested.

For example, applications that require advanced settings such as Chromium Virtualization must be applied manually in Turbo Studio after import.

Standalone Executables

A popular option for organizations that have an existing endpoint management solution like LANDesk Management Suite ®, Microsoft System Center, or Novell ZENworks is to deploy containerized applications as standalone executables. These executables are built on the SVM architecture and work just like a container.

Deploying applications within containers is convenient for running different versions of applications like Internet Explorer 8 and 11 side-by-side on the same system.

To produce an executable output, set the Project Type to ISV Application in Turbo Studio. Executables can be deployed directly to the users device or to a network share and do not have any dependency requirements.

An enterprise license for Turbo Studio is required to enable executable outputs. Contact our sales team for more information.

Command Line Options

Standalone executables have many command line options to change settings at runtime. The following is a list of available options. Note that these are case sensitive and must be specified before any command line options to the application itself.

• /XEnv=VariableName=Value specifies additional environment variables. Multiple /XEnv arguments can add additional environment variables.
• /XLayerPath=c:\path\to\image.svm adds the given SVM into the virtual environment. Multiple /XLayerPath arguments can add additional virtual layers. Refer to 'Specify Additional SVMs for a Container' for more information.
• /XSandboxPath=SandboxPath specifies the path for the application sandbox.
• /XShellEx=Command specifies a shell execute command to launch from within the virtual application environment. This option overrides any startup files specified in the virtual application configuration. Only one /XShellEx argument can be specified.
• /XShellExVerb=CommandVerb specifies the verb to use in conjunction with the /XShellEx command. The default verb is OPEN.
• /XLogPath=LogPath specifies the destination path for generated log files (only applies to executables running in diagnostic-mode). This path can include a custom file name pattern (ex. /XLogPath=c:\logs\mylog*.log). The output directory must exist for the logs to be written.
• /XSpawnVmExceptions=ProcessExceptions specifies a semi-colon delimited list of processes to add to the child process exception list.
• /XRegRoot=c:\path\to\RegistryCacheRoot specifies an override to the runtime-registry-cache portion of the sandbox.
• /XEnable=Setting and /XDisable=Setting enables or disables specific process configuration options. These options include:
  • BootstrapWait
  • ChildProcAsUser
  • DeleteSandbox
  • DEPCompat
  • Diagnostics
  • DRMCompat
  • ExeOptimization
  • IndicateElevated
  • IndicateVirtualization
  • IsolateWindowClasses
  • NotifyProcStarts
  • ReadOnly
  • ReadShare
  • ShutdownProctree
  • SpawnComServers
  • SpawnVM
  • SuppressCollisionCheck

See VM Settings for details on the available settings.

• /XCollisionCheck=FALSE disables detection of multiple apps attempting to use the same sandbox at the same time. This should only be used to support legacy behavior.

Deploying Patch Layers

When you have updates or patches that must be deployed, Turbo Studio can be used to specify additional image layers (SVMs) to load dynamically at runtime. Turbo Studio provides two mechanisms to accomplish this. Both methods support path tokens (ie. @APPDIR@) and must specify the full path to the image dependencies.

Using Studio

One mechanism is to specify the SVM dependencies in Turbo Studio.

The patch dependency editor can be accessed by going to the Layers panel and then clicking the Patches... button.

The SVM Search Pattern field specifies the complete path to where patch image layers may be located. This can be a path directly to a specific SVM file or can be a wildcard pattern to dynamically discover SVM files to load. An example of using a wildcard in the search field is @APPDIR@\patches\*.svm. This search pattern will load any .SVM file found in the "patches" directory where the virtual executable is located. Care must be taken to avoid loading arbitrary .SVM files which happen to reside in the same location.

Multiple search pattern paths may be specified by seperating with a semi-colon. SVM files specified first in the list will take precedence over SVM files specified later in the list. If multiple SVMs match a search pattern through the use of the "*" wildcard, the SVM files are applied in reverse-alphabetical priority (ex: items in patch_002.svm would have higher priority than items in patch_001.svm).

The Required SVM Name list specifies which of the SVM files specified in the search pattern are required to execute the container. Wildcard characters are not valid for this and a specific path must be used. If the file is not found during application launch, an error will be reported and the launch will be aborted.

Using Command Line

Another mechanism is by using the /XLayerPath= command line option. This parameter takes a path to additional SVMs to load. This can be useful for dynamically creating container environments depending on other user settings. These runtime settings augment any which are built into the SVM.

An example of a specified SVM path using full path:

# look for 'patches.svm' in the same directory as 'virtual-app.exe'
> virtual-app.exe /XLayerPath=@APPDIR@\patches.svm

# look for 'patches.svm' in a specific location on the local machine
> virtual-app.exe /XLayerPath=c:\path\to\patches.svm

# look for 'patches.svm' on a unc share
> virtual-app.exe /XLayerPath=\\server\dir\patches.svm

An example of specifying SVMs from multiple locations:

> virtual-app.exe /XLayerPath=@APPDIR@\patches.svm /XLayerPath=@APPDIR@\officepatches.svm

An example using a path with wildcard:

> virtual-app.exe /XLayerPath=c:\path\to\patches\*.svm

This performs a wildcard match finding any files that match the pattern, such as 'c:\path\to\patches\patch_001.svm'.

Note: SVMs that are discovered by wildcard are applied in reverse-alphabetical priority. For example, items in 'patch_002.svm' have higher priority than items in 'patch_001.svm'.

Startup File Triggers

A container package can define several startup files. These can all be activated on launch or they can be configured to only be launched given a specified trigger. This is useful for suite applications (like Microsoft Office) where most of the container package is shared.

In Turbo Studio, the startup file triggers are managed in the 'Startup Files' dialog.

In this example, an application package is defined with three startup files; word, excel, and access. Any startup files that don't have a specific trigger or have Auto Start enabled will be launched by default. Any startup file that has a trigger (but not 'auto start') will not be launched unless the trigger is specified. Multiple startup files can have the same trigger to enable grouped launching.

To launch a startup file by its trigger, specify its trigger as the first parameter to the container .exe:

# to launch word
> virtual-app.exe WORD

# to launch access
> virtual-app.exe ACCESS

# to launch excel
> virtual-app.exe EXCEL

# to launch excel as the default
> virtual-app.exe

To create an easy-to-access shortcut for a trigger, right-click on your packaged executable and select Create shortcut. Then, right-click on the newly created shortcut and append the trigger to the Target field. Change the shortcut name and icon to differentiate the application entry point that will be launched when the user runs the shortcut.

Debugger

The Turbo Studio Debugger is a tool to aid in virtual machine log analysis. It contains many tools to filter and compare logs.

Getting Started

Containers can be executed in diagnostic mode to produce log files of the inner workings of the virtual processes in that container session. There is one log file, xclog[pid].txt_, for each virtual process in the container. These log files contain lists of all system calls that pass through the Turbo virtual machine as well as other process information. There will also be one network log file, xcnetwork[pid].txt_, for each virtual process in the container. These logs files contain information about all the network communications that take place. See Diagnostic Logs for more information on enabling diagnostic mode and log file formats.

Open the Turbo Studio Debugger by clicking the Debugger button in the Advanced ribbon menu in Turbo Studio or from the start menu shortcut.

In the Turbo Studio Debugger, open the session log folder by clicking on File > Open Session Log. Select the folder than contains the session logs and press Select Folder.

After the session logs are loaded, a tree view of the processes in the session will be presented to vizualize how the processes are related to each other. Double clicking the process will open the log file for that process.

After the process log is loaded, the full log is shown with options to filter and resolve the timestamps.

Options

There are several options that can be configured for the Turbo Studio Debugger.

Text Editor sets the editor to be used when opening a log in an external editor. The default is to use the system .txt editor. Turbo commands can be set here to use any tool from a turbo.net or turbo server hub (ex: turboplay turbo run npp/notepadplusplus --isolate=merge).

Text Comparison Tool sets the text compare tool to use whenever performaning diffs. The default is to use winmerge from the turbo.net hub.

Color Scheme sets the color scheme of the window. Setting this will also change the color scheme of the main Turbo Studio window after it restarts.

Save Workspace sets whether the current tabs are maintained between debugger sessions. Values include Never, Always, and Ask. The default is Never.

Session Log View

The session log view shows a tree of all the virtual processes in the session. Processes for the child nodes in the tree were launched from the processes for the parent nodes in the tree. If the session log folder contains logs from multiple container sessions then all sessions will be shown. If a process was started outside the virtual environment from a process inside, then this process will not have a log file (for example, if the process were excluded via the Child Process Exception rules). Double-clicking a node in the tree will open the log file in a new tab.

Selecting a node in the tree will show information about the log which is represented at the bottom of the debugger window. Information includes the process ID (or PID), the size of the log file, the system time that the process executed, the duration of the process execution, and the name of the file.

Right-clicking on a node in the tree view will show a menu of additional functionality.

Open In External Editor will open the log file in the system default text editor or the text editor defined in the Turbo Debugger options.

Copy Full Path will put the path to the log file on the clipboard.

Search will perform a text or regular expression search in the selected log file. The regular expression syntax is the same as the findstr system tool.

Search All will perform a text or regular expression search in all the logs in the session log folder.

Show VM Environment Info will display the VM version and architecture as well as the operating system version information from where the process was executed.

Show VM Settings Flags will display the virtual machine settings which are enabled for this process.

Open Network Logs will open the network logs for the process (if they exist).

Refresh will reload the session log folder.

Process Log View

A process log is an individual log file for a specific process that was executed inside the virtual environment. Every process that is running inside the virtual environment will have a log file. The process log contains a lot of information about what is happening inside the virtual process, including all system API function calls that go through the virtual machine. Since there is so much detail included in these logs, they can be difficult to analyze to find root causes of problems. The process log viewer provides functionality to make this process easier.

Selecting a line of the log will display a parsed view of the trace at the bottom of the debugger window. In addition to pulling out the information that is already visible in the trace, system flags and contants which are passed as parameters to system API functions will be shown.

In this example, the trace for NtOpenFile is shown. The access flags, 0x100020 are shown as FILE_EXECUTE, FILE_TRAVERSE, and SYNCHRONIZE. These are constants defined in the Windows SDK that are documented on the Microsoft Developer Network website. When hovering the mouse over these constants, their values are shown.

Filters

There are several filters that are defined that can be useful in narrowing down the scope of the log file to make possible errant behaviors easier to see.

None shows the original, unfiltered log file.

Error shows only traces those with trace level WRN, ERR, or LOG if they contain error code information. This may be a good first filter to quickly check if there is anything that stands out. Note that there are many legitimate reasons why a level LOG trace may have an error code so these alone do not indicate a problem and even level ERR can also be benign.

COM shows only traces which have to do with Component Object Model (COM) API function calls (CoCreateInstance, CoRegisterClassObject, COM related registry key accesses, etc). This can be useful if the error being investigated is related to COM object instantiation. Note that errors here may not necessarily be a problem either. There are many COM objects that are optional components and their failure does not cause problems.

Windows shows only traces related to the Window subsystem API function calls (CreateWindowExW, FindWindowW, GetClassInfoExW, etc). This can be useful if the error being investigated is related to the application's user interface, especially in legacy applications which are being made compatible with the latest versions of the Windows operating system.

DLLs shows only traces related to DLL loading, Windows Side-by-Side (SxS), and manifests. Many application problems can be attributed to incorrect versions of DLLs being loaded. This is especially true when getting legacy applications to work on modern operating system.

In addition to filtering the log, the trace tick time can be transformed into a more useful value. Either absolute time or time relative to the beginning of the log.

Absolute time can be useful when trying to find connections to information from other sources such as application log files, Windows event viewer, etc.

Relative time can be useful when comparing to logs in other sessions or when investigating performance issues.

Process Log Reports

If a process log is being displayed or if a log is selected in the session log tree, the Create Reports button is available to generate reports on that log.

Three reports are available: path inventory, error inventory, and DLL inventory.

Path Inventory Report shows a list of all filesystem and registry paths that were accessed in the log and the exit codes returned when accessing these paths. It says nothing about how the path was accessed (for example, creating, opening, writing, etc). This can be useful if the set of potential problem paths is known but is most useful when comparing to logs from a working session.

Error Inventory Report shows the same list of paths and exit codes as the path inventory report but it sorts the information so that error with many occurrences are at the top, then all other errors, and then successes. Reviewing the common errors can reveal possible problem areas.

DLL Inventory Report shows a similar list of paths but only for .DLL file types. It also shows the version of the DLL that was accessed in each case. This can be useful when comparing to working sessions.

Session Log Comparison View

Often the easiest way to discover the source of a problem is by comparing two session log sets with each other. If one session log set is from a working environment and another is from a failing environment, the logs can be compared to see how they differ to bring to light the reason for difference in behavior. Another way to compare session logs is to copy the logs from before and after errant behavior occurs. This makes it possible to see what happened in between the two events to narrow down the scope of logs that require analysis.

To compare two session log sets, open both of them in the debugger and press the Create Comparison button. This will bring up a window which allows you to assign the left and right sets. Assign the sets or leave the defaults and press OK.

This will bring up a new view with the session log trees side-by-side and show additional functionality that is available to compare the logs in the sets.

Session Log Comparison Tools

When a session log comparison view is selected, many new ribbon menu options become available: View Differences, Inventory Report, and Create Delta Log.

View Differences

The View Differences menu shows a number of different ways to filter and compare two logs. These differences will be displayed in text comparison tool which is specified in the debugger options (default is using WinMerge from the turbo.net hub). In all cases the logs will be normalized to make them more comparable (lower cased, remove transient data such as process ID, thread ID, time stamps, memory addresses, user names and IDs, etc). Because of this normalization there will be a loss of information in the text compare tool that may need to be cross referenced with the original logs.

Full will compare the entire logs files. This can be very slow if the logs are large. This can also have limited utility depending on the logs being compared. If the logs were taken from different operating systems then the number of differences can be so large that no useful information can be easily determined. This can be more useful when comparing delta logs (see Create Delta Log below for more information).

Full with Time will convert the ticks to relative time and then do a full compare. This will create a very messy text comparison but can be useful when tracking down a series of events that lead to errant behavior.

Threads allows for comparing the traces for specific threads in two different log files. When this option is selected, the debugger will prompt for the thread ID to compare from each log. Then every trace written from a different thread will be removed before the logs are compared.

Filesystem and Registry filters out all traces except those for filesystem and registry accesses.

Errors filters out all successful API function calls and information log traces, leaving only trace level ERR, WRN, and LOG where it includes an error code.

COM filters to only show traces related to the Component Object Model (COM) such as CoCreateInstance, CoRegisterClassObject, etc.

Windows filters to only show traces for the windows subsystem such as CreateWindowEx, RegisterClassObject, etc.

DLLs filters to only show traces for DLL loading, Windows Side-by-Size (SxS), and manifests.

Network compares the network logs for the processes.

VM Settings compares the virtual machine settings flags for the processes.

Path Inventory compares the Path Inventory Report from the two logs. A quick scan can reveal if certain paths had different return codes.

DLL Inventory compares the DLL Inventory Report from the two logs. A quick scan can reveal if certain DLLs had different versions or return codes which may indicate a possible source of problems.

Search compares the search results from the two logs.

Inventory Report

The Inventory Comparison Report can be used to quickly see relevant differences in how paths are accessed in two different logs. When the two log sets compared are from working and failing cases, this may be the most useful tool in quickly determining the source of a problem.

In the report, paths and their return codes are shown. The paths are sorted into buckets of "differences" (those where the paths are in both but have different return codes), "in both" (those where the paths and the return codes are the same in both), "in only left" (those paths that are only in the left log), and "in only right" (those paths that are only in the right log). For paths to DLL files, the comparison will also take into account their version if available. Focus should be in the section highlighting "differences" where one log has a success code and the other log has an error code. These can often be problematic and are worth analysis. These lines in the report will have an asterisk (*) next to them.

Create Delta Log

A Delta Log is the log file that is produced by removing the traces that are shared in the two log files, leaving only traces for VM initialization and those that are only present in the later version of the log. This is only useful when comparing the same log file at two points in time, like before and after when an error occurs. This can be an incredibly useful tool in order to narrow the scope of the log that requires analysis. To further the utility, two delta logs (one from working set and one from failing set) can be compared with the other comparison tools. This can produce the easiest to analyze logs.

When a delta log is created, it will be placed in the session log folder where the largest version of the log file resides. It will appear in the tree view as a child of the log from which it was produced.

Log Tools

There are several tools which are specific to logs. They can be found in the ribbon menu: Lookup Flags and Resources.

The Lookup Flags window offers the same functionality that is built into the process log viewer where trace fields are broken down so that flags and constants can be resolved. This is useful when copying traces from sources outside the debugger where this is done automatically (ex: text compare tool, external log files, snips from emails, etc).

The Resources menu has a collection of links to Microsoft documentation that is frequently useful when analyzing logs. These include HRESULT, NTSTATUS, and System Error Codes which are returned from API function calls. HRESULT values will be displayed in traces with "hr" field name, NTSTATUS values will be displayed in traces with "status" field name, and system error codes will be displayed with "gle" field name.

General Tools

In the Tools ribbon menu, there are some additional tools which can be useful depending on the situation.

Compare

The Compare tool is a simple tool to compare two sets of text. The tool will normalize the text depending on how the text is to be interpreted. It is then passed to the configured text compare tool.

As Text will compare the text exactly as it appears in the window.

As Trace Log will normalize the text as a VM log file in the same manner that all previously discussed filters and comparison operations do.

As Configuration (.xappl) is used to compare two .xappl files and will normalize the text to remove all transient data (timestamps, etc). This can be useful when comparing two versions of an application xappl to narrow down the differences between them.

As Process Monitor XML is used to compare two XML files which were produced from Process Monitor (procmon) traces. This can be useful if trying to compare behavior between a native application and a virtual application since a native application will not have vm logs).

CLSID Lookup

The CLSID Lookup tool is used to quickly see what a CLSID is configured to be on the current system. When the CLSID is entered, press the Find button. The description field will be shown and all occurrences of the CLSID in the registry will be displayed. Press the Open Key button to open the registry editor to the selected key.

Thread Security Descriptor

The Thread Security Descriptor tool will look up the security descriptor of the specified thread object (not the thread user's security descriptor) and display the Security Descriptor Definition Language (SDDL) string. The string can be copied from the message box with CTRL+C.

File and Folder Attributes

The File Attributes and Folder Attributes tools show the file system attributes of the file or folder selected. For more information on file system attributes, see File System Attributes.

Apply Configuration

The Apply Configuration tool will copy the contents of the specified configuration to the host machine, including both registry and filesystem. This can be useful for troubleshooting issues where the installation media is not available. This operation cannot be undone so it is strongly encouraged to only use this on a virtual machine that can be restored and not on desktop system.

Command Line Tools

The command-line version of Turbo Studio is called XStudio.exe and can be found in the Turbo Studio installation directory. See below for a list of command-line arguments and options for the XStudio tool.

Note: If running XStudio displays the error <SandboxCollision> is missing from the string table the XStudio application cannot be run while Turbo Studio is also running. Turbo Studio must be closed before running XStudio via the command line.

Build

Build the specified container configuration.

> xstudio.exe [path-to-xappl] [optional]

Optional parameters:

• /l [path] specifies a path to the license file to use. The license file needs to be stored in Unicode format. This is only necessary if the license file was not installed on the machine through Turbo Studio.
• /o [path] overrides the path to the output file.
• /component overrides the Project Type to be Layer resulting in an SVM output rather than EXE output.
• /d enables the Generate diagnostic-mode executable setting.
• /compressed enables the Compress payload setting.
• /uncompressed disables the Compress payload setting.
• /deletesandbox enables the Delete sandbox on application shutdown setting.
• /v [version] assigns the Version of the output exe.
• /startupfile [path] overrides the Startup File of the output file.

Setup Capture

Start the capture recording.

> xstudio.exe /capture start /destination [path]

Parameters:

• /destination [path] specifies the path to where the XAPPL configuration and files are to be saved after the capture is complete.

Stop the capture recording. > xstudio.exe /capture stop

Note: Configuration files that are generated from the capture will not have an output file specified in the XAPPL configuration file. When using scripting for captures, it may be necessary to apply changes to the generated XAPPL file, either manually or programmatically.

Snapshot

Take a before snapshot.

> xstudio.exe /before /beforepath [path]

Parameters:

• /beforepath [path] specifies the path to where the snapshot file is to be saved.

Take an after snapshot.

> xstudio.exe /after /beforepath [path] /o [path]

Parameters:

• /beforepath [path] specifies the path to where the snapshot file is to be loaded.
• /o [path] specifies the path to where the resulting container configuration file will be saved.

Note: Configuration files that are generated from the command-line after using the /after flag do not have an output file specified in the XAPPL configuration file. When using scripting for snapshots, it may be necessary to apply changes to the generated XAPPL file, either manually or programmatically.

Import

Import MSI, AXT, or ThinApp configurations.

xstudio.exe /import /i [path] /o [path]

Parameters:

• /i [path] specifies the path to the configuration file to be imported.
• /o [ath] specifies the path to where the resulting container configuration file is to be saved.

Merge Layers

Combine two or more SVM layers into a single file.

xstudio.exe /merge [path-to-layer1.svm] [path-to-layer2.svm] ... /o [path]

Parameters:

• [path-to-layer1.svm] specifies the path to the first SVM layer file.
• [path-to-layer2.svm] specifies the path to the second SVM layer file.
• ... specifies the path of additional SVM layer files to combine.
• /o [path] specifies the path to output combined SVM file.

Sandbox Merge

Merge the contents of a sandbox into a container configuration.

xstudio.exe /sandboxmerge [path-to-sandbox] /i [path] /o [path]

Parameters:

• /i [path] specifies the path to source configuration file.
• /o [path] specifies the path to output merged configuration file.

Dump Settings

Dump a list of all configuration settings in the specified configuration file, container image, or standalone executable.

xstudio.exe /vmsettings [setting] /i [path]

Parameters:

• [setting] specifies the name of a specific setting to return the value of. This is optional and if not specified will show the values of all the available settings.
• /i [path] specifies a path to a .xappl, .svm, or .exe.
• /nologo is an optional flag that specifies that the Turbo Studio copyright and logo information is to be suppressed. Useful when consuming the output in scripts.

Transform Path

Transform a path to its tokenized form or back from its tokenized form. For example, to convert "c:\program files\internet explorer\iexplore.exe" to "@PROGRAMFILES@\internet explorer\iexplore.exe". This tool can also be used for registry paths.

xstudio.exe /pathreplace [path-to-transform] [optional]

Optional parameters:

• /reg specifies that the path is a registry path, not filesystem.
• /revert specifies that the path is tokenized and is to be converted back to native machine path.
• /nologo specifies that the Turbo Studio copyright and logo information is to be suppressed. Useful when consuming the output in scripts.

Turbo Studio in Azure

A preconfigured application capture environment can be deployed to Azure via the Turbo Studio Azure Marketplace Image (AMI). A Turbo Studio AMI deployed instance has Turbo Studio and Turbo Client preinstalled on a clean machine to allow for accurate application captures whether the Setup Capture or Snapshot method is used.

Users will need the following to deploy the Turbo Server AMI:

• Azure subscription
• Feee Turbo.net account

The Remote Desktop Protocol (port 3389) is open by default once the Turbo Studio AMI is deployed.

Note: While there are no extra charges to deploy the Turbo Studio AMI, the Azure subscription will still be charged for any usage.

Deployment

To deploy the Turbo Studio AMI go to portal.azure.com, click Create a resource, search for "Turbo Studio", select the desired plan, and click Create.

The following information will be needed to deploy the Turbo Studio AMI:

• Resource group: Resource group to deploy the AMI
• Region: Azure region to deploy the AMI
• Virtual Machine Name: Hostname of the VM
• Username and password: Local administrative account on the VM

Click Create when all the required information is added to the deployment and the review step passes validation.

When the deployment completes, open a Remote Desktop Protocol (RDP) conection top the VM using the Public IP address from the Overview page of the deployed Turbo Studio AMI VM in the Azure Portal.

The deployed Turbo Studio AMI can now be used to capture applications using the Setup Capture or Snapshot methods.

4.3 Advanced Topics

Large Applications

Issues with Large Applications

Large applications, particularly those over 1GB in size, pose special deployment and performance issues:

• Windows has a hard-coded limit of 4GB for EXE type files. Attempting to execute a virtual standalone EXE over 4GB will result in an error.
• The Windows loader performs preprocessing on EXE files prior to execution. A very large EXE file may introduce undesired startup latency. Minimizing the executable file size also minimizes application startup time.

Factoring Large Applications

It is recommended to factor large applications into two or more pieces consisting of a single small EXE file and one more larger SVM files. Turbo can then combine these layers at runtime. This can be done using the Factor Configuration tool in Turbo Studio or manually using the steps below.

To split your existing application image:

• Save a copy of your current application as data.xappl

• Open data.xappl in Turbo Studio

  • Change the Project Type to Layer (SVM)

  • Change the Output File to data.svm

  • Save the file and build

• Open your existing XAPPL in Turbo Studio

  • Add @APPDIR@\data.svm to the SVM Search Pattern and data.svm to the list of required layers

  • Remove everything from Filesystem and Registry nodes. If you have multiple layers, you can remove all layers other than the default layer. If your application is configured to inherit metadata and icons from the startup file, then you will need to keep the startup file .exe in the Filesystem node, including its full directory hierarchy.

  
  • Save the file and build

• To deploy, place your EXE and SVM in the same directory. This can be repeated for multiple SVMs by adding additional file names or a wildcard pattern into the SVM Search Pattern

Alternately, external SVMs can be imported explicitly via the command line using the /XLayerPath= command line option. This parameter takes a path to additional SVMs to load.

An example of a specified SVM path using full path:

# look for 'patches.svm' in the same directory as 'virtual-app.exe'
> virtual-app.exe /XLayerPath=@APPDIR@\patches.svm

# look for 'patches.svm' in a specific location on the local machine
> virtual-app.exe /XLayerPath=c:\path\to\patches.svm

Startup/Shutdown Scripts and Shims

Turbo Studio allows for custom operations to be performed at the beginning and end of a container's life. This allows for application specific configuration steps to be performed before a container starts (ie. install a necessary driver) or clean up to be performed afterward.

Container Life Cycle

Containers are managed with a root parent process known as a "bootstrap process". This process hosts the virtual machine engine from which the rest of the container executes. In the Turbo command line environment, turbo.exe hosts a shared bootstrap process for each instance of the same container. For Turbo standalone executables ("ISV Applications"), a seperate bootsrap process is used for each invocation of the .exe.

Startup shims and scripts are executed when the first container bootstrap process is started but before the startup files are launched. Execution of the shims and scripts will block the startup files so any long running operations will delay container startup.

Shutdown shims and scripts are executed when the last process inside the container is closed.

Scripts

For simple tasks, a .bat or .cmd script can be configured.

Put the script in the container file system (a full isolated folder in @SYSDRIVE@ such as "scripts" is recommended). Specify the full path to the script in studio. Note that the untokenized form of the path must be used here (c:\scripts\init.cmd rather than @SYSDRIVE@\scripts\init.cmd). Environment variables can also be used in the path (ex: %systemdrive%\scripts\init.cmd) if they are defined on the machine or in the container's custom environment variables.

An example startup script might look like this:

    @ECHO Initializing environment
    if exist C:\workspace\first goto Skip

    :Create-Workspace
    @ECHO Preparing Workspace
    mkdir C:\workspace\first
    echo print("Hello World!") > C:\workspace\first\helloworld.py
    goto Done

    :Skip
    @ECHO Workspace already created, skipping step

    :Done
    @ECHO Done.    
    exit

A common use of startup scripts is to install some required component (driver, etc) to the native system if not already present. Such installers will require admin privileges so will require UAC elevation. Below is one way this can be accomplished using a runtime generated VBS script:

    # create vbs script to ShellExecute a command with "runas" verb to show the UAC prompt if required
    echo Set UAC = CreateObject^("Shell.Application"^) > "%temp%\elevate.vbs"
    echo UAC.ShellExecute "cmd.exe", "/c ""c:\path\to\installer.exe", "", "runas", 1 >> "%temp%\elevate.vbs"

    # execute the vbs script and wait until it completes
    start /b /wait >nul cscript /nologo "%temp%\elevate.vbs" 2>&1

    # clean up
    del "%temp%\elevate.vbs"

To troubleshoot script issues, set the __DEBUGINITSCRIPTSHIM environment variable to true. This will show the command window that is executing the script so you can see output and any generated errors.

Shims

For complex tasks, a DLL can be written to be executed. DLLs can be written in any programming language that supports them but do note any framework requirements must be configured inside the container.

The shim must conform to Turbo Studio interface in order to be loaded properly. Startup shims must be compiled with an exported OnInitialize function. Shutdown shims must be compiled with an exported OnShutdown function. The same DLL can be used for both if both functions are exported.

Shim function signatures: typedef BOOL (__stdcall *FnOnInitialize) (LPCWSTR pwcsInitializationToken); typedef void (__stdcall *FnOnShutdown)(LPCWSTR pwcsShutdownToken);

The return value of the startup shim indicates to the bootstrap process whether it should proceed with execution of the container.

The functions are acquired by the virtual machine with LoadLibrary and GetProcAddress win32 APIs.

    LPCWSTR pwcsInitToken = "VendorSpecificToken";
    HMODULE hShim = ::LoadLibrary("c:\path\to\shim.dll");
    FnOnInitialize fnOnInit = (FnOnInitialize)::GetProcAddress(hShim, "OnInitialize");
    BOOL fResult = fnOnInit(pwcsInitToken);

Note that the DLL must be compiled for the correct architecture (x86 or x64) in order to be loaded. Since the DLL is loaded by the bootstrap process, it must match its architecture, not the startup file.

4.4 Working with Containers

Containers

In this section you'll learn a variety of methods for managing and building containers and images with Turbo Studio and the command-line interface. You'll also learn how to integrate containerization with your continuous integration server.

Creating Containers

The turbo new command starts new containers. You must specify a base image to provide the virtual filesystem and registry for the container. If no files or registry keys are necessary, use the empty clean image.

# Launch a command window in a new container with clean as the base image
> turbo new clean

Operations executed in the new command window are applied to the container, not the host system. This means you do not have access to local files, the container is fully isolated.

To avoid confusion, the prompt is prepended by the image name and the first 8 characters of the container ID when a command window is running in a container. Alternatively, a container can be assigned a name, this will be illustrated in the Installing MSI Packages in Containers section.

# Host command window
> turbo new clean

# Container command window
(clean#0bad25c4) >

Edit and modify the container's virtual filesystem and registry using the same command-line interfaces available in Windows Command Prompt.

Installing MSI Packages

Installing MSI packages in containers is supported, but in some instances an install may fail e.g. a custom action may attempt to runs but fails when run in the fully isolated Turbo VM. If an MSI install fails, try creating the container using Turbo Studio.

This section will detail steps for creating a container for InstEd, a popular MSI editor.

Begin by downloading the application here

Copy the MSI to a new directory: C:\Installers on your local machine.

By design the Turbo VM is fully isolated and does not permit access to local files. In order to use the MSI in your local C:\Installers directory, you must poke a hole in the isolation. Use the --mount flag to poke a hole in the isolation. Use the -n flag to set a name for the container.

# Poke a hole in isolation
> turbo new clean --mount="C:\Installers" -n=instedcont

Launch the install.

# Install InstEd
(instedcont#95c15a32) > C:\Installers\InstEd-1.5.15.26.msi

When prompted, click Next.

Click on the checkbox to agree to accept the terms in the license agreement and then click Next.

Click Next.

Click Install followed by Finish.

Exit the Turbo VM from the launched command prompt.

# Close Turbo VM
(instedcont#95c15a32) > exit

Once you finish editing a container, it can be saved and distributed in the form of images. For more information on images, read on here.

Ensure the --startup-file flag is set to the application's main executable. Provide an image name, in this example use instedit.

# Commit container into an image
> turbo commit instedcont --startup-file="C:\Program Files (x86)\instedit.com\InstEd\InstEd.exe" instedit

By default, the commit command merges sandbox changes with the base images and builds a new image from these merged layers. Specifying the "--no-base" option builds a new image of the sandbox changes without merging the base images.

Test the new InstEd image.

# Launch a new instance of Insted using the instedit image
> turbo new instedit

Accessing Local Files

You may notice when attempting to open an MSI on your local machine, you will not have access to it. Similarly, when creating a new MSI and attempting to save to a local machine directory, you will not be able to save locally. This is expected behavior. By default containers run in full isolation. Use the --isolate flag to launch a new instance of InstEd with isolation set to merge with the local system.

Launch application with access to local files.

# Launch instedit image
> turbo new instedit --isolate=merge

You will now have access to any local files.

Pushing Images to the Hub

We created an image which can be pushed to our Hub and run by anybody. To do this, we must first login to Turbo.net from the command prompt. Enter turbo login and then enter your turbo username and password when prompted.

# Login
> turbo login

Push the image by entering turbo push %lt;imagename>.

# Login
> turbo push instedit

Publishing Images

Our image has been pushed to the Hub. Now we will configure the repo settings and other publishing settings. Navigate to Turbo.net and clicking Sign In.

If you do not have a Turbo.net account click Sign Up to create a new account. If you do have a Turbo.net account, enter your Turbo.net username and password and then click Sign In.

After logging into Turbo.net you are presented with your home screen that contains your applications. Click on instedit.

Hover over the large icon in the header of the page to upload a suitable image for the application. Hover just below the instedit text in the banner and click edit to provide a description.

On the same page, hover beside the description heading and click edit to provide a description of the application. When complete, hover over the readme heading and click edit to provide information useful to people who may try to use your image. e.g. what commands should be used.

Navigate to Settings. A default display name is set, you can change this to something more appropriate such as Instedit or Insted.

Optionally, under Repo Information enter a build script URL if you have one. For more information on how to create a build script read on here. Enter a Developer website and Support website if desired. This information will be displayed on the application's repo page. When using a free account, click Update as there will be no other options available for you.

The Turbo.net Hub provides the ability to create custom run pages for applications. For an example of this, click here. The run page provides a great presentation and end user experience. If enabled, this run page can also be embedded within a website or blog. For an example of an embedded run page click here and scroll to the bottom of the page.

Enter a Heading, which will be the application name displayed to the end users. Enter a SubHeading which should contain a brief description of the application. Optionally enter an Article URL which will provide a hyperlink to a source page e.g. if you choose to host an application you created, you can link to your own hosted blog with information about the application.

Click on Choose File to upload a Splash image. (1033 x 752 px is a good size for this) This could be a static screenshot of the application or possibly an animated gif of the application being used. Click on Choose File to upload a Background image. Optionally repated these steps to upload a Splash thumbnail and Background thumbnail image.

Optionally, enter a Run button color and Background image color. This may be useful if the background you choose conflicts with the color of the button.

If you do not wish to use a Splash image you may choose to enable a Background banner. This will present a banner across the run page containing your run page information.

Navigate to Icon Settings and set a Background color. If the icon you uploaded has a white background, it is best to enter transparent as the value for the Background color. Optionally select if the icon should Padded. This will trim the edges of the image. In some cases, this can make certain icons look much better.

Navigate to Launch Configuration. If any additional flags are required for the application to function, enter these here. For a list of available flags read here. Enter additional Image layers if you wish to launch the application with other dependent images. Always ensure the application you wish to launch is in the last image in the list. Seperate each image you wish to layer with a comma.

To force the use of a certain version of the Turbo VM enter the version number under VM version.

In the above example, InstEd requires local file access. This can be permitted by setting File Isolation to Write Copy of Merge.

Enable Isolate network to isolate all tcp,udp and named object calls within the container.

Navigate to Admin Settings. Under Shortcut Icon (.ico) click Choose File to upload an icon file for the application. Click on the dropdown menu for Categories to assign the relevant categories for the application to appear in on the Turbo.net Hub.

Enable the application as Official to ensure it can be found in Turbo Launcher and from a search on the Turbo.net Hub. Click Embeddable to allow the run page to be embedded on websites and blogs.

When complete. Click Update.

We are always looking for new applications to host on the Turbo.net Hub. If you would like to share your work with everybody, please reach out to us via Twitter: @turbohq or alternatively send us an e-mail to: support@turbo.net.

Managing Containers

Once created, track and manage containers with these commands.

# List containers with base images, commands, creation date, and status
> turbo containers

ID           Images            Command       Created          Status
03bddd8bef   spoonbrew/clean   cmd           8/14/2014 1:03   Stopped
52hd888xa3   local/server-app  startup.bat   8/14/2014 1:00   Running

# Remove a specific container from the host system
> turbo rm 03bddd8bef

# Remove all containers
> turbo rm -a

Note that running containers must be stopped before being removed.

Processes and Stopping Containers

The life cycle of a container is controlled by the processes within that container. Processes in a container spawn as child processes of the Turbo VM executable, which manages the container environment.

When a process within a container exits or completes, the container exits as well.

# You can forcefully exit a container from the native command window
> turbo stop <container id>

This command kills the Turbo VM managing process along with any child processes.

You can also explicitly shut down a container from a command window running in the container by typing exit or entering Ctrl+C.

# If necessary, restart a closed container and specify the container ID
> turbo start 8dpp9eb5

Debugging

If you experience crashing or other issues with Turbo containers, here are several commands to help you debug and fix these problems.

# If your container unexpectedly crashes, enable diagnostic mode
> turbo run --diagnostic <image>

# Then fetch the logs created by the run
> turbo logs

This command returns logs of all the standard streams (STDIN, STDOUT, STDERR) for the specified container.

Please note that enabling diagnostic mode will cause your container to run slower than expected. Therefore we recommend only enabling this mode for diagnostic/debugging purposes.

# You can also debug by viewing changes to a container's filesystem and registry
> turbo diff 8dpp9eb5

# Similarly you can revert changes to get the container back to a running state or to debug changes
> turbo revert 8dpp9eb5

IP Routing

Turbo container IP routing can be used to map container network ports to those on the native machine. This is possible using the --route-add flag.

The syntax for the --route-add flag is <protocol>://<containerPort>:<hostPort>. For example, to map container TCP port 8080 to host port 80, you would use the command flag --route-add=tcp://8080:80.

In addition, the ip protocol is supported which applies routing to all IP-based communication. For example, the command --route-block=ip blocks all IP traffic. Subsequent --route-add flags can be appended to whitelist specific IP addresses.

It is also possible to map a container port to a random high host port for security purposes or to avoid binding conflicts. This port can subsequently be queried with the turbo netstat command. To map container TCP port 4321 to a high random host port, use the flag --route-add=tcp://4321:0. The 0 here represents a randomly assigned high port.

Sample: PuTTY Whitelisting

PuTTY is a popular free Telnet client for Windows. To create a PuTTY container with all outbound access blocked except to IP address 10.0.0.34:

> turbo new putty --route-block=ip --route-add=ip://10.0.0.34

Now let’s reroute all traffic from 1.1.1.1 to 10.0.0.34, making it possible to connect to host at 10.0.0.34 typing address 1.1.1.1 in PuTTY:

> turbo new putty --route-block=ip --route-add=ip://10.0.0.34 --route-add=ip://1.1.1.1:10.0.0.34

It is also possible to block or map IP ranges using the CIDR notation. For example, the following command allows PuTTY in the container to connect only to hosts in the 192.168.1.0/24 network:

> turbo new putty --route-block=ip --route-add=ip://192.168.1.0/24

To disallow connection to a set of specific set of IP addresses or ranges (“blacklisting”), simply specify them in the --route-block parameter:

> turbo new putty --route-block=ip://10.0.0.34

The --route-add and --route-block command flags are also supported within the commit command, so it is easy to save custom network stacks into deployable images.

Host Name-based IP Restrictions

This syntax also allows specifying host names instead of IP addresses. Often using a human-readable domain name is easier to setup, more readable, and is automatically maintained across IP address changes. When a host name is specified, it is treated as if its IP address had been specified. Cases where multiple IP addresses are resolved — including IPv6 — are handled properly. Note however that you cannot specify a host name on the right side of a route-add mapping since the result would be ambiguous if the host name resolved to multiple IP addresses.

For example, to run a Chrome container allowing only access to the turbo.net and blog.turbo.net domains, you can use the command:

> turbo new --route-block=ip --route-add=ip://turbo.net --route-add=ip://blog.turbo.net chrome https://turbo.net

Wildcards are supported in host name routing. For example, to unblock turbo.net and all of its subdomains, use the command:

> turbo new --route-block=ip --route-add=ip://*.turbo.net chrome https://blog.turbo.net

Taking this a step further, to run a Chrome container disallowing access to the facebook.com domain and all of its subdomains:

> turbo new --route-block=ip://*.facebook.com chrome

Creating IP Routing Layers

If you need to apply the same set of IP routing rules across multiple applications, it is inconvenient to repeat them each time you create a container. In this situation, you can create a layer containing the appropriate IP routing rules and apply it to all of the applicable containers.

For example, to create a layer that blocks access to all IP addresses except the turbo.net domain, the network 192.168.1.0/24, and 127.0.0.1, first create a container with the rules:

> turbo new --name=network-blocking-container --route-block=ip --route-add=ip://turbo.net --route-add=ip://192.168.1.0/24 --route-add=ip://127.0.0.1

We then commit the routing container to a new image called network-blocking-layer:

> turbo commit network-blocking-container network-blocking-layer

We can now use this layer together with any image:

> turbo new network-blocking-layer,firefox https://turbo.net
> turbo new network-blocking-layer,putty -ssh 192.168.1.1

These applications can in turn be committed to a new image that is ready for deployment:

> turbo commit firefox firefox-restricted
> turbo run firefox-restricted

IPv6 Routing

IPv6 address are also supported by this network syntax. The colons in IPv6 addresses causes conflicts with this syntax however. To solve this, IPv6 addresses in Turbo commands are enclosed in square brackets.

For example, to block the localhost address, use the command:

> turbo new putty --route-block=ip://[::1]

To block all IP traffic except the link local IPv6 space. Notice we can use the CIDR notation to specify a range of addresses.

> turbo new putty --route-block=ip --route-add=ip://[fe80::c218:85ff:febd:5c01/64]

To redirect traffic from a specific IPv6 address to localhost:

> turbo new putty --route-block=ip --route-add=ip://[2001:cdba::3257:9652]:[::1]

Routing Files

While working with long routing lists (eg to block advertising or other undesired sites) it is inconvenient to add many --route-block and --route-add flags to command line or TurboScript file. To simplify this, we use the --route-file flag.

The routing file has a simple INI-style syntax:

[<protocol-action>]
Host-address

The header contains the definition for how the below addresses should be interpreted. Supported protocols are ip, tcp, and udp and supported actions are add and block.

To block/unblock all IP addresses we can use the 0.0.0.0 literal or *.

For example, a routing file that blocks all IP traffic except turbo.net/spoon.net addresses:

[ip-block]
*
[ip-add]
*.turbo.net
*.spoon.net

The route file can be used with all other container management commands. For example:

> turbo try firefox --route-file=routes.txt --name=turbo-firefox

It can also be used during commit to persist routing settings into an image:

> turbo new firefox --name=fx
> turbo commit fx turbo-firefox –route-file=routes.txt

And can be included in a TurboScript build command:

> turbo build turbo.me --route-file=routes.txt

Blocked Site Routing

IP routing can also be used to reroute traffic from blocked sites to an internal network. As an example, we will reroute all traffic from nytimes.com to an internal containerized web server.

First, we run a preconfigured Apache server that binds to local port 80:

> turbo new apache/apache-samples --detach

Next, we run firefox with routing enabled:

# route nytimes.com traffic to local web server
turbo new firefox --route-add=ip://*.nytimes.com:127.0.0.1 

After typing nytimes.com in browser it shows our custom page, instead of original site:

Sample: Creating Single Site Browsers

Turbo’s IP routing capabilities can be used to create custom browsers that allow access only to a specific site or set of sites. A simple solution was shown in previous articles, eg:

> turbo new firefox --route-block=ip --route-add=ip://*.turbo.com --route-add=ip://*.spoon.com

The above command works for simpler websites, but more advanced websites use resources from multiple external sources. We need to allow access to those external sites for the site to load properly.

To simplify the process of creating a routing file for this scenario, we have published a PowerShell script to help. In this example we will show how to obtain this script and use it to create a forbes.com limited browser.

First, download the script from turboapps repository: route-file-builder.ps1

Example script usage:

PS> Route-file-builder.ps1 -urls “http://turbo.net”

PS> Route-file-builder.ps1 -urls (“http://turbo.net”, “http://spoon.net”) -routeFile c:\path\to\routes.txt

When the -routeFile flag is not passed, output is printed to the console.

The script runs the container in the background with a fully blocked network and iteratively unblocks hosts that the website tries to connect to.

Let’s run it for forbes.com:

PS > .\route-file-builder.ps1 -urls forbes.com -routeFile c:\s\forbes-routes.txt
Security warning
Run only scripts that you trust. While scripts from the Internet can be useful,
this script can potentially harm your computer. If you trust this script, use
the Unblock-File cmdlet to allow the script to run without this warning
message. Do you want to run C:\s\route-file-builder.ps1?
[D] Do not run [R] Run once [S] Suspend [?] Help (default is "D"): R
Running browser...
Did everything work correctly? (y/n):

In every iteration, the script opens firefox to the forbes.com site. After closing the browser it asks the user if the site was displayed correctly. Repeat the process until the web page displays correctly.

In the first iteration firefox is not displaying anything, so we choose n

Running browser...
Did everything work correctly? (y/n): n
Running browser...
Did everything work correctly? (y/n): n
Running browser…
Did everything work correctly? (y/n): y

After the fourth iteration the site is displayed correctly. Now we answer yes and script ends.

Now we can open the forbes-routes.txt file and check all the unblocked hosts:

[ip-add]
*.forbes.com
127.0.0.1
tiles.r53-2.services.mozilla.com
tiles.services.mozilla.com
location.services.mozilla.com
i.forbesimg.com
a1586.g1.akamai.net
self-repair.mozilla.org
shavar.services.mozilla.com
shavar.prod.mozaws.net
aus5.mozilla.org
aus5.external.zlb.scl3.mozilla.com
safebrowsing.google.com
sb.l.google.com
services.addons.mozilla.org
olympia.prod.mozaws.net
versioncheck-bg.addons.mozilla.org
blocklist.addons.mozilla.org
ocsp.digicert.com
search.services.mozilla.com
tiles-cloudfront.cdn.mozilla.net
www.googletagmanager.com
b.scorecardresearch.com
stats.g.doubleclick.net
tags.bluekai.com
consent.truste.com
contextual.media.net
rt.liftdna.com
www.googletagservices.com
cs9.wac.phicdn.net
tracking-protection.cdn.mozilla.net
connect.facebook.net
content.dl-rms.com
h.nexac.com
forbescount.xmlshop.biz
a1.vdna-assets.com
ml314.com
load.amexp.exelator.com
ox-d.forbesbidder.servedbyopenx.com
partnerad.l.doubleclick.net
us-ads.openx.net
ib.adnxs.com
ssum.casalemedia.com
medianet-d.openx.net
qsearch.media.net
[ip-block]
0.0.0.0

As an additional step, it is possible to manually cleanup the list (eg remove the Mozilla sites) and prepare a minimal working configuration.

The routing data can later be committed into a new image with turbo commit --route-file command.

Tips

Running Containers as Different Domain Users

By default Turbo containers will run in the security context of the user executing the turbo command. But what if we need to run as a different user?

In this example, let's run SQL Server Management Studio as a different domain user than the currently logged in user. In our scenario we have the Turbo.net Client installed in the local profile (the default behavior).

Our first attempt is to just use the runas command to execute the command turbo run ssms2012:

> runas /user:user@domain "turbo run ssms2012"
Enter the password for user@domain:
Attempting to start turbo run ssms2012 as user "user@doamin" ...
RUNAS ERROR: Unable to run - turbo run ssms2012
5: Access is denied.

Unfortunately with the Turbo.net Client installed in the local profile I cannot use runas to run SSMS in the user context I want since it does not have access to that user's profile.

One workaround then is to install the Turbo.net Client for all users and then use runas:

# install the client for all users
> turbo-client.exe --all-users

# run as a different user
> runas /user:user@domain "turbo run ssms2012"

This works well but we may not want to reinstall the plugin or may not want to install it for all users.

We can solve this by using runas with the /netonly flag:

> runas /netonly /user:user@domain "turbo run ssms2012"

The /netonly flag forces the application to use the runas account for remote resources and the logged in account for local resources.

4.5 Continuous Integration

Create automated, clean, and consistent test environments with Turbo while keeping the Continuous Integration (CI) server free from conflict causing dependencies.

Existing CI servers may have many varying libraries, runtimes, custom settings, and applications, possibly in different languages and versions, that are required for the various automated builds. Sometimes these dependencies collide to create inconsistent test environments and headaches when configuring automated builds.

With Turbo no installed dependencies are required on the CI server. All dependencies are built into containers providing consistent environments and a dependency-free CI server. This eliminates the possibility of dependency collision and makes automated build configuration very simple.

The basic steps for integrating Turbo into a CI server are to create a TurboScript, integrate it into an automated build on a CI server, and finally run and test the container.

Create TurboScript

The TurboScript contains all the steps necessary to build the container.

# Creates a new container from the specified images
layer nodejs/nodejs git/git

# Clone a project in the container
cmd mkdir c:\root
cmd git clone https://github.com/project/repo c:\root

# Install Node.js depencies 
cmd cd c:\root\server & npm install

Save your script as a .me file. See the TurboScript reference for more information on TurboScript script instructions.

Integrate into the CI server

The next step is to configure an automated build on the CI server that will execute the TurboScript and create an image. You'll need to configure the necessary triggers, schedules, notifications, etc., which will vary between CI servers.

Now add the follow commands to your automated CI build script:

# Log in if images from a hub repository are specified
turbo login <username> <password>

# Execute the TurboScript and build a new image
turbo build -n=<name> C:\path\to\turbo.me

# Export the image to a location on the host system
turbo export <name> c:\root\image.svm

Rather than exporting the image to the host system, you can also turbo push the image to the hub where other users could pull it down and test.

See the Command Line Interface page for more information on turbo commands.

Run the container

# First import the image to your local registry
> turbo import -n=<name> C:\root\image.svm

# Run the image
> turbo run <name> <command>

If you alternately pushed to the hub then use these commands to pull and run:

> turbo pull <account name>/<name>
> turbo run <account name>/<name> <command>

Example use case: running tests inside a container on the CI server

We would like to run the tests of a project inside a turbo container, all within a CI server job.

Let's assume we have an ready-built image, pushed to the hub, containing the project source code and all the development dependencies: jdk,maven,git.

layer jdk,maven,git

cmd mkdir c:\root
cmd git clone https://github.com/JodaOrg/joda-time.git C:\root

The CI server job that runs the tests inside a turbo container would look like this:

turbo login %SPOON_USER% %SPOON_PWD%

rem pull latest changes and run the tests
turbo run turbo/sample -n=ci-example --attach -w="C:\root\joda-time" /c git pull ^&^& mvm clean test
set TESTS_EXITCODE=%errorlevel%

rem capture the test results from the container, make them available to the CI server
mkdir surefire-reports
turbo cp ci-example:C:\root\joda-time\target\surefire-reports surefire-reports

rem discarding container
turbo rm ci-example

rem exit using the testrun's exit code
exit /b %TESTS_EXITCODE%

The CI server stores the Turbo credentials as environment variables SPOON_USER and SPOON_PWD

When running the image, it first pulls latest code changes and then launches the build and runs the tests.

After the tests complete, there are two things that need to be done, before it finally exits:

• test results need to be made available outside of the container, for tasks like test results parsers, which display rich information about test failures.

• the temporary container needs to be discarded.

Once these things completed, the script exits using the original tests run exit code. This to ensure that if the test run failed, the CI server will detect this by the exit code returned.

Using Turbo Studio Snapshot

While many application can be installed directly into Turbo containers through a normal install process or be built using a TurboScript, some applications require the use of snapshots to create a working image.

Snapshotting is a technique for creating images of virtual applications by detecting file system and registry modifications made during installation.

Here we will discuss how to create an automated pipeline for creating snapshot-based application images using Turbo Studio, Vagrant and Jenkins. Jenkins is an automation server used to manage automated processes. Vagrant is a tool used to manage virtual machine instances (in our case, VirtualBox).

The Basics

Creating a virtual application image using snapshots is a multi-step process. It includes taking a snapshot of a clean operating system image before installing an application, performing the installation, and taking the second snapshot after the setup completes. Extra time is required for managing a virtual machine or downloading the application installer. Overall, building application images via snapshot manually is time consuming, so the process benefits dramatically from scaling via automation.

The TurboScript plugin for Jenkins provides a build step to automate creating snapshot-based application images. With a small amount of configuration Jenkins can perform all tasks necessary to create an application image via snapshot:

• Boot a clean virtual machine
• Take the before snapshot
• Install an application
• Take the after snapshot
• Build an application image
• Import an application image to the local repository on the host machine
• Delete the virtual machine

Features available off the shelf in Jenkins help to further customize the workflow by triggering a build by an external event, downloading an application installer or publishing an image to the Turbo.net Hub.

As an example, we will show how to create a Jenkins build project for FL Studio, a popular music production system.

Initial Setup

The configuration presented below was tested using Jenkins 2.134, Vagrant 1.7.4, and VirtualBox 4.3 installed on Windows 8.1 and Windows Server 2012 R2.

First, install Jenkins for Windows, Vagrant, VirtualBox, and Turbo Studio.

The TurboScript plugin for Jenkins uses PowerShell to call external tools like Vagrant and Turbo Studio. To enable execution of PowerShell scripts on the Jenkins host machine, run the command below in an elevated command prompt:

> powershell -Command Set-ExecutionPolicy RemoteSigned

Configure Jenkins

Open the Jenkins Plugin Manager and install the latest version of TurboScript Plugin.

Go to the Jenkins configuration page and scroll down to the Studio Snapshot section.

Specify the file paths to XStudio.exe in the Turbo Studio install directory and a license file on Jenkins host machine. If you installed Turbo Studio using default settings, XStudio.exe can be found in the C:\Program Files (x86)\Turbo.net\Turbo Studio 18 folder.

Optionally, you may want to change the default virtual machine used to take snapshots. Boxes are downloaded from Vagrant's Service. The list of boxes is available here.

Create the Build Project

Go to the Jenkins dashboard and create a new Turbo Project. Name it FL Studio Snapshot and click OK.

Create a PowerShell script file which downloads the latest FL Studio installer. You can copy the code snippet below:

(New-Object System.Net.WebClient).DownloadFile(
    "http://support.image-line.com/redirect/FLStudio_Installer",
    "install.exe")
    
 $versionInfo = (Get-Item -Path "install.exe").VersionInfo
 
 $tag = ("{0}.{1}.{2}.{3}" -f $versionInfo.FileMajorPart,
     $versionInfo.FileMinorPart,
     $versionInfo.FileBuildPart,
     $versionInfo.FilePrivatePart)
 
 "flstudio:$tag" | Set-Content "image.txt"

Optionally, the script may create an image.txt file in the current working directory. The file should contain the name of the output image. It is considered a best practice to include a product version. In the sample code above the product version is extracted from file attributes.

Save the script file on the Jenkins host machine and execute it in a build step.

To add a build step, use the Execute Windows batch command option.

Specify the following command in the build step configuration:

powershell.exe -File "path_to_the_script"

Next, add a build step Take Studio snapshot and setup it in the following way:

Select the Generate using template option for installation script.

Specify /S to force a silent install.

Select the Ignore exit code checkbox.

Use a Fixed startup file set to @PROGRAMFILESX86@\Image-Line\FL Studio 12\FL.exe. For most applications, the default startup file selection made by Turbo Studio is sufficient.

Optionally, select the Overwrite checkbox if you want Jenkins to continue the build in case an image with the same version is already available in the Turbo.net Hub. Otherwise, the build will be aborted.

Save the build project and go back to the main Jenkins dashboard.

Trigger the Build

Open the context menu next to project name and click Build Now.

The build should finish in approximately half an hour. The FL Studio image will be saved in a local repository. If you want to publish it to the Turbo Hub, simply add the build steps Login to Turbo Hub and Push Turbo image.

4.6 Scenarios

Turbo.net Build Scripts

The build scripts for images in the Turbo.net hub are open source and stored on in a github repository. While these are written for our automated build system, any of these scripts can be downloaded and modified for your own use. And don't forget, contributions are always welcome!

Browser Ad Blocking

Ad blocking is important for improving user experience, maximizing performance, and eliminating an important source of security vulnerabilties.

Turbo automatically provides ad blocking in popular web browsers such as Chrome and Firefox. In addition, any application running in a Turbo container can be ad blocked using Turbo container networking.

This article will explain Turbo's built-in browser ad blocking and network routing-based container ad blocking technology.

Browser Ad Blocking on Turbo.net

Popular web browsers in the Turbo Hub such as Chrome and Firefox come pre-configured with ad blocking.

Turbo uses the uBlock Origin plugin, a popular open source system currently installed on millions of devices. Turbo augments the default configuration with data on additional advertising networks. The ad block plugin and databases are automatically updated as part of Turbo's automatic browser patching system -- users or administrators don't need to do anything!

If you wish to use a non-adblocked version of a browser, use the "Base" version in the Hub. For example, the mozilla/firefox-base image is a default Firefox image with no adblocking or other plugins applied.

IP-based Ad Blocking

Turbo also provides an alternate approach to ad blocking based on virtual network configuration in the container. Recall that Turbo supports custom IP routing rules within containers. The Turbo Hub provides a pre-configured routing table with known advertising networks and hosts blocked. Applying this layer blocks access to these advertising networks. This allows ad blocking for applications other than web browsers, where ad blocking plugin interfaces are not available.

Applications containing advertising in the Turbo.net Hub have this layer enabled by default. Examples include Skype and uTorrent.

To enable network-based ad blocking on your own applications, right-click on the application and press the Settings context menu button in the Applications tab of the dashboard. Then select the Network tab and click the Add button next to the Block Ad Networks layer:

Finally, click Save.

The Block Ad Networks layer is an aggregation of multiple databases of advertising network hosts and IP addresses. These are updated nightly by TurboBuild and pushed automatically when automatic patching is enabled. Additional manual customizations can be applied on top of the layer by clicking on the Custom sub-tab.

Customizing IP Blocking

Administrators can easily build custom network blocking rules and apply them to organization containers.

For a small group of hosts which is unlikely to change, use the route block TurboScript instruction to add blocked hosts or IP addresses.

route block ip://ads.com

See the Skype or uTorrent TurboScripts for more detailed examples.

If there are a large number of hosts to block, it is easiest to define routing rules in a route file. A simple route file is below:

[settings]
PreResolveHostNames=false

[ip-block]
*.host1.com
*.host2.com

The declaration PreResolveHostNames=false instructs Turbo to skip resolving DNS names until the first time they are used. This significantly reduces the time required for launching an application when the configuration contains thousands of hosts.

Before submitting an application image, you may want to verify how an application behaves when hosts are blacklisted. The Turbo command line interface provides --route-block and --route-file options for this purpose:

> turbo try google/chrome --route-block=ip://host.com
> turbo try google/chrome --route-file=routes.ini

Once the changes have been tested, they can be applied with the turbo commit command using the same flags.

Blocking Adult Content

The Block Adult Content routes layer can be used with any Turbo container, including web browsers, email clients, instant messengers, or any other applications. The layer contains a set of IP routing rules that automatically block connections to adult content sites.

The host list in the Block Adult Content routes layer is updated automatically by TurboBuild based on published databases of adult content sites. Updates are propagated automatically to subscribed devices if automatic updates are enabled.

To enable network-based adult content blocking on your own applications, right-click on the application and press the Settings context menu button in the Applications tab of the dashboard. Then select the Network tab and click the Add button next to the Block Adult Content layer.

The layer can also be applied using the command line interface. To use the layer, insert block-adult-routes into the image list. For example, to run Chrome with adult sites blocked, use the command:

> turbo run block-adult-routes,chrome

Blocking Social Networks

The Block Social Networks routes layer can be used to block access to popular social networking sites (Facebook, Twitter, YouTube, etc) from any Turbo web browser. A full list of the blocked sites are listed here.

As with ad and adult content blocking, you can add this layer from your turbo.net dashboard with Block Social Networks layer or from the command line:

> turbo run block-social-routes,chrome

SQL Test Lab Environments

Turbo.net is a great way to provide online learning and test lab environments for SQL Server and other complex applications. Turbo VMs provide the user with a ready-to-use database server, sample content, and test IDE environment -- without requiring any setup or modifying the host desktop.

Here we will show you how to create a SQL Server Turbo VM lab that can be easily executed in your lab environment. In our example, we will create a lab environment for this article from SQL Server Central, one of the world's largest SQL Server communities: http://www.sqlservercentral.com/articles/T-SQL/130558/.

Prerequisites

If you want to follow along building this example, you will first need to download the Wildcard Searches.sql file. This will require an account at SQL Server Central.

The Basics

Our SQL environment will consist of three Turbo container images:

• sqlserver/sqlserver-express
• sqlserver/ssms
• A content layer that will provide content specific to the article for which the image is being created. Typically this is a SQL script, but could also include a database or other resources.

Step 1: Create the Lab Image

Specify a Sample SQL Script

Create a folder on your system for the contents of the content layer and change the directory of the command window to that folder.

> mkdir %UserProfile%\Desktop\article-content
> cd %UserProfile%\Desktop\article-content

Copy the Wildcard Searches.sql file into the article-content folder. The SQL Script must be named script.sql.

Create a turbo.me file which will be used to build the image. If prompted, select to save or create the file.

> notepad turbo.me

Add the following content to the turbo.me file:

# This TurboScript creates a content image to use with sqlserver/sqlserver-express

# Copy the content from the TurboScript directory.
copy script.sql c:\sql-content\script.sql

We will be using the tempdb which is in our SQL Server Express container, so we can skip to Build the Custom Image. If you want to use a custom database as sample content, follow the instructions in the Adding a Sample Database to the Custom Image section.

Adding a Sample Database to the Custom Image

Note: This section is optional and not required for the example.

To use your own sample database, create a new container on top of the base images using the following command:

> turbo new --name=content-for-article-container sqlserver/sqlserver-express:2012,sqlserver/ssms:2012

After SSMS launches, configure the sample database. You can connect to the .\sqlexpress instance with username sa and password password1.

Alternatively you can restore the database from a backup file. To do this, use the mount option to specify the folder on the host system where the backup database file resides. In this example, the mount point is set to the folder C:\SampleDB.

> turbo new --name=content-for-article-container --mount=C:\SampleDB sqlserver/sqlserver-express:2012,sqlserver/ssms:2012

After SSMS launches, configure the sample database by restoring the .bak file.

When configuration is complete, close SSMS and the content will be saved into a container called content-for-article-container.

Copy the SQL DATA folder from the container to the host (run this command from the same directory as your turbo.me file):

> turbo copy content-for-article-container:"C:\Program Files (x86)\Microsoft SQL Server\MSSQL12.SQLEXPRESS\MSSQL\DATA" host:.

Remove the files that are not needed:

> del DATA\model.mdf DATA\modellog.ldf DATA\MSDBData.mdf DATA\MSDBLog.ldf DATA\tempdb.mdf DATA\templog.ldf

NOTE: This assumeed you made changes to 'master' database. The point of the exercise is to remove all the database files that you don't need as many files are there by default.

Once the data is copied out of the container, it may be discarded:

> turbo rm content-for-article-container

Now that the sample database is present, append a line to the turbo.me file to copy the DATA folder into the custom image during the image build process:

# This TurboScript creates a content image to use with sqlserver/sqlserver-express

# Copy the content from the TurboScript directory.
copy script.sql c:\sql-content\script.sql
copy DATA c:\sql-content\

When the SSMS container starts, the user will have to attach the database to access the data. You can also put your database files directly in the SQL Server DATA directory to be attached automatically.

Build the Lab Image

Now that we have the contents ready for the lab image, we can build the image using the turbo.me file. Use an appropriate name in place of sql-sample-content. For example, if the VM corresponds to an article, a good practice would be for the image name to match the article title. Our example is based on an article titled SQL Wildcard Searches so we will name our image turbouser/sql-wildcard-searches. The placeholder turbouser should be set to your login name (you can find your login name with the command turbo login).

> turbo build --name=turbouser/sql-wildcard-searches turbo.me

After the build completes, test the new image.

> turbo run --route-block=tcp --name=testing-for-article-container sqlserver/sqlserver-express:2012,sqlserver/ssms:2012,turbouser/sql-wildcard-searches

Publish the Custom Image

Once the image has been tested, push the sql-wildcard-searches image to Turbo.net:

> turbo push turbouser/sql-wildcard-searches

For ease, this example is already available on the Turbo.net hub: sqlserver/sqlserver-samples.

> turbo run sqlserver/sqlserver-samples

Login to the default instance with sa and password1:

From inside the container SSMS, open c:\sql-content\script.sql and execute:

Legacy SQL Server

Some legacy applications have dependencies on legacy versions of SQL Server. Here it will be shown how to create and configure a SQL Server 2005 Express Edition image using Turbo Studio and the snapshot method.

Prerequisites

Perform the snapshot on a clean Windows 7 x64 system that has all the latest Windows Updates. It is important to ensure that no Microsoft Visual C++ Redistributable packages are installed as they will be missed during the snapshot. Note that uninstalling the packages will leave behind files and registry keys that will render the resulting snapshot incomplete so they must never have been installed on the machine.

Install Turbo Studio. See downloads for the latest version.

The Build

1. In Turbo Studio, press the Capture Before snapshot button.

2. Install SQL Server 2005 Express Edition. You can download the installer here: https://www.microsoft.com/en-us/download/confirmation.aspx?id=21844

3. Install SQL Server 2005 Service Pack 4 - kb2463332

4. Configure SQL as needed. For example, you may want to add users with access or pre-configure databases.

5. Stop all SQL related services. The services have a lock on required files that prevents them from being copied to the Files snapshot folder.

# in an admin console
> sc stop sqlwriter
> sc stop sqlbrowser

# assuming the default instance name of SQLEXPRESS
> sc stop mssql$SQLEXPRESS

6. In Turbo Studio, press the Catpure and Diff snapshot button.

7. Clear out all startup file entries as well as any shortcuts that were picked up by the snapshot. This will avoid starting unnecessary processes and creating undesired shortcuts when using SQL Server Express as a component of other applications.

8. To isolate the instance, edit the .xappl configuration in a text editor and add the following to NamedObjectIsolation ("SQLEXPRESS" is the default name of the instance, if your instance name is different then you will use it below). If the instance is isolated then only application from inside the same container will be able to connect to it.

<NamedObjectIsolation enabled="False">
    <Exception regex="SQLEXPRESS" />
    <Exception regex="sql\\query" />
</NamedObjectIsolation>

Troubleshooting

The SQL Server service logs are stored in the following location inside the container C:\Program Files (x86)\Microsoft SQL Server\MSSQL.1\MSSQL\LOG.

Legacy Internet Explorer and Java

A common use case in enterprise environments is using legacy Internet Explorer browser with old versions of Java. Many line of business web applications and plugins no longer work with the latest browsers. Using a legacy browser container can solve that problem and still allow your users to have all the latest operating system patches.

Below is a step-by-step guide showing how to build a standalone executable that packages Internet Explorer 8 with Java 6.

Begin by installing the Turbo Client and Turbo Studio. You can get the latest version of each here.

With the Turbo Client installed, pull the images that we need from the Turbo.net hub:

# pull internet explorer 8
> turbo pull ie:8

# pull java 6
> turbo pull jre:6

Now we will need to import those images into Turbo Studio to use. Starting with our Java 6 image, import the image from the local repository.

Select oracle/jre:6.45.

Save the imported image to a location on your machine. Here, c:\turbo\jre-6.45 was chosen.

Once the import is complete, set the Project Type to "Layer (.svm)" and set the Output File to "jre-6.45.svm". Save and build. You will now have c:\turbo\jre-6.45\jre-6.45.svm.

Now we need to import our Internet Explorer 8 image. Import from the local repository and select microsoft/ie:8.

Save the imported image to c:\turbo\ie-8.

Change the Output File to "IE8+JRE6.exe" (or any other appropriate name for your scenario).

Add jre-6.45.svm to your layers library by clicking the Layer button and then Import Layers.... Select c:\turbo\jre-6.45\jre-6.45.svm. Select jre-6.45 in the layers list.

Save and build. Below is an image of our new IE8+JRE6 standalone executable running side-by-side with native Internet Explorer 11 on Windows 10.

Microsoft .NET Core

.NET Core is a free and open-source managed software framework for Windows, macOS and Linux. It allows you to build managed applications and deploy them across many different platforms. Below are the steps to create a custom .NET Core container image for use with your applications.

Building

Download the .NET Core Binaries from https://www.microsoft.com/net/download/dotnet-core/2.1. These instructions are the same whether you are producing a build for x86 or x64 versions of either SDK or Runtime. Select the variants required for your scenario.

Decompress the .NET Core .zip file to you application build working directory. For this example, we will assume that the working directory is c:\dotnetcore-build and our .NET Core files were unzipped to c:\dotnetcore-build\dotnet-sdk-2.1.811-win-x64.

Open Turbo Studio and save the empty configuration to c:\dotnetcore-build\dotnetcore.xappl. Set the Startup File to @SYSTEM@\cmd.exe, the Project Type to Layer (.svm), and the Output File to c:\dotnetcore-build\dotnetcore.svm. Note, depending on your scenario and deployment method, your settings may vary.

Make sure that the Copy added files to configuration folder option is enabled (see the Option menu at the top-left corner of the Turbo Studio interface).

Then select System Drive in the Filesystem editor window. Click the Add Folder button and select c:\dotnetcore-build\dotnet-sdk-2.1.811-win-x64. This will add the folder to your configuration, copying the files to the c:\dotnetcore-build\Files directory.

Next add two environment variables to the configuration. Add PATH in WriteCopy isolation mode with a value of @SYSDRIVE@\dotnet-sdk-2.1.811-win-x64 (or whatever the installation path is in your container environment). This value will be added to the existing PATH value for applications that run inside the container. Also add DOTNET_SKIP_FIRST_TIME_EXPERIENCE in Full isolation mode with a value of true. This will make first runs execute much faster as unused components will not be pre-cached.

Depending on where this image is deployed, the Microsoft Visual C++ 2015 Redistributable Update 3 may be required. This can be added to your container environment from the Turbo.net hub with the microsoft/vcredist:2015 image. For standalone executables, see the article on Legacy Internet Explorer and Java for an example of how to add a dependency from the Turbo.net hub.

Save your configuration and build the image.

Testing

To test your new container image, first import into your local Turbo repository:

> turbo import svm c:\dotnetcore-build\dotnetcore.svm --name=dotnetcore

Create a new container with this image with the new command:

> turbo new dotnetcore

Start the .NET Core sample MVC website:

(container)> cd c:\dotnet-sdk-2.1.302-win-x64
(container)> dotnet new mvc
(container)> dotnet restore
(container)> dotnet publish

# start the webapp on http://localhost:5000
(container)> dotnet run

# note: this can fail with an error about 'Unable to start Kestrel' because a valid certificate was not found.
#       if so, follow their instructions and re-run:
(container)> dotnet dev-certs https
(container)> dotnet dev-certs https --trust
(container)> dotnet run

Using launch settings from C:\dotnet-sdk-2.1.302-win-x64\Properties\launchSettings.json...
info: Microsoft.AspNetCore.DataProtection.KeyManagement.XmlKeyManager[0]
      User profile is available. Using 'C:\Users\turbouser\AppData\Local\ASP.NET\DataProtection-Keys' as key repository and Windows DPAPI to encrypt keys at rest.
Hosting environment: Development
Content root path: C:\dotnet-sdk-2.1.302-win-x64
Now listening on: https://localhost:5001
Now listening on: http://localhost:5000
Application started. Press Ctrl+C to shut down.

Microsoft Office 2010

Microsoft Office 2010 is commonly used with legacy plugins or line of business applications. This can be problematic as enterprises rush to migrate their users to the latest version of Office 365 or Office 2016 which are not able to run side-by-side with Office 2010.

Fortunately it is possible to run Office 2010 applications inside a Turbo container allowing them to be isolated from existing installations. Below are the steps required to build your own Office 2010 image.

Building

In order to make an Office 2010 build, you will need to use Turbo Studio to perform a snapshot. You will need a clean machine or VM to do this on (no other applications installed, Office not previously installed). For maximum compatibility it is recommended to use a Windows 7 x64 snapshot machine and Office 2010 x86 installer.

Download the Microsoft Office 2010 Deployment Kit for App-V. This contains licensing service components that allow Office 2010 to run in a container. You want the version of the the kit (64- or 32-bit) to match the system architecture (x64 or x86), not the installation type of Office itself.

Extract the files from the deployment kit to your snapshot machine. Install the office licensing service from the extracted deployment kit:

> msiexec /i OffVirt.msi PROPLUS=1

NOTE: The parameters to pass to OffVirt.msi depend on the Office 2010 product you are installing. See How to sequence Microsoft Office 2010 for information about the options that are available.

Use Turbo Studio to Start Capture.

Install Microsoft Office 2010. NOTE: this must be done with a KMS or VLK installer. Retail licenses will not work properly.

If there are any additional components or plugins that are to be included in the build, install those now.

Once the installation is complete, run the Office applications that were installed to ensure that initial configuration and licensing is correct.

Complete the capture.

After the snapshot is complete, the Microsoft Office Snapshot wizard will present you with some options to isolate the configuration file. In almost all scenarios you will want the first option, to isolate from the native system. This will allow you to run side-by-side with native versions of Microsoft Office. In scenarios where the Office 2010 container is run with native components and plugins, then it may be required to select the second option. However, this option generally doesn't allow for side-by-side operation with native Office installations.

Set the Project Type to Standalone/ISV Application (EXE), save the configuration, and build.

Testing

To test your Office 2010 build, copy the output .exe to a new machine. You will have to install the Microsoft Office 2010 Deployment Kit for App-V in the same manner as you did on the snapshot machine.

Integration with Native Applications

Often it is desirable to integrate containers with application toolchains that are installed natively on the machine. Turbo containers have the flexibility to allow this kind of integration. Below we will walk through how to open a .PDF file defined in a container with Adobe Reader which is installed natively on the system.

Opening with native Adobe Reader

We will start by creating a simple container image which has a .PDF in it that we will want to open. I will source the .PDF from a file on my desktop and copy it into a new folder called "MyPDFs".

# start the new container, mounting the directory where the files will be sourced from
> turbo new clean --mount="%USERPROFILE%\desktop" -n=mypdfs-container

# inside the new container, create a folder and copy the files in
(container)> mkdir c:\MyPDFs
(container)> copy "%USERPROFILE%\desktop\test.pdf" c:\MyPDFs
(container)> exit

# now commit the container to a new image
turbo commit mypdfs-container mypdfs

Now that we have the new container image mypdfs, let's use it with a natively installed Adobe Reader instance. Since the container will need to be able to view the native machine in order to "see" the Adobe Reader files, we will run in Write-Copy isolation mode. In this mode, the native machine is visible to the container but any attempts to write to the native machine will be redirected to the container's sandbox.

Also note the use of adobe/disable-reader-sandbox. This is used for compatibility of the Adobe Reader instance inside the container.

> turbo run mypdfs,adobe/disable-reader-sandbox --isolate=write-copy --startup-file="C:\Program Files (x86)\Adobe\Acrobat Reader DC\Reader\AcroRd32.exe" -- c:\MyPDFs\test.pdf

5.1 Overview

Turbo Server is an application deployment platform that enables you to launch applications instantly from websites, portals and client desktops (Windows, MacOS, iOS, Android, or any HTML5 browser).

Unlike traditional deployment methods, applications streamed from Turbo Server do not require download, installation, rebooting, administrative privileges, or separate setup steps.

Turbo Application Server allows you to run application workloads on a server for your users. Turbo Application Server can source applications from the Turbo.net Hub or an on-premises Turbo Hub Server.

Getting Started

Turbo Server is available for deployment on-premises, as well as in the cloud via the Turbo Server Azure Marketplace Image (AMI).

For more information on setting up Turbo Server on-premises, please refer to the On-Premises documentation.

For more information on setting up Turbo Server in Azure, please refer to the Azure Marketplace Image (AMI) documentation.

Architecture

There are four major server roles in a Turbo Server deployment:

• The Hub Server stores all application images and user session data. The Hub may be hosted in the Turbo.net cloud or run in a customer managed cloud or on-premises server. On-premises Hub servers can federate containers to and from other Hubs.

• The Portal Server hosts the application web portal where users can log in to view and launch applications, open files, and manage Turbo resources. A portal server also provides API services allowing other client types to interact with the Turbo environment.

• One or more Application Servers runs containerized applications and streams sessions to clients. A typical deployment uses multiple application servers in a pool to handle load volumes and provide redundancy. Application servers can be hosted in the cloud or on-premises.

• The Broker Service controls how remote applications are executed in the application server pool and routes client requests to the appropriate servers.

If Turbo is used to deliver applications to endpoints or third-party streaming products for execution, only the Hub Server or a standard file server is required.

Network Diagram

Technology

Turbo Streaming

Turbo Application Server allows an application to be executed in an application server pool while streaming the application to the client machine.

Native clients are available for Windows, Mac, iOS, and Android. An HTML5 client is also available allowing any HTML5-capable web browser to access applications.

Using Turbo container technology on the application servers allows for increased user density and less maintenance than traditional remote desktop solutions.

Features

Turbo Server enables you to accomplish the following goals:

• Host containers on the web. You can stream Turbo containers from the Turbo Streaming Server portal site, custom external sites via HTML, or third-party collaborative web portals such as Microsoft SharePoint, IBM WebSphere, and Novell Teaming.

• Provide your organization with a single access point to your application portfolio. Instead of moving desktop-to-desktop to upgrade or install software, you can publish an application to Turbo Streaming Server's portal site; this provides licensed end-users with immediate access and full functionality.

• Launch applications faster over the Internet and intranets. Streamed applications launch immediately without the need to download. Turbo Streaming does not require any special ports or proprietary protocols.

• Empower a mobile workforce. Turbo containers require no installation or administrative privileges, meaning they can launch from anywhere, even on secure, locked-down desktops such as airport and hotel kiosks.

• Run multiple versions of applications side-by-side without conflicts or dependencies. Turbo containers run in isolated sandboxed environments. This enables you to avoid conflicts and dependency issues associated with natively-installed applications.

• Migrate with confidence to Microsoft Windows 11 or Windows 10. Turbo enables you to run legacy applications as they stand on newer operating systems, including Microsoft Windows 7 and 8/8.1, without the need to recode, retest, or reinstall.

Supported Platforms

Turbo Server is compatible with the following platforms:

• Microsoft Windows Server 2022
• Microsoft Windows Server 2019
• Microsoft Windows Server 2016
• Microsoft Windows Server 2012 R2
• Microsoft Windows 11 Enterprise multi-session (Azure)
• Microsoft Windows 10 Enterprise multi-session (Azure)

Turbo Server supports x64 (64-bit) processor architectures.

End users can access Turbo Server from Microsoft Windows 11, Microsoft Windows 10, Microsoft Windows 8.1, Microsoft Windows 8, and Microsoft Windows 7 platforms. Turbo Portal Server supports Microsoft Edge, Internet Explorer, Chrome, Safari, Firefox, Opera, and other HTML5-compliant browsers.

Note: Versions of Internet Explorer prior to Internet Explorer 8 are not supported. If you are accessing the Portal Site with a newer version of Internet Explorer, but experiencing problems, be sure to disable compatibility mode. This feature is enabled automatically for intranet sites and serves to emulate Internet Explorer 7 which is not supported by the Portal Site.

5.2 Setup and Deployment

Prerequisites

In this section you will learn about system and software requirements for installing the various Turbo Server components.

System Requirements

• 64-bit 2.5 GHz CPU with 4 cores or better
• Microsoft Windows Server 2012R2+
• Microsoft Windows 10+ Enterprise multi-session (Azure)
• At least 8 GB of RAM

Additional requirements for Portal role:

• Memory usage grows with the number of streamed application connections. At minimum, 2 GB plus 50 MB of memory per concurrent user.

Additional requirements for Hub role:

• Memory usage grows with the number and size of applications pushed to the server. It also grows with the number of users pulling applications and session persistence data from the Hub storage. At minimum, 4 GB plus 50 MB per concurrent user. Typical installations have between 8 to 12 GB of memory allocated for the Hub role.
• Hard disk usage grows with the number and size of applications pushed to the server as well as the number and size of containers synchronized with the Hub.

Additional requirements for the Application role:

• The server system must meet the hardware requirements for the applications that will be executed on it for application streaming. For example, if your application requires a GPU for rendering, the server must have a compatible GPU card.
• Hard disk usage grows with the number and size of applications executed on the server as well as the number and size of the user's containers.
• RDS Licensing must be configured.

For quick demo or testing:

• Standalone installation option is sufficient with all roles on the same machine.

For proof of concept or production up to 100 users:

• Farm installation option.
• Hub and Portal roles on the same server.
• One or more Application servers depending on application requirements and expected load.

For more than 100 users:

• Farm installation option.
• Hub role on its own server.
• One or more Portal servers depending on expected load. Each portal server can support 300 concurrent users.
• One or more Application servers depending on application requirements and expected load.

For additional sizing and technical guidance, contact Turbo at support@turbo.net.

Database Requirements

For production and farm install scenarios, an external database is required. It is recommended to use Microsoft SQL Server or Azure SQL. Microsoft SQL Server Express is also supported, but will require pruning because the Analytics database grows with usage and may exceed the 10GB limit over a very long period of time.

For demonstration and testing scenarios, Turbo Server is installed with an embedded Microsoft SQL 2017 Express database when selecting the standalone install mode.

Disk Space Requirements

The initial installation of Turbo Server requires 1.05 GB of free space on your hard drive.

The amount of disk space required varies based on how many applications your server hosts as well as how many users you have.

Turbo DB uses data deduplication to minimize storage consumption when multiple copies of the same data are stored on the server, so your exact needs may vary based on the content being stored.

Firewall and Security

The Turbo Server installation automatically creates firewall rules for the selected roles. These rules allow external connections to access the Turbo Server sites and services. The opened ports are listed below:

Hub Server

Portal Server

Application Server

If your Turbo Server is running behind an external firewall that restricts these ports, you may need to configure the external firewall manually. For instructions on opening ports and for recommendations on how to best secure Turbo Server, refer to Configure Turbo Server Security.

If you have disabled outbound internet traffic from your Turbo Server but want to import the pre-built application packages available on Turbo.net Hub, the following addresses must be allowed:

• https://hub.turbo.net
• https://start.turbo.net
• https://start-c.turbo.net

Deploying On-Premises

In this section you will learn about installing, configuring, and running an on-premises Turbo Server.

Before you install

Before you install Turbo Server, please ensure that you have prepared the necessary servers configurations, certificates, and information that will be required during the installation process as described in the following sections.

Prepare the server roles deployment

As described in the architecture overview, there are three server roles to provision: Hub, Portal, and Application Server. Each machine hosting Turbo Server must have at least one server role installed. Typically, for medium-size workloads (less than 200 simultaneous users), Hub and Portal share a machine, and there are one or more Application Servers for streaming the applications. The minimum requirements for Hub/Portal role are listed here.

When you need to prepare for a bigger workload (more than 200 simultaneous users), we recommend putting Hub and Portal on separate machines. For performance and high availability reasons, you may provision multiple Portal instances (one instance is capable of handling 300 user sessions). They need to be put behind a load balancer. Such setup is described in a separate doc.

Prepare a Windows account for Turbo services

For security reasons, we recommend using a Windows account other than SYSTEM for running Turbo services. Make sure that the account password does not expire. This account also accesses the SQL Server instance (unless you won't use Windows authentication), so if you are in a domain environment, the Turbo service account should be a domain account. During the setup, the installer makes sure that the account has the necessary "Log on as a service" security policy set on the local machine. On the Application Server machine, the account must be a member of the Administrators group.

Prepare the database server

Turbo Server requires an instance of SQL Server, which is accessible by all the machines running Turbo Server roles. During the setup, the installer asks for connection strings to two databases:

The default connection string to a Configuration database is Data Source=.\TURBO;Initial Catalog=Configuration;Integrated Security=True. Data Source is the SQL Server instance address, where . is the local machine. If you have SQL Server installed on a different server, place its DNS name or IP address here. Initial Configuration is the name of the database. Integrated Security=True specifies the way how Turbo services authenticate to the database server. Integrated Security is a different name for Windows authentication, and it's the recommended value. To use it, you need to make sure that the service account (configured in the previous paragraph) can authenticate to the database server and has a db_owner membership on the Configuration and Analytics databases:

Alternatively, when SQL Server allows the mixed-mode authentication, you may specify a username and password, for example, Data Source=dbserver;Initial Catalog=ConfigurationUser Id=myUsername;Password=myPassword;.

Prepare certificates for web servers

Although both Portal and Hub can serve pages using HTTP, we highly recommend configuring HTTPS. Only the Portal machine needs to be publically accessible. However, both Portal and Hub require valid TLS certificates (Let's Encrypt certificates are OK). If Hub is on the same machine as Portal, only one certificate is needed as they share the domain address. Otherwise, Hub uses a certificate for its custom domain.

Open necessary ports

All servers hosting Turbo Server roles could be placed in one internal network. Ensure all required ports are available as described here. You may need to disable IIS if it is enabled on your server and occupies required ports.

Only Portal should be accessed from the Internet and requires HTTP (80) and HTTPS (443) ports to be available externally. When HTTPS is configured, all traffic from HTTP port is redirected to HTTPS.

Installation

This section describes the installation steps. The user which runs the installation must have read and write permissions to the database since Turbo server installation will provision the necessary database tables.

Download and run the Turbo Server Installer

Download the Turbo Server installer and run the setup application.

Provide the License Certificate

After buying a Turbo Server license, you should receive from us an XML file, which is the license certificate. If you don't have it, please contact support@turbo.net. Copy the file content and paste it into the text area:

Choose the installation folder

When installing the Hub role, make sure that the installation path points to a drive with enough space to hold the application images (we recommend at least 500GB).

Similarly, Application Server also requires a bigger drive (we recommend at least 200GB) as it caches the recently used images from the Hub. Additionally, make sure the system drive on the Application Server is big enough to store user containers. For files created by users, such as project files or documents, we highly advise using OneDrive (described later); however, there are always some application internal files or configuration settings that land in the container. They usually don't take much data, but we recommend at least 128GB free space on the system drive.

There are no special space requirements for the Portal role.

Specify the Turbo Server role(s)

It is a crucial step when you decide which server roles are to be installed on a given machine. We highly recommend dedicating a separate machine for the Application Server role. For medium-sized environments, it is accepted to install Hub and Portal roles on the same machine.

Configure the webserver URL

You will see this step only when configuring the Hub or the Portal role. The address in this field is the address at which the Portal/Hub will listen for connections. If the webserver is behind a load balancer, the address in this field should be the public address of the load balancer.

If Microsoft IIS is already on the machine then port 80 may already be in use. Verify that the ports assigned to the Administration and Hub sites are not already in use.

Configure the database connection strings

If the Farm server role was selected, the Database Setup page will request database connection information to an external SQL Server Database. When using an external SQL Server Database, be sure that the "Log On" user for the Turbo Server Windows Service has the appropriate access to the database. It may be necessary to modify the Log On user for the service by editing the service details after installing Turbo Hub Server.

Note: Turbo Server supports all versions of Microsoft SQL Server 2005 or newer and Azure SQL. Any connection string format supported by Microsoft SQL Server may be used.

Please check the section above when we prepare the database.

Configure the Turbo services account

In this step, provide the credentials for the account the Turbo services should use. Please check the preparation steps if in doubt.

The password must conform to the Turbo Server password policy.

Configure the Hub administrator account

It is the account you will later use to administer the Turbo Server environment.

After this step, the installation starts and should finish within about five minutes. If you experience any errors, please check the setup logs in the {install-dir}\Logs folder. If it is still unclear why the setup failed, please zip the logs and send them to support@turbo.net.

Post-installation configuration

Some of the settings are available only after the server is installed, and we describe them in this section.

Authentication

The Users tab in the administrative screen allows the administrator to manage the user accounts as well as change the way Portal authenticates the users.

If you plan to use custom or Active Directory accounts, please visit this page in our documentation.

If you plan on configured Single Sign-On, Turbo Server supports identity providers that support SAML 2.0 and OpenID Connect authentication. Please visit the SAML 2.0 and OpenID Connect authentication pages for more information.

Cloud Storage and other settings

To enable OneDrive mounting in user sessions, you need to register a OneDrive client ID and secret in the Cloud Storage section. The steps how to do that are described here.

Licensing servers

If you use software that requires a license server, you may configure network connectivity between the Application Servers and the license server. That will work for streamed (cloud) sessions.

For native launches, we provide a tunneling option (in preview) through Portal. In this scenario, the Portal needs to have connectivity with the license server. The tunnel allows users to runs the licensed applications natively. To learn the details, please contact support@turbo.net.

Changing the database connection string

To change the database connection string after installation on any server in the domain:

1. Open c:\programdata\turbo server\settings.xml.
2. Edit the DbConfigurationConnection and DbAnalysisConnection element values in the xml.
3. Open Task manager and restart Turbo service.
4. Verify on the admin domain page the server status is Online.

Deploying to Azure

In addition to on-premises deployment, a preconfigured Turbo Server instance can be deployed via the Turbo Server Azure Marketplace Image (AMI). The Turbo Server AMI has multiple plans which are preconfigured with the following components:

• Hub and Portal
• Hub, Portal, and Application
• Application

Users will need the following to deploy the Turbo Server AMI:

• Azure subscription
• Purchased or trial Turbo Server license

The following network ports are open by default once the Turbo Server AMI is deployed. These can be adjusted as necessary via the Azure Portal when the deployment is complete.

• 3389: RDP
• 80: HTTP
• 443: HTTPS

Note: While there are no extra charges to deploy the Turbo Server AMI, the Azure subscription will still be charged for any usage.

Hub and Portal Role Deployment

To deploy a Turbo Server AMI that includes the hub and portal roles go to portal.azure.com, click Create a resource, search for "Turbo Server", select a desired plan which includes the hub and portal roles, and click Create.

The following information is required to deploy Turbo Server AMIs prior to version 21.7:

• Resource group: New resource group to deploy the AMI
• Region: Azure region to deploy the AMI
• Virtual machine name: Hostname of the VM
• Administrative username and password: Local administrative account on the VM
• Database username and password: SQL account that will be used to access the SQL databases
• DNS prefix: Prefix of the DNS record automatically created during deployment
• Turbo Server license: Valid Turbo Server license to apply during deployment of the AMI

The following additional information is required if deploying version 21.7+ of the Turbo Server AMIs:

• Turbo Server administrative username and password: Administrative account for the Turbo Server instance
• Database username and password: SQL account that will be used to create and access the Azure SQL databases

Note: The virtual machine size can be altered prior to deployment. On the Virtual Machine Settings tab click Change size to select a different virtual machine size.

Click Create when all the required information is added to the deployment and the review step passes validation.

It takes about 10 minutes to complete the deployment. When it is complete, go to the administrative URL of the deployed Turbo Server AMI. This is the DNS name from the Overview page of the deployed Turbo Server AMI VM in the Azure Portal.

Configure administrative user

Note: This step is not needed if deploying version 21.7+ of the Turbo Server AMIs.

The Turbo Server instance is deployed without an administrative account. To setup an administrative account go to the administrative URL of the deployed Turbo Server AMI. This is the DNS name from the Overview page of the deployed Turbo Server AMI VM in the Azure Portal.

To get to the administrative portal add "/admin" to the URL.

From the administrative portal go to Users.

Select "administrator", add a new password, and click Save.

Next step is to add the "administrator" user to the Server Administrators group. This will grant Turbo Server administrative permissions to the "administrator" user. From the administrative portal go to Users.

Open the Server Administrators group, click Add Members, select the "administrator" account, and click Save twice.

This will add the administrator user to the Server Administrators group. This will also cause the Turbo Server Service to restart to complete the changes. Once the restart is complete you will be redirected to the sign-in page. Sign-in with the "administrator" user to verify access.

The required post deployment steps for the hub and portal roles are complete if the sign-in was successful. However, for security reasons, it is strongly recommended to switch the portal to HTTPS. Please check the Managing a Server section to setup HTTPS.

App Role Deployment

To deploy a Turbo Server App AMI go to portal.azure.com, click Create a resource, search for "Turbo Server", select the App plan, and click Create.

Note: An existing Turbo Server AMI with the Hub and Portal roles is required to deploy the App role AMI.

The following information is required to deploy Turbo Server App AMI prior to version 21.7:

• Resource group: New resource group to deploy the AMI
• Region: Azure region to deploy the AMI. It is required to deploy to the same region as the existing Hub and Portal VM.
• Virtual machine name: Hostname of the VM
• Administrative username and password: Local administrative account on the VM
• Hub server address: Internal hostname or IP address of the Hub and Portal AMI the App AMI will be attached to
• Database username and password: Existing SQL account from the Hub and Portal AMI the App AMI will be attached to
• Turbo Server license: Valid Turbo Server license to apply during deployment of the AMI

The following additional information is required if deploying version 21.7+ of the Turbo Server App AMI:

• Azure SQL Private Endpoint URL: Private endpoint URL for the Azure SQL instance created for the Hub and Portal AMI. To find this URL go to the resource group of the Hub and Portal AMI, open the Private endpoint resource and click DNS configuration. The required URL is the FQDN listed under config1. It will look similiar to random-string.privatelink.database.windows.net
• Database username and password: SQL account that will be used to create and access the Azure SQL databases

The same virtual network and subnet for the Hub and Portal AMI is required on the App AMI. This is the Virtual network/subnet from the Overview page of the deployed Hub and Portal AMI VM in the Azure Portal. Apply the same virtual network and subnet to the App AMI on the Virtual Machine Settings tab.

Note: The virtual machine size can be altered prior to deployment. On the Virtual Machine Settings tab click Change size to select a different virtual machine size.

Click Create when all the required information is added to the deployment and the review step passes validation.

Additional configuration steps to setup Turbo Server:

• Add applications to the Hub
• Configure Users, Directory Services, and Groups
• Configure Workspaces

Virtual Desktop Infrastructure (VDI)

Virtual Desktop Infrastructure

The following documentation describes how to setup Turbo Server in a Virtual Desktop Infrastructure (VDI) environment.

Windows Virtual Desktop

The following are required to add applications from a Turbo Server workspace to Microsoft Windows Virtual Desktop (WVD) session hosts in Azure:

• Shared image disk
• Turbo Client installed and configured

Shared Image Disk

A shared image disk is a central repository of the application images. A central repository is recommended to reduce the application image transfers and to save disk space on the WVD session hosts.

An Azure managed disk with sharing enabled can be used for this purpose and can be created with the Azure CLI or the Azure Portal:

Azure CLI:

az disk create -g <wvd-resource-group> -n <sharedimagedisk-name> --size-gb 1024 -l <azure-location> --sku Premium_LRS --max-shares

Azure Portal:

Follow the Azure documentation to create a managed disk and be sure to set Enable shared disk and set the Max shares to an appropriate number. https://docs.microsoft.com/en-us/azure/virtual-machines/windows/attach-managed-disk-portal#add-a-data-disk

Note: Different disk sizes may have a different max shares limit. https://docs.microsoft.com/en-us/azure/virtual-machines/disks-shared

The shared image disk will need to be attached to each WVD session host. This can be accomplished with the following methods:

• Manually attach the disk to the WVD sesison hosts: https://docs.microsoft.com/en-us/azure/virtual-machines/windows/attach-managed-disk-portal#add-a-data-disk

• Attach the disk during deployment via an Azure Resource Management Template:

    "dataDisks": [
        {
            "lun": 0,
            "createOption": "attach",
            "caching": "None",
            "writeAcceleratorEnabled": false,
            "managedDisk": {
                "id": "/subscriptions/b11ccec5-c64c-4633-8e45-5dfd5db5e408/resourceGroups/path/to/shared-image-disk/providers/Microsoft.Compute/disks/<sharedimagedisk>"
            }
        }
    ]
  

Turbo Client

The following are needed to setup the Turbo Client on the WVD session hosts:

• Install the Turbo Client and point to the Turbo Server URL
• Login to Turbo Server with the Turbo Client
• Subscribe to the applications in a workspace

These commands can be run manually if the session host VM images are deployed from a custom image, added to an image builder configuration (i.e Packer), or run automatically during session host VM deployment with the Azure Custom Script Extension.

Sample command to install the Turbo Client, set the Turbo server URL, and set the image path to the shared image disk created above:

turbo-client-setup.exe --all-users --silent --domain=<turbo-server-url> --add-trusted-source=<turbo-server-url> --image-path=<path-to-sharedimagedisk>

Sample commands to login to the Turbo Server with a user account or an API key:

turbo.exe login --all-users

turbo.exe login --all-users --api-key=<api-key>

Turbo Subscribe is used to add all the applications from a workspase on to the local computer. Here is a sample command to subscribe to the applications in a Workspace:

turbo.exe subscribe --all-users <workspace>

WVD Portal

When the above steps are complete the applications from the Turbo Server workspace will be visible on the WVD session hosts. Access these hosts via the WVD Portal.

Refer to the Turbo Server workspace or Add/Remove Programs application on the WVD session hosts to verify which application were added.

5.3 Licensing

Turbo Server License

The standard Turbo Server license, Turbo Server Enterprise Edition, consists of a server license and a custom number of unique or simultaneous end-users. The standard license enables an unlimited number of applications to be hosted on Turbo Server.

Users are typically accounted for with a username and password. However, you can use anonymous users. In this case, each user is defined by the domain of the hosted Turbo Server and a specific username, such as SomeCompany\SomeUser.

The Turbo Server administrator can activate and deactivate users as needed, or add additional allowed users or devices by upgrading the license. For more information about managing users refer to Managing Users and Authentication. For instructions on applying a new license to Turbo Server, refer to General.

RDS License

Servers with the Application role must have RDS licensing configured, please refer to the Microsoft documentation on how to do so.

Please note that RDS Per User CALs are not supported with the default Temporary Profile login mode. Per the Microsoft documentation, RDS Per User CALs can only be assigned to Active Directory users and temporary profiles use local non-Active Directory users.

If using Temporary Profile login mode, the application servers must be configured with RDS Per Device CALs.

Application License

Application licenses can be implemented by the native application, such as connecting to a license server, or controlled by Turbo administrative settings. Turbo allows administrators to limit the number of concurrent and named user or devices on a per application basis. See the Workspace Applications documentation for details.

5.4 Portal

Overview

The Turbo Server Portal is a web portal where users can log in to view and launch applications. Applications can be streamed from the Turbo Application Server using the Turbo Clients or HTML5 client, or ran locally using Turbo for PC. Additionally, the portal provides API services allowing other client types to interact with the Turbo environment.

Logging In

Portal user authentication is determined by the Authentication Type configured in the Turbo Server administration site.

If the server has an Authentication Type that requires users to log in with a username and password, users must provide valid credentials to access the Portal and launch applications. However, if the server has enabled anonymous access, users can access the Portal and launch applications without logging in.

If you are a user and need to log in but do not know your username and password, contact your Administrator to retrieve your credentials.

Installing the Turbo Client

For the best experience, it is recommended to install and use one of the native Turbo.net clients on your device. Turbo.net provides clients for all major desktop and mobile platforms.

If you do not use one of Turbo.net client applications, you can still use Turbo via the HTML5 interface in any major web browser.

• Turbo.net for PC
• Turbo.net for Mac
• Turbo.net for iOS
• Turbo.net for Android

If you are on a device issued by your organization, your system administrator may already have installed the necessary Turbo Client on your device.

Browser Support

The Turbo Portal supports the latest versions of modern browsers. For the best experience, we recommend using one of the following browsers:

• Google Chrome
• Apple Safari
• Mozilla Firefox
• Microsoft Edge

Using unsupported browsers or older versions may prevent some site features from functioning as expected. Some features have additional browser requirements, which are noted in the appropriate documentation.

Dashboard

The Dashboard is the primary end user interface provided by the Portal. Once the user logs in and accepts the optional notice and consent form, they are presented the Default Workspace, or a list of workspaces if they have permissions to more than one.

Click on a workspace to navigate into the workspace. The workspace will show a list of applications which the user has access to. To navigate back, use the breadcrumb at the top of the page.

Applications

Run applications by clicking on them. The application will run with the default launch method, which by default is Run in Cloud (HTML5). The administrator can change the default in the Workspace Application settings. Right click on the application to access addition launch methods if available.

Application Context Menu

The application context menu provides additional launch methods and controls for running sessions.

The following context options will launch the application

• Run in Cloud (HTML5): Launches in the cloud and connect using HTML5 client running in the browser.
• Run in Cloud (Windowed): Launches in the cloud and connects using the natively installed Turbo Client. The client must be installed.
• Run on My PC (Local): Launches in the local device if the device is capable of running the application.

The Install on My PC option will make the application available on the local device if supported.

The following context options are available if the application is currently running in the cloud:

• Disconnect: Disconnects any connected client from the cloud session. The session may be reconnected by launching again via any cloud option. If the administrator logs off the session immediately on disconnect then the application may have to be relaunched from scratch.
• Logoff: Logs off the user from the cloud session. The application must be relaunched and unsaved work may be lost.

Files

The Files tab allows users to browse and open files from their connected cloud storage providers. Cloud storage providers may be connected from the user settings Storage page.

Clicking on a folder will navigate into that folder. Users may navigate out of a folder by using the breadcrumb at the top of the page.

Clicking on a file will open it with the associated application. If no associated application exists, the view file action will be performed instead.

File associations may be managed from the workspace administration site.

File Context Menu

Right-clicking a file or folder will open a context menu with additional actions. For files, the available actions are:

• Open in Cloud (HTML5): Opens the file with the associated application in the HTML5 client.
• Open in Cloud (Windowed): Opens the file with the associated application on the application server and streams to the local Turbo client.
• Open on My PC (Local): Opens the file with the associated application in the local Turbo client.
• Download: Downloads the file to the local device.
• View: Opens the file in the local client browser. If the browser supports the file type, the browser will show a preview of the file.
• Delete: Deletes the file from the storage provider. A confirmation dialog is shown before deletion.

For folders, the available actions are:

• Delete: Deletes the folder and all of its contents from the storage provider. A confirmation dialog is shown before deletion.

Uploading Files

Users may upload files by dragging & dropping files from their local device into the file browser. Files may be dropped anywhere on the screen and will be uploaded into the current folder.

Links

The links tab contains links to external web resources such as file downloads and web sites.

Links may be managed from the workspace administration site.

Notifications

A notifications icon is displayed at the top of the Turbo Portal dashboard. clicking the notification icon will expand the notifications dropdown and list notifications in chronological order. A new notification icon will be displayed if there are unread notifications.

Search

The search text box searches the current workspace tab for related items by name.

Running Applications

Turbo applications can be ran using the Turbo Server Portal or, if installed to your local machine, directly from the Start Menu or Applications folder.

Portal

To run an application, go to the Turbo Server Portal and click on the application you want to run.

By default, applications launches will open the HTML5 client and stream the application session to the web browser. Alternately, you can run the application in one of the Turbo Clients by right-clicking on the icon and selecting Run in Cloud (Windowed).

If you are on a PC that meets the application requirements, you also have the option of running the application on your own device. There are no separate installation steps required to run applications once the Turbo for PC application is installed.

To select a specific way to run the application, right-click on the application and select one of the following:

1. Run in Cloud (HTML5): The application will run in the cloud and stream to your device inside the web browser.
2. Run in Cloud (Windowed): The application will run in the cloud and stream to your device via the Turbo.net native application.
3. Run on My PC (Local): The application will be downloaded and run on your device.
4. Install on My PC: The application will be installed on your device.

The default and available launch locations may be configured by your server administrator.

User Settings

The Settings pages allows users to manage a variety of user-related settings, such as their cloud storage connections and remote authentication.

This page is accessible from the Portal via the Settings link in the user dropdown.

Storage

The Storage page allows users to manage their cloud storage connections. Once connected, files from that cloud service will be made available in the Portal Files browser. Furthermore, applications launched in the cloud will automatically map their cloud storage folder to the T: drive.

For more information on connecting storage services and accessing files, see the End User Guide

Authentication

The Authentication page allows users to save Windows login credentials that will be used to login to the application server when launching cloud applications with Ask authentication. Users may also save their Windows login credentials when launching an application in the HTML5 client by checking the "remember me" checkbox on the login form.

Credentials are encrypted and stored in local browser storage and are never stored on the server. Users must re-enter their credentials on new browsers, devices, and Turbo login sessions.

If the stored credentials are invalid, an authentication error will be shown and the user will be asked to re-enter their credentials. Credentials may be removed from the settings page at any time.

This feature is not available in Internet Explorer 11 or below. The Turbo Server must have SSL enabled to use this feature.

5.5 Administration

Overview

The Turbo Server Administration Site enables you to manage and control all aspects of your Turbo Server.

The default location of the Administration Site is: http://localhost:80/admin, and consists of the following links:

• Hub: This page lists all applications repositories on your Turbo Server. From here Federation can be configured to source application repositories from a master hub. API Keys can be defined to allow access to your hub without using a password (useful for automation, tooling, federation, and other similar scenarios). For more information refer to Managing Hub.

• Users: This page list all users and groups on your Turbo Server. From here Directory Services can be configured to import users from LDAP or Active Directory. Authentication Method allows you to configure how users will authenticate with the Turbo Server. Device Keys allows you to manage all registered devices. For more information refer to Managing Users and Authentication.

• Domain: This page lists all servers that are included as part of the current Turbo Server installation. Server settings such as roles, web service bindings, and SSL certificates may be configured here. For more information refer to Managing the Domain.

• Workspaces: This page lists all workspaces on your Turbo Server. From here workspaces may be added, configured, and deleted. For more information refer to Managing Workspaces.

• Reports: This page provides preconfigured customizable analytics reports, sorted according to Administration, Hub, and Users. For more information refer to Reports.

• Integrations: This page provides options to configure integrations with variety of third-party services, such as cloud storage providers and Learning Management Systems. For more information refer to Integrations.

• General: This page contains a summary of your Turbo Server license, and information and options for configuring Turbo Server. For more information refer to General.

Browser Support

The Turbo Server administration site supports the latest versions of modern browsers. For the best experience, we recommend using one of the following browsers:

• Google Chrome
• Apple Safari
• Mozilla Firefox
• Microsoft Edge
• Internet Explorer 11 (limited support)

Using unsupported browsers or older versions may prevent some site features from functioning as expected. Some features have additional browser requirements, which are noted in the appropriate documentation.

Hub

All application repositories on Turbo Server are managed from the Hub page of the Administration Site.

For more information on adding application repositories to the Hub, see Deploying to Turbo Server

Managing Repositories

On the repository edit page, a repository display name can be modified. This shows up in the hub administration page list. The repository ID field cannot be modified and is assigned when the first container image is pushed to the hub.

The versions list shows all available images that are available for this repository. They can be referenced by their tag or their ID (ex, "mozilla/firefox:64.0" or "mozilla/firefox#44397e23bf46a08a8a567ba13b2c215668d451c9dde41b030706779dc977cc02"). Accessing a repository without a tag or ID will use the latest available image (ex, "mozilla/firefox"). Note that any repository updates may take up to 24hrs to be automatically retrieved by the Turbo Client.

The Dependencies and Used By lists shows all images referenced by and referencing this repository image. Dependencies are downloaded on-demand when creating a new session. For more information on dependencies, see Dependencies

The Pre-cache setting specifies whether to cache the repository on application servers. Pre-cached repositories are pulled onto the application servers every 10 minutes. A workspace may also pre-cache the repository.

The Federation section allows enabling or disabling repository federation from a configured federation source. The selected federation source's settings will be used to determine the federation behavior. If you wish to create a new federation source, please see Federation.

Importing Repositories

With the Import Repository feature, you can import repositories from an external Hub server, such as the Turbo.net Hub, into your local Turbo Server Hub. To import a repository, click the Add Repository dropdown on the Hub page and click Import Repository. The import page has the following options available:

• Hub Source URL: The Hub server from which the repository will be imported. By default only app.turbo.net is available, however if you have domain federation enabled the source domain will also be available.

  If your Turbo Server is running behind a firewall or proxy you may need to whitelist app.turbo.net to import repositories from the public Turbo Hub.

• Repository Id: The name of the external repository. For example, mozilla/firefox.

• Release: Only revisions with this release are imported from the external repository. Leave blank to import without release restrictions.

• Revision History Length: The number of revisions to pull from the remote repository. The default value is 1 revision. Revisions are imported in descending release order.

• API Key: The API key used to access private repositories from the source Hub. This field is not required for public repositories.

After setting the properties, click Import. The import may take a few minutes to complete depending on the size of the repository. After the import is complete you will see the new repository in your main repository list on the Hub administration page.

Imported repositories will enable federation from the import source URL by default. Federation may be disabled from the repository settings page.

API Keys

API Keys allow you to login to your hub with a code other than with a username/password. This is useful when configuring automation or in other scenarios where a plain text password is not desirable. If an API Key has been compromised, it can be refreshed to a new value or deleted to immediately revoke access.

Additional, you can configure a Configuration API Key used by the Launch Configuration Service to post custom application configurations. Configurations posted with this API key are publicly accessibly. This setting is recommended if you will be using an external portal instead of the Turbo Portal.

The length of time (in milliseconds) that a configuration is valid after it is added to the launch configuration service can be configured with that Configuration Cache Expiration setting. This timeout is reset any time the application configuration is accessed, such as during an application launch.

When adding an API Key, give it a name that describes the general usage of the key. It is also recommended to have distinct keys for distinct usages so that if one is compromised or updated, all usages will not require update. Run as System controls whether the key is given administrative privileges to push new images or delete repositories. Without this setting, the API key will only have read access to repositories.

Federation

The Federation page allows you to configure repository federation sources, which can be selected during repository import or applied to individual repositories to reduce setup time and keep repositories in sync across domains. Repositories that have federation enabled will periodically check the source domain for updates and pull any changes.

Please be aware that any setting changes to a federated repository will be overwritten by the repository settings on the source domain.

Federation sources can be configured with the following settings:

• Source Domain URL: The federation source domain URL from which repositories will be replicated.
• API Key (Optional): The API key used to access repositories from the federation source. This API key must be configured as a system-level key on the source server. This setting is not required for public hubs. For more information, see API Keys.
• Default Synchronization Frequency: The frequency at which this server will check the federation source for updates.

Users

Turbo Server users are tracked and managed via the Administration Site. Users are entered manually or via automated import from LDAP or Active Directory directory services. Users and user groups can be viewed and managed on the Users page. From this page you can view user directories, status, and available actions. Displayed above the user list is the total number of licenses available and the number of licenses currently in use.

Users can be internally created users, synchronized users from external directory services, or a user associated from a API key. API key users cannot be deleted unless the API key is deleted.

Managing a User

To manage a user, select the user name from the list on the Users page. The following fields are displayed on the page:

• Name: Full name of the user.

• Login Name: The unique login name for the user.

• Enabled: Determines whether a user can access Turbo Server. After a user is disabled he no longer consumes a seat.

User Permissions

The Permissions tab lists all user groups to which the user belongs. User groups determine which workspaces a user can access.

For more user group management options, please see Managing a User Group.

User Sessions

The Sessions tab lists all persisted sessions for the user. Session persistence is enabled by the Sessions are persistent workspace application setting, which automatically synchronizes the user state and settings with Turbo Server.

Reset: Resetting a user session will delete all of the synchronized state and settings from Turbo Server. Sessions that are cached on the user's local device will be reset the next time they run with session persistence enabled.

Delete: Deleting a user session will delete all of the synchronized state and settings from Turbo Server. Sessions that are cached on the user's local device will not be deleted. To prevent the locally cached session from synchronizing to the server you may disable session persistence in the application settings.

Managing a User Group

To create a user group select Add Group. The Add User Group screen displays. This screen contains the following fields:

• Name: The group name that displayed on the user screen.

• Description: A group description (optional).

• Members: Users and groups that are members of this group. Users and groups are inherited when including other groups as members. Add users or other groups by selecting Add Members.

The following groups are special groups that are created automatically and cannot be deleted:

• Administrators: This group will be able to log into the administration site and push shared images. Note that changes to the Administrators group will require a service restart before they are honored by the hub services. Access to the administration site will be honored immediately.

• Analysts: Users in the Analysts group will have access to the administration reports. No other administrative permissions are granted beyond access to reports.

• Anonymous: This group automatically includes any user discovered when the authentication mode is set to Anonymous.

• Everyone: This group automatically includes all users regardless of authentication mode.

Adding an External Directory Service

Using Turbo Server you can add an external directory service, such as Active Directory. This enables you to manage users with the touch of a button and easily import existing users and groups into Turbo Hub Server. Complete the following steps to add an external directory service:

1. Open a Turbo Server administration site page in your web browser.

2. Choose the Users category from the top navigation bar.

3. Select Manage Directory Services.

4. Select Add Service. The Add Directory Service screen displays.

5. Enter your specific settings into Turbo Server. Each section is detailed below.

Note: When synchronizing external directory-services containing of over 5,000 users, the command-line administration utility should be used instead of the Administrator web site. For more information on using the administration utility, see Manage Turbo Server from the Command Line. Synchronizing large directory services uses up to 1 GB memory per 500,000 users and groups on the hub server. Ensure that your hub server has enough memory to handle ordinary load when the directory service sync is running.

Choosing Your Connection Settings

Complete the following steps to choose your connection settings:

1. Enter the settings for the Server section. The Host, Port, and Top directory are initialized with typical values, but you can customize them to match your directory service settings. They are best discovered using the management tools for the application that hosts them, such as Microsoft Windows or Apache Directory Services.

   • The Top directory should be specified to avoid potential login issues that are difficult to troubleshoot.

2. Set the Binding Type. Changing the Binding Type will change the Port to the standard LDAP port number for that setting, if you have not specified another port number.

   • Choosing the Simple binding type is not recommended if you are binding to Active Directory, but it can be useful while on the page in diagnosing connection problems via the Test button.

3. Enter your credentials at the Synchronization Account section. To connect with a specific account in the Synchronization Account section, specify the username:

   • Active Directory: The domain login (e.g. acme\aaron)

   • Generic LDAP: The distinguished name (e.g. uid=aaron,ou=acme,ou=system)

4. To test these settings, click on the Test button.

5. Once the test is successful, proceed to the Directory Schema section.

Directory Schema

Directory schema settings are customizable within any directory service; you can change these settings to match the names in your directory service. The most common schema values are tried by selecting Discover. You can select Discover when you are not satisfied with the result in the Synchronized Directories section. Complete the following steps to use the Discover functionality:

1. Select Refresh from the Synchronized Directories section and inspect the results. If the users and groups shown there are accurate, leave the directory schema settings as they are.

2. If the Synchronized Directories does not accurately depict the users and groups you expect, select Discover and wait for the schema settings text boxes to fill with the recommended values. Test these values at any time from using Refresh in the Synchronized Directories section.

3. If you know the correct schema name for the given properties, you can enter it manually. If there are more than one name for the same value you can enter each name separated by a semicolon. Each is searched during synchronization.

4. To reset the settings to the Turbo Server default, select Defaults.

Choosing Items to Synchronize

You may limit the scope of users and groups that will be synchronized from your directory service, either by choosing specific directories within the service, or by selecting the user groups in which you are interested.

Choosing directories

Your directory service might contain some subdirectories that have useful information and others that contain unwanted information. You can choose which subdirectories to synchronize using Synchronized Items, selecting the Directories option. Complete the following steps to use Synchronized Items:

1. Select Refresh to use the current connection and directory schema settings to scan your directory service. Information about discovered sub-directories is available via tooltip popups. For large directories this operation can take several seconds to complete.

2. To narrow the scope of your synchronization to specific directories complete the following:

   a. Uncheck Include All. b. Filter results using the search text box (group name prefix). c. Check directories to include.

Choosing groups

You may have a specific subset of existing users that will use Turbo Server, in a group or groups native to your directory service. You can choose which groups to synchronize using Synchronized Items, selecting the Groups option. Complete the following steps to use Synchronized Items:

1. Select Refresh to use the current connection and directory schema settings to scan your directory service. Information about discovered group is available via tooltip popups. For large directories this operation can take several seconds to complete.

2. To narrow the scope of your synchronization to specific groups complete the following:

   a. Uncheck Include All. b. Filter results using the search text box (group name prefix). c. Check groups to include. All members of that group will be synchronized, including contained groups and all of their members.

When you are satisfied with your settings, select Save. At this point, the users and groups in your directory service are not synchronized with Turbo Server. From the Manage Directory Services page, click the synchronization button and verify there are positive counts for users and/or groups when it has finished. For large directories this can take several seconds.

NOTE: External users synchronized from active directory should not use the login prefix when logging in. User names must be unique, so if there are two users from different active directory sources, only the first one will be synchronized. Password verification is passed through to the active directory service and are not stored on Turbo Server.

Authentication Method

The Authentication Method page configures which Authentication Method is used when an end-user logs into the Hub Site and Turbo Client. The supported methods are:

• Anonymous: Anonymous authentication allows users to access the Portal without logging in. All anonymous users are added to the Anonymous Users group.

• Username and Password: Username and Password authentication requires users to provide their username and password in order to log in. Passwords may be managed from the user settings page.

• Single Sign-On: Single Sign-On authentication allows users to login to Turbo Server using an external directory service, such as Azure AD or ADFS. Turbo Server currently supports the following Single Sign-On Methods:

  • OpenID Connect: This option will redirect users an identity provider login page that supports OpenID Connect authentication. Upon a successful login, the user will be redirected back to Turbo Server and an account will be created using the basic profile information provided by the OpenID claims. Some example identity providers that support OpenID Connect include AzureAD and Google. For more information, refer to OpenID Connect.

  • SAML 2.0: This option will redirect users an identity provider login page that supports SAML 2.0 authentication. Upon a successful login, the user will be redirected back to Turbo Server and an account will be created using the basic profile information provided by the SAML response attributes and claims. Some example identity providers that support SAML 2.0 include AzureAD and ADFS. For more information, refer to SAML 2.0.

• Ticket Expiration Time: The amount of time that a login ticket is valid. By default the login ticket when logging in from the Portal will be kept for 7 days if the remember me checkbox is enabled.

• Check for compromised passwords: Checks the haveibeenpwnd database for compromised passwords when creating setting the password for internal users.

• Integrated Windows Authentication Host: The IP or hostname of the domain controller for clients using IWA. Select Default to automatically detect the domain controller's IP address.

Device Keys

The Device Keys page lists all devices that are registered to the Hub Server. Devices are automatically registered with the Hub Server when subscribing or installing applications. Device Keys may be deleted in order to immediately revoke that device's access to the Hub Server.

Domain

The Dashboard page shows real-time graphs detailing the total CPU, memory, number of sessions, and other resource usage information for the application servers.

Domain Servers

The Server page lists all servers that are included as part of the current Turbo Server installation, along with their current status. Clicking a server name will navigate to the server configuration page.

Add Server

The Add Server page allows administrators to add additional application servers to the current Turbo Server farm.

Prerequisites

Add Server currently only supports deploying application servers to Azure environments. Support for other compute infrastructures may be added in the future.

The Turbo Server farm must be running in Azure with an Azure SQL Database connection. Adding Azure application servers to a on-premises Turbo Server installation is not supported.

In order to add a server you must first setup a Compute Infrastructure and follow the Setup Guide. This feature is only available in Turbo Server 23.1 and above.

Deploying an Application Server

To deploy an application server, complete the Add Server form with the following values:

• Compute Infrastructure: Select the compute infrastructure configured in the Compute Infrastructure section
• Resource Group Name: Leave as default to use the same resource group that is configured in the compute infrastructure setting, or enter a new resource group name. A new resource group will be created if the specified resource group is not found.
• Server Name: Enter any descriptive name for the application server (ex turbo-app1)
• Administrator Username: Enter any desired administrator username that conforms to the compute infrastructure's username requirements
• Administrator Password: Enter any desired administrator password that conforms to the compute infrastructure's password policies
• Confirm Password: Re-enter the password from above
• Public IP Address: It is recommended to disable the Public IP address in production environments

Once you have completed the form, click Add to deploy the application server. After a short delay a new tab will open to the Azure deployment status page. The deployment will take several minutes, you may view the current status as well as any deployment errors on the Azure deployment status page.

Once the deployment is complete the application server will automatically be added to the Domain server list and start accepting application loads.

Domain Settings

The Settings page lists allows you to configure domain-wide settings, including:

• Domain URL: The public facing URL intended for end users to access Turbo. The firewall or load balancer should resolve this to your portal instances. For more information, see Understanding the Domain URL.

• Hub Domain URL: The public facing URL for Turbo Hub web services. If this field is not specified, the Domain URL is used.

• Portal Domain URL: The public facing URL for Turbo Portal web services. If this field is not specified, the Domain URL is used. Users must use this URL to access the portal and is typically the same as the Domain URL.

• External Administration Site: Allows external network access to the administration site from the domain url.

• API Rate Limiting: Limits the maximum number of API requests allowed per IP address per second. If this limit is exceeded, the request is rejected with a 429 Too Many Requests error response. Rate limiting is enabled by default with a limit of 20 requests per IP address per second. Enable rate limiting to deter denial of service or brute force password cracking attacks. The rate limit should be disabled if there will be many users attempting to use the service from a single IP address.

• Resource Allocation Strategy: The load balancing strategy used to allocate applications to application servers. The available strategies are:

  • Active Sessions: New application requests will be allocated to the active application server with the lowest active session count. Note that active session counters may be delayed until the application is fully launched and may not be balanced if a user launches many applications at the same time.
  • Total Sessions: New application requests will be allocated to the active application server with the lowest total session count.
  • CPU Load: New application requests will be allocated to the active application server with the lowest CPU load.

• Default Launch Mode: The default launch location used when launching applications from the dashboard. If an application is configured with its own launch location, that setting will take precedence. The available options are:

  • Run in Cloud (HTML5): Application launches will open a new browser tab to which the application will stream from the application server.
  • Run in Cloud (Windowed): Application Launches will open a new browser tab and attempt an auto-launch. If a native client is installed, the application will stream from the application server.
  • Run on My PC (Local): Application Launches will open a new browser tab and attempt an auto-launch. If a native client is installed, the application will run on the local machine.

• URL Redirects: Redirects requests from the host name to the target URL with a permanent redirect response (301). The host name must resolve to the domain in order for the redirect to occur.

Domain Federation

The Federation page allows you to configure federation across multiple domains to reduce setup time and keep domain resources in sync. According to these settings, the server will will periodically check the source domain for updates and replicate any changes.

A domain federated server replicates the source server's workspaces, workspace permissions, and the workspaces' associated image repositories. In addition, the source server's users, groups, directory services, and identity method are also replicated to allow the users to run applications from workspaces using the same login identity. If the identity method is an external authentication method such as Azure AD, the subdomain's redirect url must be added in the Azure Portal.

If an existing login name or built in group, directory service, or user exists on the server, it will not be replicated. For example, the built in SYSTEM user will not be replicated. Replicated users will automatically belong to the 'Everyone' built in user group, but not the Anonymous or Administrator built in user groups.

If an existing workspace with the same url friendly ID exists on the subdomain, it will be overwritten. If the source workspace permission references a built in group (Anonymous, Administrators, or Everyone), it will be normalized to reference the subdomain's built in group and automatically apply to the users belonging to those groups.

The available configurations are described below:

• Source Domain URL: A federation source URL from which domain resources will be replicated.

• System API Key: The API key used to access federation resources from the federation source. This API key must be configured as a system-level key on the source server. See Managing API Keys for information on configured API keys.

• Default Synchronization Frequency: The frequency at which this server will check the federation source for updates.

• Identity: Federate identity data from the source domain, including users, groups, directory services, and authentication settings.

  • Include Admininistrators Group: Identity federation will also include the Server Administrators group permissions.

• Workspaces: Federate all or selected workspaces from the source domain. All repositories associated with the selected workspaces will also be federated. The available options are:

  • Enable: Federates all workspaces on the source domain, automatically adding new workspaces.
  • Custom: Federates selected workspaces from the source domain. New workspaces from the source domain must be manually added.

• Request Forwarding: Automatically pull repositories from the federated domain when a local repository is not found.

• Revision History Length: Number of application revisions to pull from the remote repository.

Managing a Server

Server Dashboard

The Server Dashboard page displays a summary of the server load, alerts, and setting updates.

The Alerts table lists important status alerts such as server health warnings. Servers with Fatal alerts may fail to perform their given role or may cease operation completely. To resolve a Fatal alert, follow the action recommended in the alert Event to repair the server then click the Clear action to restore server operation.

The Pending Changes table list server setting changes that have been saved but have not yet been applied to the server. The Recent Changes table lists server setting changes that have been applied in the last 10 minutes. Setting changes that occurred more than 10 minutes ago are located in the audit logs under Reports > Events.

Server Sessions

The Sessions section lists all user sessions that are running on the server except for the local system user. This section is only available for servers with the application role.

Administrators may manually log off users by clicking the Close action, which will issue a log off command from the Turbo service user. In order for this action to succeed, the Turbo service user must have permission to log off the user. Please be aware that logging off users may result in the loss of unsaved data.

Server Settings

• Name: A display name for the server, shown in the Administration Site.

• Role: The roles for which this server is responsible, including: Hub , Portal, and Application Server. Changing the server role will trigger a service restart which may take a few minutes to complete.

• Internal Web Service Root: Configures the web service bindings for where the hub, portal, broker, and public web services will be hosted.

• Internal Hostname or IP Address: The hostname or IP address used to resolve all internal services, such as RDP. If this field is not specified, the Internal Web Service Root is used.

• Web Service SSL Certificate: Configures the SSL certificate files that are used for HTTPS web service bindings. The provided file paths must point to permanent locations that are available to the service account.

• Use Advanced Video Coding: Enables the use of Advanced Video Coding (H.264) for remote application streaming if the Application Server supports it. This setting is only available for servers with the Application role enabled.

• User Profile Pool Size: Number of pre-created user profiles on the application server. The default size is 25. The recommended size is the number of concurrent launches expected for the server.

• Cache Temporary User Profiles: Enables caching of temporary profiles for application server role indefinitely. If disabled, any files saved by a temporary profile user on the application server will be removed along with the profile 10 minutes after the session ends. Users should be instructed to save to cloud storage or a redirected network drive. All non-administrative local accounts will be removed according to the Temporary User Profile Lifespan setting.

• Temporary User Profile Lifespan: Length of time since last login that a temporary profile will be cached, if cache temporary user profiles is enabled. Default to 7 days. Profile expirations are checked in 10 minute intervals.

• Application Image Path: The path where the application server will store SVM images. The default value is 'allusers'. Leave blank to prevent the service from setting the value. If the value is changed to a different folder such as 'E:\turbo-images', it must be changed to 'allusers' to restore the default value. Clearing the textbox will leave the value to 'E:\turbo-images'. Multiple application servers may share the same folder.

• Image Cleanup: Removes images on the server after the given interval. Leave blank to disable image cleanup. Target image cache size must be specified if image cleanup is enabled.

• Java Virtual Machine Settings: Configures the JVM settings for the Hub and Broker Java processes. Available settings include:

  • Heap Space: Configures the maximum JVM heap space allocated for the Hub and Broker Java processes. This setting is only available for servers with the Hub or Portal roles enabled.
  • Proxy Server: Configures the JVM proxy server for all outgoing http(s) requests from the Hub Java process. This setting is only available for servers with the Hub role enabled.

• Hub Image Cache: Configures an image cache path where the Hub will store SVM images. This prevents the redownload of the same application when ran by different users. This can be a local file path which will be shared by all users on the same device, or a network path which may be shared by all users across multiple devices. This setting is only available for servers with the Hub role enabled.

  The Cache action may be used to manually populate the image cache with the latest revision of all repositories in the Hub.

  Images in the cache are removed if the repo's revision are deleted from the Hub. Cached images may be manually removed from the server by deleting the file from the Windows Explorer.

• Hub Storage Path: Sets the hub storage path to a custom path. Ensure the target path is empty and not used by other applications, and has sufficient storage for storing all images and persisted data. The path can be changed later, but will require momentary downtime of the hub depending on how much data will be moved. The service user must have full access to the target path. Please see the Backup and Recovery documentation for additional details and troubleshooting.

• Hub CDN URL: The Hub block storage CDN URL. The Hub CDN URL must be a valid absolute http(s) URL. If the URL is not specified, blocks will be fetched from the original Hub URL.

  For more information on the Hub CDN and common CDN configurations, see Configuring Content Delivery Network (CDN)

• Hub CDN Max File Size: The maximum file size supported by the CDN provider, in megabytes. Supporting clients will download files exceeding this size using the Turbo synchronization protocol.

• Block Storage: Scans and repairs errors in the block storage. Images should not be pushed to the server until the repair is complete. This action is only available for servers with the Hub role enabled.

• Optimize Storage: Scans and deletes unreferenced blocks from the block storage. This action is only available for servers with the Hub role enabled. Optimize storage requires free space equal to the current size of the block storage size to complete successfully.

Server Security

The Server Security page displays the required Windows Firewall configurations as well as other configurable security settings.

• Firewall and Security: A list of ports that are required by the selected server roles. For a full list of ports that are used by Turbo Server, please refer to Firewall and Security.

• SSL OCSP Stapling: Enables OCSP Stapling for SSL. SSL must be enabled with the intermediate certification file specified.

• HTTP Strict Transport Security: Enables the HTTP Strict Transport Security (HSTS) header on all requests. The HSTS header uses a 1-year expiration and leaves all other options as default. The header is disabled by default.

  NOTE: If you downgrade your server to HTTP, the HSTS setting must be cleared from the client browser in order to re-enable access the server.

Server Diagnostics

The Server Information page displays the start time and up time of the Windows server that Turbo Server is installed on.

Clicking the Reboot Server button will reboot the server (shutdown and restart Windows). Any sessions running on the restarting server will be terminated without warning, and any Windows updates listed in the Pending Windows Updates section will be installed. Use the Reboot Server button in case the server appears unresponsive as a last resort.

The Service Information section displays the start time and up time of the Turbo Server service.

The Pending Windows Updates section displays all Windows updates that require a system reboot and are pending install on the Windows server.

The Operations table lists all operations that are managed by the Turbo service as well as their last know status. If an operation failed to complete successfully, the operations table will report an Error status and a short description of the error.

The Server Logs section displays the most recent Turbo service logs. From this page administrators can create and download log archives directly from the administration site.

Clicking the Archive button will gather all of the logs across the various Turbo Server services and compress then into a single .zip file. Once compressed, the archive will be made available for download and the original log files will be cleaned up.

Server Tags

Server Tags are user-defined name value pairs that can be used to organize, manage, and filter servers. Server tags must include a name and may optionally include a value. Server tag names and values are case-insensitive.

For example, tags may be used to restrict workspace application launches to application servers that meet certain requirements, such as GPU capabilities or licensing.

Workspaces

A workspace defines a set of applications and user permissions. These workspaces are shown on the Turbo Portal and on the Turbo Clients to users with sufficient permissions. By default there is a single Default Workspace with User permissions granted to the Everyone user group, allowing access to all users. Applications, permissions, and analytics can be managed from the the Workspace Administration page.

Server Administrators, as well as users with Administrator permissions to the workspace, may click the Manage button to access the Workspace Administration site.

Workspace Dashboard

The Dashboard page shows application usage analytics for the workspace. The analytics are separated into 4 sections:

• Application Launch Volume: A graph visualizing the application launch volume for the past week.

• Key Statistics: A summary of the unique applications, launches, users, and devices for the past week.

• Usage Summary: A table grouped by application summarizing each application's launch volume for the past week.

• Recent Activity: A table detailing the last 100 application launches.

Workspace Applications

The Applications page lists all applications that have been added to this workspace and provides management options such as adding, editing, and deleting applications. Applications added to the workspace will be displayed on the portal to users will sufficient permissions and will be available for launch.

Applications are broken down into several different types:

PC Applications

A PC Application is a Windows desktop application that runs in a containerized environment using the Turbo VM. These applications can be configured with a variety of launch, virtualization, and display settings.

PC Applications can be managed from the Application Settings page and contain the following fields:

General

• Display Name: The application display name shown on the portal.
• Icon: The icon that will be displayed to end users on the Portal. The icon must be a valid image type and at most 1MB in size. We recommend using a square icon that is at least 60px x 60px. If no icon is configured, the repository icon will be displayed.
• Repository: The name of the image repository used by this application.
• Application Version: The application version that will be launched. By default, the latest version will be used. The available application versions are sourced from the base repository.
• Allowed Launch Modes: Application launch modes that are available for applications on the portal. Disallowed launch modes will be disabled.
• Default Launch Mode: The launch mode the application will use by default if the user does not specify a launch mode. The is the default left-click behavior on the portal.
• Video Encoding: The preferred video encoding used for remote execution. Video encoding support depends on the application server settings and hardware.
• Startup File: The startup file that is used when launching the application. By default the image's startup file is used.
• Startup File Arguments: Arguments passed to the application startup file.
• Profile Mode: The login mode used when launching applications in the cloud. Possible options are:
  • Temporary Profile: A temporary user profile will be created on the Application Server. Temporary profile persistance can be configured on the Server Settings page.
  • Ask for Credentials: The user will be prompted to enter their Windows credentials for the Application Server. Both down-level and UPN logon names are accepted. Users must enter the UPN logon name format for Windows 10+ Enterprise multi-session. NOTE: HTML5 file integration may not function properly if the down-level domain is entered along with a UPN.
  • Kerberos: The user will be prompted to login using Kerberos authentication.
• Restrict to AD Groups: Restricts the application's visibility to members of the specified AD group. If a value is provided, then only members of that AD Group will see the application on the portal. If no value is provided, then all users with access to the workspace will see the application.
• VM Version: The VM version is a version string that specifies which Turbo VM version will be used for execution. The available VM versions are sourced from the Turbo Virtual Machine system image. See VM Version.
• Enable Assembly cache: Enables pre-caching of application DLL and EXE files on the Application Servers’ local disk for faster loading. See Use DLL cache.
• Launch on Install: Automatically launch the application when it is registered onto a device, such as when running the subscribe <workspace> --register commands from the Turbo client.
• Container Name: The container name that is used when launching the application. By default the image's name is used.

Isolation

• Access Local User Folders: Allows the application to access the host device's local user folders, such as Desktop, Downloads, Documents, Music, Pictures, and Videos. See Access local user folders.

  Set to Inherit from Workspace to inherit this setting from the corresponding workspace setting, or select a custom isolation settings to override the workspace setting.

• File Isolation: Determines the level of file visibility and access from the vm to the host environment. By default, local launches use Full isolation and cloud launches use Write Copy isolation. See Isolation Settings.

  Set to Inherit from Workspace to inherit this setting from the corresponding workspace setting, or select a custom isolation settings to override the workspace setting.

Network

• Isolate Network: Isolates the virtualized network environment from the host device's network. See Isolate network.
• Tunneling: Tunneling allows the application to tunnel traffic from the virtual environment to the specified targets accessible from the Portal server. Tunneling currently supports TCP and IP protocols and requires SSL (https) to be enabled on the domain. UDP is not supported. See Proxy Settings.
• Network Routes: A whitelist or blacklist of network routes that are accessible by the virtual network environment. See Controlling Outbound Traffic.

Components

• Components: A list of additional image repository IDs that are added to the base image as layers. See Components.

Storage

• Sessions are persistent: Persists the application state and settings on the host machine, enabling persistence across multiple sessions. Typically this setting should be enabled in order to prevent loss of data. This setting defaults to true.
• Synchronize across devices: Automatically synchronizes the application state and settings with the Hub server, enabling persistence across multiple devices. Sessions are persistent must be enabled to change this setting. This setting defaults to false.
• Drive Visibility: Controls which drives are visible in the virtualized application environment during cloud runs. This setting does not apply to local runs. By default, only the system drives and T: Drive are visible.
• Mount Points: A list of mount points that mount file paths from the host into the container. Supports NTFS paths, UNC paths, and special folder variables (see Folder Variables)

Licensing

• Licensing: Restricts the number of users or devices that can launch the application. The license counters are reset when the setting is modified. Available options are:
  • Unlimited: No limits to the application. Set to unlimited to reset previously assigned named licenses.
  • Named Users: Restricts the total number of named user that can run the application. A named user is a distinct Turbo user, which includes anonymous users and api-key sessions.
  • Concurrent Users: Restricts to the number of users allowed to run the application at a given time.
  • Named Devices: Restricts the total number of devices that can run the application. A named device is base on the end user operation system SID and MAC address.
  • Concurrent Devices: Restricts to the number of devices allowed to run the application at a given time.

IP Restrictions

• IP Access Rules: A whitelist or blacklist of IPs that control access to this workspace application. Clients that access the Portal dashboard from a blacklisted IP will not be able to view the application.

  Detailed access control information may be found at Access Control.

Server Assignment

• Server Tag Rules: Restricts cloud application launches to application servers that satisfy the tag rules. An application server must contain the exact tag name and value for all tags in order to qualify. Comparisons are case-insensitive and empty tag values will match against any value.

  For information about configuring Server tags, see Managing a Server

Installation

• Shell Integration: Enables or disables shell integrations that determine how installed applications interact with the host device, such as by adding shortcuts, file associations, and shell extensions. By default, all shell integrations will be enabled except for services and the default start menu shortcut.

  Web applications only support the default start menu shortcut and cannot be customized.

  Shell integrations are configured in the application image. For more information on configuring shell integrations in Turbo Studio, see Desktop Integration.

  For more information on using shell integrations, see Shell integration

PC Native Applications

A PC Native Application is a Windows desktop application that launches an existing installed application on the application server or local client host in a containerized environment using the Turbo VM.

When adding a Native Application to a workspace, a list of applications will be recommended based on the link files in the application servers' all users (common) Desktop and Start Menu folders. Selecting an application will set the launch settings to the link file's target and arguments. The application list is updated on service start and every 30 minutes thereafter.

If you do not see your desired application, check to see if the application has shortcuts in the common Desktop or Start Menu folders on the application server. This may be the case for Internet Explorer if is not installed on the server (no shortcuts, but still exists in program files). You may also select Custom application to manually enter your settings. We recommend setting the Startup File to the target file path instead of a link file path to ensure that the path is resolved correctly. Please ensure that the file path exists on the target Application Servers and client hosts, or else the application will fail to launch.

The Native Application isolation must be set to write-copy or merge in order to access the natively installed application. Using full isolation will cause the application to fail to launch.

Native Applications offer the same launch, virtualization, and display settings as PC Applications. These settings may be managed from the Application Settings page.

Web Applications

A Web Application is a link to an external website or resource that is opened in a new virtual browser environment.

When adding a Web Application to a workspace, you must select a repository with the browser category. Repository categories may be managed from the Repository Settings page.

Web Applications offer the same launch, virtualization, and display settings as PC Applications, in addition to the following Web Application specific fields. These settings may be managed from the Application Settings page:

• URL: The target URL that is opened when launching the web application.

To launch the browser with more complex startup arguments, the placeholder value %web-url% may be added to the Startup File Arguments field. This placeholder will be replaced with value in the URL field.

Workspace Startup

The Startup page allows administrators to configure the startup behavior for installed workspace applications.

The Startup Applications table lists all workspace applications and and their startup settings. Applications with startup enabled will run automatically when the application is installed to the device. This setting is disabled by default.

When an application is marked as a startup application, commands that install that application to the device such as turbo subscribe --register and turbo subscription register will run the application automatically. The application is launched by shell executing the default shortcut. If the application has no shortcuts then the application will not be launched. For more information on configuring shortcuts with Turbo Studio, see Desktop Integration Settings

Workspace Links

The Links page allows administrators to create and customize web links for end users to open URLs from their dashboard. These links appear under the Links tab on the Portal dashboard.

To create a new workspace link, click the Add Link button and enter your preferred options:

• Name: The name that will be displayed to end users on the Portal.
• URL: The target URL of the workspace link. If a URL is not include a protocol, then "https://" will be prepended automatically.
• Open in New Tab: If enabled, the link will be opened in a new browser tab. Otherwise, the link will be opened in the current browser tab.
• Icon: The icon that will be displayed to end users on the Portal. The icon must be a valid image type and at most 1MB in size. We recommend using a square icon that is at least 60px x 60px. If no icon is configured, a default icon will be displayed.

Sharing a Workspace Application

The Sharing page allows administrators to create shareable URLs for end users to run applications without having to log into the portal.

To create a new shareable URL, first create a non-system API key using the API Key administration page.

Next, click the Share Application button and select your preferred launch options:

• Application: The workspace application that will be launched.
• Name: A display name for the share link. This name is only displayed on the workspace administration site to help differentiate share links.
• API Key: The API key that will be used to authentication anonymous users who use this share link. If None is selected, user's will authenticate using their logged in credentials. The API Key Name must be added to the Workspace User Permissions as a User or the shared application will fail to launch due to insufficient permissions.
• Launch Location: The location where the application will be launched.

To test your link, open an incognito browser window without logging into Turbo.net and paste the URL into the browser address bar. The application should run without requiring a login. Please be aware that the Share URLs use an API Key that allows access to your organization's applications and should be kept secure within the organization.

If you wish to modify or revoke your Share URL, you may do so by clicking Settings button on the appropriate Share URL.

Testing Workspace Applications

The Test page allows administrators to perform multiple workspace applications launches simultaneous with various test configurations. Each application is launched in the HTML5 client with a unique temporary profile. These tests can, for example, simulate heavy application server loads and identify load related issues.

The following form fields are described below:

• Application: The application that will be launched. Applications must belong to the current workspace to be selectable.
• Instances: The number of application instances that will be launched. Each application instance is assigned an incrementing ID that creates a unique session. The ID is specified by the instance URL query parameter in the HTML5 client. The test will always start at instance ID 0, which will reuse any existing test sessions. This allows the tester to know exactly how many sessions of the application is running.
• Server Assignment: The rules that dictate the application servers to which the test workload is assigned.

  • Auto: The application server will be assigned without restriction based on the resource allocation strategy configured in the domain.

  • Application Server: The selected appliation server will be assigned.

  • Server Tag Rules: Filters the application servers that can be assigned the application instance according to their tags. A server must satisfy all of the supplied tag rules to qualify for launch.

    Tag name and values are case-insensitive. If no rules are provided then a server will be assigned without tag restriction.

Additional supported query params on the HTML5 client:

• cache-mode: A number that determines which caches will be enabled or disabled for this launch. Missing or empty will launch with all caches enabled. The cache mode value uses the following bitmasks to determine the cache behavior:
  • 1 (0b01): Launch with the Portal caches disabled
  • 2 (0b10): Launch with the Broker caches disabled
  • 3 (0b11): Launch with both portal and broker caches disabled
• no-logoff: Determines the remote session behavior on browser tab closure. By default, the remote session will be logged off on tab closure. If this query parameter is present, the remote session will instead disconnect and will logoff according to the configured Streaming settings.

Clicking the Run button will execute the test, opening an HTML5 client browser tab for each application instance.

NOTE: Some browsers may attempt to popup block the test instances. If your browser notifies you about blocked popups, please allow them for the Turbo Server administration site.

Diagnosing Test Results

The following section describes some resolutions to common issues when testing an application.

Application launches are slow with some instances that fail to start

Check the HTML5 client's browser console logs. If the PUT session request fails with 502 error, then the Broker may not be responding in time due to a resource constraint. Increase the number of Portal and application servers to improve the performance.

Application launches are slow with instances in session closed state

Check the CPU and memory usage on the application server when launching a large number of instances. If the sessions are bound by the CPU, they may not start in a timely manner resulting in the RDP protocol to disconnect. Increase the number of application servers or CPU cores on the application server.

Workspace Users

The Users page allows administrators to manage user-related settings, assign user and group entitlements, and manage channels.

Please note that changing or removing an existing workspace permission may take up to 5 minutes to be reflected on the Portal site. During this time, a user that is upgraded from User to Administrator may not see the workspace listed in the account dropdown or be able to access the workspace administration site. Likewise, a user that was downgraded or removed may still see the workspace listed in their account dropdown, however they will not be able to access the workspace administration site. The user may logout then login to see the change immediately.

General

The users General page allows the administrator to configure the following settings:

• Default Item Permission: The default user entitlement for workspace items. If this setting is disabled, workspace items will not be visible to users unless they have been granted access, such as through channel membership. Permission is enabled by default.
• Default Active Directory Domain: Sets the default Active Directory domain used to login when launching applications in the cloud with non-temporary profiles.

Permissions

The users Permissions page lists all user and user group permissions that have been added to the workspace and provides management options such as adding and deleting permissions. The following permissions are available:

• User - Grants read access to the worksapce dashboard.
• Read-Only Administrator - Grants read access to the workspace APIs, in addition to access granted by User.
• Administrator - Grants full access the workspace administration site and workspace APIs, in addition to access granted by Read-Only Administrator and User.

Channels

A channel is a collection of workspace items such as applications, links, and files that are made available to a configurable list of users and groups. Channels are visibile on the Turbo Server portal to users with sufficient permissions.

The users Channels page lists all channels that have been added to this workspace and provides management options such as adding and deleting channels.

Channels can be managed from the following channel settings pages:

General

The channel General page allows the administrator to configure the following settings:

• Display Name: The name that will be displayed to end users on the Portal.
• Web Path: The web path that uniquely identifies this channel, used to form the channel URL.

Items

The channel Items page lists all workspace items that have been added to the channel and allows the administrator to add and remove workspace items.

To add a workspace item to a channel link, click the Add button and select the workspace item type that you wish to add. The add dialog will list all items of the corresponding type that exist in the workspace. Items must be added to the workspace before they can be added to a channel.

Users

The channel Users page lists all user and user group permissions that have been added to the channel and provides management options such as adding and deleting permissions. Granting User permissions will allow that user or user group to access the channel, while granting Administrator permissions will allow that user or user group to access the channel administration page on the portal.

The Everyone group is automatically added with User permissions when the channel is created.

If the Default Item Permission workspace setting is enabled, all channel items will be visible from the workspace dashboard regardless of channel membership.

Workspace General

• Display Name: The display name of the workspace.

• Web Path: Folder name consisting of letters and numbers used to form the workspace URL.

• Precache Applications: Controls whether this workspace is automatically cached to the Application Server.

• Access Local User Folders: Allows workspace applications to access the host device's local user folders, such as Desktop, Downloads, Documents, Music, Pictures, and Videos.

  The Reset action will reset all workspace applications in this workspace to Inherit from Workspace local user folder access.

• File Isolation: Determines the level of file visibility and access that workspace applications have from the vm to the host environment. By default, local launches use Full isolation and cloud launches use Write Copy isolation.

  The Reset action will reset all workspace applications in this workspace to Inherit from Workspace file isolation.

URL Handlers

Desktops and mobile devices handle URLs by launching an application registered to the URL's scheme (often described as a protocol handler). For example, HTTP or HTTPS URLs are opened by the device's natively installed web browser.

Organizations may require that URLs that match a specific scheme and optional authority plus path should be opened by a Turbo application instead of by the device's native application.

The scheme and host of the URL determines the application used to run the URL. Turbo Client opens a Turbo application associated with that URL. URL paths are pattern matched using a pattern string along with a match mode to launch different Turbo applications or passed through to the native application protocol handler.

Turbo Client registers the protocol handlers in the OS for the user's Workspaces that contain Workspace URL handlers. Once the URL handler is triggered by the OS by a user action such as clicking on a URL link or typing in the command prompt, the Turbo application launches with the URL as the parameter as if the application was installed and registered as the native protocol handler.

The supported launch methods are remote HTML5, remote native, and local if the platform requirements are met.

The following table describes the match modes used by the Workspace URL handlers:

File Associations

File associations allow user's files and registered desktops to open the specified file types with a workspace application.

• Extension - The file extension that maps a file to a workspace application. The extension must be non-empty. Extensions are case-insensitive and are normalized on submission.
• Application - The workspace application that will be launched for files with the matching file extension.
• Action - The action that will be performed on the file, such as open or edit. This field is optional.

The equivalent command to open the file via Turbo CLI is turbo run <application> --startup-file=<file> --startup-verb=<action>.

Administrators must ensure the application is configured to handle the verb for the give file type, see Studio Desktop Integration.

Reports

The Reports page provides pre-configured, detailed analytic reports, broken-down into categories. Selecting a report takes you to the Report page, which consists of a Date Range control and the Report Viewer. Use the Date Range control to adjust the time period for the selected report.

Note that if the server uses Anonymous login mode, the user name in the reports will display the Windows login profile name. This applies even for logged in users with cached credentials.

Administration Reports

• Events: Presents a record of all Turbo Server alerts. Common events include errors and administrative changes.
• Application Sessions: Presents a detailed record of each application session.
• Application Usage: Provides a detailed breakdown and comparison of the usage for each application.
• Session Logs: Provides a detailed record of all session events, including launching or stopping an application.
• User Sessions: Provides a detailed record of each application session, broken-down by user.
• User Usage: Presents a detailed breakdown and comparison of application usage for each user
• Performance: Presents performance metrics for each application launch.

Use the Download button located at the top of the Report Viewer to perform the following tasks export the report to a file in any of the following formats:

• Adobe Acrobat (PDF) file
• Comma-Separated Values (CSV) file

Integrations

The Integrations page provides options to configure integrations with variety of third-party services, such as cloud storage providers and Learning Management Systems.

Storage Providers

The Storage Providers page allows administrators to view and manage connections with various cloud storage providers such as OneDrive and Dropbox. End-users may then use these connections to login to their cloud storage accounts and access their files while running applications.

Storage Provider Settings

• Storage Type: The storage type you are integrating with Turbo Server. Instructions for setting up a Storage Provider connection are available for:

  • OneDrive
  • Dropbox
  • Google Drive
  • Filr
  • File Share (SMB)

• Name: The display name of the storage provider connection.

• Client ID/Secret/Other: The application registration information for the storage provider. Varies by storage provider type, see instructions above for more information.

• T: Drive Path: The full file path where the storage provider will be mounted. Defaults to T:\{storage-type}.

• Supported Account Types: The account types that are allowed to login and access thier files with this storage integration. Multitenant allows users from any tenant to login, while Single tenant restricts users to a single tenant.

• Test: Storage provider configurations may be tested before committing any changes by clicking on the Test button. Common errors such as invalid or missing credentials or application registration misconfigurations will be reported during the testing process.

Compute Infrastructure

The Compute Infrastructure page allows administrators to view and manage connections with various compute infrastructures such as Azure. These connections may be used to deploy additional applications servers and join them to the Turbo Server farm.

Prerequisites

Compute Infrastructure currently only supports Azure environments. Support for other compute infrastructures may be added in the future.

The Turbo Server farm must be running in Azure with an Azure SQL Database connection. Adding Azure application servers to a on-premises Turbo Server installation is not supported.

For more information on setting up an Azure Turbo Server farm, see the Turbo Server AMI setup docs: /docs/server/setup-and-deployment/deploying-to-azure#hub-and-portal-role-deployment.

Azure Setup Guide

Before any application servers can be deployed to Azure, the Azure tenant must be configured with an application registration that has permissions to create new resources.

First, the application registration must be created. This application will be used to generate an access token to the Azure tenant with a limited set of permissions. To create the application registration:

1. Login to the Azure Portal and switch to your desired directory
2. Go to App Registrations and click New Registration
3. Enter a descriptive name such as Elastic Deployment then click Register. The other settings can be left as default.
4. Make note of the Application (client) ID and Directory (tenant) ID for later
5. Go to API Permissions > Add a permission
6. Select Azure Service Management > user_impersonation then click Add permissions
7. Click Grant admin consent
8. Go to Certificates & secrets
9. Click Client secrets > New client secret
10. Enter a desired description and expiration date then click Add. Make note of the key value for later.

Next, the application registration must be granted the Contributor role. This will allow the application registration to create Azure resources within the Azure subscription. To grant the Contributor role:

1. Login to the Azure Portal and switch to your desired directory
2. Go to Subscriptions > Pay-As-You-Go. Make note of the Subscription ID for later.
3. Go to Access control (IAM) > Role Assignments
4. Click Add > Add role assignment
5. Select the Contributor role
6. Click Members
7. Click Select Members and add the application registration that you created in the previous section
8. Click Review + Assign

Compute Infrastructure Settings

• Platform: The compute infrastructure that is being integrated, such as Azure.
• Name: The display name of the compute Infrastructure that will be shown on the Turbo Server administration site.
• Client ID: The Client ID from the compute infrastructure application registration. For Azure this is the Application (client) ID from the Setup Guide.
• Secret: The Client Secret from the compute infrastructure application registration. For Azure this is the Client secret value from the Setup Guide.
• Directory ID: The Directory ID from the compute infrastructure application registration. For Azure this is the Directory (tenant) ID from the Setup Guide.
• Subscription ID: The Subscription ID from the compute infrastructure application registration. For Azure this is the Subscription ID from the Setup Guide.
• Region: The region to which resources will be deployed, such as westus or eastus2. The region must be available in your subscription.
• Resource Group Name: The name of the resource group to which resources will be deployed. A new resource group will be created if the specified resource group is not found.
• Virtual Network Name: The name of the Virtual Network to which deployed resources will be assigned.
• Virtual Network Subnet: The name of the Virtual Network Subnet to which deployed resources will be assigned.
• Virtual Network Resource Group Name: The name of the resource group where the Virtual Network is located

The above configurations can be tested by clicking the Test button. This will verify that the Client ID, Secret, Directory ID, Subscription ID are present and configured correctly in Azure. It will also check that the Region is available in the subscription.

Learning Management Systems (LMS)

The Learning Management Systems (LMS) page allows administrators to view and manage connections with various LMSs such as Canvas, Moodle, and Blackboard. Once configured, students may access the Turbo Portal and launch applications through their LMS.

Instructions for setting up an LMS connection are available for Canvas, Moodle, and Blackboard.

The following sections describe the avaiable LMS configurations:

Show in Course Navigation

When the LTI Configuration URL is used, Turbo Server sends user interface instructions to the LMS Platform. These UI instructions include a Turbo icon, description and the following fields:

• Placement location: Course Navigation
• Link text: Apps (customizable)
• Visibility: public
• Default: enabled (customizable)

When Show in Course Navigation is disabled, the Default setting changes to disabled. New courses then hide the apps link from students by default until an instructor chooses to enable it.

Show in Course Navigation and Link Text settings will not affect LMS Platforms using the LTI Tool Provider URL.

Turbo must be removed and then re-added to the LMS platform for changes to these settings to take effect.

User Identity

Upon receiving a LTI 1.0/1.1 Launch Request from the LMS platform, Turbo Server must determine the user identity requesting access. Turbo identifies users with two values, both of which must be unique and immutable:

• Login Name: User friendly identifier for signing in to Turbo resources.
• User ID: User's primary key in your organization's Learning Information System (LIS) or Directory Service.

By default, Turbo will look for these values in LTI Launch Request fields specific to each LMS Product. The following table describes the default fields used for identity for a given LMS.

If your organization has modified the platforms’ identity settings, you may configure Turbo Server to find the Login Name and User ID under custom field names.

Navigate to the LTI page of the Turbo administrator site. Under the relevant value, check Custom to override the default field, then type in the name of the LTI Launch Request field for Turbo Server to use.

Workspace

Associating a workspace with the LMS integration allows configuration of where end users will be redirected to when launching Turbo from the LMS. Additionally, this determines the workspace to which channels will be added when Automatically Create Channels is enabled.

Selecting "None" will redirect users to the Turbo Portal homepage. If the user has access to exactly one workspace then that workspace will be displayed, otherwise a list of available workspaces will be displayed.

Automatically Create channels

Automatically creates a new channel in the specified workspace for unknown courses. A workspaces must be selected to enable this setting.

If the role of the user is an instructor, content developer, or administrator, grant the user administrative permissions to the channel when the channel is created. The instructor will be able to add users and applications to the channel from the portal.

Automatically Grant Permissions

Automatically grants user level permissions for the user to the target workspace.

Courses

Adding a Course to the Turbo Server allows configuration of a custom link to a particular Workspace or Channel. When a user launches Turbo from a known course, they are routed directly to the configured view.

To add a course to Turbo, it must first exist in the LMS. To edit an existing course, click on its name in the Courses table.

• Name: Administrative display name for the course, not seen by users.
• Course ID: Unique identifier for the course given by the LMS. Refer to the section below to obtain the value for the desired courses.
• Workspace: The Workspace users from the course will be routed to.
• Channel: The Channel view that users will be routed to. If left blank, users will be routed to the Workspace view.
• Default Channel Access: Automatically grant channel access to users from the LMS course. If the setting is not enabled, users must be granted permissions to the channel manually. Users must also have access to workspace regardless of this setting.

Renaming or deleting a course does not affect the LMS itself; these properties affect only how Turbo interacts with the course.

The following section desribes how to locate the course ID for supported LMS.

CANVAS

Navigate to any page of the desired course in Canvas. The URL will take a form similar to:

https://canvas.instructure.com/courses/2307642/quizzes

The number immediately after /courses/ is the Course ID. In this example, that number is 2307642.

BLACKBOARD LEARN

Navigate to the Blackboard Administrator Panel. Under the section Courses, click on the Courses link.

Locate your course in the table. The Course ID is shown for the course.

MOODLE

Navigate to the settings page of the desired course.

The settings page can be reached by clicking the gear icon on the course’s home page or the gear icon on the listing in Course and category management.

The Course ID is located under General. If the course does not yet have an ID, one must be given.

General

The General page provides options to configure and customize Turbo Server. The page contains the following sections:

• License: Provides an overview of information associated with the current Turbo Server license, including number of seats, allowed portals, computer name, and machine identifier. If server users are licensed to run applications on more than one machine, this number is reflected here. This section also contains a link to add a New License; you can use this to update an existing license as well.

• Administrator Email: Users are directed to this email address if they encounter any errors or issues while using Turbo Server.

• Notice and Consent: Users will see a notice and consent dialog after logging into the Portal. They must accept the notice and consent dialog before using the Portal. Markdown syntax is supported for links, headers, font styles, and more.

Notifications

The Notifications page allows admins to notify groups of Turbo Server users with custom message, such as service maintenance periods or product updates. Notifications may be customized with the following fields:

• Title: The message title that will be displayed to the end user in the notification.
• Icon: A preset or custom icon that will be displayed to the end user in the notification. When uploading a custom icon, we recommend using an image that is at least 80px x 80px.
• Display Type: The display type for this notification. The available types are:
  • Default: A low priority notification, displayed in a notification dropdown. This is the default setting.
  • Toast message: A notification that is shown at the top of the Portal dashboard. This notification may be dismissed and does not interrupt the user.
• Description: The message body that will be displayed to the end user in the notification.
• Groups: The user groups that this notification will be sent to.

The end-user may view their notifications on the Turbo Portal under the notifications dropdown, which are listed in order from most recent to least recent. Notifications are sent immediately upon submit, but may be changed later on through the notifications settings page.

Streaming

The Streaming page provides remote application streaming configurations for the Application servers.

• Active sessions: The maximum amount of time that a Remote Desktop Services session can be active before it is automatically disconnected.

  This setting corresponds to the Set time limit for active Remote Desktop Services sessions Group Policy setting. The value 0 will set the Group Policy setting to Never.

  Turbo Server defaults this setting to 21600000.

• Active but idle sessions: The maximum amount of time that an active Remote Desktop Services session can be idle (without user input) before it is automatically disconnected.

  This setting corresponds to the Set time limit for active but idle Remote Desktop Services sessions Group Policy setting. The value 0 will set the Group Policy setting to Never.

  Turbo Server defaults this setting to 21600000.

• Disconnected sessions with running applications: The maximum amount of time that a disconnected session remains active on the server.

  This setting corresponds to the Set time limit for disconnected sessions Group Policy setting. The value 0 will set the Group Policy setting to Never.

  Turbo Server defaults this setting to 300000.

• Disconnected sessions without running applications: How long a user's RemoteApp session will remain in a disconnected state after closing all RemoteApp programs before the session is logged off from the RD Session Host server.

  This setting corresponds to the Set time limit for logoff of RemoteApp sessions Group Policy setting. The value 0 will set the Group Policy setting to Immediately.

  Turbo Server defaults this setting to 600000.

  NOTE: Windows terminal services will honor this value only if the RemoteApp session remains connected until the application is successfully terminated. If the HTML5 client browser process is terminated before the application can disconnect vai RemoteApp shutdown procedure, the session will remain for a longer than expected disconnected state. The RemoteApp shutdown procedure takes up to 20 seconds after the application window is closed. To learn more, see the Microsoft documentation.

• Enable Drive Redirection: Enables the mapping of client drives when streaming remote applications.

  This setting corresponds to the Do no allow drive redirection Group Policy setting.

  The Turbo Server installer does not define a default value for this setting. Resetting this value will set it to Not configured.

  The default Windows value for this setting is Not configured.

• Network Drives: Maps network drives when streaming remote applications. Network drives will be mapped when users run sessions on the application server. Network drive paths support Windows environment variables.

  The \\tsclient\{path} can be used as the network drive path but is only supported when connecting with clients that redirect drives. For example, \\tsclient\c can be used to map the to local C: drive when connecting using Turbo for PC, and \\tsclient\Home may be used to map to the local Home folder when connecting using Turbo for Mac.

  NOTE: Network drives will not be mounted if the path is invalid or inaccessible to the remote user. Furthermore, network drive letters that conflict with existing local or network drives will not be mounted.

• Require NLA: Enables Network Level Authentication, requiring users to authenticate before establishing a remote connection.

  This setting corresponds to the Require user authentication for remote connections by using Network Level Authentication Group Policy setting.

  Turbo Server defaults this setting to Disabled.

• Restrict NTLM: Incoming NTLM traffic: Allows or denies incoming NTLM traffic from client computers, other member servers, or a domain controller.

  This setting corresponds to the Network security: Restrict NTLM: Incoming NTLM traffic Group Policy setting.

  The Turbo Server installer does not define a default value for this setting. Resetting this value will set it to Allow all.

  The default Windows value for this setting is Not defined, which is equivalent to Allow all. The server will allow all NTLM authentication requests.

• Restrict NTLM: NTLM authentication in the domain: Allows or denies NTLM authentication within a domain from this domain controller.

  This setting corresponds to the Network security: Restrict NTLM: NTLM authentication in this domain Group Policy setting.

  The Turbo Server installer does not define a default value for this setting. Resetting this value will set it to Disable.

  The default Windows value for this setting is Not defined, which is equivalent to Disable. The domain controller will allow all NTLM authentication requests in the domain where the policy is deployed.

• Preemptive Authentication: Allows the HTML5 client to show a login dialog when launching applications with Ask for Credentials authentication. If disabled, the HTML5 client will connect without credentials and defer to the remote login window. This setting does not apply to other clients or profile modes.

  The default value for this setting is Enables.

  NOTE: If Network Level Authentication is required, then launching applications in the HTML5 client with Ask for Credentials will fail with an authentication error.

The Inherit from Group Policy option will not update the local group policy and the behavior will be determined by existing GPOs or Windows defaults.

The Custom option updates the Local Group Policy on all application servers in the Turbo Server farm. Please be aware that this setting will always be overriden if your server is joined to a domain and the equivalent Domain Group Policy is defined.

The Reset button will reset the local group policies to their Turbo Server default values and remove all configured network drives on each application server. See each individual setting for more information on their default values. Confirming the reset confirmation dialog will apply the changes and reload the page, saving the settings form is not required.

Setting changes are applied approximately once every 20 seconds. You may need to exit and relaunch the group policy editor (gpedit.msc) to see the updated settings on the application servers if it was already opened.

Appearance

The Appearance page provides customization options for the Turbo Server portal, such as icons and background images. Appearance changes can take up to a couple minutes to apply to the Portal site.

• Dashboard Theme: Changes the appearance of the Portal dashboard site by altering the text colors and default background image. The available themes are:

  • Light: Dark text on a light background.

  • Dark: Light text on a dark background.

  The light theme is used by default.

  Internet Explorer 11 only supports the light theme. Viewing alternate themes in Internet Explorer 11 or below and may result in degraded visuals.

• Show Launch Page: When enabled, application launches will open a new browser tab to a launch landing page. This page provides detailed launch status information and a Turbo client download link.

  When disabled, application launches will launch directly from the dashboard without opening a new tab. A notification will be displayed at the top of the page with some basic launch status information.

  Run in Cloud (HTML5) is not affected by this setting and will always open a new tab to the HTML5 client.

  The launch page is enabled by default.

• Show Client Download Banner: When enabled, a download banner will appear at the top of the Portal dashboard page that provides a Turbo client download link appropriate for the user's device. If no such client is available, the download banner is not shown. This banner can be dismissed by the end-user.

  The download banner is enabled by default.

• Show Help Link: When enabled, a "Help" link will appear in the Portal's header that opens the provided URL in a new browser tab.

  The help link is disabled by default.

5.6 Applications

Overview

Turbo Server supports following types of applications:

• PC applications: Virtual applications packaged in the SVM format.
• Native applications: Applications installed natively on an application server.
• Web application: Browser based applications with a URL and potentially plugin layers.

To add applications to a workspace, refer to Workspace Applications.

Applications can be packaged using Turbo Studio or imported directly from the Hub.

Access Control

Turbo Server allows workspace administrators to control access to workspace applications according to a configurable set of access rules.

Access rules may be configured per workspace application on the workspace administration site. For more details on the workspace application administration, see the Workspace Applications.

IP Access Rules

Workspace administrators may configure IP access rules to restrict workspace application access by user IP address. Users that access the Portal dashboard from a blacklisted IP will not be able to view the workspace application.

IP access rules can be organized using the following rule sets:

• Disallow all except: Only users accessing the workspace from an IP address included in the access rules can view the workspace application. Users accessing the workspace from an IP address that is not included in the access rules will not be able to view the workspace application.
• Allow all except: Users accessing the workspace from an IP address included in the access rules will not be able to view the workspace application. Users accessing the workspace from any other IP address can view the workspace application.
• Custom (apply rules in order): Access rules are applied in the order that they are configured. Rules may be reordered at any time.

IP access rules can be configured by IP Address and Country.

IP Address

IP address rules can be configured as an exact IP address or address range in CIDR notation.

Exact IP addresses can be specified in either IPv4 (ex. 192.168.99.0) or IPv6 (ex. 2001:1234::). The access rule will apply if the user's IP is an exact match.

Address ranges must be specified in Classless Inter-Domain Routing (CIDR) notation (ex. 192.168.99.0/24 or 2001:1234::/64). This notation specifies an IPv4 or IPv6 address and a number of significant bits separated by a slash (https://turbo.net/undefined). All IPv4 addresses can be specified using 0.0.0.0/0, and all IPv6 addresses can be specified using ::/0. If the access rule and user IP are not using the same address family, the access controller will attempt to map the user IP to the same address family. The access rule will apply if the user's IP falls within the address range.

Country

Country rules can be configured using the corresponding 2-letter country code in ISO 3166-1 alpha-2 format (ex. US or AU).

When a user accesses the workspace, the user's IP addresses is looked up using the IP address to country database. The access rule will apply if the county code lookup finds a matching country code. Administrators may supply their own lookup database following the instructions listed under Import IP Addresses to Country Database.

Import IP Addresses to Country Database

The default list of IP to country database is sourced from the IP to Country Lite database. The database is imported using a Turbo Server administator tool which takes a CSV file.

To import an up to date list of IP addresses to country, download the update database in CSV format. Open the Turbo Server Administration Command Prompt through the start menu, or manually using the command line "C:\Program Files (x86)\Turbo Server\Server.exe" /XShellEx=cmd.exe /k pushd "C:\Program Files (x86)\Turbo Server"

Run the command IpCountryImporter.exe import [<ip2countrylist.csv>]. If the import fails and you wish to import the default list, run IpCountryImporter.exe import. For help with additional commands run IpCountryImporter.exe help.

KMS Licensing

The following section describes how to set up application servers to run Microsoft Office in Turbo, using KMS license activation.

1. Remote into your application server.
2. Copy the contents of the Office-MachinePrep-20.6.1353.0.zip archive.
3. Run the MachinePrep.exe tool in an elevated administrator command prompt to apply the licensing for the product you wish to use.

# Apply KMS licensing for Project 2016
# Note: use the --license-server flag to specify the hostname or IP of the license server if your system is unable to automatically detect your KMS server  
> MachinePrep.exe Project-2016

# For additional options, see the help
> MachinePrep.exe --help

4. Import the Microsoft Project 2016 (microsoft/project) repository from Turbo.net Hub by going to the Admin portal > Add Repository > Import Repository to make it available for your workspace.

The following section describes how to set up application servers to run natively installed Microsoft Office using an application stub.

1. Use the Office Customization Tool https://config.office.com/deploymentsettings to create the installation configuration file and Export it.
2. Install the Office Deployment Tool https://www.microsoft.com/en-us/download/details.aspx?id=49117 on the application servers and run the following commands:

# Download Office
setup.exe /download installation-config.xml
# Install Office
setup.exe /configure installation-config.xml

3. Create a new application configuration in Turbo Studio and add the native Office EXE as the Startup File. For example, if creating a stub for Excel 2019, the Startup File would be "C:\Program Files\Microsoft Office\root\Office16\EXCEL.EXE"
4. Build the application stub and use the Publish to Turbo Server wizard to push to Turbo Server.
5. Add the application stub to a workspace and test.

Troubleshooting

An error dialog appears with the text: The application has encountered an error.

The office license script requires cscript.exe. Your security settings or antivirus may be blocking execution of the file C:\Windows\System32\cscript.exe. Please check the security settings to allow execution.

If the error continues, please run with the diagnostics command line flag:

> MachinePrep.exe /XEnable=Diagnostics <project>

Logs will be generated in the same folder. Please send the logs to support@turbo.net.

An error dialog appears with the text: The products we found in your account cannot be used to activate Office in shared computer scenarios.

This is an Microsoft 365 Apps licensing error and is unrelated to Turbo Server. Please refer to the Troubleshoot issues with shared computer activation for Microsoft 365 Apps document to resolve this error.

5.7 Authentication

SAML 2.0

Turbo Server supports logging in users via Single Sign-On (SSO) using an external identity provider that supports SAML 2.0 authentication. The SAML 2.0 authentication protocol is supported by many identity providers, such as AzureAD, ADFS, and WSO2.

Prerequisites

The following section describes the requirements to use SAML 2.0 with Turbo Server.

Identity Provider Account

You must have access to an identity provider (IdP) that supports the SAML 2.0 protocol and an account that has permission to create and configure an application with that IdP.

Turbo Server Configuration

Single Sign-On requires all servers in the farm to use https in order to keep users data secure. Make sure SSL is enabled during installation or install SSL from the Domain > Servers > Server page.

Turbo Server must be configured to use SAML 2.0 authentication with configurations obtained from the IdP from the Users > Authentication Method page.

Identity Provider Attibutes and Claims

SAML 2.0 obtains a response token from the identity provider containing user information during the authentication process. Turbo Server uses the following token attributes and claims to create or login to the associated Turbo account:

• nameID or http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier - Used as the Turbo account username. If both claims are defined, nameID will be used.
• http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname - Used in combination with surname as the Turbo account display name.
• http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname - Used in combination with givenname as the Turbo account display name.
• http://schemas.xmlsoap.org/claims/group - User groups to which the Turbo account will be assigned.

The identity provider must be configured to accept the requested attributes and claims.

Certificate File

Turbo Server uses the SAML Signing Certificate to verify that the SAML response received during login is signed by the expected identity provider.

This certificate file is provided by your identity provider and must be manually installed on the Hub server. Please refer to the provider-specific documentation for more information on locating and installing this certificate.

How Turbo Users and Groups are created

When SSO is configured, a Turbo Server user will be created on a successful login if the user does not already exist. Users are created using the name identifier, given name, and sur name attributes and claims as specified in the Identity Provider Attributes and Claims section. User groups received in the groups claim will be created and the user assigned to them on each login. Users must be manually removed from the Turbo Server if removed in the external identity provider.

Automatically created user groups from SSO will be created in the Single Sign-On directory service. The user's group membership will be automatically removed from the group if removed in the external identity provider on the next sucessful login. If the SSO user is manually added to an internal group, then the user's group membership must also be manually removed.

Supported Identity Providers

Turbo Server supports Single Sign-On against any identity provider that supports SAML 2.0 authentication. Setup guides are available for the following identity providers:

• Azure Active Directory with SAML 2.0
• Active Directory Federation Services

For other identity providers, please refer to the identity provider documentation for information on configuring the claims listed in the Identity Provider Attributes and Claims section, as well as how to obtain the fields required by the Turbo Server user authentication form.

Troubleshooting

If an error is reported by the Turbo Server after logging into the external identity provider, the first place to check will be the Hub logs.

Failed to validate SAML token

Error log located in the API log file:

04/07/2020 17:44:42.6736 - Critical - 0x070C: Failed to validate SAML token: System.IdentityModel.Tokens.SecurityTokenValidationException: 
The X.509 certificate CN=Microsoft Azure Federated SSO Certificate is not in the trusted people store. 
The X.509 certificate CN=Microsoft Azure Federated SSO Certificate chain building failed. 
The certificate that was used has a trust chain that cannot be verified.
Replace the certificate or change the certificateValidationMode. 
A certificate chain processed, but terminated in a root certificate which is not trusted by the trust provider.

The Hub server failed to validate the SAML token. This can be caused by a missing or invalid SAML Signing Certificate. Please ensure that the SAML Signing Certificate has been added to the certificate store.

04/07/2020 17:44:42.6736 - Critical - 0x070C: Failed to validate SAML token: System.IdentityModel.Tokens.SecurityTokenException: The issuer of the security token was not recognized by the IssuerNameRegistry. To accept security tokens from this issuer, configure the IssuerNameRegistry to return a valid name for this issuer."

The Hub server did not recognize the token issuer identified by the Signing Certificate Thumbprint and Signing Certificate Common Name. This can be caused by missing or invalid Signing Certificate values. Please ensure that the correct values were configured in Turbo Server, and that the Signing Certificate has been added to the certificate store.

OpenID Connect

Turbo Server supports logging in users via Single Sign-On (SSO) using an external identity provider that supports OpenID Connect (OIDC) authentication. The OIDC authentication protocol is supported by many identity providers, such as Azure Active Directory or Google.

Prerequisites

The following section describes the requirements to use OpenID Connect (OIDC) with Turbo Server.

Identity Provider Account

You must have access to an identity provider (IdP) that supports the OIDC protocol and an account that has permission to create and configure an application with that IdP.

Turbo Server Configuration

SSO requires all servers in the farm to use https in order to keep users data secure. Make sure SSL is enabled during installation or install SSL from the Domain > Servers > Server page.

Turbo Server must be configured to use OIDC authentication with configurations obtained from the IdP from the Users > Authentication Method page.

Identity Provider Scopes and Claims

OpenID Connect obtains claims from the identity provider containing user information during the authentication process. Turbo Server uses the following claims to create or login to the associated Turbo account:

• email - Used as the Turbo account username.
• sub - Used as the Turbo account username if the email does not exist.
• given_name - Used in combination with family name as the Turbo account display name.
• family_name - Used in combination with given_name as the Turbo account display name.
• groups - (Optional) User groups to which the Turbo account will be assigned. Some providers supply group information through different means, see the provider-specific setup guides for more information.

Turbo Server sends the following scopes during authentication to authorize access to the required claims: profile, openid, and email.

The identity provider must be configured to accept the requested scopes and return the requested claims.

How Turbo Users and Groups are Created

When SSO is configured, a Turbo Server user will be created on a successful login if the user does not already exist.

The Turbo accounts' username comes from the email claim if it exists, otherwise it comes from the sub claim. The Turbo accounts' display name comes from the given_name, and family_name claims.

User groups received in the groups claim will be created and the user assigned to them on each login. Users must be manually removed from the Turbo Server if removed in the external identity provider.

For more information on these claims, see Identity Provider Scopes and Claims.

Automatically created user groups from SSO will be created in the Single Sign-On directory service. The user's group membership will be automatically removed from the group if removed in the external identity provider on the next sucessful login. If the SSO user is manually added to an internal group, then the user's group membership must also be manually removed.

Supported Identity Providers

Turbo Server supports SSO against any identity provider that supports OIDC authentication. Setup guides are available for the following identity providers:

• Azure Active Directory with OpenID Connect

For other identity providers, please refer to the identity provider documentation for information on configuring the claims and scopes listed in the Identity Provider Scopes and Claims section, as well as how to obtain the fields required by the Turbo Server user authentication form.

Azure Active Directory with SAML 2.0

Turbo Server can be configured to allow users to log in via Azure Active Directory (Azure AD) Single Sign-On (SSO) using the SAML 2.0 authentication protocol.

For prerequisites and additional information about the SAML 2.0 authentication protocol, please refer to the SAML 2.0 Prerequisites section.

Configure Azure AD

The following section describes how to integrate Turbo Server with Azure AD SSO using SAML 2.0.

To enable Azure AD SSO, a new Enterprise Application must be registered in your Azure AD tenant. From your Azure AD homepage, click Enterprise applications and then New Application. Enter your desired name then click Add.

Once the application has been created, click on the Single sign-on tab and select the SAML authentication method.

Once selected, you will need to configure the application to point to the correct Turbo Server URLs. Please configure the following settings and claims:

Basic SAML Configuration

• Identifier (Entity ID): - A unique identitier that will be the audience of the SAML response. For example: https://example.turbo.net.
• Reply URL (Assertion Consumer Service URL): The default reply URL for the SAML response. This must match the endpoint listed on the Turbo Server authentication method page. For example: https://example.turbo.net/auth/saml/return.

User Attributes and Claims

• Unique User Identifier (Name ID): The claim that will uniquely identify the user and will be used for their Turbo Server username. This claim must have the following properties:

  • Namespace: http://schemas.xmlsoap.org/ws/2005/05/identity/claims
  • Name: nameidentifier
  • Format: Email address
  • Source Attribute: user.userprinciplename

• Given Name: The claim that will be used for the user's first name display in Turbo Server. This claim must have the following properties:

  • Namespace: http://schemas.xmlsoap.org/ws/2005/05/identity/claims
  • Name: givenname
  • Source Attribute: user.givenname

• Surname: The claim that will be used for the user's last name display in Turbo Server. This claim must have the following properties:

  • Namespace: http://schemas.xmlsoap.org/ws/2005/05/identity/claims
  • Name: surname
  • Source Attribute: user.surname

• Group: The group claim that will be used to assign group membership for the user in Turbo Server. This claim must have the following properties:

  • Namespace: http://schemas.xmlsoap.org/claims
  • Name: group
  • Source Attribute: DNSDomain\sAMAccountName
  • Emit groups as role claims: unchecked

Users and Groups

On the Users and groups tab, add the users and groups that will have permissions to login with this application.

Configure Turbo Server

Once you have configured Azure AD, you are ready to enable SSO on Turbo Server.

Open the Turbo Server administration site and navigate to the Users > Authentication Method page. Change the Authentication Method to Single Sign-On and the Single Sign-On Method to SAML 2.0.

Fill in the following fields according to the Azure AD configuration:

• Application Id: The Application Id as configured in the Azure AD Overview section.
• Issuer: The Identifier (Entity ID) as configured in Azure AD Basic SAML Configuration section.
• Entry Point: The Login URL as configured in Azure AD Set up [Application Name] section.
• Logout URL: The Logout URL as configured in Azure AD Set up [Application Name] section.
• Signing Certificate Thumbprint: The Thumbprint as configured in Azure AD SAML Signing Certificate section.
• Signing Certificate Common Name: The Common Name as configured in Azure AD SAML Signing Certificate section.

Install the SAML Signing Certificate

The SAML Signing Certificate is used by Turbo Server to ensure that the SAML response is signed by the expected identity provider. This certificate must be manually installed on the Hub server.

First, download the certificate from Azure AD. This can be found listed as Certificate (Base64) in the SAML Signing Certificate section:

Next, login to the Windows Server machine that the Hub server is installed on as an administrator. Install the certificate with the following steps:

1. Select Run from the Start menu and enter mmc.
2. Click on File then click Add/Remove Snap In.
3. Select the Certificates option then click Add
4. Select Computer account, select Local computer, and then complete the dialog.

5. Complete the rest of the import wizard with the default options.

Once installed, Turbo Server portal logins should now complete successfully.

Troubleshooting

Please refer to the SAML 2.0 Troubleshooting section.

Azure Active Directory with OpenID Connect

Turbo Server can be configured to allow users to log in via Azure Active Directory (Azure AD) Single Sign-On (SSO) using the OpenID Connect (OIDC) authentication protocol.

For prerequisites and additional information about the OpenID Connect authentication protocol, please refer to the OpenID Connect Prerequisites section.

Configure Azure AD

The following section describes how to configure your Azure AD using the Azure Portal for use with Turbo Server.

To enable Azure AD SSO, a new application must be registered in your Azure AD tenant. Although it is possible to use the Service Principal account for authentication, we stongly recommend creation of a separate application with permissions only to authenticate users against Azure AD.

To create the application, log into your Azure Portal, navigate to the App registrations page and click New registration. Enter the following fields and submit the form:

• Name: Your desired display name for this application.
• Supported account types: Accounts in this organizational directory only (Turbo.net only - Single tenant)

Once created you will be redirected to the Overview page. Click on the Endpoints link in the header and save the OpenID Connect metadata document URL so that it can be added to Turbo Server later.

Authentication

From the Authentication tab, click Add a platform and follow the setup guide using the following fields:

Platform: Web
Redirect URI: The default reply URL for the Azure AD response. This must match the endpoint listed on the Turbo Server authentication method page. For example: https://{Web Service Root}/auth/openid/return.
Implicit Grant: ID tokens

API Permissions

From the API permissions tab, click Add a permission and add the following permissions:

• Microsoft Graph > Delegated permissions > User > User.Read
• Microsoft Graph > Delegated permissions > Directory > Directory.Read.All

The User.Read permission allows Turbo to create a Turbo account with the user's basic profile information upon successful Azure AD authentication.

The Directory.Read.All permission allows access control of Turbo Portal content based on Active Directory group membership. To access this information, Turbo uses the memberOf method of the Microsoft Graph API.

Click Grant admin consent and Save to grant consent on behalf of all users in this directory, ensuring that end users will not be required to consent when using the application.

Client Secret

From the Certificates & secrets tab, click New client secret and enter your desired description and expiration date. Once created, save the Client Secret value so that it can be added to Turbo Server later.

Configure Azure AD for Moble Clients

To enable SSO from mobile clients you must register a new Azure AD native client application that is separate from the Azure AD web application registration. Follow the Configure Azure AD instructions to create a new application registration, replacing the Web platform in the Authentication section with Mobile and desktop applications, and leaving the Certificates & secrets section blank.

Client applications are not configured with secrets because they run on the user's device and are not trusted to keep the secret. The web application runs as part of Turbo Server so it's considered a confidential client and is trusted to keep the secret. Please refer to the Microsoft documentation for more information.

To check that the application is a native application, navigate to the Azure Portal app registration manifest and verify the manifest has the field "allowPublicClient": true.

Configure Turbo Server

Once you have configured Azure AD, you are ready to enable SSO on Turbo Server.

Open the Turbo Server administration site and navigate to the Users > Authentication Method page. Change the Authentication Method to Single Sign-On and the Single Sign-On Method to OpenID Connect.

Fill in the following fields according to the Azure AD configuration:

• Provider Metadata URL: The OpenID Connect metadata document from your application registrations overview > endpoints page.
• Web Application ID: The Application ID from your web application registration overview page.
• Web Application Secret: The Client Secret from your web application registration's certificates & secrets page.
• Native Application ID: The Application ID from your native client application registration overview page.

Troubleshooting Azure AD App Registration Permissions

You may review which permissions the app registration requires by forcing the consent dialog to appear during login. To do so, please consult to Microsoft docs: https://docs.microsoft.com/en-us/azure/active-directory/manage-apps/configure-user-consent#force-user-consent-through-a-url-request

Active Directory Federation Services

This section describes the steps required to configure Single Sign-On (SSO) against an ADFS server using the SAML 2.0 authentication protocol. Turbo currently supports ADFS2 and ADFS3.

For prerequisites and additional information about the SAML 2.0 authentication protocol, please refer to the SAML 2.0 Prerequisites section.

Configure ADFS

The following section describes how to integrate Turbo Server with ADFS SSO using SAML 2.0.

Create a Relying Party Trust

A relying party trust object specifies identifiers, claims, and rules that allow Turbo Server to interact with the local Federation Service.

To create the relying party trust:

1. Open the ADFS management window and go to Trust Relationships > Relying Party Trusts settings. Then right-click on the Relying Party Trusts and add a new Relying Party:

   

2. In the Wizard choose Enter data about the relying party manually setting and click Next.

   

3. Fill the Display Name with a meaningful name, for instance, Turbo Portal, and click Next.

4. Choose AD FS profile as we will be using SAML tokens to authenticate and click Next.

5. Leave the token encryption certificate data empty and click Next.

   

6. Set the URLs for WS-Federation and SAML 2.0 to https://{Web Service Root}/auth/saml/return, replacing {Web Service Root} with your Turbo Server portal host, and click Next.

   

7. In addition to the URL from the previous step, add a relying party trust identifier to be used by the Turbo Client, https://{Web Service Root}/turbo-client, and click Add and then Next.

   

8. Click Next through the rest of the wizard and Close at the end.

Create new claims

Once the relying party trust is created, a few claim rules will need to be added to pass the user's name and AD groups to the Turbo Portal.

To add the claims:

1. Open the Edit Claim Rules window from the relying party trust.

2. Click on the Add Rule... button, choose the Send LDAP Attributes as Claims option, and click Next.

3. Set Attribute store to Active Directory, add the Claim Rules from the table below, and click Finish:

   LDAP Attribute	Outgoing Claim Type
   Display-Name	Name
   User-Principal-Name	UPN
   E-Mail-Addresses	E-Mail Address
   Token-Groups - Qualified by Domain Name	Group

Set the Authentication Policy

To configure how users will log into ADFS:

1. Open the Global Authentication Policy settings from the Authentication Policies administration panel.

   

2. Forms Authentication must be enabled for both Extranet and Intranet.

   

Get the Token-Signing Certificate

1. From the ADFS management window go to Service > Certificates.
2. Double-click on the Token-signing certificate.
3. Click Details and copy the thumbprint and common name. These values will be used when configuring the Turbo Server.

Configure ADFS for Native Clients

Native Client App access can be configured on ADFS using the Add-AdfsClient command in an elevated powershell cmdlet.

(ps)> Add-AdfsClient -ClientId <CLIENT_ID> -Name <APP_NAME> -RedirectUri <REDIRECT_URI>

• CLIENT_ID is a GUID. Used guidgen.exe or other method to generate a new value.
• APP_NAME is the name of the app. This can be anything but must be unique.
• REDIRECT_URI is an unused but required value. This can be anything but must be unique.

Example command:

(ps)> Add-AdfsClient -ClientId 54707E09-E6A2-4F22-9C73-638610AFE38A -Name Turbo-Client -RedirectUri http://turbo.net

Configure Turbo Server

Once you have configured ADFS, you are ready to enable SSO on Turbo Server.

Open the Turbo Server administration site and navigate to the Users > Authentication Method page. Change the Authentication Method to Single Sign-On and the Single Sign-On Method to SAML 2.0.

Fill in the following fields according to the ADFS configuration:

• Application Id: The Application ID used to configure your Native Client App, see Configure ADFS for Native Clients.
• Issuer: The issuer of the relying party login request. This must match one of the relying party Identifiers, as configured in your ADFS relying party.
• Entry Point: The ADFS login URL. Specified by the SAML 2.0/WS-Federation URL in your ADFS service endpoints (ADFS > Service > Endpoints).
• Logout URL: The ADFS logout URL. By default, this URL is constructed by adding ?wa=wsignout1.0 to your Entry Point URL.
• Signing Certificate Thumbprint: The ADFS Token-Signing Certificate's thumbprint, see Get the Certificate.
• Signing Certificate Common Name: The ADFS Token-Signing Certificate's common name, see Get the Certificate.

Troubleshooting

Please refer to the SAML 2.0 Troubleshooting section.

Kerberos

Turbo Server applications can be configured to allow user credential delegation using the Kerberos protocol in order to avoid multiple logins when launching a web application.

Azure AD SSO requires all servers in the farm to use https in order to keep users data secure. Make sure SSL is enabled during installation or install SSL from the /admin/servers/ page.

Configure Turbo Server

To enable Kerberos delegation during application launches, navigate to the workspace administration site and push the Settings button on the application for which the feature is desired. On the application's General Settings page, scroll down to Profile Mode and select Kerberos from the dropdown.

This feature is currently only implemented for the Windows native client. HTML5 and mobile clients will behave as if the Ask for Credentials profile mode is selected.

Configure Client Machines

Each client machine where users will connect to the Application Server requires the Credentials Delegation policy to be configured and the SSL gateway be disabled on the Turbo Client.

In the Group Policy Editor, go to Computer Configuration > Administrative Templates > System > Credentials Delegation > Allow delegating default credentials.

Check the Enabled checkbox and press the Show... button. For each Application Server that is in the Turbo Server farm, add an entry in the following format: TERMSRV/[server], where server is the fully qualified domain name of the Application Server. For example, if the domain name is test.net and the Application Server name is turbo1, then the correct entry value would be TERMSRV/turbo1.test.net.

Add "enableRdpGateway":"false" to C:\Users\username\AppData\Local\Turbo\Containers\settings.json while maintaining proper JSON syntax.

Example settings.json:

{"enableRdpGateway":"false","settingsVersion":3}

Run turbo config to verify SSL gateway is disabled:

> turbo config
Domain URL: https://turbo.net/
Turbo Drive (T: drive): Enabled
SSL gateway: Disabled
Image cache size: unlimited
Image GC interval: never
Image GC expiration: 90 days
Trusted sources:
  https://turbo.net
  http://turbo.net

When SSL gateway is disabled the client system will connect to the application servers directly.

Google LDAP

To configure Turbo Server to authenticate against Google LDAP, add an external directory service.

Refer to the Google LDAP documentation to set up the Google LDAP service for your Google Workspace.

Connection Details

Google requires client side certificate to validate the connection over SSL. Obtain the client certificate and key files as described in the Google LDAP documentation.

You must add the client certificate to the Windows Certificate store, as a single combined certificate and key file in pkcs12 format. To combine the cert and key file from google you will need openssl.

> openssl pkcs12 -export -in <path-to-cert>.crt -inkey <path-to-key>.key -out <path-to-cert-key>.pfx

Next, login to the Hub server as the service user and import the certificate-key file to the Current User windows keystore under Personal Certificates. Restart the Turbo Service to pick up the new certificate.

Connect using the following settings when adding the external directory service:

Type: Other LDAP

Host: ldap.google.com

Port: 636

Top Directory: dc=example,dc=com

Binding Type: SSL

Synchronization Account: Ensure you connect with a specific account if required by your Google LDAP configuration, in addition to SSL certificate authentication.

Directory Schema Consult the Google LDAP schema documentation to configure the Directory Schema settings. Example settings are provided below.

• Users

  • Filter: (objectClass=inetOrgPerson);(objectClass=posixAccount)
  • Class: inetOrgPerson;posixAccount
  • Login name: uid;cn
  • First name: givenName
  • Last name: sn
  • Full name: displayName;cn

• Groups

  • Filter: (objectClass=posixGroup)
  • Class: posixGroup
  • Name: displayName
  • Description: description
  • Members: member

Page Size: 0

Integrated Windows Authentication

Integrated Windows Authentication

The Turbo Client can be configured to login with the user's current Windows credentials instead of specifying a username and password.

This authentication method is desirable in centralized and VDI environments where an administrator deploys Turbo-packaged applications with the use of scripting, because it does not prompt the user to login in order to authenticate themselves to the Turbo Server. Since the user is authenticated as themselves instead of using a shared API key, this also allows fine-tuning of application permissions and accurate collection of analytics.

Configure Turbo Server

1. Join the Turbo Server system to your domain.
2. Set the service user to the desired user. If the service worker is a local system user, skip step 3.
3. Add an SPN record for the Turbo Server to your domain.

> setspn -S HTTP/hostname domain\serviceuser
> setspn -S HTTP/hostname.domain domain\serviceuser.

5. Synchronize users from your Active Directory.

Configure Turbo Client

1. Ensure the Turbo Client system is joined to the domain.
2. Login to Windows as a domain user.
3. Point the Turbo Client to your Turbo Server: turbo config --domain=https://turboserver.turbo.net. For all users: turbo config --domain=https://turboserver.turbo.net --all-users
4. Login with integrated authentication. You must be logged in as a domain user: turbo login --auth=integrated.

Example login script:

# Point Turbo Client to your Turbo Server.
turbo config --domain=https://turboserver.turbo.net

# Optionally point Turbo Clint to image share for VDI scenario. 
# See (Image Streaming|https://app.turbo.net/docs/server/advanced-topics/image-streaming)
turbo config --image-path=\\networkshare\turboimages

# Authenticate Turbo Client.
turbo login --auth=integrated

# Register shortcuts to Start Menu for Default workspace
turbo subscribe default --register

Troubleshooting

Integrated login works from Turbo Server system, but not Turbo Client system.

The Turbo Client system reports Error: Unable to login to http://turboserver.domain as domain\user, because Turbo Server is unable to decode the user’s Kerberos ticket.

To resolve this issue, ensure that you have added the correct SPN record for your Turbo Server to your domain.

> setspn -S HTTP/hostname domain\serviceuser
> setspn -S HTTP/hostname.domain domain\serviceuser.

Integrated login fails from any system.

Ensure that you are logged in Windows as a domain user that has been synchronized to Turbo Server via Active Directory synchronization.

5.8 Network and Load Balancing

Installing Redundant Roles

Turbo Server allows installing redundant roles across multiple servers. To install the role on separate servers, run the Turbo Server installer and select the role you would like to install.

The administrator can also add or remove roles on that server after installation. For more information refer to Managing the Domain.

It is recommended to install more than one Portal server for failover purposes, or for a large number of concurrent users (see Portal System Requirements). The number of application servers should depend on the number of concurrent users and the resource requirement of the applications being ran.

For maximum redundancy, a redundant domain should be setup that uses federation to replicate the workspaces and authentication settings from the primary domain.

Configuring Network

The administrator may want to use a reverse proxy to accesss the internal Turbo Server services. The administrator can configure which URLs the services and clients will use to talk to each other. For more information refer to Domain Addresses.

Configuring Content Delivery Network (CDN)

Turbo SVM images may be delivered over standard content delivery networks. To enable CDN for the Hub block storage, set the Hub CDN URL.

CDN support works best when delivering Turbo images using the Turbo synchronization protocol. Supporting clients will automatically select the Turbo synchronization protocol for objects over the configured Hub CDN Max File Size. Please consult your CDN provider to ensure that the correct max file size is configured. If you chose not to specify a max file size, then the automatic protocol selection will not occur.

For clients that do not support automatic protocol selection, users should have direct download disabled in the Turbo Client configuration.

If direct download is used, be aware that certain CDN providers limit the object size which may be exceeded by certain Turbo images. In that case the image must be delivered by the origin server.

Be aware that images delivered over the CDN may be downloaded from the public internet. Ensure that there is no confidential data in the images when delivering them over a CDN.

Sample CDN Configurations

Here are sample configurations for using Cloudflare, AWS CloudFront, and Azure CDNs with Turbo Server.

Cloudflare

Create a CNAME that resolves the URL of the Turbo Server instance and turn Proxy status on. The CNAME will be the Hub CDN URL in Turbo Server.

Create two Page Rules in Cloudflare:

• Cache Level: Cache Everything
• Edge Cache TTL: a month

Set the Hub CDN URL in Turbo Server to the CNAME address created in Cloudflare. Set the Hub CDN Max File Size to the maximum file size your Cloudflare subscription allows.

AWS Cloudfront

Create a CloudFront distribution with the following options:

• Origin domain: URL of the Turbo Server instance
• Path pattern: Default (*)
• Viewer protocol policy: Match the HTTP configuration of the Turbo Server instance
• Allowed HTTP methods: GET, HEAD

Set the Hub CDN URL in Turbo Server to the Distribution domain name. Set the Hub CDN Max File Size to the maximum file size your CloudFront subscription allows.

Azure CDN

Create an Azure CDN resource with the following options:

• Pricing tier: Standard Microsoft
• Check Create a new CDN endpoint
• Origin type: Custom origin
• Origin hostname: URL of the Turbo Server instance

Set the Hub CDN URL in Turbo Server to the Endpoint hostname. Set the Hub CDN Max File Size to the maximum file size your Azure subscription allows.

Load Balancing

To load balance Application Servers, install the Application Server role on the desired servers. Then, configure the load balancing strategy as described in Domain Settings.

To load balance Portals, set the Domain URL to an external load balancer.

Understanding the Domain URL

The Domain URL is the URL for any end user or client to access the Turbo Server services. The Domain URL must be accessible on the network the end user is intended to run Turbo applications from. It should map to the server with the Portal role installed. End users can access the web portal through the domain hostname using a web browser. When logging in with the android or iOS application, the end user should put in the Domain URL under the server setting. For example, if the Domain URL is https://mydomain.com, the administrator should assign their dns entry at mydomain.com to the Turbo Server farm's Portal role server. End users can then navigate to https://mydomain.com to view the web portal.

The command line interface (CLI) should be configured using the Domain URL. Run the command turbo config --domain=mydomain.com to set the CLI to the correct domain. For more information refer to Command Line Reference

In addition to being used to accessing the web portal, the Domain URL will also be used to query the service topology for the underlying Turbo Server services. The endpoints that are exposed, using the above example, is the https://mydomain.com/service/settings and https://mydomain.com/service/topology. These endpoints are used to determine what server services are available, such as the Hub's IO service, the login service, and Application Server Broker.

Alternatively, the administrator may leave the Domain URL setting blank to have it be defaulted to the first server with the Portal role installed.

5.9 Security

Application Security

Application servers provide end users the ability to run Turbo applications remotely in containers. The container model provides limited security against malicious users by preventing users to modify files and registry outside of the containers isolation setting. Additional care must be taken since the user may upload and attempt to execute arbitrary applications.

AppLocker can be used to prevent malicious applications from executing. Please refer to the documentation. You may also choose any off the shelf software that can perform application whitelisting.

Network

Application server users may attempt to probe the network using tools that can be run in the Turbo virtual runtime. Ensure that application servers do not have network access to resources that are not intended for the target end user.

In addition, a user could attempt to download and run Wireshark in the virtual runtime to capture network packets. However, if WinPcap is not installed (driver) then the user cannot capture anything.

If the application server is isolated in their own virtual network, make sure to configure two way https access to the Hub server and SQL server.

Securing Remote Access

Turbo uses temporary profiles for running applications on application servers. Temporary profiles are anonymized local machine accounts with randomized passwords that do not require domain authentication, and so application servers are not required to join the domain and will keep the domain secure by design. NTLM is the default authentication method for local machine accounts connecting via RDS.

It may be desirable for an organization to fully disable NTLM authentication for compliance purposes. The following settings allow administrators to disable NTLM when running Turbo remote sessions. Under admin/general/streaming.aspx Network Security section set the following settings:

Require Network Level Authentication Custom: Not enabled

NLA should not be required as RDP authentication must be used when running applications using temp profiles. If the users will authenticate to application servers using AD Kerberos then NLA can be required.

The default Windows value for this setting is Not Configured.

Restrict NTLM: Incoming NTLM traffic Custom: Deny all accounts

The default Windows value for this setting is Allow all.

Restrict NTLM: NTLM authentication in this domain Custom: Deny all

The default Windows value for this setting is Disable.

The following table describes there EnableSspSupport will be used in the native client to connect to cloud RDP sessions.

*Native clients will always set EnableCredSSPSupport to true when using Kerberos login mode as it is required for Kerberos login.

*Temp profile will not work if both Require NLA and NTLM traffic is restricted settings are set to true. Applications must use Ask or Kerberos login modes to run in the cloud.

*The HTML5 client will not work if both Require NLA and NTLM traffic is restricted settings are set to true. The Server Administrator should disable the Run in Cloud (HTML5) launch mode to ensure users launch using the Run in Cloud (Windowed) mode via the Turbo Client.

If require NLA is not set, EnableCredSSPSupport is true because modern operating systems require NLA by default. Under gpedit > administrative templates > windows components > remote desktop services > remote desktop session host > security > require user authentication for remote connections by using network level authentication:

If you do not configure this policy setting, the local setting on the target computer will be enforced. On Windows Server 2012 and Windows 8, Network Level Authentication is enforced by default.

Securing Execution using AppLocker

AppLocker can be used to enforce that only Turbo runs on the application server. The following configuration allows only the Turbo Client to execute on the application server.

<AppLockerPolicy Version="1">
  <RuleCollection Type="Appx" EnforcementMode="NotConfigured" />
  <RuleCollection Type="Dll" EnforcementMode="NotConfigured" />
  <RuleCollection Type="Exe" EnforcementMode="Enabled">
    <FilePathRule Id="921cc481-6e17-4653-8f75-050b80acca20" Name="(Default Rule) All files located in the Program Files folder" Description="Allows members of the Everyone group to run applications that are located in the Program Files folder." UserOrGroupSid="S-1-1-0" Action="Allow">
      <Conditions>
        <FilePathCondition Path="%PROGRAMFILES%\*" />
      </Conditions>
    </FilePathRule>
    <FilePathRule Id="a61c8b2c-a319-4cd0-9690-d2177cad7b51" Name="(Default Rule) All files located in the Windows folder" Description="Allows members of the Everyone group to run applications that are located in the Windows folder." UserOrGroupSid="S-1-1-0" Action="Allow">
      <Conditions>
        <FilePathCondition Path="%WINDIR%\*" />
      </Conditions>
    </FilePathRule>
    <FilePathRule Id="fd686d83-a829-4351-8ff4-27c7de5755d2" Name="(Default Rule) All files" Description="Allows members of the local Administrators group to run all applications." UserOrGroupSid="S-1-5-32-544" Action="Allow">
      <Conditions>
        <FilePathCondition Path="*" />
      </Conditions>
    </FilePathRule>
    <FilePublisherRule Id="a7863604-0cfa-429d-b8b0-3a9716e75757" Name="Signed by O=CODE SYSTEMS CORPORATION, L=SEATTLE, S=WASHINGTON, C=US" Description="" UserOrGroupSid="S-1-5-32-555" Action="Allow">
      <Conditions>
        <FilePublisherCondition PublisherName="O=CODE SYSTEMS CORPORATION, L=SEATTLE, S=WASHINGTON, C=US" ProductName="*" BinaryName="*">
          <BinaryVersionRange LowSection="*" HighSection="*" />
        </FilePublisherCondition>
      </Conditions>
    </FilePublisherRule>
  </RuleCollection>
  <RuleCollection Type="Msi" EnforcementMode="NotConfigured" />
  <RuleCollection Type="Script" EnforcementMode="NotConfigured" />
</AppLockerPolicy>

To install run this in an elevated Powershell prompt:

Set-AppLockerPolicy -XMLPolicy c:\<path-to>\applocker-turbo-server-working.xml

Open Group Policy Editor, navigate to Local Computer Policy > Computer Configuration > Windows Settings > Security Settings > Application Control Policies > Applocker > Executable Rules, and verify the rules have been imported.

Restart the AppIDSvc Windows Service.

To view blocked EXE events open Event Viewer and navigate to Application and Services Logs > Microsoft > Windows > Applocker > EXE and DLL.

Note that the whitelist rule applies specifically to the Remote desktop users group, and that it does not prevent executable running within the Turbo virtual environment. To prevent specific executables in the Turbo environment, add additional FilePathRule rules:

<FilePathRule Id="b68894c7-ecc7-4cc0-abe9-2317221bf221" Name="EXE Name Block: C:\*\minergate*.exe" Description="" UserOrGroupSid="S-1-5-32-555" Action="Deny">
  <Conditions>
    <FilePathCondition Path="C:\*\minergate*.exe" />
  </Conditions>
</FilePathRule>    

FAQ

How are Turbo application verified when end users launch the application?

Application are configured by the administrator of the workspace. The configurations are hashed using SHA-256 and verified by the Turbo client prior to launching. If a malicious user attempts to tamper the application configuration in any way, the client will detect a hash mismatch and refuse to launch the application.

What is a device key and why are there locally generated private keys?

The device key is used by the local machine to register the device (under a specific Turbo user) to Turbo Server. The local private key is used to sign the device's identity to validate itself to Turbo Server. The private key should be kept secure on the local device. In the event the key is leaked, delete the device key registration using the administrative site located at /admin/users/devicekeys.aspx.

Can end users modify the system drive on application servers?

Not by default. Turbo uses low privilege local users to run Turbo applications on the application server, and by default those users should not have write access to the system drive. If the application isolation is set to Merge then any user attempt to write to the system drive will attempt to pass through and fail. In full or write-copy isolation mode, the virtual environment will allow users to write to the system drive but is sandboxed within the virtual environment. The user will perceive that the drive is writable, but is not. In addition, an application server can be configured to disallow any modfications to a drive using the standard built in ACL in Windows. Refer to the Microsoft Windows documentation to achieve this.

How are Turbo applications verified before they are executed on end user devices?

Users must agree to trusting a domain before running an application from a Turbo Server portal. Once the domain is trusted, the application's image and settings are verified using SHA-256 hash to ensure integrity of the application from the domain. If the hash does not match then the client will prevent the execution of the application.

Password Policy

The following password policy is enforced by Turbo Server when creating internal users to ensure the server is more secure against password attacks. This password policy does not apply to users created with the Anonymous or Single Sign-On authentication methods.

Complexity Requirements

• The password must be at least 8 characters in length
• The password must not be the same as the username

Data Breach Requirements

The following requirements only apply if the Check for Compromised Passwords setting is enabled:

• The password must not be contained in a data breach. Turbo Server checks the HIBC database for compromised passwords.

5.10 Cloud Storage

OneDrive

To allow users to connect their OneDrive accounts and access them while running their applications, you must first configure a OneDrive application registration. This OneDrive application controls the permissions, branding, and routing for the OneDrive SSO.

If you are using Azure Active Directory with OpenID Connect Authentication, you may configure OneDrive to automatically connect on login by using the same application registration. See Automatically Connect OneDrive

Setup the OneDrive Application

Create a new OneDrive Application

The following section describes how to create a new OneDrive application that can be integrated with Turbo Server.

1. Follow the Microsoft docs to set up a OneDrive application registration. If you are using Turbo Server 22.4 or earlier, make sure to select one of the Multitenant supported account types when creating the application registration.

2. Add the following Redirect URLs:

   • https://{Web Service Root}/oauth/onedrive/callback/login
   

3. Enable the following Delegated Permissions:

   • Files.ReadWrite.All
   • offline_access
   

Update an Existing Application

The following section describes how to update an existing Azure Active Directory with OpenID Connect application to automatically connect OneDrive when users login to the Portal using Single Sign-On.

1. Add the following Redirect URL:

   • https://{Web Service Root}/oauth/onedrive/callback/login
   

2. Enable the following Delegated Permissions:

   • Files.ReadWrite.All
   • offline_access
   

Configure Turbo Server

Next, Turbo Server must be configured to use the newly created OneDrive application. Once configured, users may connect their OneDrive account from the portal settings.

1. Go to the Turbo Server Administration site Integrations > Storage Providers page.
2. Click on Add.
3. Select OneDrive as the storage type.
4. Enter the OneDrive Application Id into the corresponding Client Id field.
5. Enter the OneDrive Application Secret into the corresponding Secret field.
6. Select the Supported account types you selected when creating the application registration. If you selected single tenant, enter the OneDrive Directory ID into the corresponding Directory ID field.
7. Save your settings. Setting changes may take a couple minutes to take affect.

Troubleshooting

The following section contains solutions for issues with regards to setting up cloud storage.

Issue:

User sign in results in error message "[The Azure Application] is not configured as a multi-tenant application. Usage of the /common endpoint is not supported for such applications created after ‘[Some date]’. Use a tenant-specific endpoint of configure the application to be multi-tenant."

Solution:

This error occurs when the OneDrive integration is configured with Multitenant supported account types, but the OneDrive application registration was created with Single tenant supported account types.

Open the OneDrive storage provider settings page and ensure that the Single tenant supported account type was selected.

In server 22.4 an earlier, only multitenant application registrations were supported.

Issue:

When the user is prompted to grant permission they’re warned about the domain being "unverified".

Solution:

This document explains how to resolve the unverified message:

How to: Configure an application's publisher domain

The setting is located in Azure Portal > App registrations > Branding > Publisher Domain

Issue:

User sign in results in error message "AADSTS50011: The reply url specified in the request does not match the reply urls configured for the application: '[Application ID]'."

Solution:

Ensure the correct Redirect URI is set. The setting is located in Azure Portal > App registrations > Authentication > Redirect URIs.

Issue:

User sign in results in error message "Need admin approval".

Solution:

Follow the instructions to grant admin consent for the Turbo OneDrive app registration for the entire tenant.

Alternatively if you would like each user to agree to consent, follow the instructions to configure how end-users consent to applications.

Issue:

The OneDrive folder does not appear in the T: drive. User has tried disconnecting and reconnecting to the storage provider but the issue persists.

Solution:

The Hub server is unable to reach the OneDrive services. This is typically caused by a proxy or firewall misconfiguration or other network issues. To resolve, ensure the https://login.microsoftonline.com/common/oauth2/v2.0/token URL is accessible from the Hub server.

Dropbox

To allow users to connect their Dropbox accounts and access them while running their applications, you must first configure a Dropbox app registration. This Dropbox app controls the permissions, branding, and routing for the Dropbox SSO.

Setup the Dropbox Application

1. Create a Dropbox app registration.

2. Add the following Redirect URI: https://{Web Service Root}/oauth/dropbox/callback/login

3. Set the Permission type to: Full Dropbox

   

Configure the Turbo Server

Next, Turbo Server must be configured to use the newly created Dropbox application. Once configured, users may connect their Dropbox account from the portal settings.

1. Go to the Turbo Server Administration site Integrations > Storage Providers page.
2. Click on Add.
3. Selected Dropbox as the storage type.
4. Enter the Drobpox App key into the corresponding Client Id field.
5. Enter the Dropbox App Secret into the corresponding Secret field.
6. Save your settings. Setting changes may take a couple minutes to take affect.

Google Drive

To allow users to connect their Google Drive accounts and access them while running their applications, you must first configure a Google application. This application controls the permissions, branding, and routing for the Google Drive SSO.

Prerequisites

We recommend that you have a G Suite account. Accessing Google Drive files from Turbo Server requires a restricted scope that is only available to internal G Suite users by default. If you wish to allow integration with public Google accounts, this application will need to go through the Google verification process.

Setup the Google Application

1. Go to the Google API Console and log in as your G Suite user.

2. Click CREATE PROJECT and create a new project with your desired project name.

   

3. Click on the Library tab and search for Google Drive. Click Google Drive API, then click Enable to add Google Drive access to your application.

   

4. Click on the OAuth consent screen tab, select the Internal User Type, then click Create.

   * Internal user selection requires you to be a G Suite user. If you wish to allow external users, your application will need to go through the Google verification process.

   

5. Under Scopes for Google APIs add the ../auth/drive scope.

   

6. Click on the Credentials tab then click CREATE CREDENTIALS > OAuth client Id.

   

7. For the Application Type select Web application, and for the Authorized redirect URIs enter https://{Web Service Root}/oauth/googledrive/callback/login.

   

8. Once created you will receive a Client ID and Client Secret. Save these values for later as they will be used on the Turbo Server administration site.

   

Configure the Turbo Server

Next, Turbo Server must be configured to use the newly created Google application. Once configured, users may connect their Google Drive account from the portal settings.

1. Go to the Turbo Server Administration site Integrations > Storage Providers page.
2. Click on Add.
3. Selected Google Drive as the storage type.
4. Enter the Google application client id into the corresponding Client Id field.
5. Enter the Google application client secret into the corresponding Secret field.
6. Save your settings. Setting changes may take a couple minutes to take affect.

Filr

To allow users to connect their Micro Focus Filr accounts and access their My Files while running their applications, you must set up a Filr Server with accounts for your users.

Prerequisites

The Filr integration requires Filr version 4.3 or higher.

Setup Filr Server

1. Follow the Micro Focus documentation to set up a Filr Server and Filr accounts for your users.
2. Add the following Redirect URI:
   • https://{Web Service Root}/oauth/filr/callback/login

Configure Turbo Server

Next, Turbo Server must be configured to use the newly created Filr application. Once configured, users may connect their Filr account from the portal settings.

1. Go to the Turbo Server Administration site Integrations > Storage Providers page.
2. Click on Add.
3. Select Filr as the storage type.
4. Enter the display Name for the Filr Storage Provider.
5. Enter the Authentication URL for the Filr Server.
6. Enter the Filr Application Id into the corresponding Client ID field.
7. Enter the Filr Application Secret into the corresponding Secret field.
8. Enter the full path where the service provider will be mounted. If left blank, the default T:\{storage type} will be used.
9. Save your settings. Setting changes may take a couple minutes to take affect.

File Share (SMB)

The file system storage provider integration allows users to store their files on a local file system folder or a network share (SMB) through the T: Drive. The files under the configured path can be set to read only, or scoped to each individual user's private folder.

Configure the File Share

The SMB file share must be accessable by each Portal server via a UNC path such as \\SERVERNAME\path. The Portal service user must have full control access to the SMB file share.

If you are using a single portal solution, the storage path can be a local drive path, such as D:\shared.

Quota Enforcement

Storage quotas can be enforced via the underlying OS's quota enforcement tools. A quota error message will be displayed to the user when they upload a file that exceeds the configured quota to the Portal files shell or T: Drive with Background Sync disabled.

For Windows Server, quotas can be configured using the File and Storage Services server role.

To install this role:

1. Launch the Server Manager and click on Manage > Add Role and Features
2. Continue to Server Roles and select File and Storage Services > File and iSCSI services > File Server Resource Manager
3. Complete the wizard and wait for the role install

Then, to configure the storage quota:

1. Click on Tools > File Server Resource Manager
2. Open Quota Management > Quota Templates
3. Select your desired template then click Create Quota from Template…
4. Enter your root share path into Quota path.

If you are using Shared storage it is recommended to select Create quota on path.

If you are using Per User storage it is recommended to select Auto apply template and create quota on existing and new subfolders. This will automatically apply the quota to each user subfolder.

6. Complete the dialog making any desired changes then click Create.

Configure Turbo Server

1. Go to the Turbo Server Administration site Integrations > Storage Providers page.
2. Click on Add.
3. Select File System as the storage type.
4. Enter the file system provovider Name.
5. Enter the file system File Share Root.
6. Select the desired File Share Target Path.

• Per User mode restricts access to the user's sub folder under the path.
• Shared (Read-Only) mode allows read-only access to all files and folders under the path.
• Shared (Read-Write) mode allows read-write access to all files and folders under the path.

7. Select the desired Background Upload setting, which determines whether files will be uploaded to the storage provider asynchronously or synchronously when using the T: Drive. Synchronous uploads will display upload error messages to the user.
8. Enter the desired T: Drive Path.
9. Save your settings. Setting changes may take a couple minutes to take affect.

Users can access their file share from the portal dashboard Files tab and Turbo Client's T: Drive.

End User Guide

To enable cloud storage for end users, they must add their cloud storage account using the Portal interface. Applications launched in the cloud by the end users will automatically map their cloud storage folder to the T: drive.

The following is a setup-by-step user guide to connect and access files from the cloud:

1. From your Portal, click on Files to manage the cloud storage services connected to your account. Click on the Connect button and select your desired cloud storage service to link the storage service to your account.

   

2. You will be asked to authenticate your account with the storage service. Once the authentication succeeds, the storage service status will show as connected.

   

3. Files from the storage service will now be available under the T:\ drive for applications running in the cloud.

   

Access from Local Launches

Cloud storage integration requires WinFsp drivers which are automatically installed on the application server, but not is not included in the Turbo Client installer for end users. Download and install WinFsp 1.4.19016 if you wish to launch local with the same T: drive integration.

If WinFsp drivers are not installed, T: drive will automatically map to the local OneDrive folder.

Troubleshooting

Upload failed due to quota limit

This error occurs when the total size of your files exceeds the user storage quota limit on the connected storage provider. Please try deleting some of your files and try again.

Upload failed due to insufficient permissions

This error occurs when you do not have permission to upload a file to the current folder. Please try uploading to a different folder, or contact your administrator about granting you permission to that folder.

Upload failed due to restricted file type

This error occurs when the file type of the uploaded file is not allowed by the connected storage provider. Please change your file to a different file type and try again.

Upload failed due to file size limit

This error occurs when the size of the uploaded file exceeds the maximum file upload size configured on the connected storage provider. Please try reducing the file size, such as by compressing the file, and try again.

The connection to OneDrive expired. Please reconnect OneDrive to Turbo.net.

The administrator may have changed a setting that requires users to reconnect to the cloud storage provider. Log in to the portal and reconnect the corresponding cloud storage provider from the Files tab.

Tdrive does not start or launching a file from the Portal exits immediately.

An antivirus may be preventing the TDdrive driver to launch correctly. Please disable any antiviruses on the system and try again.

Files API

The following documentation describes the Files API implemented by the Turbo Server Portal. The Files API allows users to view and manage files stored in their connected cloud storage accounts.

For more information cloud storage integrations and connecting cloud storage accounts, see:

• OneDrive
• Dropbox
• Google Drive
• Filr
• File Share (SMB)
• End User Guide

All request paths described in this document are relative to the base Portal URL: https://{portal}

Authorization

All requests expect an X-Turbo-Ticket header with a JWT access token value. If this token is missing or invalid, a 401 unauthorized response error is returned.