Novell is now a part of OpenTextNovell is now a part of OpenTextTo 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 and files.
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.
For the best experience, it is recommended to install the native Turbo.net applications 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 a web browser.
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.
Turbo.net applications can be opened using the Portal or, if configured by your administrator, directly from the Start Menu or Applications folder.
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:
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:
Turbo.net let you use files located on your device or on popular online storage providers such as OneDrive and Dropbox.
Users may access files on their local system when launching an application in the Cloud or on a local container instance.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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:
localhost name references the server running the application in the cloud.localhost.turbo.net references the client device.For example:
Click on Settings at the bottom right of the Turbo Launcher to bring up the Settings dialog.
Click on the gear (⚙) icon at the top-right of the Launcher to access the settings.
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
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?
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.
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 *.
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
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
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.
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.
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.
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.
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.
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.
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 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.
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.
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
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.
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!
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.
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!
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:
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!
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.
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.
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
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.
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.
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.
Turbo.net has many capabilities that we didn’t discuss in other sections. Here are a few:
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.
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
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)
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.
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.
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.
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
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
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
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
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.
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.
# 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!
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
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.
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.
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!
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
Users may browse the applications available on Turbo.net by clicking on the Hub link at the top of the Turbo.net homepage.
Click on the Add button for an application to add it to your dashboard.
Once you've added the applications, they will be available to launch from the dashboard or from Turbo Launcher.
There are four ways to create an image:
# 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.
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
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
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:
.msi)package.ini)Use the appropriate file type parameter:
# MSI
> turbo import msi <path to .msi>
# ThinApp configuration
> turbo import thinapp <path to package.ini>
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
Images in a local registry can be copied to a remote repository on the hub with the turbo push command to make your images available to your team members, end-users, or the public.
# 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.
For basic users, pushed images will be public by default. For paid users, pushed images will be private by default until the private repository limit is reached. Visit the hub to change these defaults.
See more information on using the hub.
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.
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.
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:
turbo run --isolate=merge-user --startup-file=explorer.exe python/python:3.7.3C:\ProgramData\Microsoft\Windows\Start Menu\Programs\Python 3.7IDLE (Python 3.7 32-bit).lnkIDLE (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.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.
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.
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
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.
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!
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; or to a shared team account with a Turbo.net Team plan. Enterprises can host Turbo repositories on-premises with TurboServer.
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.
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 jre,firefox:35
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 jre:7.51,firefox:35 --detach
> turbo run jre:8,firefox:38 --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.
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 http://turbo.net/hub/[profile]/[repo], where profile is the username of the repository owner and repo is the name of the repository. The homepage contains 3 sections:
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 stream the project directly from the browser in a variety of ways. They can Run your image in a new container. This is equivalent to this command executed 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>
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.
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.
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.
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.
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.
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.
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.
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 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.
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.
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.
A recipe is a set of reproducible instructions used to build an image. These instructions may include information such as software prerequisites, installation steps, registry keys, files, and more.
Recipes may be published to Turbo.net repository pages where they may be viewed by all users who have access to that repository.
On the repository page, go to the Recipes tab and click Edit. This page is only visible to your repository owners and organization administrators.
Make any edits you desire to the recipe and then click Save.
The Import feature allows you to copy an existing recipe from another repository.
On the edit recipe page, click the Import button at the bottom of the page.
Input the namespace and name of the repository you wish to copy the recipe from then click Import. This requires ownership or organization administrator permissions of both repositories the source and target repositories.
To publish a recipe to a new repository without pushing an image, you may create an empty repository.
Go to the Repositories tab and click on Create a Repository.
Input the name of the repository you wish to create and click Create. You will be redirected to the new repository.
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.
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 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 made available publicly or privately to a specified set of users.
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.
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 Hub in your browser.
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 Hub in your browser.
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 Turbo.net 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.
Turbo Workspaces allow organizations to publish applications to users from a central portal. Applications can be run from the cloud or on users' own devices.
This section provides an overview of Turbo Workspaces user experience and architecture.
End users can authenticate using Single Sign-On (SSO) over a wide variety of providers, including Azure AD, ADFS, and existing on-premises Active Directory and LDAP providers.
Each Workspace contains a set of applications determined by administrator-defined entitlements. The application launches after a click on its icon. There are three ways to run an application:
The Windowed modes require a Turbo native client on the end user device. The My PC mode is only available on PCs with the Turbo for PC client installed.
The following diagram gives an overview of the components in an Azure-based Workspace:
The lists below describe resources required to host Workspaces in Azure in a recommended configuration. We can add additional components to the base configuration if needed. Example of such a situation could be adding an NV6 Compute Pod for engineering applications.
Virtual Machines:
Storage:
Network:
The following diagram shows a minimal Azure Workspace deployment:
Workspaces are deployed in the following order:
.start.turbo.net. [<0.5h]In most cases, an initial deployment can be completed within one day. Additional time may be required depending on the number and complexity of additional applications to be deployed.
This section lists all the requirements needed to deploy the Digital Workspace in Azure successfully. For simplicity's sake, let's assume that we are configuring a production environment for a Demo University (unidemo). The university homepage is https://unidemo.edu and Portal will be available at the https://unidemo.start.turbo.net address. Students and staff members authenticate through Azure AD.
The subscription on which we deploy DW needs to have the following Resource Providers registered:
Please also check the "Usage + quotas" settings for your subscription, and make sure the quotas are higher or equal to the minimum values presented below:
We recommend creating a separate Resource Group (for example turbo-unidemo-prod) for the DW deployment. It makes it easier to manage resources and avoids risks of interference between DW elements and your current configuration.
The Service Principal account is the account we will use to run the deployment. You may register it in the portal or use Azure CLI.
Take note of the following information and provide it to Turbo:
Finally, we need to give the Service Principal permissions to modify the Azure resources. The quickest solution is to assign a Contributor role to the entire turbo-unidemo-prod Resource Group to the Service Principal.
To use a more limited set of permissions it is possible to add a unique role in the Azure AD. For this purpose, you need to create a turbo-custom-role.json file with the following JSON data. In this example, replace <subscription-id> and <resource-group-name> with data taken from your subscription:
{
"Name": "Turbo Custom Role",
"Id": "9d2ba02b-2dc7-462f-9607-003f18b786ae",
"IsCustom": true,
"Description": "Custom role with permissions required for Turbo.net deployment",
"Actions": [
"Microsoft.Authorization/*/read",
"Microsoft.Compute/locations/*",
"Microsoft.Compute/virtualMachines/*",
"Microsoft.Compute/disks/*",
"Microsoft.Compute/images/*",
"Microsoft.Insights/alertRules/*",
"Microsoft.Insights/diagnosticSettings/*",
"Microsoft.Network/*",
"Microsoft.ResourceHealth/availabilityStatuses/read",
"Microsoft.Storage/storageAccounts/*",
"Microsoft.Resources/deployments/*",
"Microsoft.Resources/subscriptions/resourceGroups/read",
"Microsoft.Resources/subscriptions/resourcegroups/write"
],
"NotActions": [
],
"AssignableScopes": [
"/subscriptions/<subscription-id>/resourceGroups/<turbo-resource-group-name>"
]
}
Create the role in Azure and assign it to the Service Principal:
az role definition create --role-definition /mnt/d/temp/sp-permissions/turbo-custom-role.json
az role assignment create --assignee unidemo-sp --role "Turbo Custom Role"
If you would like to use your own certificates to configure HTTPS on the start.turbo.net domain, please request them before starting the deployment. You may later save them in the Azure Key Vault and give read access to the Service Principal account.
Another option is to use the Let's Encrypt certificate. In this scenario, the configuration script will prepare all the necessary files.
While it is not required, we strongly recommend creation of a test account for Turbo support in the client's domain. This account allows Turbo support to assure portal authentication and other integrations are working properly.
To enable Single Sign-On authentication with Azure AD, a new application must be registered in Azure AD with an appropriate Home Page URL and Reply URL. These addresses will be provided by Turbo.
For an org named unidemo, the URLs will be of the form:
https://unidemo.start.turbo.nethttps://unidemo.start.turbo.net/auth/openid/returnAlthough 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.
It is also necessary to generate a secret for the application. The generated Application ID, Tenant ID, and Client Secret should be provided to your Turbo implementation specialist, who will finalize integration of authentication settings. (Note: The term Tenant ID and Directory ID are used interchangeably. It may be specified either by an alias or in the form of a UUID.)
These accounts may be created manually as described below, or using a bash script.
The bash script requires Azure CLI and may be run from any Linux machine or from WSL (Windows Subsystem for Linux).
After downloading the script from this link, run it in bash providing as parameters the subscription id, the resource group name, the Azure location, and the tenant name. For example:
./azure-create-app-accounts.sh
--subscription aaaaaaaa-cccc-1111-3333-bbbbbbbbbbbb
--resource-group turbo-prod
--location eastus
--tenant unidemo
Copy the output and share it with your implementation specialist through a secure channel. We recommend Azure Key Vault or OneDrive for this purpose.
Finally, go to the Azure portal and grant the admin consent to the newly created applications. Go to Enterprise applications on the Azure Active Directory tab and find the Turbo.net-Client and Turbo.net-Web applications. Choose Permissions and then Grant admin consent.
To allow Portal to authenticate Azure AD users, the registered application requires the Microsoft Graph Sign in and read user profile permissions.
Turbo supports customization of portal items based on Active Directory group membership. To access this information, Turbo uses the memberOf method of the Microsoft Graph API. This method requires the Read directory data permission in the Microsoft Graph namespace.
To create the application:
Turbo.net.Accounts in this organizational directory only (Turbo.net only - Single tenant).https://unidemo.start.turbo.net/auth/openid/return.Next, we need to configure permissions for this new application:
ID tokens checkbox. Click Save to apply the setting.To generate the client secret:
Finally, we need to grant an administrator consent for the application:
Turbo.net application.In summary the registered application should have permissions:
With Authentication setting:
The values required to send to Turbo:
This section describes the steps required to configure authentication against an ADFS server. Turbo currently supporst ADFS2 and ADFS3 protocols.
On the ADFS server 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:
In the Wizard choose Enter data about the relying party manually setting and click Next.
Fill the Display Name with a meaningful name, for instance, Turbo Portal, and click Next.
Later, choose AD FS profile as we will be using SAML tokens to authenticate and click Next.
Leave the token encryption certificate data empty and click Next.
Set the service URLs for WS-Federation and SAML 2.0 to the value provided by us and click Next.
Use the same URL as the relying party trust identifier and click Add. Add one more identifier that is unbound to SAML or WS-Federation to be used by the Turbo Client. Click Add and then Next.
Click Next through the rest of the wizard and Close at the end.
The Edit Claim Rules for Turbo Portal window should appear. We need to add two claim rules to pass the user's name and AD groups to the Turbo Portal.
Click on the Add Rule... button, choose the Send LDAP Attributes as Claims option, and click Next. 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 |
| Token-Groups - Qualified by Domain Name | Group |
| E-Mail-Addresses | E-Mail Address |
| Token-Groups as SIDs | Group SID |
Confirm Global Authentication Policy settings from the Authentication Policies administration panel.
Forms Authentication must be enabled for both Extranet and Intranet.
Add Native Client App access to ADFS. Do this with the Add-AdfsClient powershell cmdlet.
(ps)> Add-AdfsClient -ClientId <CLIENT_ID> -Name <APP_NAME> -RedirectUri <REDIRECT_URI>
(ps)> Add-AdfsClient -ClientId 54707E09-E6A2-4F22-9C73-638610AFE38A -Name Turbo-Client -RedirectUri http://turbo.net
In this section we go over the required settings changes to configure your on premises installation for ADFS login. The following instructions are for the Ubuntu installation steps:
adfs.crt.adfs.crt to the turbo.net directory.tar -xzvf turbo-net.tar.gz
cd turbo.net
Ensure the ADFS related fields in config.yml are filled.
nano config.yml
login_mode The login mode used to access the portal, use the value ADFS
adfs_issuer The ADFS relying party's identifier.
adfs_entry_point The ADFS relying party's endpoint.
adfs_logout_url The ADFS relying party's logout endpoint.
adfs_signing_cert_thumb The ADFS Token-Signing Certificate's thumbprint.
adfs_signing_cert_cn The ADFS Token-Signing Certificate's common name.
adfs_cert_file The ADFS Token-Signing Certificate, in PEM format.
Run:
sudo ./setup.sh
If you would like to manually edit the configuration file for an already configured Turbo Portal, open the /props/config.ini file. If you are running Turbo Portal in a Windows Turbo Container, run the following command turbo run turbo/portal --startup-file=c:\websites\portal\src\props\config.ini. Fill in the following fields:
# Controls what mode of login this portal uses
# ADFS: Login to ADFS with SAML auth
loginMode = ADFS
# Controls which ADFS you SSO into
#Obtained from your ADFS relying party client- / app-id
ADFSAppId=
# Obtained from your ADFS relying party identifier
ADFSIssuer =
# Obtained from your ADFS relying party endpoints
ADFSEntryPoint =
# Obtained from your ADFS relying party endpoints
ADFSLogoutUrl =
# Obtained from your ADFS token-signing certificate
ADFSSigningCertThumb =
# Obtained from your ADFS token-signing certificate
ADFSSigningCertCN =
To manage the workspace, you need to use your personal Turbo account. Make sure that this account has administrative rights in the organization. After signing in to https://turbo.net, click the profile icon (in the right upper corner) and you should see a list of workspaces to which you have access. Your workspace should be there too. After switching to it, you may search for new images and add them to the workspace, or remove the ones that are already there (hover over the image and click on the gear icon).
When you publish a new university app image to the hub, you should use the organization namespace, for example, turbo push unidemo.edu/myapp:2.0. Publishing an image under the unidemo.edu namespace makes it accessible only to the @unidemo.edu accounts. As an administrator of the organization, you may configure settings for each image under the unidemo.edu namespace. If you click the gear icon on an image, you may select the Go to Repository option:
On the settings tab, two most important sections are the Launch Configuration panel and the Admin panel:
The File Isolation defines the default isolation mode for the image (that’s what we will use to make the native Office365 visible). The Using textbox allows you to specify which other images (layers) should turbo import before running the main image (this could be 7zip or/and Adobe Reader, for example). Finally, the Official switch makes an image available for the cloud runs, and Launch Location configures possible ways of running the image.
This section provides information to help troubleshoot common issues you might encounter while using an On-Premises Turbo Portal.
Enabling diagnostic mode generates debug output logs. These can be used to help the Turbo support staff diagnose and debug issues.
When troubleshooting an issue related to launching applications from the web, Turbo recommends enabling diagnostic mode for the Turbo Client. Complete the following steps to enable diagnostic mode and capture debug output logs for the Turbo Client:
Download and run the DebugView application from: http://technet.microsoft.com/en-us/sysinternals/bb896647.aspx
Run Regedit.exe, the Microsoft Windows default registry editor tool.
Add the following String value to the registry key: HKEY_CURRENT_USER\Software\Code Systems\Turbo with the name set to TraceLevel, and the value set to Debug.
Restart the Turbo Client by selecting Start > All Programs > Startup > Turbo Sandbox Manager n.nn. If multiple versions of the Turbo Sandbox Manager exist, restart each.
When the application is launched again with Turbo, the DbgView Output displays debugging logs.
There are several types of logs available for Turbo Server, including logs for the Portal, Application Broker, and Application Server.
Portal Logs
The logs for the Portal service can be accessed with the following command:
sudo systemctl status portal.turbo.service
Application Broker Logs
The logs for the Application Broker service can be accessed with the following command:
sudo systemctl status remoteapp-web.service
NGINX Logs
Guacd Logs
The Guacamole proxy translates the Windows RDP protocol into the Guacamole protocol for the HTMl5 guacamole client.
sudo docker logs -f guacd
Portal Logs
The Portal container outputs logs to stdout. You can access these logs with the following command:
turbo logs --stdout <container>
Application Broker Logs
The Application Broker container outputs logs to stdout. You can access these logs with the following command:
turbo logs --stdout <container>
Turbo Cmd Logs
RDPProxy Logs
The RDPProxy translates the Windows RDP protocol into the RXP protocol for the HTMl5 h264 client.
The Windows Event Viewer is another useful source of information. If there is an issue with the Application Server configuration or RDP authentication there may be information reported in the Window Event Viewer to help diagnose the problem.
Turbo supports deploying containers from the Turbo.net hub to your desktop using the Sync Device feature. 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.
The Sync Device feature on the Turbo.net Hub provides the ability to deploy applications directly to your desktop from the Hub in two simple steps: Add applications in the Turbo.net hub, when complete just click Sync Device on your user or organization homepage.
The Sync Device button will update to show the syncing has begun.
When complete a prompt appears to confirm Applications synced to Device with an instruction that shortcuts have also been created in the start menu.
On your machine you will notice that a scheduled task has been created. The scheduled task will perform the application updates. Modify the schedule to ensure the applications are only updated when you want them to. Optionally, Run the task to cache the applications. If you do not run the task, launching an application will present a buffer dialog on first launch.
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.
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.
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.
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.
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.
There are two configuration steps for the file share server:
turbo-client-19.9.2054.0.exe --silent --all-usersturbo pull --all-users xvmturbo pull --all-users cleanFrom 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.
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).
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
Intune is an Azure-based device management solution by Microsoft.
This section describes the process for deploying the Turbo client to Intune-managed devices.
https://start.turbo.net/install?msi=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.
--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.--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.CMDLINE="--image-path=allusers --add-trusted-source=https://myhub.start.turbo.net"To deploy Turbo.net for Android via InTune:
https://play.google.com/store/apps/details?id=net.turbo.android.launcherSystem 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.
Citrix Receiver Applications Side by Side Launched
Turbo containers can be deployed to Citrix XenApp servers using the Turbo command line interface. Below are the steps required.
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
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.
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.
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.
Turbo containers can also be deployed to XenApp using powershell helper scripts to automate the deployment.
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.
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.
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.
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.
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.
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.
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.
In the following pages you will learn about how to use the Turbo Client and Turbo Launcher.
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.
When installing the Turbo Client for a managed environment, there are command line flags that may be useful.
Turbo-plugin.exe [Option]
| Parameter | Behavior |
|---|---|
|
--silent |
Installs the Turbo Client silently. |
|
--all-users |
Installs the Turbo Client under the All Users profile, so it is available to all profiles on the machine. |
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:
Navigate to the Control Panel in your windows Start Menu.
Select the Internet Options icon.
Select the Connections tab, then LAN Settings.
Enter the proxy settings specified by your network administrator.
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.
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
The Turbo Client installs an application called Turbo Sandbox Manager 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.
Turbo-Sandbox.exe [Option]
| Parameter | Behavior |
|---|---|
|
/uninstall |
Uninstalls the Turbo Client. Close all web browsers before uninstalling. |
|
/silent |
Used with /uninstall to perform a silent uninstall. |
|
/delete-user-data |
Used with /uninstall and /silent to remove user container data during uninstall. |
|
/uninstall-launcher |
Uninstalls the TurboLauncher but leaves the rest of the client. |
|
/uninstall-redirector |
Uninstalls the TurboRedirector but leaves the rest of the client. |
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.
<?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.
<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.
Turbo Studio can be used to package virtual applications as portable EXEs and MSIs.
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 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.
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.
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.
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.
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
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.
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.
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.
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.
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.
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
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.
The first step is to create an API key. To do this, go to your account or organization's dashboard page, click the Setting button, click the Profile and Account button, 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.
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.
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.
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.
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.
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.
You can use either the PowerShell New-NetFirewallRule cmdlet or call the Windows netsh command directly.
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:
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.
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.
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.
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.
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.
For more information on the snapshot process, see Snapshot documentation.
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:
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.
Note: Turbo Studio users are responsible for any third-party licensing compliance for redistributable components included using virtualization.
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.
Folders may be containerized in Full, Merge, Write Copy, or Hide mode.
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.
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.
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.
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.
Below is a walkthrough of the steps required to setup capture ShareX.
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:
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.
For ShareX, select only the ShareX.exe and ShareX-13.2.1-setup.exe processes 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.
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.
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:
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.
Capture the before image: Select Capture Before on the Virtual Application tab on the ribbon bar. This may take several minutes to complete.
(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.
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.
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.
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.
Container updates can be captured within Turbo Studio via snapshots.
Complete the following steps to capture an update via snapshots:
Install the native version of the application on a clean machine.
Select Capture Before.
Install necessary updates to the native application.
Select Capture and Diff to create the after snapshot. This captures the deltas between the original and updated versions.
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.
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.
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.
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.
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.
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.
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.
/XLogPath=c:\logs\mylog*.log). The output directory must exist for the logs to be written.See VM Settings for details on the available settings.
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.
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.
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'.
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.
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 the specified container configuration.
> xstudio.exe [path-to-xappl] [optional]
Optional parameters:
Take a before snapshot.
> xstudio.exe /before /beforepath [path]
Parameters:
Take an after snapshot.
> xstudio.exe /after /beforepath [path] /o [path]
Parameters:
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 MSI, AXT, or ThinApp configurations.
xstudio.exe /import /i [path] /o [path]
Parameters:
Combine two or more SVM layers into a single file.
xstudio.exe /merge [path-to-layer1.svm] [path-to-layer2.svm] ... /o [path]
Parameters:
Merge the contents of a sandbox into a container configuration.
xstudio.exe /sandboxmerge [path-to-sandbox] /i [path] /o [path]
Parameters:
Dump a list of all configuration settings in the specified configuration file, container image, or standalone executable.
xstudio.exe /vmsettings [setting] /i [path]
Parameters:
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:
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.
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.
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.
A ProgID (short for PROgrammatic IDentifier) is the mechanism in Microsoft Windows where actions (known as verbs) can be defined for specific file types.
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.
The Extensions list defines file types and their associated ProgIDs.
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.
Large applications, particularly those over 1GB in size, pose special deployment and performance issues:
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.
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.
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
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.
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.
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.
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.
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.
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 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
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.
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
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.
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.
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
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
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.
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.
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
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 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]
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
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:
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.
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.
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.
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.
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.
# 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>
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.
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).
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:
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.
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
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.
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.
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.
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!
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.
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.
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.
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.
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
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
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/.
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.
Our SQL environment will consist of three Turbo container images:
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.
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.
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
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:
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.
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.
In Turbo Studio, press the Capture Before snapshot button.
Install SQL Server 2005 Express Edition. You can download the installer here: https://www.microsoft.com/en-us/download/confirmation.aspx?id=21844
Install SQL Server 2005 Service Pack 4 - kb2463332
Configure SQL as needed. For example, you may want to add users with access or pre-configure databases.
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
In Turbo Studio, press the Catpure and Diff snapshot button.
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.
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>
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.
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.
.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.
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.
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 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.
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.
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.
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.
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
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.
There are four major server roles in a Turbo Server deployment:
The Hub Server is 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.
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.
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 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.
Turbo Server is compatible with the following platforms:
Turbo Server supports x64 (64-bit) processor architectures.
End users can access Turbo Server from 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.
Turbo Server is an on-premise application delivery platform. In this section you will learn about system requirements and instructions for installing, configuring and running Turbo Server.
Additional requirements for Portal role:
Additional requirements for Hub role:
Additional requirements for the Application role:
For quick demo or testing:
For proof of concept or production up to 100 users:
For more than 100 users:
For additional sizing and technical guidance, contact Turbo at support@turbo.net.
Turbo Server is installed with an embedded SQL Express database in standalone mode for demonstration and testing purposes. When using Turbo Server in production and farm install scenarios, an external Microsoft SQL Server or Azure SQL database is required.
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.
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:
| Port | Protocol | Description | Required Externally |
|---|---|---|---|
| 80 | TCP | Administration Site HTTP | Yes |
| 443 | TCP | Administration Site HTTPS | Yes |
| 8085 | TCP | Turbo Server Service | No |
| Port | Protocol | Description | Required Externally |
|---|---|---|---|
| 80 | TCP | Portal Site HTTP | Yes |
| 443 | TCP | Portal Site HTTPS | Yes |
| 8085 | TCP | Turbo Server Service | No |
| Port | Protocol | Description | Required Externally |
|---|---|---|---|
| 80 | TCP | HTTP Service | No |
| 443 | TCP | HTTPS Service | No |
| 8085 | TCP | Turbo Server Service | No |
| 3389 | TCP | Application Server RDP | No |
| 5850 | TCP | Application Server RDP Proxy | No |
| 8084 | TCP | Application Server Service | No |
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.
In this section you will learn how to use the Setup Wizard to automatically configure Turbo Server. For details regarding manual configuration of Turbo Server, refer to Manually Configure Turbo Server.
Complete the following steps to set up Turbo Server:
Download Turbo Server and run the setup application.
Select Next to start the installation wizard.
Read the End User License Agreement, check the box and select Next.
Enter the License Certificate from your Account Licenses page and select Next.
Use Destination Folder to choose where Turbo Hub Server files are installed and select Install.
Choose the Server Roles that will be installed on the machine and select Next.
Enter the web service scheme, hostname, and port where your hub, portal, broker, and public web services will be hosted and select Next. The Administration Site and Hub Site will be accessible from this web service root after the install completes.
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.
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.
Enter your Administration Account credentials and select Install. This administration account will be used to access the Administration Site after install.
Select Install to begin configuring Turbo Hub Server.
After setup is complete the Administration Site automatically opens and displays a web page where you can apply your license. Both evaluation and retail licenses are applied here. To obtain an evaluation license, login or create an account on http://turbo.net. For information on purchasing a retail license, refer to the Licensing topic.
Start using Turbo Hub Server!
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.
Turbo Server has an administration site interface that enables Turbo Hub Server administrators to manage and control all aspects of a Turbo Server instance, including:
The Administration Site also provides detailed application usage analytics via pre-configured reports. The administration site is automatically configured during Turbo Server setup, and is assigned to path /admin on port 80 by default. For more information about how to administer Turbo Server, refer to Turbo Server Administration.
The Turbo Server Portal gives users access to application repositories from the Turbo Launcher, Turbo Client command line tools, or from a connected Turbo Streaming Server instance. The Portal is assigned to port 80 by default.
If the server has an Authentication Type that enables anonymous access, users can launch applications without logging in. If the server requires users to log in with a username and password, however, users must provide valid credentials to access the hub and application repositories.
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.
Users can also log in or out via the Turbo Launcher after it is installed on their local machine. Users can bring up the Turbo Launcher by either going to the System Tray or hitting the keys "Alt + Windows." If the user is not logged in already, a login form will be available. If logged in, the user can click on the arrow in the lower-left corner of the Console and select "Sign Out" or "Exit."
When specifying the server URL in the login form, use one of the conventions, below, as appropriate:
The Turbo Client interacts with the Turbo VM kernel to allow container execution. If you want your Turbo Client to automatically be updated for compatibility and feature fixes, download the Windows client installer from http://turbo.net/downloads. If you want to manage updates manually, download the Windows client installer from the hub at http://[hubserver]/Plugin/Install/ (note that the path is case sensitive and requires the trailing slash).
The new version of Turbo Hub Server will include a new Turbo Client, an updated Hub Site, and many other new features.
When upgrading Turbo Hub Server, the service will restart. Be sure to alert users that the system is under maintenance before upgrading.
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.
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.
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;.
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.
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.
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.
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:
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.
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.
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.
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.
In this step, provide the credentials for the account the Turbo services should use. Please check the preparation steps if in doubt.
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.
Some of the settings are available only after the server is installed, and we describe them in this section.
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.
For Azure AD SSO configuration, please check the Azure Active Directory Integration page.
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.
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.
To change the database connection string after installation on any server in the domain:
c:\programdata\turbo server\settings.xml.Online.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.
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.
All application repositories on Turbo Server are managed from the Hub page of the Administration Site.
Each new application repository is added to Turbo Hub Server in the form of a Turbo container image, or SVM, which are pushed to the hub using the Turbo Client command line tools. For more information about SVMs and Turbo Virtualization Technology refer to Turbo Server Technology.
Complete the following steps to add a new application image to Turbo Hub Server:
Install the Turbo Client for Windows platform.
Connect the client to your hub server using the turbo config command. See Config Command for more information.
> turbo config --hub=http://[hubserver]
turbo login command. See Login Command for more information.> turbo login admin-user
-OR-
> turbo login --api-key=6g8BwsIlU7ezl_CMIZ_0PYBwK6WVAUZdx1mxYO1WFOg
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. This image will be accessible to all users who are defined to have access to the hub server.
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.
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.
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.
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:
mozilla/firefox.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.
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.
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, sychronized 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.
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.
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.
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.
Resetting a user sessions 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.
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.
There are three special groups that are created automatically, Administrators, Anonymous Users, and Everyone:
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.
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.
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:
Open a Turbo Server administration site page in your web browser.
Choose the Users category from the top navigation bar.
Select Manage Directory Services.
Select Add Service. The Add Directory Service screen displays.
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.
|
Section |
Description |
|---|---|
|
Name |
This field indicates which service is being added or controlled by the entry. The Name field must not be the same as the service or server you are using. |
|
Description |
(Optional) |
| Login Prefix |
Login prefixes are given to each user in the directory service to use when they log into the server and are helpful in distinguishing users across different directories. For example, if the directory's login prefix is "acme" and the users name is "aaron", they would log on using the full name "acme\aaron." Once this login prefix is chosen for a directory, it cannot be changed. If you must change the login prefix, the directory service can be deleted and a new one added for the same directory; settings for all users from that directory are lost. |
| Type | In the Type section you can choose the type of the directory service from which to import users and groups. There is variability in location, security, and schema settings for directory services. Turbo Server provides two templates: Active Directory and Other LDAP. The local Active Directory can be found by selecting Try Local. When found, working connection settings are set automatically. To synchronize with the local Microsoft Windows domain's Active Directory service, select Try Local. This loads default settings into the Connection and Directory Schema fields. For large directories this can take several minutes. If the operation is unsuccessful, continue to the Choosing Your Connection Settings section. If the operation is successful, continue to the Choosing the Directories to Synchronize section. |
| Server |
This section can be used to specify your connection settings to the LDAP directory you are trying to connect to. For more on this section, scroll down on this page to Choosing Your Connection Settings |
| Binding Type |
This field is used to specify the form of security being employed by the LDAP server you are connecting to. If "Default" is chosen for Port in the Server section, changing the Binding Type will automatically change the port to the standard LDAP port number for that setting. |
| Synchronization Account | This field specifies the account to use when synchronizing users with the directory services. For more information, scroll down on this page to Choosing Your Connection Settings. |
| Directory Schema | Allows the administrator to specify which names in the LDAP directory will be imported into the Turbo Server user information. For more information, see Directory Schema, further down this page |
| Page Size | The page size used when synchronizing the directory service. Typically, the default value for Active Directory services is 1000. Some LDAP implementations do not support the PageSize property, and should be set to 0. |
| Synchronized Items | Used to identify items in the directory tree that should be synchronized with Turbo Hub Server. For more information, see Choosing Items to Synchronize, further down this page. |
Choosing Your Connection Settings
Complete the following steps to choose your connection settings:
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.
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.
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)
To test these settings, click on the Test button.
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:
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.
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.
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.
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:
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.
To narrow the scope of your synchronization to specific directories complete the following:
a. Uncheck Include All.
b. 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:
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.
To narrow the scope of your synchronization to specific groups complete the following:
a. Uncheck Include All.
b. 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.
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:
Azure AD: This option will redirect users to the Azure Active Directory login page. 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 Azure AD. This option uses the OpenID Connect authentication protocol. For more information, refer to Configure Azure AD.
SAML 2.0: This option will redirect users to the configured identity provider's login page. 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 identity provider. The configured identity provider must support the SAML 2.0 authentication protocol. For an example on setting up ADFS with SAML, refer to Active Directory Federation Services.
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.
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.
The Domain 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.
The Dashboard page shows real-time graphs detailing the total CPU, memory, number of sessions, and other resource usage information for the application servers.
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.
Resource Allocation Strategy: The load balancing strategy used to allocate applications to application servers. The available strategies are:
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:
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.
Workspaces: Federate selected workspaces from the source domain. All repositories associated with the selected workspaces will also be federated.
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.
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.
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.
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.
SSL OCSP Stapling: Enables OCSP Stapling for SSL. SSL must be enabled with the intermediate certification file specified.
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.
Cache Temporary User Profiles: Enables caching of temporary profiles for application server role. If disabled, any files saved by a temporary profile user on the application server will be removed along with the profile. 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. Default to 7 days. Profile expirations are checked in approximately 10 minute intervals.
Java Virtual Machine Settings: Configures the JVM heap space for the Hub and Broker Java processes. This setting is only available for servers with the Hub or Portal roles enabled.
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.
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.
Hub Storage Path: Sets the hub storage path to a custom path. Defaults to C:\ProgramData\Turbo Server\io if unspecified. Ensure the target folder 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.
Optimize Storage: Scans and deletes unreferenced blocks from the block storage. This action is only available for servers with the Hub role enabled.
Dashboard: Displays server load and running sessions.
The Server Information section displays the start time of the Turbo Server service, and total up time of the service. Clicking the Reboot Server button will reboot the server (shutdown and restart Windows) once. Any sessions running on the restarting server will be terminated without warning. Use the Reboot Server button in case the server appears unresponsive as a last resort.
The server 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.
A workspace defines a set of applications and user permissions. These workspaces are shown on the Turbo Streaming Server 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.
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.
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:
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:
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 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, you may 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.
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:
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.
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:
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:
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.
The Users page allows administrators to manage user-related settings, assign user and group entitlements, and manage channels.
The users General page allows the administrator to configure the following settings:
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. Granting User permissions will allow that user or user group to access the workspace, while granting Administrator permissions will allow that user or user group to access the workspace administration site.
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:
The channel General page allows the administrator to configure the following settings:
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.
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.
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.
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:
The Integrations page provides options to configure integrations with variety of third-party services, such as cloud storage providers and Learning Management Systems.
The Cloud Storage page provides configuration options for integration with Cloud Storage providers such as OneDrive and Dropbox. This allows users to be able to access their files from these providers while running applications. For more information refer to the Cloud Storage Integration section.
Clicking the Test button allows administrators to test storage configurations before committing any changes. Common errors such as invalid or missing credentials or application registration misconfigurations will be reported during the testing process.
Instructions for setting up LTI can be found in under the Integrations documentation.
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:
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.
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:
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.
| LMS | Login Name | User ID |
|---|---|---|
| Canvas | custom_canvas_user_login_id | user_id |
| Moodle | ext_user_username | user_id |
| Blackboard | list_person_sourcedid | user_id |
| Other | lis_person_contact_email_primary | user_id |
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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 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.
Setting changes can take up to 20 seconds to apply to the application servers.
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.
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 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.
This section describes the steps required to configure authentication against an ADFS server. Turbo currently supports ADFS2 and ADFS3.
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.
The following section describes how to integrate Turbo Server with ADFS SSO using SAML 2.0.
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:
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:
In the Wizard choose Enter data about the relying party manually setting and click Next.
Fill the Display Name with a meaningful name, for instance, Turbo Portal, and click Next.
Choose AD FS profile as we will be using SAML tokens to authenticate and click Next.
Leave the token encryption certificate data empty and click Next.
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.
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.
Click Next through the rest of the wizard and Close at the end.
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:
Open the Edit Claim Rules window from the relying party trust.
Click on the Add Rule... button, choose the Send LDAP Attributes as Claims option, and click Next.
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 |
To configure how users will log into ADFS:
Open the Global Authentication Policy settings from the Authentication Policies administration panel.
Forms Authentication must be enabled for both Extranet and Intranet.
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>
Example command:
(ps)> Add-AdfsClient -ClientId 54707E09-E6A2-4F22-9C73-638610AFE38A -Name Turbo-Client -RedirectUri http://turbo.net
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:
?wa=wsignout1.0 to your Entry Point URL.
Turbo Server can be configured to allow users to log in using Azure Active Directory single sign on (AD SSO).
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 Domains > Servers > Server page.
The following section describes how to enable Azure AD SSO using the Azure Portal.
To enable Single Sign-On authentication with Azure AD, 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:
Accounts in this organizational directory only (Turbo.net only - Single tenant)
Once created you will be redirected to the Overview page. Save the Application (client) ID and Directory (tenant) ID so that it can be added to Turbo Server later.
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
From the API permissions tab, click Add a permission and add the following permissions:
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 customization of Turbo Portal items 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.
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.
To enable SSO from mobile clients you must register an Azure AD native client application. It is recommended that this application is separate from the Azure AD web application registration. Follow the instructions to create an application registration list above, replacing the Web platform in the Authentication section with Mobile and desktop applications.
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.
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 Azure AD.
Fill in the following fields according to the Azure AD configuration:
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
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.
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.
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.
Turbo Server can be configured to use Single Sign-On (SSO) to login users using an external identity provider that supports SAML 2.0 authentication, such as Azure AD, ADFS, or WSO2.
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.
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:
https://example.turbo.net.https://example.turbo.net/auth/saml/return.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:
http://schemas.xmlsoap.org/ws/2005/05/identity/claimsnameidentifierEmail addressuser.userprinciplenameGiven Name: The claim that will be used for the user's first name display in Turbo Server. This claim must have the following properties:
http://schemas.xmlsoap.org/ws/2005/05/identity/claimsgivennameuser.givennameSurname: The claim that will be used for the user's last name display in Turbo Server. This claim must have the following properties:
http://schemas.xmlsoap.org/ws/2005/05/identity/claimssurnameuser.surname
On the Users and groups tab, add the users and groups that will have permissions to login with this application.
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:
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:
mmc.Certificates option then click Add
Once installed, Turbo Server portal logins should now complete successfully.
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.
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, see Install the SAML Signing Certificate.
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.
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
Groups
Page Size: 0
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.
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.
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. Built in load balancing will be coming soon!
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.
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.
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.
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>
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.
To allow users to connect their OneDrive accounts and access them while running their applications, you must first configure a OneDrive app registration. This OneDrive app controls the permissions, branding, and routing for the OneDrive SSO.
Follow the Microsoft docs to set up a OneDrive app registration.
Add the following Redirect URLs:
https://{Web Service Root}/oauth/onedrive/callback/login
Enable the following Delegated Permissions:
Files.ReadWrite.Alloffline_access
Next, Turbo Server must be configured to use the newly created OneDrive application. Once configured, users may connect their OneDrive account from the portal dashboard Files tab.
Go to the Turbo Server Administration site General > Cloud Storage page.
Enter the OneDrive Application Id into the corresponding OneDrive Client Id field.
Enter the OneDrive Application Secret into the corresponding OneDrive Secret field.
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:
The user is trying to log in with their external OneDrive account which requires a multi-tenant app registration. Ensure that the application registration is multi-tenant and separate from the application used for SSO.
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.
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.
Create a Dropbox app registration.
Add the following Redirect URI: https://{Web Service Root}/oauth/dropbox/callback/login
Set the Permission type to: Full Dropbox
Next, Turbo Server must be configured to use the newly created Dropbox application. Once configured, users may connect their Dropbox account from the portal dashboard Files tab.
Go to the Turbo Server Administration site General > Cloud Storage page.
Enter your Drobpox App key into the corresponding Dropbox Client Id field.
Enter your Drobpox App secret into the corresponding Dropbox Secret field.
Save your settings. Setting changes may take a couple minutes to take affect.
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.
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.
Go to the Google API Console and log in as your G Suite user.
Click CREATE PROJECT and create a new project with your desired project name.
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.
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.
Under Scopes for Google APIs add the ../auth/drive scope.
Click on the Credentials tab then click CREATE CREDENTIALS > OAuth client Id.
For the Application Type select Web application, and for the Authorized redirect URIs enter https://{Web Service Root}/oauth/googledrive/callback/login.
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.
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 dashboard Files tab.
Go to the Turbo Server Administration site General > Cloud Storage page.
Enter the Google application client id into the corresponding Google Drive Client Id field.
Enter your Google application client secret into the corresponding Google Drive Secret field.
Save your settings. Setting changes may take a couple minutes to take affect.
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:
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.
You will be asked to authenticate your account with the storage service. Once the authentication succeeds, the storage service status will show as connected.
Files from the storage service will now be available under the T:\ drive for applications running in the cloud.
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.
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.
Memory sharing can be optimized for applications that have large memory requirement. Turbo can utilize Window's dll and exe sharing by using the precache command. This will reduce the startup time and memory consumption of applications ran by different users on the application server.
For example, to allow dll and exe memory sharing for the application MATLAB:
# Verify the image has been pulled and cached locally
> turbo images
1a2b3c mathworks/matlab
# Run the precache command
> turbo precache mathworks/matlab
Using VM 20.6.1523 from local
Using image clean:30 from local
Using image matlab from local
Precaching assemblies in mathworks/matlab
Precached 3023 files in 0:00:37.2151653
Next, enable the Enable Assembly Cache setting under the workspace application's general tab from the admin site.
Graphic application routing support will be coming soon.
The following section describes how to set up application servers to run Microsoft Office in Turbo, using KMS license activation.
# 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
The following section describes how to set up application servers to run natively installed Microsoft Office using an application stub.
# Download Office
setup.exe /download installation-config.xml
# Install Office
setup.exe /configure installation-config.xml
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.
This section describes advanced topics you may encounter when implementing Turbo Server.
Turbo Hub Server enables you to manually configure settings during setup. Using this process you can control the database connection strings used by Turbo Hub Server and the domain names for the Administration and Hub Sites. Turbo Hub Server supports the use of any connection string format used by Microsoft SQL Server.
Complete the following steps to install Turbo Server:
Download the Turbo Hub Server setup file and save it locally.
Open a Microsoft Windows Command Prompt and navigate to the directory of the saved setup file.
Enter the following command: Setup.exe /noprovision. This brings up a file installation wizard. Navigate through the prompts until file installation is complete, and then select Finish.
Complete the following steps to manually configure Turbo Server:
Return to the Microsoft Windows Command Prompt and navigate to the directory where the installation files are saved. You specified this location in the previous step; the default location is C:\Program Files\Turbo Server.
To manually configure Turbo Hub Server, type the command: Server.exe /provision [ADMINISTRATOR EMAIL]. Add any of the optional command-line arguments from the following table. Omitting any command-line arguments causes the default setting to apply.
|
Command Line Argument |
Setting |
|---|---|
|
|
Configures the connection string for the library database where settings and user information is stored. |
|
|
Configures the connection string for the manager database where usage information is stored. |
|
|
Assigns the port and fully qualified domain name for the hub site. |
|
|
Assigns the port and fully qualified domain name for administration site. |
server.exe /provision admin@acme.com /dblibrary "Integrated Security=true;Data Source=acme;Initial Catalog=Library;" /dbmanager "Integrated Security=true;Data Source=acme;Initial Catalog=Manager;" /wwwsite http://www.acme.com /adminsite http://www.acme.com:81
Note: The Microsoft SQL Server connection string will depend on the Microsoft SQL Server configuration. For more information about the connection string, contact the database administrator. Before configuring the Turbo Server, confirm that the running user for the Windows service has appropriate access rights to the database. The service runs under the Local System account by default but the running user can be changed in the Windows services settings.
Select Enter to submit the command and choose Y to proceed.
Fully-qualified domain names can be specified on the Domain page of the Administration Site. For more information about modifying servers refer to Managing the Domain.
By default Application Servers download the application images from Hub before running them. It is however possible to stream the images directly from Hub. To configure the streaming, follow the steps listed below.
The first step is to create a file share where Hub will store the images. Clients will use it as an image cache. For this document, let's assume we want to use the path D:\image-share. It is available for client machines as a read-only Windows share at an address \hub\share (hub is the name of Hub in the internal network).
Now, it’s time to configure Hub. Sign in as an administrator, go to the Server list and click on the server in the hub role. Scroll to the bottom, and there should be an Image Path section. You need to type there the local path of the share folder with images subfolder. In our example, it will be:
After saving the settings, Hub will restart, and new images will automatically appear in the image cache.
To enable streaming, we need to configure the clients to use the hub image cache. It is as simple as running: turbo config --image-path=\\hub\share --all-users. The file share should be read-only. Otherwise, simultaneous client access may corrupt it.
Side note:
The latest Turbo client (19.12.2108) added new options for configuring the machine-scope client settings. The --all-users flag behavior is inconsistent between various commands. Thus we introduced a TURBOAS environment variable to define the scope of the running commands. For example, to set the image-path globally, you may run the following commands in PowerShell:
$env:TRUBOAS=”all-users”
turbo config --image-path=\\hub\share --as-override (if you want to allow users to change this setting, use --as-inherit)
With the image path configured, you may use turbo run or installi on the clients’ machines, and they should directly use the images from the image cache.
This section explains how to manually configure Turbo Server's security settings on common Microsoft Windows platforms. These settings restrict external connections to the Turbo Server sites and services.
To secure the Turbo Server, enable Microsoft Windows Firewall with Advanced Security. The default settings of Microsoft Windows Firewall with Advanced Security block all external connections to the Administration and Portal Sites (assigned to port 80 by default). After Microsoft Windows Firewall with Advanced Security is enabled, add exceptions to the default settings to provide licensed users with access the Hub Site.
Complete the following steps to enable Microsoft Windows Firewall with Advanced Security for access to the Hub Site:
Open the Control Panel and select System and Security.
Open Administrative Tools, then select Windows Firewall with Advanced Security.
Select Inbound Rules and choose New Rule.
Select Port.
Select TCP and Specific local ports. Add the ports required by your server role as described in Firewall and Security.
Select Allow the Connection.
Select the domain, private, and public profiles.
Add a name and description.
The Turbo Server executable, server.exe, is located in the installation directory of Turbo Hub Server (usually C:\Program Files (x86)\Turbo Server). It has many administrative options that are accessible by using command line parameters.
When using the Turbo Server command line administrative tools, it is important to remember the following:
Run the command window as Administrator (right-click Run as Administrator).
When working in the command window place quotation marks around parameters and paths that include a space.
Server.exe can be used with the following arguments to manage provisioning, uninstall, upgrade, and service recycling:
|
Option |
Description |
|---|---|
|
|
Creates the Turbo Hub Server data and sites. For additional details use |
|
|
Uninstalls Turbo Hub Server. |
|
|
Restarts Apache web service gracefully. |
|
|
Prints this usage information. |
Server.exe can also be used to create and update applications, as well as to manage other server settings. This is done by specifying any of the given topics after the Server.exe admin command.
Server.exe admin --directory-services
|
Option |
Description |
|---|---|
|
|
Prints the current list of directory services. |
|
|
Creates a new directory service with default settings. |
|
|
Deletes the given service. |
|
|
Prints help information. |
Print the current directory services:
Server.exe admin --directory-services
Create a new directory service with prefix "loc":
Server.exe admin --directory-services new loc
Delete the "loc" directory service:
Server.exe admin --directory-services delete loc
Server.exe admin --directory-service
|
Option |
Description |
|---|---|
|
|
Attempts to connect to local Active Directory. If it succeeds, the connection and schema settings are printed. |
Server.exe admin --directory-service <login prefix>
|
Option |
Description |
|---|---|
|
|
Prints the current settings for the directory service. |
|
|
Prints the current value of <property>. |
|
|
Sets the value of <property> to <value>. |
|
|
Imports the settings from a file, or standard input if no file is specified. Settings files are in the same format as the output of the print function. |
|
|
Attempts to connect to local Active Directory. If it succeeds, the connection and schema settings are printed. |
|
|
Scans the directory service for recommended schema settings. |
|
|
Prints the subdirectories within this directory service. |
|
|
Prints the user groups within this directory service. |
|
|
Synchronizes users and groups from the directory service. |
|
|
Prints the current synchronized items. |
|
|
Adds an item to be synchronized. |
|
|
Deletes all sync items. |
|
|
Prints help information. |
Connection settings: host, port, binding type, username, password
Schema settings: user and group attribute names used by the external directory service
Synchronized items: if the entire external directory should not be imported, the items commands should be employed to add specific user groups or LDAP directories to include
The following examples describe a typical set of steps to set up a directory service for the local Active Directory.
Print the settings of directory service "ad":
Server.exe admin --directory-service ad
Change the name of directory service "ad":
Server.exe admin --directory-service ad name "Local Active Directory"
Dump the settings of directory service "ad" to a file:
Server.exe admin --directory-service ad print > ad-settings.txt
Discover the schema of directory service "ad":
Server.exe admin --directory-service ad discover
Copy/paste the recommended schema from the console to the ad-settings.txt file.
Print all the groups found in "ad":
Server.exe admin --directory-service ad groups
Specify a user group to be synchronized:
Server.exe admin --directory-service ad items add Group "cn=All,dc=acme,dc=com"
Set all the settings of "ad" from a file:
Server.exe admin --directory-service ad set ad-settings.txt
Server.exe admin --global
|
Option |
Description |
|---|---|
|
|
Prints the current global settings. |
|
|
Prints the current value of <property>. |
|
|
Sets the value of <property> to <value>. |
|
|
Prints help information. |
Examples:
Print the current settings:
Server.exe admin --global
Print the OneDrive Client Id settings:
Server.exe admin --global onedrive-client-id
Set the OneDrive Client Id settings:
Server.exe admin --global onedrive-client-id 9ac73e7d-83aa-425d-8b04-fac64a702f77
Server.exe admin --hub
|
Option |
Description |
|---|---|
|
|
Prints the current hub settings. |
|
|
Prints the current set of API keys. |
|
|
Creates an API key with the given name. Specify "system" or "user" for the type of key to create. |
|
|
Regenerates the value of the API key with the given name. |
|
|
Deletes the API key with the given name. |
|
|
Prints the launch configuration service settings. |
|
|
Enables the launch configuration web service. The authentication key is required to be passed in the header of all POST requests to the web service. The service is disabled by default. |
|
|
Disables the launch configuration service. |
|
|
Sets the length of time (in minutes) that a launch configuration is available after last use. Default is 1-hour. |
|
|
Prints help information. |
|
|
Imports a public image repository from the url (e.g. https://turbo.net/mozilla/firefox). |
Print the current settings:
Server.exe admin --hub print
Add an API key:
Server.exe admin --hub key create "Test Lab Key" system
Enable launch configuration service:
Server.exe admin --hub configsvc enable C68480F0BD594684A90EEB889118CEB6
Server.exe admin --license
|
Option |
Description |
|---|---|
|
|
Prints the current license. |
|
|
Sets the license to the contents of the given text file. |
|
|
Prints help information. |
Print the current license:
Server.exe admin --license print
Set the current license:
Server.exe admin --license set ss-license.txt
Server.exe admin --server
|
Option |
Description |
|---|---|
|
|
Prints the current primary server settings. |
|
|
Prints the current value of <property>. |
|
|
Sets the value of <property> to <value>. |
|
|
Prints help information. |
Print the current primary server settings:
Server.exe admin --server
Print the root web address:
Server.exe admin --server <server-name> web-root
Set the root web address:
Server.exe admin --server <server-name> web-root https://acme/turbo
Set the SSL certificate file path:
Server.exe admin --server <server-name> ssl-certificate-file c:\programdata\acme\cert.txt
Server.exe admin --users
|
Option |
Description |
|---|---|
|
|
Prints the current users and groups. |
|
|
Changes the current authentication type. |
|
|
Gets or sets the number of days that a login ticket is valid when "remember me" is selected. The default is 1 week. The minimum value is 1 day. The maximum value is 200 years (73000 days). |
|
|
Prints help information. |
Print information about current users and groups:
Server.exe admin --users
Change the authentication type to "Forms":
Server.exe admin --users authentication-type Forms
Change the login timeout duration to four weeks:
Server.exe admin --users ticket-timeout 40320
Server.exe admin --user-groups
|
Option |
Description |
|---|---|
|
|
Prints the current list of user groups. |
|
|
Creates a new user group with default settings. |
|
|
Deletes the given group. |
|
|
Prints help information. |
Print the current groups:
Server.exe admin --user-groups
Create a new group with name "Power Users":
Server.exe admin --user-groups new "Power Users"
Delete group 2:
Server.exe admin --user-groups delete 2
Server.exe admin --user-group
|
Option |
Description |
|---|---|
|
|
Prints the current settings for the user group. |
|
|
Prints the current value of <property>. |
|
|
Sets the value of <property> to <value>. |
|
|
Imports settings from a file, or standard input if no file is specified. Settings files are in the same format as the output of the print function. |
|
|
Removes all members from the group. |
|
|
Prints help information. |
Examples:
Print the settings of group 2:
Server.exe admin --user-group 2
Print the properties and members of group 2:
Server.exe admin --user-group 2 print
Remove all members from group 2:
Server.exe admin --user-group 2 clear
Server.exe admin workspace app add [repoId] [workspace] --isolate=[isolation]
Adds application with repoId namespace/name:release to workspace. If workspace is ommited, then server attempts to add the application to the default workspace. Accepted values for the optional isolation flag are full, write-copy or merge.
Server.exe admin workspace app remove [repoId] [workspace]
Removes all applications with repoId namespace/name:release from the workspace. If workspace is ommited, then server attempts to remove all matching applications from the default workspace.
The launch configuration web service provides storage for application configurations which may be used to execute applications from a custom web portal using turbo urls. If the Turbo Portal is used as your application portal, this service is not necessary.
The launch configuration service may be configured using the API Keys form on the admin site.
In this example, the authentication key is set to F207AC681BBD40A0BF56ECF95B344EBC. This value is required to be passed to all POST requests to the service in the X-Config-Api-Key HTTP header. The authentication key can be any string value but should be something long and randomly generated.
NOTE: It is important that this authentication key be kept secret to prevent unauthorized users from generating malicious application configurations. Any usage of the key or the code to submit a configuration must be done on the web portal's server side code (not in the browser client where a user can retrieve the key).
To submit a custom application configuration, a simple web POST such as shown in the follow example may be used:
// create a application configuration object. this example assumes that there is a hub image called "test/test".
// this application configuration will result in the turbo command: turbo try test/test --isolate=full
var appConfig = {
v: 1,
verb: "try",
repoId: "test/test",
isolation: "full"
}
// submit the application configuration to the service
var request = new XMLHttpRequest();
request.open("POST", "http://[hub-server]/start/app");
request.setRequestHeader("Content-Type", "application/json");
request.setRequestHeader("X-Config-Api-Key", "F207AC681BBD40A0BF56ECF95B344EBC");
request.send(JSON.stringify(appConfig));
request.onreadystatechange = function () {
if(request.readyState === 4) {
if(request.status === 200) {
console.log(request.responseText);
}
else {
console.log("request failed with status code: " + request.status);
}
}
};
Submit a POST request to the web service with the configuration json string, note the required request headers of Content-Type and X-Config-Api-Key. The response json contains a set of turbo urls that can be used to execute the application from the browser, for example:
{
"url": "turbo://[hub-server]/start/app?t=config&h=sha256:66a123724dd6f8fb5ee050644a5494795fed2a1901d0c56def4030d8a6a26175&scheme=http&v=2",
"urlInternal": "turbo://[hub-server]/start/app?t=config&h=sha256:66a123724dd6f8fb5ee050644a5494795fed2a1901d0c56def4030d8a6a26175&scheme=http&v=2"
}
Once submitted, the configuration will be available for the configured timeout period. This can be set on the server administration website (the default is 24-hour). The timeout is reset whenever the configuration is retrieved.
You may also lookup configs from the launch configuration service by performing a GET request on the same URL with an HTTP/S scheme, for example:
http://[hub-server]/start/app?h=sha256:66a123724dd6f8fb5ee050644a5494795fed2a1901d0c56def4030d8a6a26175&scheme=http&v=2
// open turbourl to config
var url = "turbo://[hub-server]/start/app?t=config&h=sha256:66a123724dd6f8fb5ee050644a5494795fed2a1901d0c56def4030d8a6a26175&scheme=http&v=2";
window.open(url);
To execute a submitted configuration file, you must use a turbo protocol url. Your web portal can open these turbo urls to attempt to execute the configuration. The turbo protocol is handled by the Turbo Client if installed and will execute the configuration that it points to.
The first time you attempt to open a turbo url, the browser will show a security message like the following (each browser is different). The user can choose to hide future messages for turbo urls.
After the turbo url is allowed by the browser, a security message from the Turbo Client will be shown (see below). This message is to ensure that the user trusts the hub that the container is coming from. It is important that user do not execute containers from untrusted hubs. The user can choose to run this instance or trust all instances from the same hub.
After this the user will be prompted to login if necessary. Once logged in (or if login is not necessary), the container will execute.
{
// The configuration JSON format version. Must be 1.
"v":1
// The turbo command used to execute the application. Possible values are "try", "run", and "new". Required.
"verb":"try",
// The repository ID of the image to execute. Required.
"repoId":"test/test",
// The isolation mode to run in. These are the same as those that can be passed to turbo run commands with `--isolate` flag. Optional, default is "full".
"isolation":"full",
// Allows merge access to special user folders such as documents. Optional, default is false.
"mergeUser":false,
// Whether network isolation is enabled in the container. Optional, default is false.
"isolateNetwork":false,
// A list of network mappings. Optional, default is empty.
// Example: routes:[{"rule":"ip","type":"deny"},{"rule":"ip://*.turbo.net","type":"allow"}],
"routes":[],
// A list of additional image repository IDs that are permanently layered in to the container. Optional, default is empty.
// Example: layers: [{"repoId":"npp/notepadplusplus","enabled":true}],
"layers":[],
// A list of additional image repository IDs that are temporarily layered in to the container. Optional, default is empty.
// Example: using: ["gnu/wget"]
"using":[],
// Overrides the default startup file. Optional, default is no override.
//"startupFile":"cmd",
// Command line parameters that are passed to the startup file of the container. Optional, default is empty.
// Example: cmdLineArgs: "echo test",
"cmdLineArgs":"",
// Automatically synchronizes the application state and settings with the Turbo Hub server. Optional, default is false.
"sync": true,
// Enables pre-caching of application DLL and EXE files on the Application Servers’ local disk for faster loading. Optional, default is false.
"useDllCache": false,
// Specifies drive visibility in the virtual application using the format: <*|V:|-V:>[,...]. Optional, default is *,-T:.
"hideDrive":"*,-T:",
// The VM version is a version string that specifies which Turbo VM version will be used for execution. Optional, default is latest.
//"vm": "19.6.1427.29"
}
Follow these steps to test Turbo Hub Server with SSL enabled using a self-signed certificate.
Configure the container server to use HTTPS/SSL with the Turbo Hub Server command line administration utility.
# change hub url to use https
> server.exe admin /server web-address https://[hub-server-host]
# set certificate files
> server.exe admin /server ssl-certificate-file [path to .crt file]
> server.exe admin /server ssl-certificate-key-file [path to .key file]
# optionally set the certificate key chain file
> server.exe admin /server ssl-certificate-chain-file [path to chain file]
On the client machine, double-click on your certificate.crt file to install it in the "Trusted Root Certification Authorities for Windows"
Access the hub using the Turbo Client command line tools, Turbo Launcher, or connected Turbo Streaming Server portal.
Federation feature allows distributing hub servers across different regions to achieve faster streaming for end users and allows higher availability by redundancy. Federation works by assigning a root server from which the child hub servers to copy repositories from.
Federation child communicates with the root server using an API key which is a secret key between the servers. API keys can be disabled and recreated on demand from the admin user interface to ensure repository access to the server is secure. API keys can be configured to grant low privilege tokens which ensure the key is used only to read repository data from the root server.
Federation repositories can be explicitly cached and synchronized on the child hub by adding them from the federation repository page. Federation repositories can also be automatically forwarded to the root server by using request forwarding. Request forwarding is achieved by forwarding https requests to the root hub.
If the root hub is unavailable due to network outage or maintenance, the child hub will continue to service requests against explicitly synchronized repositories without any downtime to the end users. Request forwarding will be temporarily unavailable. If the child hub becomes unavailable, then the end users will only be able to use their locally cached applications.
Follow the documentation to setup a Hub Server and your repositories to the hub. The server which will contain the source of the repositories will be called the root server.
Setup an API Key
On the root server, navigate to https://{root}/admin/hub/keys.aspx. Add an API Key with a descriptive name such as "Federation Key for {child}". Run as system setting is not required. Copy the generated API key.
Add the federation source to child hub
On the child hub(s), navigate to https://{child}/admin/hub/federationsource.aspx. Change the Hub text box to the root hub host's URL. Add the previously copied API Key and press save.
Add a federated repository
Navigate to https://{child}/admin/hub/federation.aspx. Add a federated repository by using the repository identifier namespace/name (example: mozilla/firefox), and press save. The repository should begin to synchronize immediately with the status displayed on the federation page.
Use the federated repository
Once the repository has finished synchronizing, you may begin using the repository on the child server from a workspace.
You can also install the repository image directly using the turbo cli on the user's machine.
turbo config --hub={child}
turbo login {user}
turbo installi namespace/name
The application should be available from the start menu.
The Hub Server stores repositories and sessions in a file system based database. The database is located under the path C:\ProgramData\Turbo Server\io (formerly C:\turbo-server\io). Administrators should back up that folder in case of drive failure.
The legacy default folder C:\turbo-server\io is a virtualized folder, which will store files in the Turbo Server installation folder sandbox. In addition, any folder under the installation folder will be virtualized and stored in the sandbox. It is recommended to migrate to a folder outside of any virtualized folders.
The recommended action to migrate the legacy Hub storage is to clear the Hub storage setting field which will migrate the data to the new default folder (C:\ProgramData\Turbo Server\io). Prior to migration, please ensure that the Hub storage has been backed up in case of unexpected failures, and that there is enough room in the destination drive.
Internal Turbo Servers users may sign in to a Portal configured to use the single sign-on authentication method by appending the ?mode=forms URL parameter to the login page:
http://my-turbo-server/login?mode=forms
This override can be used when testing and troubleshooting the Turbo Server configuration.
Microsoft RemoteApp disconnects sessions after the initial window is shown then dismissed, and no subsequent windows are shown after a short timeout. Remove any custom splash screens that may cause the timeout to happen, as Turbo will automatically detect the first shown window and delay the timeout as appropriate. If the application itself has transition delays between its windows, then a custom solution may be required. Please contact support@turbo.net. See the Microsoft Documentation for more information.
The following are RDP logon or disconnection errors that can cause the connection to the remote application to fail. These error codes may be found in the Details section on the HTML5 launch error page.
The disconnection was initiated by an administrative tool on the server in another session.
Occurs when an administrator manually disconnects the user, or a script running as an administrator disconnects the user.
The disconnection was due to a forced logoff initiated by an administrative tool on the server in another session.
Occurs when an administrator manually logs off the user, or a script running as an administrator logs off the user.
The idle session limit timer on the server has elapsed.
This timeout is controlled by the Set time limit for active but idle Remote Desktop Services Group Policy setting. The default value set by Turbo Server is 21600000 milliseconds.
To configure this timeout, see Streaming for more information.
The active session limit timer on the server has elapsed.
This timeout is controlled by the Set time limit for active Remote Desktop Services sessions Group Policy setting. The default value set by Turbo Server is 21600000 milliseconds.
To configure this timeout, see Streaming for more information.
Another user connected to the server, forcing the disconnection of the current connection.
Only one connection is allowed at a time per user per application per application server.
To resolve this issue, close all open connections by the user and then relaunch the application.
The logon failed because the logon credentials are not valid.
For non-temporary user authentication, such as Ask and Kerberos, this indicates that the user provided an incorrect password.
For temporary user authentication, this indicates that the temporary login credentials cached by the Broker service differ from the Windows login credentials. This may occur due to manual accounts changes, or due to a Broker service error causing the login credentials to get out of sync.
To resolve the issue:
The attempted logon is not valid. This is due to either an incorrect user name or incorrect authentication information.
For temporary user authentication, this indicates that the temporary login credentials cached by the Broker service differ from the Windows login credentials. This may occur due to manual accounts changes, or due to a Broker service error causing the login credentials to get out of sync.
To resolve the issue:
Remote disconnection by server.
This may indicate that the Windows user does not have permission to login remotely to the application server. Please make sure that the Windows user is part of the Remote Desktop Users group:
Remote Desktop Users, then click OK.Occurs when license negatiation failed due to an expired or invalid RDS license. Please make sure that the RDS license installed on the application server is valid.
For information on setting up RDS licensing, please refer to the Microsoft documentation.
The user must update their password to continue logging on.
To manually remove this login requirement from a user:
The Windows account that is running the remote application session is disabled.
To manually enable a user:
The Windows account that is running the remote application session is locked out.
Account lockout is controlled by the Account lockout threshold Group Policy setting. If you wish to change your account lockout behavior, please update your Group Policy setting:
To manually update a user's lockout status:
The Windows account that is running the remote application session has an expired password.
Account password expirations are controlled by the Maximum password age Group Policy setting. If you wish to change your account password expiration behavior, please update your Group Policy setting:
To manually set a user's password to never expire:
The following are Turbo Server errors that can cause the remote session creation to fail. These error codes may be found in the Details section on the HTML5 launch error page.
The remote application tunnel failed to reconnect due to too many reconnection attempts.
Occurs when the client machine cannot access the Application server. For example, the client machine may be experiences a network issue or the Application server service may be down.
Please check your network connection and wait a few minutes, then relaunch the application. If the error persists, logon to the Application server and check that the Turbo.AppServer service is running.
The events websocket failed to authenticate.
Occurs when the user's Portal login session is missing or invalid. For example, the user's login session may be expired, or the authentication key used to sign the user's login session may have changed.
To resolve this issue, please log out and back into the Portal and then relaunch the application.
The events websocket connection could not be established.
Occurs during Portal service interruptions or connection errors. Please ensure that the portal is available and accessible by your browser.
The requested repository could not be found. Please ensure that the repository exists on the Hub server.
You may manage your repositories from the administration site Hub page.
The remote session could not be found.
Occurs if the remote session is not present in the Broker cache. Please relaunch the application to create a new remote session.
No application servers are currently available. Occurs when there are no application servers running, or when the Broker service cannot access the application servers.
To check if an application server is running and accessible, logon to the Portal server and try opening a browser tab to http://{app-server-host}/server/, replacing {app-server-host} with the internal hostname of your application server (Internal Hostname or IP Address in your domain server settings). A successful response will show a page listing the server version:
If this page return a IIS 404 error page, then uninstall IIS from the server. If IIS is using the same port as the Application server, then the Application server will not be able to be contacted.
If this page returns a Not Found (404) response code, then the application server may be down or the internal hostname may be incorrect. To verify that the application server is running, logon to the application server and check that the Turbo.AppServer service is running.
If this page returns a Connection Timeout, then there may be a Windows firewall issue. To verify your Windows firewall configuration, please refer to the Firewall and Security documentation.
If this page returns a Service Unavailable (503) response code, then the application server is most likely restarting. Please wait a few minutes and try again.
The remote session could not be created due to invalid arguments.
Occurs when the application configuration is missing or invalid.
The remote session could not be created due to an authentication failure.
Occurs when the user's Portal login session is missing or invalid. For example, the user's login session may be expired, or the authentication key used to sign the user's login session may have changed.
To resolve this issue, please log out and back into the Portal and then relaunch the application.
The remote session could not be created because the Broker service could not be found.
Please ensure that the Broker is available and accessible by the portal.
The remote session could not be created due to Broker service availablility.
Occurs when the Broker service is restarting.
Please wait a few minutes for the Broker service to become available and then relaunch the application.
The remote session could not be created due to an unknown server error.
The launch request could not be created due to invalid arguments.
Occurs when the application configuration is missing or invalid.
The launch request could not be created due to an authentication failure.
Occur when the user's Portal login session is missing or invalid. For example, the user's login session may be expired, or the authentication key used to sign the user's login session may have changed.
To resolve this issue, please log out and back into the Portal and then relaunch the application.
The launch request could not be created because the API service could not be found. Please ensure that the API service is available and accessible by the portal.
The launch request could not be created due to API service availablility.
Occurs when the API service is restarting.
Please wait a few minutes for the API service to become available and then try relaunching the application.
The launch request could not be created due to an unknown server error.
If your application fails to start when launched from the Turbo Server workspace, identify what causes the failure.
Confirm that there isn't a problem with Turbo Server by launching an application that is known to work.
A good example is npp/notepadplusplus from Turbo.net Hub, which can be added to Turbo Server from Admin > Hub > Add Repository > Import Repository.
If this application fails similarly, then the problem is likely with Turbo Server rather than the application configuration. In this case, see the Application Server Troubleshooting section.
If the issue is isolated to your application, see the Application Troubleshooting section.
Check the application behavior in each launch mode by right-clicking on the application in the workspace and selecting Run in Cloud (HTML5), Run in Cloud (Windowed), and Run on My PC.
If the application works in HTML5 but not Windowed mode (or vise versa), it is likely a bug in the Turbo Server or Client. Please report the issue to us.
If the application works with Run in Cloud but not Run on my PC, it is probably an application issue. See the Application Troubleshooting section.
If the application works with Run on my PC but not Run in Cloud, test an application that is known to work to determine if the issue is with the server or application configuration.
Run the application from the command-line by opening a command prompt and executing the following to launch the application in a new temporary container: turbo try application-image. Perform this test on the system where the application fails to start (for example, the application server).
If the application fails, then the issue is probably related to the configuration. See the Application Troubleshooting section.
If the application works, then the issue may be caused by a corrupted sandbox or the workspace application settings, such as container isolation or components.
Check if the application launches successfully when using a clean sandbox. The easiest way to perform this test is to create a temporary internal user by going to Admin > Users > Add User and using it to launch the application.
If the application launches successfully, clear the persisted session from the Hub for the affected user by going to Admin > Users > Username > Sessions.
In addition, clear the local session sandbox on systems where the issue occurs by opening a command prompt and executing turbo containers & turbo rm containername or deleting the session folder from C:\Users*username*\AppData\Local\Turbo\Containers\Sandboxes.
Remove all components that are not required to start the application from the Workspace Application settings > Components to check if the issue is caused by a conflict with one of its component.
If the application launches successfuly, see the Application Troubleshooting section to troubleshoot the component issue.
The default container isolation mode is set to Full isolation, which would hide most applications installed on the system and may cause launch failures in some cases. Decrease the container isolation mode to Write-Copy or Merge to check if this is the cause for the failure.
If the application launches successfully after changing the isolation, review the application configuration for missing dependencies.
For some applications issues, it may be necessary to generate and analyze VM diagnostic logs. To generate the logs, append &diagnostic= to the launch page URL.
Original: https://turboserver/run/3c3120d5-0151-41fa-9f35-bb2a8082c291?loc=2&title=Notepad%2B%2B
Diagnostic Logging Enabled: https://turboserver/run/3c3120d5-0151-41fa-9f35-bb2a8082c291?loc=2&title=Notepad%2B%2B&diagnostic=
The VM logs will be written to the container sandbox folder on the local system (when using Run on my PC) or application server (when using Run in Cloud). By default, this would be in %LOCALAPPDATA%\Turbo\Containers\sandboxes*sandbox-guid*\logs.
For more information on analyzing VM logs, see the Application Troubleshooting section.
If you have recently published an application update, ensure that the new application image is being used by opening a command prompt and running turbo images on the system where the application is executed. Confirm that the application image ID matches your updated image.
The Turbo Client checks for application updates once every 24 hours. If you have pushed an update recently, perform a manual pull to update the client repository immediately instead of having to wait for the automatic update check by running the following in a command prompt: turbo pull application-image.
Some applications and licensing mechanisms require the application to be executed under an Active Directory Windows user.
If the application has this requirement, set the Workspace Application settings > General > Profile Mode to Ask for Credentials, then launch the application and enter your user credentials when prompted to execute it under your user.
If a particular application runs on one environment and not another, it could also be related to the security software installed on the particular system. Please refer to the Antivirus and Security Software documentation.
If Internet Explorer is required by your application, ensure the application isolation is set to write-copy or merge. Full isolation may not be compatible with applications that require external software built into Windows such as Internet Explorer.
A common point of failure is due to the group policy applied to the application server. In a typical enterprise scenario the administrator has applied Microsoft's security baseline group policies on Windows servers. There are some group policies that will prevent the application server from functioning. Some of these policies may not appear in your Group Policy editor if the template is missing from your Windows Policy folder, but must be changed to install correctly. Ensure the following group policies are either unconfigured or set to the following values in the table:
|
Path |
Setting |
Value |
Comment |
|---|---|---|---|
| Administrative Templates > Windows Components > Remote Desktop Services > Remote Desktop Session Host > Security | Always prompt for password upon connection | Disabled | A login prompt will prevent remoteapp applications from launching. |
| Require use of specific security layer for remote (RDP) connections | Enabled (SSL) or not configured | Enhances security by requiring TLS 1.0 to authenticate the RD Session Host server during RDP connections. | |
| Require user authentication for remote connections by using Network Level Authentication | Enabled or not configured | Enhances security by requiring user authentication earlier in the remote connection process. Some clients may require NLA authentication to login. | |
| Administrative Templates > Windows Components > Remote Desktop Services > Remote Desktop Session Host > Connections | Allow users to connect remotely by using Remote Desktop Services | Enabled or not configured | If this is not configured and users are able to connect then it may be left as not configured. |
| Administrative Templates > Windows Components > Remote Desktop Services > Remote Desktop Session Host > Device and Resource Redirection | Do no allow drive redirection | Disabled or not configured (Recommended) | Disables the mapping of client drives when streaming remote applications. |
| Administrative Templates > Windows Components > Remote Desktop Services > Remote Desktop Session Host > Session Time Limits | Set time limit for active Remote Desktop Services sessions | 21600000 (Recommended) | The maximum amount of time that a Remote Desktop Services session can be active before it is automatically disconnected. |
| Set time limit for active but idle Remote Desktop Services sessions | 21600000 (Recommended) | The maximum amount of time that a Remote Desktop Services session can be active before it is automatically disconnected. | |
| Set time limit for disconnected sessions | 3000 (Recommended) | The maximum amount of time that a disconnected session remains active on the server. | |
| Set time limit for logoff of RemoteApp sessions | 600000 (Recommended) | 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. | |
| Windows Settings > Security Settings > Local Policies > User Rights Assignment | Deny access to this computer from the network | Remove Local account | Local users must be able to remote into application server to run applications and configure the machine using the --app-server install. This is not required if using active directory authentication. |
| Deny log on through Remote Desktop Services | Remove Local account | Local users must be able to remote into application server to run applications. This is not required if using active directory authentication. | |
| Allow log on through Remote Desktop Services | Add Users | Click object types and check "groups" then add the object "Users". | |
| Windows Settings > Security Settings > Application Control Policies > AppLocker > Executable Rules | Allow Everyone | %OSDRIVE%\PROGRAMDATA\TURBO\* | Turbo VM images may be cached in the PROGRAMDATA folder. |
| Windows Settings > Security Settings > Application Control Policies > AppLocker > Executable Rules | Allow Everyone | %OSDRIVE%\USERS\*\APPDATA\LOCAL\TURBO\* | Turbo Container Sandboxes may be cached in the user's local AppData folder. |
The following group policies enables WinRM for legacy (prior to version 2019.7.26) Turbo Broker:
|
Path |
Setting |
Value |
Comment |
|---|---|---|---|
| Administrative Templates > SCM: Pass the Hash Mitigations | Apply UAC restrictions to local accounts on network logons | Disabled or not configured | Security baseline will enable this value. If the policy path is missing, locate the ptH.admx and add it in your group policy templates folder. |
| Administrative Templates > Windows Components > Windows Remote Management > WinRM Client | Allow Basic authentication | Enabled or not configured | Security baseline default value is not configured. |
| Allow unencrypted traffic | Enabled or not configured | Security baseline will set this to disabled. The winrm command will test the connection using basic http. | |
| Administrative Templates > Windows Components > Windows Remote Management > WinRM Service | Allow remote server management through WinRM | Enabled or not configured | Application server provision requires WinRM. If enabled, make sure you set the IPv4 and IPv6 filters correctly. |
| Allow Basic authentication | Enabled | Application server provision requires WinRM. | |
| Allow unencrypted traffic | Enabled | Application server provision requires WinRM. | |
| Windows Settings > Security Settings > Local Policies > User Rights Assignment | Deny access to this computer from the network | Remove Local account | Application server provision requires WinRM potentially over the local administrator account. |
In a command prompt on the application server, issue the following command:
>winrm identify -r:http://localhost:5985 -auth:basic -u:{adminuser} -p:{password} -encoding:utf-8
The command should be an IndentifyResponse. If command fails and you have checked the group policies have been properly set, try the winrm quickconfig command. Note that the quickconfig command will request LocalAccountTokenFilterPolicy. Turbo does not require that setting to be enabled.
>winrm quickconfig
WinRM service is already running on this machine.
WinRM is not set up to allow remote access to this machine for management.
The following changes must be made:
Configure LocalAccountTokenFilterPolicy to grant administrative rights remotely to local users.
Make these changes [y/n]? y
WinRM has been updated for remote management.
Configured LocalAccountTokenFilterPolicy to grant administrative rights remotely to local users.
>winrm quickconfig
WinRM service is already running on this machine.
WinRM is already set up for remote management on this computer.
The application server provisioner should make the required changes to enable RemoteApp execution. Ensure these registry settings were applied properly:
|
Path |
Setting |
Value |
Comment |
|---|---|---|---|
| HKLM:\SOFTWARE\Policies\Microsoft\Windows NT\Terminal Services | fDenyTSConnections | 0 (DWORD) | Enables Terminal Services. |
| fResetBroken | 1 (DWORD) | ||
| fDisableCam | 0 (DWORD) | Enables audio. | |
| DisablePasswordSaving | 0 (DWORD) | ||
| fPromptForPassword | 0 (DWORD) | ||
| fEncryptRPCTraffic | 0 (DWORD) | ||
| MinEncryptionLevel | absent | Remove this value. | |
| Shadow | 1 | Enable admin session shadowing. | |
| fSingleSessionPerUser | 0 | Allows the user to run multiple applications in separate sessions. | |
| HKLM:\SOFTWARE\Policies\Microsoft\Internet Explorer\Main | DisableFirstRunCustomize | 1 (DWORD) | Disable IE first run dialog |
| HKLM:\Software\Policies\Microsoft\Windows\CurrentVersion\Internet Settings\Zones\1 | 2500 | 0 (DWORD) | Enable IE Protected mode for local intratet, avoiding warning on first use |
| HKLM:\Software\Policies\Microsoft\Windows\Windows Error Reporting | DontShowUI | 1 (DWORD) | Disable crash report UI |
| HKLM:\Software\Policies\Microsoft\Windows\WindowsUpdate | ElevateNonAdmins | 0 (DWORD) | Disable Windows Update UI for non-admins |
| HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion\Policies\Ext | RestrictToList | 1 (DWORD) | Disable IE addons dialogs |
| HKLM:\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Terminal Server\TSAppAllowList | fDisabledAllowList | 1 (DWORD) | Enables the RemoteApp allowed program list. |
| CustomRDPSettings | authentication level:i:2 (String) | Specifies RemoteApp custom settings such as the authentication level. | |
| HKLM:\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Terminal Server\TSAppAllowList\Applications\turboplay | Path | C:\Program Files (x86)\Turbo\Cmd\turboplay.exe (String) | Make sure turboplay is allowed. |
| HKLM:\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Terminal Server\TSAppAllowList\Applications\turbo | Path | C:\Program Files (x86)\Turbo\Cmd\turbo.exe (String) | Make sure turbo is allowed. |
| HKLM:\SYSTEM\CurrentControlSet\Control\Terminal Server\WinStations\RDP-Tcp | SecurityLayer | 2 (DWORD) | Require TLS 1.0 to authenticate the RD Session Host server. |
| UserAuthentication | 1 (DWORD) | Enable Network Level Authentication. |
The following Windows updates are required to establish secure connections between the client and RD Session Host. Not installing the following updates on the application server may prevent connections between the client and application server from functioning:
|
Operating System |
Update |
Comment |
|---|---|---|
| Windows Server 2012 | KB4103730 or KB4103726 | Security update for Remote Desktop connections. |
| Windows Server 2016 | KB4103723 | Security update for Remote Desktop connections. |
Disable Automatic Updates if Windows Update notifications are being shown on remote sessions:
First open the Local Group Policy Editor:
> gpedit.msc
Set Configure Automatic Updates to disabled under Computer Configuration/Administrative Templates/Windows Components/Windows Update.
The remote application failed to launch
There is a 20 second interval when the Turbo Server service is starting where the communication between the Broker and Application Server is out of sync. The application launch should succeed once the interval has elapsed.
Application Server performance is poor
Ensure that background processes such as Windows updates is disabled when the Application Server is expected to be in use. Log in as administrator and open Task Manager. If the TiWorker.exe is running with high CPU usage then it indicates that a Windows update is in progress.
The broker logs indicate the application server is unavailable
Ensure the application server service can be started by remoting into the server and using the url http://localhost:8085/server/. If the service responds then the service should be working, if not continue to the next step.
Next use the internal hostname url such as `http://{internal-url}/server/. If the URL responds with an IIS 404 error, then uninstall IIS from the server. Turbo server requires IIS to not use the same ports as the application server port. If the service is completely unresponsive, open Windows task manager and restart the Turbo service. Check the URL again to see if its responsive.
If the application itself is encountering errors or hangs, the first step to troubleshoot the issue is to log into the application server directly and attempt to run it there using the turbo command line interface (ie. turbo run [app]). If the problem reproduces in this way then see application troubleshooting suggestions here.
This section provides information to help troubleshoot common end user issues.
The service does not have permissions to upload a file on behalf of the user due to missing domain credentials when running the application in ask for domain login mode. Users must use the down-level style login (domain\username) when asked to login to the application, or have the administrator set the default domain if the end user omits it during login. To allow users to omit the domain, please set the default domain of the intended for the workspace under admin -> general section located at https://{portal-host}/workspace/{workspace-name}/admin/general.
The lock screen timeout is controlled via group policy setting. To configure custom session timeouts, please refer to the Streaming section on the Turbo Server administration site.
For older versions of Turbo Server, you may change the group policy setting manually. Please refer to the microsoft documentation to disable or extend the timeouts.
By default, client drives are made available when streaming a remote application from the native client. This behavior can be controlled via group policy setting. To enable or disable drive redirection, please refer to the Streaming section on the Turbo Server administration site.
If the Turbo Server with the Hub role is not running, users would not be able to sign in to the workspace portal. The Portal log will contain a message that it failed to load the public key, similar to the following:
[2020-12-08T22:39:30.584] [INFO] default - Fetching JWT public key from https://hubserver/
[2020-12-08T22:39:51.672] [ERROR] default - Failed to load JWT public key: Error: connect ETIMEDOUT 10.1.2.4:443
[2020-12-08T22:39:54.378] [WARN] default - Failed to decode ticket, JWT public key is not available.
To resolve the issue, start the Turbo Server with the Hub role and wait a minute for the Portal to successfuly load the public key.
This section provides information to help troubleshoot common issues you might encounter while using Turbo Server.
The following table lists common issues/questions and their solutions:
|
Issue/Question |
Solution |
|---|---|
| There is an error during installation: Turbo Hub Server installation failed, please contact the administrator. | This may occur if there is a timeout when starting or accessing the database services. Go to Control Panel > Administrative Tools > Services and try restarting the Turbo Hub Server service. |
| The Turbo Hub Server service fails to start. | This may occur if there is a timeout when starting or accessing the database services. Go to Control Panel > Administrative Tools > Services and try restarting the Turbo Hub Server service. If the service continues to fail to start, review the required ports for the installed roles. Ensure that other services such as IIS do not conflict with required ports. |
|
I am unable to access the Administration Site or Hub Site from another machine. |
Microsoft Windows security settings might be restricting external connections to the ports assigned to the Administration and/or Hub sites. For information about configuring Turbo Hub Server security settings, refer to Configuring Turbo Hub Server Security. |
|
My application does not appear on the Turbo Streaming Server portal. |
Verify that the application has been pushed to the correct org account dashboard (for turbo.net hub) or namespace (for Turbo Hub Server). For more information about publishing application versions, refer to Managing Applications. |
|
Where do I install a new license? |
New licenses can be applied by clicking the New License link found on the Admin page in the Administration Site. |
| Turbo Hub Server is no longer accessible after making a Network Configuration change | Turbo Hub Server service may need to be restarted after making a network configuration change. Go to Control Panel > Administrative Tools > Services and try restarting the Turbo Hub Server service. |
|
HTML5 cloud launch fails to start the application and results in the generic error page. |
Review the SSL troubleshooting documentation. If it is not a certificate issue, the application server may not be accessible from the broker. Check that port 80 or 443 can be accessed from the broker to the application server. |
|
HTML5 cloud launch fails to start the application with The service not available error. |
This error may occur if the application login mode is set to ask, and the user attempts to login with a user that is not part of the Remote Desktop Users group. Ensure the user is part of the Remote Desktop Users group. |
|
Help! I forgot the administrator account password and can't access the Administration Site. |
Remove the admin group by using the server cli. Open a command prompt as administrator and navigate to the installation folder. Run `Server.exe admin user-group 2 clear` which clears all users from the server administrator's group. This allows you to access the the Administration Site without login. Reset the admin user's password and add the user back to the administrator's group to secure the Administration Site. |
|
An error occurs when pushing large images to the hub. |
Hub JVM may require more memory to synchornize large images. Navigate to the admin's /admin/domain/servers.aspx page and navigate to the Hub server's settings. Increase the Hub heap max setting. |
|
The admin site displays Compiler Error Message: The compiler failed with error code -1073741502. |
The service user does not have permissions to modify the asp.net temporary compiler cache. Stop the Turbo service. Delete C:\Windows\Microsoft.NET\Framework\{version}\Temporary ASP.NET Files. Restart the Turbo service. |
|
Unable to run applications remotely on Application Server due to Windows Interactive Login Message feature. |
Use the **Notice and Consent** setting under /admin/general. Remove the group policy as described [here](https://docs.microsoft.com/en-us/windows/security/threat-protection/security-policy-settings/interactive-logon-message-text-for-users-attempting-to-log-on), and disable the following registry keys: |
|
Error 'The remote name could not be resolved' when accessing the administration site. |
Open command prompt on the Hub server and issue ping commands to well known hosts. If the ping commands fail then the DNS server may not be resolving correctly. Switch to a public DNS server and see if the ping commands work. If they work then the error is due to the previous DNS server. |
|
Upgrade fails with error 'Cannot start service Turbo on computer'. |
Unknown error in Windows service control manager. Restart the computer and try again. |
Enabling diagnostic mode generates debug output logs. These can be used to help the Turbo support staff diagnose and debug issues.
Diagnostic logs are written to the c:\users[user]\appdata\local\turbo\logs directory.
When troubleshooting an issue related to the general administration of Turbo Hub Server, enable diagnostic mode for Turbo Hub Server. Complete the following steps to enable diagnostic mode for Turbo Hub Server:
Open a Windows Command Prompt as an administrator (cmd.exe).
Enter the following command: net stop turbo
Navigate to C:\ProgramData\Turbo Server and open settings.xml with Notepad or another text editor.
Add a new element called TraceLevel with value Debug as a child element to Settings; after adding this element the file should resemble the following:
<?xml version="1.0" encoding="utf-8"?>
<settings>
<InstallPath>[Path]</InstallPath>
<InstalledVersion>[Version]</InstalledVersion>
<DbLibraryConnection>embedded</DbLibraryConnection>
<DbManagerConnection>embedded</DbManagerConnection>
<TraceLevel>Debug</TraceLevel>
</settings>
Enter the following command: net start turbo
There are several types of logs available for Turbo Server, including logs for the installation process, Apache, and SQL Server. The log file locations are dependent on the install location of Turbo Server. The default location is "C:\Program Files\Turbo Server".
Turbo Hub Server Installation Logs
Turbo Hub Server Service Logs
Turbo Hub Server Web Services Logs
Turbo Hub Server SQL Server Logs (Embedded SQL Server Express)
Turbo Hub Server Apache Logs
Turbo Streaming Server Logs
turbo logs [container] --export=c:\path to retrieve the logs.Oftentimes, troubleshooting and fixing problems in Turbo Server requires the Turbo Server service be restarted.
There are currently two ways of doing this, through either the Control Panel or the Command Prompt. Each method is listed, below:
Through the Control Panel
a. Navigate to Control Panel > Administrative Tools > Services or Control Panel > System and Security > Administrative Tools > Services
b. Restart the Turbo Server service
Via the Command Prompt using the net command
a. Run a new command prompt (cmd.exe) as Administrator
b. Type the command net stop turbo to stop the Turbo Server service
The expected output for this command is:
The Turbo Server service is stopping.
The Turbo Server service was stopped successfully.
c. Type the command net start turbo to start the Turbo Server service
The expected output for this command is:
The Turbo Server service is starting.
The Turbo Server service was started successfully.
The Windows Event Viewer is another useful source of information. If there is an issue starting the Windows service for Turbo Hub Server there may be information reported in the Window Event Viewer to help diagnose the problem.
This section provides information to help troubleshoot common Single Sign On (SSO) issues.
For information on how to configure Turbo Server to use SSO, please refer to the Authentication Method section.
Occurs when the application registration was not configured with the correct implicit grant type. Please ensure that you have configured your application registration to issue ID tokens.
See Configure Azure AD for more information on configuring the implicit grant types.
Occurs when the application registration was not configured with the correct API permissions. Please ensure that you have configured your application configuration to grant User.Read and Directory.Read.All permissions.
See Configure Azure AD for more information on configuring the API permissions.
The login response did not return the state that was expected by the Portal.
This may occur for various reasons, for example:
The login request was invalidated by another login or logout request by the same user
To resolve, close any browser tabs with active login attempts then click on the Portal Login button to initiate a new login request.
The login took too long to complete
To resolve, click on the Portal Login button to initiate a new login request and complete the login before the time limit expires.
By default the login request expires in 1 hour.
The user exceeded the maximum number of concurrent login requests
To resolve, close any browser tabs with active login attempts then click on the Portal Login button to initiate a new login request.
By default a user can have a maximum of 5 concurrent login request.
The Portal service restarted after the user initiated the login request.
The Portal server stores the expected login response states server-side in an in-memory cache. If the Portal restarts mid login request, the expected login response state will be cleared from memory, and the login request will fail.
To resolve, wait for all Portal service restart to complete then click on the Portal Login button to initiate a new login request.
The Portal connect.sid cookie saved on the client machine is invalid
The connect.sid cookie associates the client browser to the server-side user session cache where the state expected by the login response is stored. If this state becomes invalid for any reason, the login response validation will fail.
This can be resolved by removing the connect.sid cookie from the client machine. To remove this cookie from your browser:
Chrome: Visit chrome://settings/siteData and search for your Portal server's hostname. Click on the matching search result, then click Remove All to clear all Portal cookies.
Firefox: Visit about:preferences#privacy and click Manage Data under Cookies and Site Data. Search for your Portal server's hostname, then click Remove All Shown to clear all Portal cookies.
Edge: Visit edge://settings/siteData and search for your Portal server's hostname. Click on the matching search result, then click Remove All to clear all Portal cookies.
Occurs when the login request fails to authenticate due to an application registration or Turbo Server configuration error, such as:
See Configure Azure AD for more information.
The Turbo user could not be created due to a missing user principal name (UPN) claim.
Turbo Server expects the following claim to be returned in email format by the identity service:
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier
If you are using AzureAD with SAML 2.0, see Configure Azure AD for more information on setting up the claims.
If you are using ADFS with SAML 2.0, see Configure ADFS for more information on setting up the claims.
The Turbo user could not be created due to an authentication failure.
Occurs when the Portal service has a missing or invalid API key. The Portal may have started with invalid settings due to a configuration change or database access error.
To resolve, please restart the Turbo service on the Portal server and try again in a few minutes.
The Turbo user could not be created due to API service availablility.
Occurs whens the API service is restarting. Please wait a few minutes and try again.
The Turbo user could not be logged in due to an authentication failure.
If you are using SAML authentication, please make sure that your values for the Signing Certificate Thumbprint and Signing Certificate Common Name are correct and that your signing certificate is installed on the Hub server. See Configure Turbo Server for more information on setting up the signing certificate.
The Turbo user could not be logged in due to API service availability.
Occurs when the API service is restarting. Please wait a few minutes and try again.
Unable to login to the portal after installing SSL certificates. Unable to launch applications remotely on application server. Please check the portal logs. The logs contain the following error(s):
[ERROR] default - Failed to load JWT public key: Error: self signed certificate in certificate chain
[ERROR] default - Failed to authenticate: self signed certificate in certificate chain
Solution: If the certificate specified is self signed, the Hub and Portal servers must have the self signed certificate installed into the certificate store. If the certificate requires an intermediate certificate, the certificate must be installed into the Intermediate Certificatation Authorities store on both the Hub and Portal servers.
Unable to login to the portal with the following log:
[ERROR] default - Failed to authenticate: {User} unable to verify the first certificate
Solution: The SSL chain file is missing or invalid. Use openssl to test the certificate chain:
> openssl s_client -showcerts {hubserverhost}:443
CONNECTED(00000005)
depth=0 CN = hubserverhost
verify error:num=20:unable to get local issuer certificate
verify return:1
depth=0 CN = hubserverhost
verify error:num=21:unable to verify the first certificate
verify return:1
The error can be further validated using ssllabs.com by entering the host of the Turbo Server to analyze. Expand the certification paths section to see which part of the certificate chain is missing. If parts of the certificate chain is missing, contact the administrator to obtain the correct certificate chain.
IMPORTANT: The chain file should be in crt format. If the cert extension is .p7b you must convert that to crt using the following opensll command:
openssl pkcs7 -print_certs -in old.p7b -out new.crt
Check the proxy-apache.log file in the Turbo Server\Logs folder.
[ssl:emerg] [pid 2828:tid 1084] AH02561: Failed to configure certificate s27-2016-2.start.turbo.net:443:0, check C:/c/cert.crt
[ssl:emerg] [pid 2828:tid 1084] SSL Library Error: error:0906D06C:PEM routines:PEM_read_bio:no start line (Expecting: CERTIFICATE) -- Bad file contents or format - or even just a forgotten SSLCertificateKeyFile?
[ssl:emerg] [pid 2828:tid 1084] SSL Library Error: error:140AD009:SSL routines:SSL_CTX_use_certificate_file:PEM lib
AH00016: Configuration Failed
You may have a DER encoded file. Use openssl to convert it to the PEM.
openssl x509 -inform der -in certificate.cer -out certificate.crt
Attempting to access the Admin portal shows the following error message:
The remote certificate is invalid according to the validation procedure.
This error occurs when validation of the SSL certificates fail.
Solution: Check that the certificates match the configured Internal Web Service Root URL and that they are not expired.
Confirm that your certificates are trusted by the Windows operating system and perform the troubleshooting steps above.
Temporarily disable HTTPS to access the admin site and make configuration changes:
# Change directory to Turbo Server install folder
> cd "C:\Program Files (x86)\Turbo Server"
# Get name and web-root of the hub server
> Server.exe admin --server
# Switch from HTTPS to HTTP to regain access to the admin portal
> Server.exe admin --server <hub-name> http://<hub-web-root>
Check the corresponding log in %LOCALAPPDATA%\turbo\logs. If the logs indicate an SSL failure during sync:
02/16/2021 11:27:45.6419 - Debug - 0x1118: {"log":"*** Sync encountered an error: Received fatal alert: handshake_failure","msSinceStart":1795}
02/16/2021 11:27:45.9703 - Debug - 0x1118: {"log":"(javax.net.ssl.SSLHandshakeException)\n\njavax.net.ssl.SSLHandshakeException: Received fatal alert: handshake_failure
...
02/16/2021 11:27:45.9703 - Debug - 0x1118: exit -1
Trouble shoot your SSL certificate using ssllabs.com.
The following documentation describes how to upgrade Turbo Server to the latest version.
Make sure the administrator who will be running the setup file has SQL database access. Database read and write permissions are required because the setup will upgrade any database schema changes. There will be a brief maintenance window during the upgrade process. Ensure there is sufficient time to perform the upgrade process. Allocate at least approximately 30 minutes for possible maintenance downtime.
Turbo Server 21.3.2732.2 has updated Web Applications to improve customization and consistency with other application types. The follow migration guide details the process required to migrate existing Web Applications when upgrading from Turbo Server 21.1.2640 to 21.3.2732.2 or later.
If you do not have any Web Applications, do not wish to migrate your Web Applications, or are upgrading from an earlier version, no changes are required.
To migrate your existing Web Applications that are configured to use a virtual browser, you must first collect the Web Application information before upgrade, and then create new Web Applications using that information post upgrade.
Please perform the following steps before upgrading:
Repeat this process for each of your Web Applications. Once complete, you may upgrade your Turbo Server.
Once your upgrade is complete, please update the repositories used by your browsers. This will allow the repositories to be selected when creating Web Applications.
browser to the Categories field and click Save.Repeat this process for each of your browser repositories.
Finally, please recreate your Web Applications:
Repeat this process for each of your Web Applications.
To migrate your existing Web Applications that are configured to use a local system browser, you must create a Link with equivalent settings to your Web Application. Links are availables from the Links tab on the dashboard.
Please perform the following steps before upgrading:
Repeat this process for each of your Web Applications. Once complete, you may upgrade your Turbo Server.
The following document describes external services that can be used to check the health status of Turbo Server.
Nagios can be used to monitor the health of a Turbo Server environment.
The following configuration monitors the HTTP response times and SSL certificate validity of the Portal.
define service {
use local-service
host_name <turbo-server-hostname>
service_description HTTP Response Time
check_command check_http!<turbo-server-hostname>!https://<turbo-server-hostname>!5!10!-S
}
define service {
use local-service
host_name <turbo-server-hostname>
service_description SSL Certificate Expiration Check
check_command check_http_cert!<turbo-server-hostname>!14
}
The HTTP Response Time check will cause a WARNING alert if the response time is over 5 seconds and a CRITICAL alert if over 10 seconds or not responding. The SSL Certificate Expiration Check will cause alerts if the certificate will expire in under 14 days.
The following configuration monitors the Turbo Server Windows Services.
define service {
use generic-service
host_name <turbo-server-hostname>
service_description Turbo Server Hub/Portal Service
check_command check_nt!SERVICESTATE!-d SHOWALL -l Turbo
}
define service {
use generic-service
host_name <turbo-server-hostname>
service_description Turbo Server Application Service
check_command check_nt!SERVICESTATE!-d SHOWALL -l Turbo.AppServer
}
The Windows Service check will cause alerts if the services are not running.
Datadog can be used to monitor the health of a Turbo Server environment.
The following configuration monitors the HTTP response times and SSL certificate validity of the Turbo Server portal instance.
- name: <turbo-server-hostname>
url: https://<turbo-server-hostname>
seconds_warning: 5
seconds_critical: 10
check_certificate_expiration: true
disable_ssl_validation: false
days_warning: 14
This check will cause a WARNING alert if the response time is over 5 seconds and a CRITICAL alert if over 10 seconds or not responding. This check also cause an alert if the certificate will expire in under 14 days.
The following configuration monitors the Turbo Server Windows Services.
- services:
- Turbo
- Turbo.AppServer
The Windows Service check will cause alerts if the services are in a not running state.
Configuring Turbo Server with Canvas allows students and instructors to access their Portal Dashboard with one click from Canvas. Turbo Server functionality is added to Canvas LMS as an external application from the Canvas user interface.
Turbo Server uses the open Learning Tools Interoperability (LTI) specification (version 1.0) to communicate with Canvas.
Canvas requires the following to connect to Turbo Server Application:
The values can be obtained from the Turbo Server administration site. Navigate to General > Learning Tools Interoperability.
A canvas account can be created at https://canvas.instructure.com.
Turbo can be linked with an individual course by an instructor or with all courses by a Canvas Administrator. Navigate to the Course or Administrator Account you wish to link.
Adding Turbo to an Administrator Account will require a single setup for all courses. Every instructor will see the option to enable Turbo in their Course Navigation.
Go to Settings > Apps > View App Configurations > +App.
Change the Configuration Type dropdown to By URL.
Enter the information from the Turbo Server administrator site:
Click on Submit and refresh the page. The Turbo Entry point will be in the Course Navigation.
Turbo can be enabled or disabled on a course by course basis.
Configuring Turbo Server with Blackboard Learn allows students and instructors to access their Portal Dashboard with one click from Blackboard.
Turbo Server uses the open Learning Tools Interoperability (LTI) specification (version 1.0) to communicate with Blackboard.
Obtain a blackboard license from https://www.blackboard.com/.
Blackboard requires the following to connect to Turbo Server Application:
The values can be obtained from the Turbo Server administrator site. Navigate to General > Learning Management System.
Before adding Turbo to an individual course, an administrator account must configure Turbo site-wide from the Blackboard administration site.
From System Admin, navigate to LTI Tool Providers, listed under Integrations. Select Register LTI 1.1 Provider.
Under Provider Domain Status, in the Provider Domain box, enter the hostname portion of the Tool Provider URL shown on the Turbo Server administrator site. Set the Provider Domain Status to Approved.
Under Default Configuration, select Set Globally. Fill in the Tool Provider Key and Secret with the values from the Turbo Server administrator site.
Under Institution Policies, configure the following:
Click Submit.
If your organization has any courses set to Original UI, the following steps are required for instructors of those courses to see Turbo. Administrator privileges are required.
From the LTI Tool Providers page, open the Options Menu dropdown beside Turbo.
Select Manage Placements. Then select Create Placement. Under Placement Information, set Label to Turbo.net and Handle to something unique for your Blackboard Site.
Turbo supports the following options for Type:
The Turbo Icon can be downloaded here.
Under Tool Provider Information, enter the Tool Provider URL from the Turbo Server administrator site.
Click Submit.
These steps require at least instructor privileges and do not apply to courses with the Ultra UI. An administrator must have already added Turbo site-wide and created a Course Placement. The administrator and end users must also be enrolled in the course to access Turbo.net.
Navigate to the Content page of the desired course
Open the Tools dropdown. Select More tools.
Select Turbo.net. Configure as desired and click Submit.
These steps require at least instructor privileges and apply only to courses with the Ultra UI. An administrator must have already added Turbo site-wide. The administrator and end users must also be enrolled in the course to access Turbo.net.
Navigate to the Ultra course desired. Click the plus icon and select Create to add Course Content.
From the right sidebar, select Teaching tools with LTI connection.
Set as Visible to students.
Under Configuration URL, enter the Tool Provider URL from the Turbo Server administrator site.
The error occurs after Turbo.net has been added to Blackboard by an administrator and activated on the course.
Solution: Ensure your user is enrolled in the course. Blackboard prevents unenrolled users (including administrative users) from accessing LTI apps.
The error occurs when the secret does not match.
Solution: Ensure the secret in the Blackboard administration site matches the secret from the Turbo administration LTI page.
Configuring Turbo Server with Moodle allows students and instructors to access their Portal Dashboard with one click from Moodle.
Turbo Server uses the open Learning Tools Interoperability (LTI) specification (version 1.0) to communicate with Moodle.
Download Moodle from moodle.org then follow the installation instructions.
Moodle requires the following to connect to Turbo Server Application:
The values can be obtained from the Turbo Server administrator site. Navigate to General > Learning Management System.
Instructors will be able to add Turbo to their courses with a few clicks. Administrator privileges within Moodle are required.
Navigate to Site administration > Plugins. Navigate to Manage tools, listed under Activity modules > External tool.
Select configure a tool manually.
Fill in the following fields:
Turbo must already be configured by a Moodle administrator. Instructor level privileges are required for the course.
Browse to the desired course in Moodle. Select Turn Editing On.
Locate the place Select + Add an activity or resource.
Under Activities, select External tool.
Under General, select Turbo.net from the Preconfigured tool dropdown. Set Activity Name to Turbo.net.
Click Save and return to course.
If Turbo has not been configured site-wide by a Moodle administrator, instructors can configure Turbo specifically for their course. Instructor level privileges are required for the course.
Browse to the desired course in Moodle. Select Turn Editing On.
Locate the place Select + Add an activity or resource.
Under Activities, select External tool.
Under General, click Show more… and configure as follows:
Under Privacy, ensure “Share launcher’s name with tool” and “Share launcher’s email with the tool” are both checked.
Click Save and return to course.
Unlike other virtualization solutions that require an entire copy of the host operating system, Turbo's container technology only emulates the features required to run application. Turbo containers have the same performance characteristics as native applications, but without any changes to system infrastructure.
The core of Turbo virtualization technology is the Turbo Virtual Machine (VM) kernel. Occupying just a few megabytes of storage and minimal performance overhead, Turbo VM is a lightweight implementation of core operating system APIs, including file system, registry, process, and threading subsystems.
Turbo VM is implemented entirely within the user-mode space, meaning Turbo applications can run without any driver installation or administrative privileges.
Turbo containers interact with a virtualized file system, registry, and process environment contained in the kernel, rather than directly with the host device operating system. Requests are handled internally within the virtualized environment, but can also be redirected or overridden based on your configuration.
A key benefit to Turbo virtualization technology is the assurance of forward compatibility of applications as new version of the underlying operating system are released.
Turbo VM provides a translation layer that mitigates incompatibilities across diverse operating system variants, providing a consistent environment for the application and its dependencies.
Turbo conducts continuous testing against OS builds distributed on the Windows Insider Track and makes VM updates as required. These updates are periodically published to Turbo.net but are not pushed to users. Specific VM versions may be pulled and tested by application publishers prior to general availability.
Upon availability of a new Windows Semi-Annual Channel release, Turbo validates and publishes the corresponding VM update. Unless otherwise specified by the administrator, users are automatically updated at that time to the latest Turbo VM via the Turbo.net cloud.
The Turbo VM is capable of running multiple images in a single virtual machine container by layering the file system and registry of each image.
This allow's users to create modular components that can be reused by larger projects.
In this section, the term layer is used interchagibly with image, since a layer within a container is always created by an image.
Layering is used to support Turbo Studio components. It is also used when dependencies are created.
In most scenarios, image layers will define unique resources that do not conflict with each other. However, it is possible for the layers to have conflicting resources and settings.
If multiple layers define different isolation modes for the same path, the first layer that defines the isolation mode will be used.
For example, if a container includes a git image with c:\git set to full isolation and a nodejs image with c:\git set to merge isolation, the conflict between the isolation settings will be resolved by the ordering of the layers.
The following command will create a container with the folder c:\git set to full isolation.
> turbo run git,nodejs
The following command will create a container with the folder c:\git set to merge isolation.
> turbo run nodejs,git
Turbo VM maps well known root folders such as Documents and Program Files based on the host operating system at runtime.
These variables may also be used in TurboScript and as part of command-line arguments when building images or starting Turbo containers.
Note: Folder variables are case sensitive. They must appear in all caps to be recgonized by the command processor.
|
Variable |
Description |
|---|---|
@APPDIR@ |
(Application Directory): Folder where the virtual application executable resides. |
@WINDIR@ |
(Windows): The operating system installation location root as in c:\windows. |
@SYSDRIVE@ |
(System Drive): The root folder of the drive containing the operating system installation as in c:\. |
@PROGRAMFILES@ |
(Program Files): The 64-bit Program Files folder. |
@PROGRAMFILESX86@ |
(Program Files (x86)): The 32-bit Program Files folder. Program Files on 32-bit platform, and Program Files (x86) on 64-bit platform. |
@PROGRAMFILESCOMMON@ |
(Program Files\Common): The 64-bit Program Files\Common folder. |
@PROGRAMFILESCOMMONX86@ |
(Program Files (x86)\Common): The 32-bit Program Files folder\Common. Program Files\Common on 32-bit platform, and Program Files (x86)\Common on 64-bit platform. |
@SYSTEM@ |
(Windows\System32): The Windows 64-bit System32 folder. |
@SYSWOW64@ |
(Windows\SysWOW64): The Windows 32-bit System32 folder. Windows\System32 on 32-bit platform and Windows\SysWOW64 on 64-bit platform. |
@APPDATALOCAL@ |
(Current User Directory\AppData\Local): The folder that serves as a common repository for application-specific data used by the current, non-roaming user. |
@APPDATALOCALLOW@ |
(Current User Directory\AppData\LocalLow): The folder that serves as a common repository for application-specific data used by the current, non-roaming user for applications running with the Low integrity level. |
@APPDATA@ |
(Current User Directory\AppData\Roaming): The folder that serves as a common repository for application-specific data for the current roaming user. |
@STARTUP@ |
(Current User Directory\Start Menu\Programs\Startup): The folder containing the current user's startup items. |
@PROGRAMS@ |
(Current User Directory\Start Menu\Programs): The folder containing the user's program groups. |
@STARTMENU@ |
(Current User Directory\Start Menu): The folder containing the user's Start Menu contents. |
@DESKTOP@ |
(Current User Directory\Desktop): The current user's Desktop folder. |
@TEMPLATES@ |
(Current User Directory\Templates): The folder that serves as a common repository for the current user's document templates. |
@FAVORITES@ |
(Current User Directory\Favorites): The current user's Favorites folder. |
@DOCUMENTS@ |
(Current User Directory\Documents): The current user's Documents folder. |
@MUSIC@ |
(Current User Directory\Music): The current user's Music folder. |
@PICTURES@ |
(Current User Directory\Pictures): The current user's Pictures folder. |
@VIDEOS@ |
(Current User Directory\Videos): The current user's Videos folder. |
@DOWNLOADS@ |
(Current User Directory\Downloads): The current user's Downloads folder. |
@PROFILE@ |
(Current User Directory): The folder that stores the current user's profile data. |
@APPDATACOMMON@ |
(All Users Directory\Application Data): The folder that serves as a common repository for application-specific data shared by all users. |
@STARTUPCOMMON@ |
(All Users Directory\Start Menu\Programs\Startup): The folder containing startup items for all users. |
@PROGRAMSCOMMON@ |
(All Users Directory\Start Menu\Programs): The folder containing components shared across applications. |
@STARTMENUCOMMON@ |
(All Users Directory\Start Menu): The folder containing the Start Menu contents for all users. |
@DESKTOPCOMMON@ |
(All Users Directory\Desktop): The shared Desktop folder. |
@TEMPLATESCOMMON@ |
(All Users Directory\Templates): The folder that serves as a common repository for shared document templates. |
@FAVORITESCOMMON@ |
(All Users Directory\Favorites): The shared Favorites folder. |
@DOCUMENTSCOMMON@ |
(All Users Directory\Documents): The shared Documents folder. |
@MUSICCOMMON@ |
(All Users Directory\Music): The shared Music folder. |
@PICTURESCOMMON@ |
(All Users Directory\Pictures): The shared Pictures folder. |
@PICTURESCOMMON@ |
(All Users Directory\Pictures): The shared Pictures folder. |
@PROFILECOMMON@ |
(All Users Directory): The folder that stores shared profile data. |
@PROFILECOMMON@ |
(All Users Directory): The folder that stores shared profile data. |
The behaviour of containers and images can be modified by changing VM settings at runtime.
Effect the settings flags below using the --enable=VALUE or --disable=VALUE flags with the turbo run or turbo build command.
# Example
turbo run --enable=IsolateWindowsClasses nodejs cmd
Altering VM settings for a container will override the settings of the base image(s).
|
Flag |
Default |
Persisted to Images |
Behavior |
|---|---|---|---|
DEPCompat |
Disabled |
Yes |
Enables compatibility for systems with Data Execution Protection (DEP) enabled. Enable this setting for containerized applications running on Windows 2003. |
DRMCompat |
Disabled |
Yes |
Enables additional compatibility with common DRM systems such as Armadillo. |
FaultExecutables |
Disabled |
Yes |
Forces all executable files to be faulted into the application container. |
HonorWow6464Access |
Enabled |
Yes |
Grants registry access to 32-bit applications snapshotted and running on 64-bit operating systems. |
IndicateElevated |
Disabled |
Yes |
Forces an application to run as if it has elevated security privileges even if the application does not. Enabling this setting will also eliminate UAC security prompts for elevation and subsequent application crashes. |
IsolateWindowsClasses |
Enabled |
Yes |
Prevents a containerized process from viewing window classes that are registered by external processes. You can use this to prevent interaction between containerized and non-containerized versions of the same program when the application checks for existing class registrations. |
MergeStartupDir |
Disabled |
Yes |
If executing a shell operation, instead of setting isolation level to Merge for the startup file only, set it for its parent folder and all subfolders except well-known root folders. |
PeriodicRegFlush |
Disabled |
No |
Enables a container's registry to be periodically flushed to disk storage. |
ReadOnly |
Disabled |
Yes |
Any attempts to write to a file or registry value will result in an access denied error code. |
ReadShare |
Disabled |
Yes |
Forces any files opened within the container to open with the `READ_SHARE` flag. Enabling this setting may help resolve compatibility issues caused by sharing violations. |
ShutdownProcTree |
Disabled |
Yes |
Forces all child processes in the container to shutdown when the root process exits. |
SpawnComServers |
Enabled |
Yes |
Forces any COM servers to be isolated from the host device. By default, COM servers are created outside the virtual environment to allow COM communication between containerized processes and native applications. |
SpawnVM |
Enabled |
Yes |
Forces all child processes of a container to be launched inside the container with access to the virtual environment. |
SuppressPopups |
Enabled |
Yes |
Suppresses any error popup dialogs that the virtual environment generates during application runtime. |
Data Execution Protection (DEP) is a combined hardware and software technology designed to prevent execution of malicious code. DEP prevents memory pages not explicitly marked as executable from executing.
DEP has been supported on Windows since Windows XP SP2 and is supported by both Intel (via Execute Disable Bit or XD) and AMD (via No-Execute Page Protection or NX).
Certain applications may execute memory not marked as executable content as part of their dynamic runtime behavior. This behavior is detected by Windows if DEP is enabled and causes the application to crash. Such applications may require DEP to be disabled on the system.
The DEP Compatibility Mode in Turbo VM allows applications otherwise incompatibile with DEP to execute successfully without modifications to the host OS settings.
DEP Compatibiity Mode works by forcing Turbo VM to apply executable permissions to all memory pages used by applicable virtual processes.
This option is enabled via the Turbo Studio intefarce under the Process Settings or via the DEPCompat flag.
Note that enabling this option disables protections provided by DEP. This option is disabled by default and should only be enabled when required for compatibility purposes.
XAPPL files specify the configuration for a container image created with Turbo Studio. XAPPL files are in XML format so it's easy to edit a container's configuration in a text editor just as you can with Turbo Studio user interface.
Here is a list that describes the purpose of each of the tags you see in XAPPL files created with Turbo Studio:
Path to the folder where the output is saved after a successful build. This can be a local path, a UNC path, or a mapped drive.
Name of the image file output (ie. image.svm or application.exe).
The type of output that is created when built.
Possible values:
The expiration settings for the output image.
Attributes:
The child elements ExpiredMessage, ExpirationWarning, and UnreachableWarning are the text messages that are displayed.
The output options for the application build.
Attributes applicable to standalone applications:
/XEnable=Diagnostics command line parameter.Attributes applicable to portable applications:
The output settings for the MSI setup file.
Attributes:
Contains a Proxy element.
The network proxy settings for the container image.
Attributes:
The clipboard settings for the container (ie. copy-paste operations).
Attributes:
The global environment variable settings.
Attributes:
Contains a collection of Dependency elements. These only affect container environments run through the Turbo.net Client Runtime platform and have no effect on standalone executable builds.
Specifies a Turbo.net Hub dependency for the image.
Attributes:
Contains a collection of Requirement elements. These only affect container environments run through the Turbo.net Client Runtime platform and have no effect on standalone executable builds.
Specify various requirements that are enforced at runtime.
Attributes:
Configuration settings of runtime packages which are included in the image. Contains Java and a collection of Package elements.
Attributes:
Indicates that a layer is to be merged into the image at build-time. Turbo Studio searches the local Layers cache for matching packages. The Layers cache is in C:\Users[user]\Documents\Turbo.net\Components and is configured in the Turbo Studio Layers panel.
Attributes:
Configuration settings for the virtual java runtime. Contains Runtime and Settings elements.
Configuration settings for the virtual java runtime.
Attributes:
Configuration settings for the virtual java runtime.
Attributes:
Virtual machine configuration settings which affect runtime behavior. Also contains a ChildProcessVirtualization element.
Attributes:
Settings for how child processes are handled in the container. Contains a collection of ChildProcessException elements.
Attributes:
Indicates a child process that is to have different spawnVm settings than the default specified in ChildProcessVirtualization.
Attributes:
Allows a container to search for additional layers to load at runtime. Contains a collection of RequiredXLayer elements.
Attributes:
Specifies which layers are required to be present in order for the container to launch. The search pattern in XLayers element must be specified.
Attributes:
Allows isolation of specific named objects in the container (such as events, mutexes, and semaphores). Contains a collection of Exception elements.
Attributes:
Specifies exceptions to the default named object isolation rules.
Attributes:
Specifies DNS mappings inside the container environment. Contains a collection of Entry elements.
Specifies a mapping for hostnames and IPs from one to another.
Attributes:
Overwrites device characteristics of the machine where the container is executed. Contains elements for MachineName, MachineSid, NetworkAdapters, and ComputerSystemProduct. Use xstudio.exe /capture-device to fill in the information.
Overwrites the name of the machine which is returned from GetComputerNameEx and GetComputerName system APIs. Does not change the COMPUTERNAME environment variable.
Overwrites the SID (Security Identifier) of the machine.
Replaces the network adapters which appear available to the container. Contains a collection of NetworkAdapter elements which contain a PhysicalAddress element. The PhysicalAddress element accepts the MAC address of the adapter that will be returned by the GetAdaptersAddresses system API (ex: 000d83b1c08e).
Overwrites the machine system product UUID returned from Win32_ComputerSystemProduct WMI. Contains a UUID element (ex: FAF76B96-798C-11D2-AAD1-006008C78BC7).
Contains information about the snapshot machine where the application configuration was created. For non-snapshot scenarios, this element is empty.
Attributes:
Specifies which directory the virtual application will execute from.
Attributes:
A list of VM settings which are to be disabled in the Turbo.net Client Runtime environment (including portable executables). Not applicable to standalone executables or their dependencies. Contains a collection of DisabledVmSetting elements.
Specifies a VM setting to be disabled in the Turbo.net Client Runtime environment.
Attributes:
A list of user defined shims that will be executed on container startup. Contains a collection of Shim elements.
A list of user defined shims that will be executed on container shutdown. Contains a collection of Shim elements.
A user defined DLL that contains custom functionality to be executed before or after a container's life.
Attributes:
A user defined shell script file (.bat or .cmd) that is executed before or after a container's life.
Attributes:
Specifies launch restrictions based on Active Directory group or domain membership.
Attributes:
Configures standard metadata properties. For standalone executables, these values show up in .exe properties. For layers, these values will be used when displaying information when imported in the Layers panel in Turbo Studio. Contains a collection of StandardMetadataItem elements.
Standard metadata which is applied to the image.
Attributes:
Configures custom metadata properties. For standalone executables, these values show up in .exe properties. Contains a collection of CustomMetadataItem elements.
Custom metadata which is applied to the image.
Attributes:
Defines a splash image that is displayed while the startup file is being executed.
Attributes:
Defines the available files that can be executed to start the container. Contains a collection of StartupFile elements.
Defines a file that can be used to start the container.
Attributes:
--trigger parameter can be used to specify the group to execute. If this is empty, it will be executed by default (same as default attribute).Defines layers of virtual operating system settings which are merged together at runtime. Layers are loaded in the order that they are defined in the xappl. Conflicting settings (ie. a file defined in multiple layers with different isolation settings) are won by the layer that is loaded first. Containers a collection of Layer elements.
Defines a layer of the virtual operating system. Contains elements for Condition, Filesystem, Registry, EnvironmentVariables, EnvironmentVariablesEx, PortMaps, ObjectMaps, Services, Shortcuts, ProgIds, Extensions, DefaultPrograms, SnapshotDirectories, and ShellExtensions.
Attributes:
Defines a condition that must pass at runtime for the layer to be applied.
Attributes:
variable - The type of the condition. Possible values include:
operator - The operator used in the condition. Possible values are context specific and include Less, LessEqual, Equal, NotEqual, GreaterEqual, Greater, AND, OR, NOT, Exists, and DoesNotExist.
value - The comparison value for the condition. Acceptable values are context specific.
Defines the virtual filesystem. Contains a collection of root Directory elements.
Root directory elements include:
Defines a directory in the virtual filesystem. Contains a collection of Directory and File elements.
Attributes:
Defines a file in the virtual filesystem.
Attributes:
Defines the virtual registry. Contains a collection of root Key elements.
Root registry key elements include:
Defines a registry key in the virtual registry.
Attributes:
Defines a registry key value in the virtual registry.
Attributes:
name - The name of the registry value. Set to empty string for the default value.
isolation - The isolation level of the registry key. Possible values are Full and Hidden.
type - The type of registry value. Possible values include:
value - The registry value in string format. See above type for format. This is not applicable to StringArray types.
pathInformationTuples - An optional value that is set for the string types if the value was normalized during the snapshot process. The three values in the tuple are:
Deprecated. See EnvironmentVariablesEx.
Defines virtual environment variables. Contains a collection of VariableEx elements.
Defines a virtual environment variable.
Attributes:
Defines mappings between virtual network ports and native ports. Contains a collection of PortMap elements.
Defines a mappings between a virtual network port and a native port.
Attributes:
Defines name mappings for various Windows objects. Contains a collection of ObjectMap elements.
Defines a name mapping for various Windows objects.
Attributes:
Possible values:
| Type | Name | Mapping |
|---|---|---|
| pipe - Indicates that a named pipe should be isolated from the native system. | The name of the pipe that is to be isolated. | Unused. Must be assigned to the value "0". |
| ip - Maps requests to the specified IP address to another IP address. | The IP address to map from. The name can include an optional flag to not preresolve hostnames. This is done be prefixing the name with $$donotpreresolvehostnames$$ (ex: ip://$$donotpreresolvehostnames$$1.1.1.1:2.2.2.2). | The IP address to map to. To deny access to the named IP, set this value to 0.0.0.0. This value can be made identical to the IP to map to allow the IP if there are other generic mappings to deny it (ex: ip://1.1.1.1:1.1.1.1). |
| host - Maps requests to the specified host name to another host or IP address. | The host name to map from. A wildcard character is supported at the beginning (ex: * or *.google.com). | The IP address or host name to map to. To deny access to the named IP/host, set this value to 0.0.0.0. This value can be made identical to the name to map to allow the host if there are other generic mappings to deny it (ex: host://*.google.com:*.google.com if host://*:0.0.0.0 also exists). |
| window - Indicates that a window class name should be isolated from the native system. | The name of the window class to be isolated. | Unused. Must be assigned to the value "0" (ex: window://IEFrame:0 will isolate Microsoft Internet Explorer's main window from the native environment). |
Defines virtual services. Contains a collection of Service elements.
Defines a virtual service.
Attributes:
sc start command.Defines shortcuts that will be added with desktop registration or MSI deployments. Contains a collection of root Folder elements.
Root shortcut folders include:
Defines a folder where shortcuts will reside that will be added with desktop registration or MSI deployments. Contains a collection of Folder and Shortcut elements.
Attributes:
Defines a shortcut that will be added with desktop registration or MSI deployments. The shortcut must point to an existing startup file. Optionally contains an IconResource element.
Attributes:
The icon to use for the shortcut.
Attributes:
Defines virtual COM ProgIDs that will be added with desktop registration or MSI deployments. Contains a collection of ProgId elements.
Defines a virtual COM ProgID that will be added with desktop registration or MSI deployments. This is used for file associations. Contains a collection of Verb and IconResource elements.
Attributes:
Defines shell verbs that can be used with associated files.
Attributes:
The icon to use for the file extension mapped to this ProgID. If not present then the Windows default empty document icon will be used.
Attributes:
Defines the file associations which will be added with desktop registration or MSI deployments. Contains a collection of Extension elements.
Defines a file association which will be added with desktop registration or MSI deployments.
Attributes:
Deprecated. Leave empty.
Records the native environment where a snapshot was taken. These mappings are used at runtime to resolve paths in opaque data structure (ie. application files) that couldn't be resolved at build time (like can be done for registry key values). Contains a collection of Directory elements.
Records a mapping for root filesystem directory nodes. These are used instead of the standard mappings.
Attributes:
Defines shell extensions that will be added with desktop registration. Contains a collection of ShellExtension elements. For internal use only.
Defines a shell extension that will be added with desktop registration.
Attributes:
Unused. Leave empty.
Deprecated. Leave empty.
A unique GUID for the configuration.
Attributes:
Once your container package is built, it is time to test on the platforms that you expect to encounter. When issues surface there are several things that can be done to track down the cause.
Some problems are caused because the xappl configuration didn't render an environment as was expected. To determine if files and registry keys are as they should be, instances of Windows command prompt or registry editor can be started in the container.
To start a command prompt instance in a virtual application's container environment:
> turbo run <image> --startup-file=cmd.exe
-OR-
> virtual-app.exe /XShellEx=cmd.exe
This will start a command prompt inside the application's container. Now you can move around the file system to see exactly what the application's in the container can see. Make special considerations for paths that have 32-bit vs 64-bit implications (ie. "program files" vs "program files (x86)"), especially when troubleshooting environments with mixed process architectures.
Note, it is easy to forget that a command prompt is for the container rather than for your native system. To prevent confusion it is recommended to set the title of the command prompt by executing title in container which will put "in container" as the prompt title.
To start a registry editor instance in the virtual application's container environment:
> turbo run <image> --startup-file=c:\Windows\system32\regedt32.exe
-OR-
> turbo run <image> --startup-file=c:\Windows\syswow64\regedt32.exe
-OR-
> virtual-app.exe /XShellEx=c:\Windows\system32\regedt32.exe
-OR-
> virtual-app.exe /XShellEx=c:\Windows\syswow64\regedt32.exe
This will start an instance of the registry editor inside the container environment. Note that Windows only allows one instance of the registry editor to be running so close down all other instances before running this command or else you may not be viewing what you think you are.
The 32-bit vs 64-bit registry is also something to be aware of with the registry editor. Select the registry editor to launch based on the architecture of the process that you are investigating.
Turbo has a team of knowledgable support engineers to help you build your packages. We can help you through any problems that you face. Email our team at support team. See Support Programs for more information on the services that we offer.
When troubleshooting issues with containers, it is often useful to generate diagnostic logs for analysis. These logs show detailed information about system calls and error codes that were generated during the application life.
If you are running with the Turbo cli, use:
turbo run --diagnostic <image>
If you are running a standalone executable, use:
> virtual-app.exe /XEnable=Diagnostics
Alternatively, an environment variable can also be set to enable diagnostic logs. This allows access to diagnostic information when the command line options are not easily modified (ex. service containers, container launched from non-container, etc).
> SET __VMDIAGNOSTICS=true
> virtual-app.exe
NOTE: Can also specify this as a global environment variable.
In diagnostic mode, a log file will be created for each process that is spawned in the container environment. By default the virtual machine logs are named "xclog_[pid].txt" and the network logs are named "xcnetwork_[pid].txt", where "pid" is the process ID in hexidecimal format. The virtual machine logs show diagnostic information about the code executing in the process. The network logs show specifics about network handling, virtual proxies, and routing.
Virtual machine logs are frequently very large and it can be a difficult task to isolate which of the many error conditions are causing problems. There are several techniques that can be employed to make the task easier.
The first technique is to compare working logs to failing ones. In many cases, a container will work in most situations but fails in a certain environment. Collecting logs on both working and failing machines allows us to ignore the errors that are "expected" and focus only on those that are unique. This technique is most useful when there are working and failing cases on very similar platforms (ie. both Win7 x64). Comparing logs from different platforms (ie. WinXP vs Win10) often have too many differences to be of much use. To compare the logs, tools such as WinDiff or WinMerge can be used. Even having the files open side-by-side can produce results.
The second technique is to narrow the scope of the logs that you have to look through. For example, if an error only occurs after a button is pressed, then copying off the logs immediately before and after the button press will allow you to determine the set of log entries that were written for the operation that led to the error (the difference between the before and after logs). This can be especially effective when coupled with the first technique of comparing working to failing logs.
The Turbo Logs Investigator tool allows filtering logs and comparing the logs side-by-side to find errors. We recommend using WinMerge as the text comparison tool.
Virtual machine logs show every system function call that comes from the process.
An example of a log entry is below:
pid:1240, tid:5416, tick:0x1757B5, lvl:LOG, func:NtQueryValueKey, status:0xC0000034, name:"InprocServer32", class:0x2, length:0x90, resultlength:0x0, handle:0x79E, path:"\Registry\Machine\Software\Classes\CLSID\{4B429D05-8931-11D2-A213-0008C71AB540}\InprocServer32"
The fields of the log entry are:
pid - The ID of the process that generated the log entry.
tid - The ID of the thread that generated the log entry.
tick - The tick count when the log entry was written. Tick count is the number of elapsed milliseconds since the machine was started.
lvl - The severity of the log entry. Possible values include "OK", "LOG", "WRN", and "ERR". "OK" indicates the entry was a success case. "LOG" indicates that the function failed or was other informative non-function call log entry. "WRN" indicates that something failed unexpectedly and may suggest a problem. "ERR" indicates that something failed unexpectedly and is likely a problem. Note that not all "LOG" entries are ignorable and every "ERR" entry is a problem, any log entry requires analysis based on the context of the call.
func - The function where the log entry was written from. Most often these will be Windows APIs that have entries in Microsoft Docs or Microsoft Developer Network that can give more context about the parameters in the log entry.
status - The NTSTATUS code that is returned from the function. See NTSTATUS Values for a list of values. In this case we see 0xC0000034 which is for STATUS_OBJECT_NAME_NOT_FOUND. Not all functions return NTSTATUS codes. Some may have "gle" which is the system error code returned from GetLastError. See System Error Codes for a list of values. Other functions have "hr" which is for an HRESULT code. HRESULT values are usually very context specific so no single resource catalogs their values. A quick web search will often find their meaning.
After the return value, the log entry will show the list of parameters that were passed to the function. This will depend on the function being called and is where checking the Microsoft documentation can be helpful.
In our example for "NtQueryValueKey", the Microsoft documentation is here. Note, many of the function calls in the virtual machine are at a very low level and will be listed in the documentation for drivers with "Zw" rather than "Nt" (ie. "ZwQueryValueKey" not "NtQueryValueKey"). This is Microsoft naming convention for user-mode and kernel-mode APIs.
In this doc, we see that the signature for "NtQueryValueKey" is:
NTSYSAPI NTSTATUS ZwQueryValueKey(
HANDLE KeyHandle,
PUNICODE_STRING ValueName,
KEY_VALUE_INFORMATION_CLASS KeyValueInformationClass,
PVOID KeyValueInformation,
ULONG Length,
PULONG ResultLength
);
From this Microsoft documentation, we see that the purpose of this function is "return a value entry for a registry key" and the remaining fields of the log entry are:
name - The name of the value entry to obtain data for.
class - A KEY_VALUE_INFORMATION_CLASS value that determines the type of information returned in the KeyValueInformation buffer. For more information about the values that this can be, see the doc on KEY_VALUE_INFORMATION_CLASS.
length - The size, in bytes, of the KeyValueInformation buffer.
resultlength - The size, in bytes, of the key information.
handle - The handle to the key to read value entries from. This was created by a previous call to NtCreateKey or NtOpenKey.
path - The resolved path in the container that the handle represents.
From viewing this log entry, we can determine that this thread was looking up a COM GUID to determine how it should be activated. It was not able to find the information it was looking for at this location. This might be a problem or it might continue its search in another location (ie. in HKCU, etc). NOTE: There are always many error codes returned by system calls so determining which error is causing a problem can be tricky.
This is just one example but following the same procedures to cross reference with Microsoft documentation can be used to decipher most any log entry.
Network logs show details about any network operations that pass through the process.
An example of a log is below:
Bind succeeded: 127.0.0.1
Connect succeeded: 127.0.0.1
GetAddrInfoW resolving detectportal.firefox.com
Host detectportal.firefox.com resolved to: 104.80.89.26
Host detectportal.firefox.com resolved to: 104.80.89.24
GetAddrInfoW resolving detectportal.firefox.com
Connect succeeded: 104.80.89.26
Host detectportal.firefox.com resolved to: 104.80.89.26
Host detectportal.firefox.com resolved to: 104.80.89.24
DnsQuery_A resolving a1089.d.akamai.net
GetAddrInfoW resolving location.services.mozilla.com
Host location.services.mozilla.com resolved to: 34.252.164.43
Host location.services.mozilla.com resolved to: 52.16.107.9
Host location.services.mozilla.com resolved to: 52.17.111.251
GetAddrInfoW resolving location.services.mozilla.com
Host location.services.mozilla.com resolved to: 34.252.164.43
Host location.services.mozilla.com resolved to: 52.16.107.9
Host location.services.mozilla.com resolved to: 52.17.111.251
DnsQuery_A resolving locprod1-elb-eu-west-1.prod.mozaws.net
Host locprod1-elb-eu-west-1.prod.mozaws.net resolved to: 52.16.107.9
Host locprod1-elb-eu-west-1.prod.mozaws.net resolved to: 52.17.111.251
Host locprod1-elb-eu-west-1.prod.mozaws.net resolved to: 34.252.164.43
This log snippet was generated by starting an instance of a Mozilla Firefox browser container. Here we see that the winsock calls to GetAddrInfo, DnsQuery, etc were made as well as how each of the hosts were resolved. These logs can be especially useful when troubleshooting issues with virtual network routing and proxies.
Turbo applications are compatible with all major antivirus and security software vendors. However, there are many configurations of these which can cause errors or hangs in Turbo applications. If encountering issues, a good first step is to disable any security software to rule it out as a possible cause.
This error indicates that there is a problem accessing the container executable from itself. This can occur from security software that limits what applications have access to or if the application was started with a low privilege user which doesn't have access to the folder where the executable resides.
Try adding exclusions to your security software for the application. Also, try enabling the Launch child processes as user setting.
This error indicates that the container cannot access files in the environment found in the application directory. The most common reason for this is that the application path is not being resolved correctly. This can happen if there are path resolution rules defined for the container. For example, if there is a Snapshot Directory mapping from @PROGRAMFILES@ to c:\program files (x86), then running the container from c:\program files will fail. See xappl reference for more information.
If you attempt to execute an EXE file over 4GB in size you will get the error message:
See the article on handling Large Applications for information on containerizing and optimizing large applications.
Applications cannot be run by anonymous users.
Would you like to upgrade your account now? (y/n)
Ensure the correct domain is set and login to a valid Turbo Server account:
turbo config --domain=<your domain>
turbo login <username>
Critical error: An unhandled exception has occured
Please contact support@turbo.net
Sandbox is already in use.
There is an existing instance of the application that is in use. Use turbo stop <containerid> to stop the existing instance. If the command does not succeed, find the corresponding turbo.exe process using Task Manager and kill process. If the process cannot be found, use Process Explorer to find the process. You can find virtual processes by searching for the string handle _xvm_mtx.
Turbo applications are compatible with all major antivirus and security software vendors. However, there are many configurations of these which can cause errors, hangs, or false positives in Turbo applications. If encountering issues, a good first step is to disable any security software to rule it out as a possible cause. If disabling the security software fixes the issue, further analysis is required to determine if there is indeed a security compromise or if it is an incompatability with your application.
In some configurations, Sophos Endpoint Protection application hooks can cause hangs in Turbo applications. If this is the case, exclusions can be added to prevent Sophos from inserting itself into the application.
Add the following Turbo folders to the Global Exclusions:
For more information on adding Global Exclusions, please see docs.sophos.com.
Configure an Exploit Mitigation Exclusion to prevent Sophos from affecting the container environment. For more information on configuring Exploit Mitigation Exclusions, please see docs.sophos.com.
The following document describes how to obtain a .DMP file for a running application that is in an erroneous state for diagnostics.
Open taskmgr.exe (defaults to 64 bit if trying to debug turbo server service). The 32 bit taskmgr.exe can be found under c:\windows\syswow64 on 64 bit Windows.
For Turbo Server service, you can find the process by looking at the command line column by right clicking the task manager column. Look for Turbo Virtual Machine with command line TurboServer-Service.exe.
Right click on the process and select Create Dump File.
Alternatively, you can use WinDbg to create the file. A portal version can be found here.
To create a dump file using WinDbg, attach the process and run the command:
> .dump /ma c:\path\to\your\dump
To debug the .DMP file, open in windbg x64 using file open crash dump.
You can debug .NET applications by using the sos module:
> .loadby sos clr
> !eestack -ee
If .loadby fails with some load module errors, make sure the bitness of windbg is correct. Detailed documentation can be found here.
To look at a stack on a specific thread, ex: thread #6
> ~6s
> !dumpstack
The Turbo command line interface (CLI) is accessible from the Windows command prompt using the turbo command.
The Turbo CLI provides programmatic access to all major Turbo functions and can be used, for example, to automate processes or interface with third party products.
The Turbo CLI is installed as part of any of the Turbo Client, Turbo Server, and Turbo Studio setups.
This section provides a general reference for all Turbo CLI commands. For details on using the CLI for specific purposes (eg for automated desktop deployments or SCCM integration), see the appropriate section in the Turbo documentation.
The build command is used to automate the creation of images. The build command can build images from a TurboScript or a .xappl configuration file.
Usage: turbo build <options> <path>
<options> available:
--diagnostic Enable diagnotic logging
-e, --env=VALUE Set environment variables inside the container
--env-file=VALUE Read in a line delimited file of ENV variables
--format=VALUE Use json format for output
--mount=VALUE Mount a host folder into the container. Format: [other-container:]SourceFolder=TargetFolder
-n, --name=VALUE Name of the image
--no-base Do not merge the base image into the new image
--overwrite Overwrite existing image
--route-file=VALUE Specify a routing rules file
--vm=VALUE The Turbo VM version to run the container with
--wait-after-error Leave program open after error
--wait-after-exit Leave program open after it exits
To build an image from an existing container, use the commit command.
A TurboScript is a list of instructions that Turbo will follow to create a container. After the last instruction in a script, Turbo will automatically run turbo commit on the recently created container, creating a new image.
When building from a .me script, Turbo will take the following steps:
from instruction -- this is equivalent to turbo run <image>If there are any conflicts between a TurboScript instruction and a command-line flag then the TurboScript instruction will take precedence.
A .xappl file is an XML file that contains all of the filesystem, registry, and configuration information for a given image. A .xappl file can be built using Turbo Studio.
Environment variables can be added to the container through the -e or --env-file flags. These environment variables are initialized at container creation and thus may be overridden by variables created with the env instruction in the build script.
To create multiple environment variables in the container, use multiple -e flags. For example, the following command would add two environment variables, VAR1 with value 1 and VAR2 with value 2, to the built image.
> turbo build -e=VAR1=1 -e=VAR2=2 C:\TurboScript
Alternatively, use the --env-file flag and specify all of the environment variables you wish to add to the image in a line-delimited text file. For example, the previous command could be replicated using the following command:
> turbo build --env-file=C:\env-vars.txt C:\turbo.me
where env-vars.txt has the contents:
VAR1=1
VAR2=2
Note: If the --env-file and -e flags are used in the same command, the env-file flag is always processed before the -e flag. In the case of a conflict, the -e flag always takes precedence.
Name images using the -n flag and overwrite existing images with the same name using the --overwrite flag.
> turbo build -n=my-new-image C:\turbo.me
...
Output Image: my-new-image
# Try to build the same image second time
> turbo build -n=my-new-image C:\turbo.me
Error: The image already exists. You can overwrite with the --overwrite flag
# Try third time, with --overwrite flag
> turbo build -n=my-new-image C:\turbo.me --overwrite
...
Output Image: my-new-image
# Tags can be optionally added to the -n flag
> turbo build -n=my-new-image:1.0 C:\turbo.me
...
Output Image: my-new-image:1.0
The build command will create the intermediate container and output image using the latest version of the Turbo VM. To use a legacy version, specify the version number you wish to use with the --vm flag.
# Build the image using version 11.6.205 of the Turbo VM
> turbo build --vm=11.6.205 C:\turbo.me
The --diagnostic flag enables logging within the intermediate container. This flag does not create diagnostic-mode images.
The build command will include all images, which are referenced with the from statement in the script. For example, when the script uses from spoonbrew/git, spoonbrew/nuget, then these two containers will be merged and stored into the newly built container.
The --no-base option will not merge in the script. Instead, the images are included at runtime.
When --format=json option was passed this command will provide output in JSON format. It will contain either an image object with information about result image or an error object if command failed.
The commit command builds an image from a container. The image is built from the container's most recent state.
Usage: commit <options> <container> <image> [--args <startup file params>]
<options> available:
--ad-domain-allow=VALUE Allow execution from the Active Directory domain
--ad-domain-deny=VALUE Disallow execution from the Active Directory domain
--ad-group-allow=VALUE Allow execution for members of the Active Directory group
--ad-group-deny=VALUE Disallow execution for members of the Active Directory group
-e, --env=VALUE Set environment variables inside the container
--env-file=VALUE Read in a line delimited file of ENV variables
--format=VALUE Use the specified format for output. Supported values: json
--hosts=VALUE Add an entry to the virtual /etc/hosts file (<redirect>:<name>)
--no-base Do not merge the base image into the new image
--no-base-file-assocs Do not merge the file associations from the base image into the new image
--overwrite Overwrite existing image
--route-add=VALUE Add route mapping. Supported protocols: ip, pipe, tcp, udp
--route-block=VALUE Block specified route or protocol. Supported protocols: ip, tcp, udp
--route-file=VALUE Read in a INI file of routing configuration
--startup-file=VALUE Override the default startup file and save it to the committed image
--trigger=VALUE Execute named group of startup files
--wait-after-error Leave process open after error
--wait-after-exit Leave process open after it exits
The commit command will merge all the base images used in the container. This behavior can be overridden with the --no-base flag.
For example, if a container were created with the command turbo run git/git,nuget/nuget and later committed with the command turbo commit <container id> my-new-image, the new image would contain:
However, if the same container were committed with the command turbo commit --no-base <container id> my-new-image, my-new-image would only contain the files and registry keys created or modified in the container. The git/git and nuget/nuget images are included as a dependency at runtime.
To alter the selected startup file, apply the new value with --startup-file parameter. All parameters which are passed after the --args flag will be used as parameters to the startup file.
When --format=json option was passed this command will provide output in JSON format. It will contain either an image object with information about commited image or an error object if command failed.
The config command displays and allows modification of the current configuration settings.
Usage: turbo config <options>
<options> available:
--add-trusted-source=VALUE Add a source hub to the trusted list
--all-users Applies the configuration settings to all users
--as-inherit Sets the all users settings as the inherited values which can be overridden by the user
--as-override Sets the all users settings as the values which override the user values
--block-trusted-source=VALUE Add a source hub to the blocked list
--container-path=VALUE Overrides container storage to the specified path
--debug-vm-path=VALUE Path to debug VM
--disable=VALUE Disables a feature: DirectDownload, MergeIsolation, Redirector, TurboDrive, LocalNetworkAccess
--domain=VALUE The domain to log into
--enable=VALUE Enables a feature: DirectDownload, MergeIsolation, Redirector, TurboDrive, LocalNetworkAccess
--format=VALUE Use the specified format for output. Supported values: json
--gci-interval=VALUE The number of minutes between automatic image garbage collection checks. Set to 0 to disable.
--image-cache-size=VALUE Limits the maximum image cache size, in megabytes. Set to 0 for unlimited.
--image-path=VALUE Overrides image storage to the specified path. Supported values: full path, or "allusers" to use the system wide shared folder
--remove-trusted-source=VALUE Remove a source hub from the trusted list
--reset Reset configuration to default values
--storage-path=VALUE Path to local container and image storage
--using=VALUE Use specified images as temporary dependencies
--wait-after-error Leave process open after error
--wait-after-exit Leave process open after it exits
If turbo config is executed without command line parameters then the current settings are returned.
To modify any settings, specify them as command line flags and assign a value to the flag. This value will then be applied to that setting.
The server that Turbo will connect to, and thus push to and pull from, can be configured with the --domain flag.
By default, Turbo is configured to connect to https://turbo.net.
The storage path points to the directory where images and containers are saved. By default, images and containers are saved in %LOCALAPPDATA%\Turbo\Containers. Use the --storage-path flag to set the storage path to a different location.
It may be more efficient to share a repository of images in multi-user environment while keeping container storage in a separate, per user location.
Use the --container-path flag to specify a new location for container storage.
Finally, the storage path can also be overwritten by the TURBOREPO environment variable which may be useful for testing an alternate location quickly without updating the client configuration.
The image cache size flag will set the amount of disk space local images will consume before deleting lesser prioritized images. Set the value to 0 for unlimited cache size. The default value unlimited.
> turbo config
Image cache size: unlimited
# Set cache size to 2 GB
> turbo config --image-cache-size=2048
Image cache size: 2.00 GB
# Back to unlimited
> turbo config --image-cache-size=0
Image cache size: unlimited
# Set container and image root path to C:\ProgramData\Turbo\Containers
> turbo config --storage-path=C:\ProgramData\Turbo\Containers
# Set the container storage path to %LOCALAPPDATA%\Turbo\Containers\sandboxes
> turbo config --container-path=%LOCALAPPDATA%\Turbo\Containers\sandboxes
> turbo config
Hub server: https://turbo.net/
Storage path: C:\ProgramData\Turbo\Containers
Container storage path: C:\Users\matt\AppData\Local\Turbo\Containers\sandboxes
Browser redirection: enabled
# Switch storage path to %LOCALAPPDATA%\Turbo\Containers\repo\images
# Keep container storage path in %LOCALAPPDATA%\Turbo\Containers\sandboxes
> SET TURBOREPO=%LOCALAPPDATA%\Turbo\Containers
# Sets the image repository storage path to C:\ProgramData\Turbo\Containers for all users
> turbo config --image-path=allusers --all-users
Turbo Drive is a special drive (T:) mounted in your system, which allows you to access your cloud storage accounts. Turbo Drive requires WinFSP to be installed in the system, and a Cloud Storage accounts to be configured in the Turbo Server. Turbo Drive uses a persistent cache to make working with the cloud files faster. The cache is located in the encrypted (EFS) folder at %TEMP%\TURBO\cmd\turbo-drive.
To enable Turbo Drive, run turbo config --enable=TurboDrive.
The configuration settings for Turbo can be reset to their default values by issuing the config command with the --reset flag.
When --format=json option was passed this command will provide output in JSON format. It will contain either a configuration object with information about configuration or an error object if command failed.
The containers command lists all containers on the local machine.
Usage: turbo containers <options>
<options> available:
--csv Print output with tab-separated columns
--format=VALUE Use json format for output
--include=VALUE Specify a column that is to be returned
-l, --latest List the most recently created container
-n, --number=VALUE List the 'n' most recently created containers
--no-trunc Don't truncate output
Command line flags for the containers flag serve to modify or filter the command's results.
# Only show most recently created container
> turbo containers -l
ID Images Command Created Status
-- ------ ------- ------- ------
db4d5baff206 spoonbrew/clean 9/3/2014 11:26:35 AM Stopped
# Show last 'n' created containers
> turbo containers -n=3
ID Images Command Created Status
-- ------ ------- ------- ------
db4d5baff206 spoonbrew/clean 9/3/2014 11:26:35 AM Stopped
b5c63c6d242e nodejs/nodejs node app.js 9/3/2014 11:25:18 AM Running
b92981a3dd27 nodejs/nodejs node app.js 9/3/2014 11:05:36 AM Stopped
If the value specified for -n is greater than the number of containers present on the local machine, all of the containers are listed (same result as running turbo containers).
The table that is returned by the containers command is space-formatted. If you wish to return the table with tabs between each column then use the --csv flag.
> turbo containers --csv
Data in the table returned by the containers command is truncated so that it prints nicely and is easily readable in a command prompt. If you wish to view the untruncated data in each column, use the --no-trunc flag.
> turbo containers --no-trunc
The --no-trunc flag includes additional columns in the output, Ports, Settings and VM version, as seen below.
ID Images Command Created Status Ports Settings VM version
-- ------ ------- ------- ------ ----- -------- ----------
df6ac93f8b6147b986d4c7849c3dcef0 ghost:0.5.1 8/26/2014 3:27:17 PM Running 8080:2368 SpawnVm 11.6.270
d6e44ae706c44ed1bd75a0830bed3239 ghost:0.5.1 8/26/2014 3:22:14 PM Stopped SpawnVm 11.6.270
The Ports column contains active port mappings. See the turbo netstat command for more information. The VM version contains version number of VM used to create and run container.
When --format=json option was passed this command will provide output in JSON format. It will contain either a containers array with information about available containers or an error object if command failed.
The continue command downloads the last state of a container and then starts it.
Usage: turbo continue <options> <state-id>
<options> available:
-a, --attach Attach to stdin, stdout, and stderr of the
container
--admin Run the container as admin user
-d, --detach Run the container in the background
--diagnostic Enable diagnotic logging
--disable=VALUE Disable the specified Turbo VM setting
--disable-sync Disable container synchronization
-e, --env=VALUE Set environment variables inside the container
--enable=VALUE Enable the specified Turbo VM setting
--enable-sync Enable container synchronization
--env-file=VALUE Read in a line delimited file of ENV variables
--format=VALUE Use json format for output
--hosts=VALUE Add an entry to the virtual /etc/hosts file
(<redirect>:<name>)
-i, --isolate=VALUE Set isolation level: full, write-copy or merge
--link=VALUE Add link to another container
(<container>:<alias>)
--mount=VALUE Mount a host folder into the container. Format:
[other-container:]SourceFolder[=TargetFolder]
--private Synchronize this container privately, visible
only to me
--public Synchronize this container publicly, visible to
everyone
--route-add=VALUE Add route mapping. Supported protocols: ip, pipe, tcp, udp
--route-block=VALUE Block specified route or protocol. Supported protocols: ip, tcp, udp
--route-file=VALUE Specify a routing rules file
--startup-file=VALUE Override the default startup file
--startup-verb=VALUE Override the default startup verb
--trigger=VALUE Execute named group of startup files
--using=VALUE Use selected images as a temporary dependency
--vm=VALUE The Turbo VM version to run the container with
--wait-after-error Leave program open after error
--wait-after-exit Leave program open after it exits
--with-root=VALUE Set the containers root directory
If the continue command is run against an already-running container then no action will be taken.
To enable diagnostic logging for the container, specify the --diagnostic flag.
To run the container in the background, specify the -d or --detach flag.
When --format=json option was passed this command will provide output in JSON format. It will contain either a container object with information about executed container or an error object if command failed.
The copyi command copies an image to another repository on your local machine. cpi is an alias for this command.
Usage: turbo copyi <options> <image> [<repository>/]<image>[:<tag>]
<options> available:
--format=VALUE Use json format for output
--overwrite Overwrite existing image
--wait-after-error Leave program open after error
--wait-after-exit Leave program open after exit
If the repository specified in the command does not already exist, a new one is automatically created.
# Copy nodejs/nodejs to a new repository
> turbo copyi nodejs/nodejs my-node
Output image: my-node
# Copy the image to the existing repository with a new tag
> turbo copyi nodejs/nodejs my-node:1.0
When --format=json option was passed this command will provide output in JSON format. It will contain either an image object with information about forked image or an error object if command failed.
The cp command copies a files from one container to another or between a container and the native filesystem.
Usage: turbo cp [<source-container>:]<path-from> [<target-container>:]<path-to>
<options> available:
--format=VALUE Use json format for output
# Copy a file from a container to the native system
> turbo cp 2de7:C:\project\file.txt C:\Users\Turbouser
# Copy a file from a container to another container
> turbo cp 2de7:C:\project\file.txt 3vj3:C:\other-project
# Container paths must be absolute
> turbo cp 2de7:file.txt C:\Users\Turbouser
ERROR
# Native paths are relative to the current prompt
C:\Users> turbo cp 2de7:C:\project\file.txt \Turbouser
When --format=json option was passed this command will provide output in JSON format. It will contain only an exit code data or an error object if command failed.
The diff command shows changes made in a container's filesystem.
Usage: turbo diff <options> <container>
<options> available:
--format=VALUE Use json format for output
--path=VALUE Only show changes in subdirectories of the specified path
--registry-path=VALUE Only show changes in subkeys of the specified registry path
--subsystems=VALUE Show only diff for selected subsystems: files, registry
Changes are shown relative to the base images that the container was created from.
# Show all changes made in a container
> turbo diff <container id>
The leading character of each line denotes the type of change made at that path.
|| Character || Type of Change || || A || Added || || C || Changed || || D || Deleted ||
If a file is changed, the diff results will show the a change in the folder along with the change to the file.
For example, if one added a file to a container at C:\Users\Turbouser\file.txt:
> turbo diff --subsystems=files <container id>
File system changes:
C C:\Users\Turbouser
A C:\Users\Turbouser\file.txt
The diff command will show changes in the virtual filesystem and registry. To change this behavior use the --subsystems flag.
# Only show changes to the registry
> turbo diff --subsystems=registry <container id>
# Only show changse to the filesystem
> turbo diff --subsystems=files <container id>
To only show changes beneath a certain node in the filesystem or registry directory tree, use the --path or --registry-path flags.
# Only show changes in HKCU
> turbo diff --registry-path=@HKCU@ <container id>
# Only show changes in system32
> turbo diff --path=C:\Windows\system32
When --format=json option was passed this command will provide output in JSON format. It will contain either a diff object with information about differences or an error object if command failed.
The export command copies an image from the local registry to a specified path on your local machine or network.
export - Export an image from the local repository to the specified path
Usage: turbo.exe export <options> <image> <path>
<options> available:
--format=VALUE Use the specified format for output. Supported values: json
--type=VALUE Export image type. Supported values: svm, exe
--wait-after-error Leave process open after error
--wait-after-exit Leave process open after it exits
# Export an image to the local file system
> turbo export image C:\path\to\image.svm
# Export an image to a network share
> turbo export image \\server\folder\image.svm
# Export an image to a portable exe
> turbo export --type=exe image C:\path\to\image.exe
When --format=json option was passed this command will provide output in JSON format. It will contain either a file object with information about export file or an error object if command failed.
The fork command creates a copy of an existing container.
Usage: turbo fork <existing container> [<new container name>]
<options> available:
--format=VALUE Use the specified format for output. Supported values: json
--images=VALUE Use specified images for new container
--wait-after-error Leave process open after error
--wait-after-exit Leave process open after it exits
The `--images' flag replaces all images in the new container with the ones that are specified. Any images from the original container that are required in the new container would need to be specified again.
# Create an unnamed copy of a container
> turbo fork 28c
# Create a named copy of a container
> turbo fork test-container copy-of-test-container
# Create a copy with Java & Firefox as new main images
> turbo fork chrome-container --images=oracle/jre,mozilla/firefox
When --format=json option was passed this command will provide output in JSON format. It will contain either an container object with information about cloned container or an error object if command failed.
The gc command garbage collects unused containers that have been forked. By default a container is considered unused if not run within the past 7 days.
Usage: turbo.exe gc <options>
<options> available:
--all Include unforked containers for removal
--days=VALUE Number of days until a container is considered unused
--format=VALUE Use the specified format for output. Supported values: json
--trial Run without deleting the images
The run or subscriptions commands forks containers when the base image is automatically upgraded to a newer release. The gc command removes older version of these forked containers.
The gci command garbage collects unreferenced images.
Usage: turbo.exe gci <options>
<options> available:
--all-users Applies command to images stored in all users folder
--format=VALUE Use the specified format for output. Supported values: json
--ignore-containers Remove images even if they are referenced by containers
--ignore-forks Remove images even if they are referenced by forked containers
--trial Run without deleting the images
Images used in containers, subscriptions, or installed images are kept in local repository cache. All other images are considered unreferenced and removed.
To list the available commands in Turbo, execute turbo without parameters.
> turbo
To view help for a specific instruction, execute turbo help <command>.
See below for a list of all of the commands available through Turbo's command-line interface.
The history command lists all images used in the past.
Usage: turbo history <options> <image>
<options> available:
--csv Print output with tab-separated columns
--format=VALUE Use json format for output
-n=VALUE List the 'n' most recently used images
--no-trunc Don't truncate output
The most used recent images are listed first.
# List the recently used images
> turbo history
ID Last used Name Tag
-- --------- ---- ---
73dfe6973074 8/29/2014 4:51:08 PM nodejs/nodejs
07b66f57ed8d 8/29/2014 4:50:33 PM git/git
To show the history of a certain image, use turbo history image-name.
By default 50 entries are shown. Specify -n flag to show more entries.
The results of turbo history are truncated so that they are most readable in the command prompt. To prevent Turbo from truncating data, specify the --no-trunc flag.
The --csv flag can be specified to return the output as a tab-separated table.
When --format=json option was passed this command will provide output in JSON format. It will contain either an images array with information about list of recently images or an error object if command failed.
The images command lists all of the images present in the local registry.
Usage: turbo images <options>
<options> available:
--csv Print output with tab-separated columns
--format=VALUE Use json format for output
--no-trunc Don't truncate output
The results are truncated so that they are most readable in the command prompt. To prevent Turbo from truncating data, specify the --no-trunc flag.
The --csv flag can be specified to return the output as a tab-separated table.
# List all images in local registry
> turbo images
ID Name Tag Created Size
-- ---- --- ------- ----
7a85fe8f7ad1 chocolatey/chocolatey 8/22/2014 11:34:19 AM 3.6 MB
When --format=json option was passed this command will provide output in JSON format. It will contain either an images array with information about available images or an error object if command failed.
The import command is used to add Turbo images or non-Turbo file types from your local machine to your local registry.
Usage: turbo import <options> <type> <path>
<options> available:
--format=VALUE Use json format for output
-n, --name=VALUE Name of the image
--overwrite Overwrite existing image
--wait-after-error Leave program open after error
--wait-after-exit Leave program open after exit
The type must be specified when importing external configurations into the Turbo registry.
svm Turbo image
msi Microsoft Software Installer
thinapp Thinapp Configuration
You can optionally specify a name for the newly-imported image. Use the --overwrite flag to overwrite an existing image.
# Import a thinapp config
turbo import -n=my-thinapp-image thinapp C:\s\package.ini
# Import a turbo image
turbo import -n=my-svm-image svm C:\s\my-image.svm
Turbo Studio users can use this command to import their existing components.
When --format=json option was passed this command will provide output in JSON format. It will contain either an image object with information about imported image or an error object if command failed.
The inspect command displays contents of the image.
inspect - Inspect changes to the image
Usage: turbo inspect <options> <image>
<options> available:
--exclude=VALUE Show details for all subsystems, except the
specified ones
--format=VALUE Use json format for output
--include=VALUE Show only details for selected subsystems:
dependencies, files, registry, services, startu-
p, dns, ports, env
# Show all details about the image
> turbo inspect my-image
# Show filesystem changes only
> turbo inspect --include=files my-image
# Show all changes, but files and registry
> turbo inspect --exclude=files,registry my-image
When --format=json option was passed this command will provide output in JSON format. It will contain either an inspect object with all available information about image or an error object if command failed.
The install command creates a shortcut for the specified container in the Start Menu
Usage: turbo.exe install <options> <container> [run flags...]
<options> available:
--format=VALUE Use the specified format for output. Supported values: json
--no-desktop-integration Don't integrate with the host machine for installed applications
--no-desktop-shortcuts Don't create desktop shortcuts for installed applications
--no-file-associations Don't register file associations for installed applications
--no-send-to-shortcuts Don't create Send To menu shortcuts for installed applications
--no-shell-extensions Don't register shell extensions for installed applications
--no-start-menu-shortcuts Don't create Start menu shortcuts for installed applications
Installation integrates the container into the Windows shell by adding a Start Menu shortcut for the specified container.
Use the turbo containers --no-trunc command to see the list of installed containers.
There are two options for removing the container from the system:
turbo uninstall commandAny supplied run flags are passed to the run command when an installed application is executed. For example, turbo install [container] --vm=1.2.3.4 --diagnostics will result in shortcuts that have a run command like turbo start [container] --vm=1.2.3.4 --diagnostics [additional installation params]. These can be used to customize the installation behavior.
When --format=json option was passed this command will provide output in JSON format. It will contain exit code and an error object if command failed.
The installi creates Start menu shortcuts for the specified image set.
Usage: turbo.exe installi <options> <image> [run flags...]
<options> available:
--all-users Install for all users on this machine. Requires admin privilege.
--format=VALUE Use the specified format for output. Supported values: json
-n, --name=VALUE Name of installed image
--no-desktop-integration Don't integrate with the host machine for installed applications
--no-desktop-shortcuts Don't create desktop shortcuts for installed applications
--no-file-associations Don't register file associations for installed applications
--no-send-to-shortcuts Don't create Send To menu shortcuts for installed applications
--no-shell-extensions Don't register shell extensions for installed applications
--no-start-menu-shortcuts Don't create Start menu shortcuts for installed applications
--offline Allows the images to be installed without a hub connection if all images are present locally
--register-services Register services for installed applications
--skip-installed Skip installation if already installed
--wait-after-error Leave process open after error
--wait-after-exit Leave process open after it exits
Any supplied run flags are passed to the run command when an installed application is executed. For example, turbo installi 7-zip --vm=1.2.3.4 --diagnostics will result in shortcuts that have a run command like turbo run 7-zip --vm=1.2.3.4 --diagnostics [additional installation params]. These can be used to customize the installation behavior.
It is sometimes desired to configure your installed containers to execute completely offline to manage deployment and updates manually. Special planning must be considered if this is your goal.
Before running the installi command, all images must be present. The installi command will fail if any of the required images are not present.
# if using FULL isolation mode
> turbo pull clean
# if using MERGE or WRITE-COPY isolation modes
> turbo pull base
# pull the container vm engine
> turbo pull /xvm
# or if a specific version is desired
> turbo pull /xvm:1.2.3.4
# pull or import your application image
> turbo pull [application]
> turbo import svm c:\path\to\application.svm --name=[application]
Once the images are present, the installi command can be executed.
> turbo installi [application] --offline
# or if a specific version of the container vm engine is required to be locked in
> turbo installi [application] --offline --vm=1.2.3.4
If this is for a multi-user workstation, then additional steps are required to make components available to all users.
# install the client for all users on the machine
> turbo-client.exe --all-users
# configure shared image cache so that multiple copies of the application are not on the machine
# once the image cache path is updated, all future pulls and imports will save images to that location
> turbo config --all-users --image-path=allusers
# install the container for all users
> turbo installi [application] --offline --all-users
Virtual services defined in the images are not installed by default as they will be executed from the user's container automatically or on-demand as configured in the image. Virtual services will be installed to the Windows Service Control Manager and will be run as SYSTEM account by default.
There are a couple ways to organize your images with virtual services:
The login command is used to log a user into the current remote registry.
Usage: turbo login [<username> <password>]
<options> available:
--all-users Applies the login to all users on the machine. Requires admin privilege.
--api-key=VALUE Login with specified API key
--format=VALUE Use json format for output
API Keys can be used to login to a user account or an organization without providing a username and password. It eliminates the need to hard code passwords or pass them in as parameters to automation scripts. API Keys are generated and revoked using user profile or organization settings at the Turbo.net website.
# Log in by specifying username and password
> turbo login turbouser password-here
# Without parameters, returns state of logged-in user
> turbo login
turbouser logged in at 8/25/2014 at 5:40:45 PM
# Log in to shared user credentials
> turbo login --all-users
Login: turbouser
Password: ********
Logged in as turbouser
# Login in by specifying API key
> turbo login --api-key=key-here
turbouser logged in at 8/25/2014 at 5:40:45 PM
See turbo config for information about setting your remote registry location.
When --format=json option was passed this command will provide output in JSON format. It will contain either an user object with information about logged user or an error object if command failed.
The 'logout' command is used to log the current user out of the remote registry.
Usage: turbo logout
<options> available:
--format=VALUE Use json format for output
--all-users Logout from the shared user credentials. Requires admin privilege.
# Logout the current user
> turbo logout
turboiuser logged out
# Logout from shared user credentials
> turbo logout --all-users
turbouser logged out
# No action taken if a user isn't currently logged in
> turbo logout
You are not currently logged into Turbo
When --format=json option was passed this command will provide output in JSON format. It will contain only an exitCode value or an error object if command failed.
The logs command displays the logs for a container. This is especially useful for debugging or inspecting containers.
Usage: turbo logs <options> <container>
<options> available:
--diagnostic Show diagnostic logs
-f Follow log output
--format=VALUE Use json format for output
--list List available logs
--pid=VALUE Show logs for specified process (default: 0=main process of container)
-s Show stream prefixes of log entries
--stderr Only show the stderr logs
--stdout Only show the stdout logs
-t Show timestamps of log entries
--tail=VALUE Only show the last VALUE lines of each log file
Only the standard streams for a container are recorded and logged. To enable more comprehensive logging, use the --diagnostic flag of the run command when the container is created or of the start command when the container is restarted.
Previous logs are kept until the next start of a given container instance. Logs can be viewed at any time. To see available logs, use the --list flag.
# Show only stdout or stderr logs
> turbo logs --stdout 2de7fda8
> turbo logs --stderr 2de7fda8
# Show timestamps for log entries
> turbo logs -t 2de7fda8
# Show stream prefixes of log entries
> turbo logs -s 2de7fda8
# Follow log output in real-time
> turbo logs -f 2de7fda8
# Similar to Unix 'tail', only show last 5 lines
> turbo logs --tail=5 2de7fda8
# Show diagnostic logs instead of standard streams
> turbo logs --diagnostic 2de7fda8
# Show logs for specified process
> turbo logs --pid=666 2de7fda8
# List available logs
> turbo logs --list 2de7fda8
When --format=json option was passed this command will provide output in JSON format. It can contain streamLogs and diagnosticLogs arrays if asked for list of logs, a log string if asked for specific log, or an error object if command failed.
The netstat command displays active port mappings, name resolution information, and links for the specified container.
Usage: turbo netstat <container>
<options> available:
--format=VALUE Use json format for output
> turbo run --route-add=tcp://80:0 --route-add=tcp://8081:0 --hosts=localhost:lhost --link=0218:service -d <image> 63621076457c4b4fb7fff3fcbfda06b1
> turbo netstat 6362
Active port mappings:
49767:80
Name resolution overrides:
localhost lhost
Container links:
021833f5b86c4a80980eff9e5e9f39e2 as service
Note: only active port mappings are printed. Since the container in the example did not expose any service on tcp port 8081, the mapping corresponding to flag --route-add=tcp://8081:0 was not present in the output.
When --format=json option was passed this command will provide output in JSON format. It will contain ports, dns and containerLinks arrays with information about container or an error object if command failed.
The new command creates new container from an image.
Usage: new <options> [<image>] [--name=<name>]
<options> available:
-- Parameters after -- are passed directly to the container process
-a, --attach Attach to stdin, stdout, and stderr of the container. This setting is not saved in the container.
--ad-domain-allow=VALUE Allow execution from the Active Directory domain
--ad-domain-deny=VALUE Disallow execution from the Active Directory domain
--ad-group-allow=VALUE Allow execution for members of the Active Directory group
--ad-group-deny=VALUE Disallow execution for members of the Active Directory group
--admin Run the container with administrative permissions
--app=VALUE Run the application specified by an URI
-d, --detach Run the container in the background
--diagnostic Enable diagnostic logging
--disable=VALUE Disable the specified Turbo VM setting. This setting is not saved in the container.
-e, --env=VALUE Set an environment variable inside the container. This setting is not saved in the container.
--enable=VALUE Enable the specified Turbo VM setting. This setting is not saved in the container.
--enable-sync Enable container synchronization. This setting is not saved in the container.
--env-file=VALUE Read in a line delimited file of environment variables. This setting is not saved in the container.
--format=VALUE Use the specified format for output. Supported values: json
--hide-drive=VALUE Hide specified drives. This setting is not saved in the container. Format: <*|V:|-V:>[,...]
--hosts=VALUE Add an entry to the virtual /etc/hosts file (<redirect>:<name>). This setting is not saved in the container.
-i, --isolate=VALUE Set isolation level: full, write-copy, merge or merge-user.
--install Installs the container after it is created
--link=VALUE Add link to another container (<container>:<alias>). This setting is not saved in the container.
--mount=VALUE Mount a host folder into the container. This setting is not saved in the container. Format: [other-container:]SourceFolder[=TargetFolder]
--mount-if=VALUE Mount a host folder into the container but does not fail if the mount point doesn't exist. This setting is not saved in the container. Format: [other-container:]SourceFolder[=TargetFolder]
-n, --name=VALUE Name of created container
--network=VALUE Run container in specified named network. This setting is not saved in the container.
--no-pull Uses local images to run the container if possible. If not present, will pull from the hub.
--no-run Create the container without executing it
--proxy-password=VALUE Password used to connect to the proxy server. It is not required when using Tnlr. This setting is not saved in the container.
--proxy-server=VALUE Proxy or Tnlr server (Tnlr requires TLS). This setting is not saved in the container. Format: [socks5|http|https|tnlr]://proxy-address:port.
--proxy-targets=VALUE A list of addresses (separated by semicolons) which will be proxied. If not set, all traffic will go through the proxy. The address could be either a DNS name or an IP address.
--proxy-username=VALUE Username used to connect to the proxy server. It is not required when using Tnlr. This setting is not saved in the container.
--route-file=VALUE Read in a INI file of routing configuration. This setting is not saved in the container.
--set-startup-file=VALUE Override the default startup file permanantly
--set-startup-verb=VALUE Override the default startup verb permanantly
--show-window=VALUE Controls how window is shown. Supported values: max, default
--startup-file=VALUE Override the default startup file. This setting is not saved in the container.
--startup-verb=VALUE Override the default startup verb. This setting is not saved in the container.
--stream Enable streaming of the image if available
--temp Remove container when it exits
--trigger=VALUE Execute named group of startup files. This setting is not saved in the container.
--use-dll-cache Use image DLL cache as created by the precache command. This setting is not saved in the container.
--using=VALUE Use specified images as a temporary dependency
--vm=VALUE Use the specified Turbo VM version for execution
-w, --working-dir=VALUE Set the initial working directory inside the container. This setting is not saved in the container.
--wait-after-error Leave process open after error
--wait-after-exit Leave process open after it exits
Turbo new can be used to specify multiple images by separating each image with a comma. If the same file, registry entry, or environment variable exists in multiple images, then the one from whichever image was specified last will win the conflict and be used in the virtual environment. Virtual machine settings are taken from the last specified image. Due to this "layering" approach, it is a good practice to specify images with newer versions of applications or libraries after images with older versions.
# Create a container with the apache/apache image
> turbo new apache/apache
# Create a container with apache and mysql
> turbo new apache/apache,mysql/mysql
# Create a container with .NET 3 and 4
> turbo new microsoft/dotnet:3.5.1,microsoft/dotnet:4.0.3
To use images temporarily, without committing them to the final image, use the --using switch. This is handy for a tool like 7zip and Git that may only needed during the build process.
# Create a container using git temporarily to get a project
> turbo new --using git/git clean
# Clone a git project
(0x3842xd) C:\> git clone https://github.com/JodaOrg/joda-time.git C:\root
# Build project...
# Exit and commit image
(0x3842xd) C:\> exit
# Git will not be part of the container after shutdown
Containers are started with the startup file specified in the last passed image that is not a modifier layer. A modifier layer is an image that has no startup file or auto-start services defined. Regardless of its position on the command line, it is never used as the entry point to the container.
If a startup file is not set in the base image then cmd.exe /k is used.
# Default startup file is used to start container
> turbo new oracle/jdk
# Override the startup file to use the command prompt
> turbo new --startup-file=cmd.exe oracle/jdk
When passing arguments to a startup file or command, we recommend separating these arguments from the rest of the command with a --. Arguments specified after the -- mark are passed directly to the startup file/command.
If a -- mark is not used, any argument matching a new command flag will be interpreted by Turbo which may lead to unexpected behavior.
# Turbo will interpret the /d flag and execute a container in detached mode
> turbo new spoonbrew/clean /d
# /d flag is passed to cmd.exe, disabling execution of AutoRun commands from the registry
> turbo new spoonbrew/clean -- /d
A container's standard streams (stdin/out/err) can be redirected to either the current command prompt or the background using the --attach and --detach flags.
# Redict standard streams to current command prompt
> turbo new -a <image>
# Detach the container from the native prompt
> turbo new -d <image>
Detaching from a container will allow further work to be done in the native prompt while the container is running.
The initial working directory for the container can be set with the workdir instruction or the -w flag. The current directory will be used if workdir was not specified and no --startup-file parameter was provided when building the image.
# By default, a container's working directory matches the host's working directory
C:\Users> turbo new git/git
(0x3842xd) C:\Users>
# This sets the working directory to the root of the C drive
C:\Users> turbo new -w="C:\" git/git
(0x3842xd) C:\>
Containerized applications can be distinguished from normal apps with skin layering. Passing +skin(color) switch after image names pulls skin layer from hub. Skin layer paints colored border around all containerized application windows.
# Opens detached, containerized notepad with blue border around its window
turbo new --startup-file=notepad -d clean+skin(blue)
Turbo VM settings can be enabled or disabled with the --enable and --disable flags, respectively. For a list of Turbo VM settings, see VM Settings section of the documentation.
When the --diagnostic flag is used, the container will generate diagnostic logs that detail all of the operations that occur within the container. These diagnostic logs can later be viewed using the turbo logs command and be used to troubleshoot errors and configuration issues.
Please note that turbo.exe always runs outside of the container on the host even if executed from within the container.
Environment variables can be added to a container with the -e or --env-file flags.
# Add environment variable 'foo' with value 'bar'
> turbo new -e=foo=bar <image>
# Specify multiple env vars with multiple flags
> turbo new -e=foo=bar -e=x=2 <image>
If your container requires several environment variables then we recommend creating an env-file. An env-file is a line-delimited text file that lists all the environment variables to add to the container. The example file below lists 3 environment variables:
foo=bar
utensil=turbo
my-var=10
Environment variables are always expanded on the host system before they are added to the container.
> echo %PATH%
C:\Windows\system32;C:\Windows;
> turbo new -e=%PATH%;C:\Users <image>
(2fedfja3) > echo %PATH%
C:\Windows\system32;C:\Windows;C:\Users
By default, containers run in the host network, meaning that any services exposed by a container can be accessible to the outside world just as if the application was running natively on the host. However, it is possible to run containers in virtualized network environments by specifying a network name other than "host" with the --network flag. Running a container in virtualized network environment prevents it from exposing services to the outside world (unless --route-add flag is used appropriately) while allowing for easy communication between containers running in the same virtualized network environment. In a virtual network, containers can connect to each other using their names as specified with the --name flag if there was any or auto-generated from the image name otherwise.
# Launch a new container in the host network context (the default)
> turbo new --network=host <image>
# Launch two containers in a "mynet" virtual network
> turbo new -d --network=mynet --name=web <image>
web#88e3bb0e
> turbo new -d --network=mynet myself/webbrowser http://web
webbrowser#dd73e48a
# The former will accessible by its name "web" within the network,
# and the latter by its auto-generated name: "webbrowser"
Note: When connecting, always use the container name and not the network name. After all, what should your application connect to if there were two separate containers exposing the same services on the same virtual network if you connected by network name instead of container name?
All network operations (opening/closing ports, for example) are passed through to the local machine when running in the host network context. To remap container ports to other ports on the local machine, use the --route-add flag. This flag also works when running in a virtualized network environment (by specifying the --network flag).
# Map container tcp port 8080 to local port 80
> turbo new --route-add=tcp://8080:80 <image>
# Map udp traffic on container port 8080 to local port 80
> turbo new --route-add=udp://8080:80 <image>
# Map container tcp port 80 to random port on local machine
# The random port can be later queried using the netstat command
> turbo new --route-add=tcp://80:0 <image>
The default policy of allowing containers to bind to any port on the local machine can be changed with the --route-block flag. It isolates all services bound to container ports on specified protocols (tcp or udp). They can only be opened using the --route-add flag.
# Isolate all tcp services of a container
> turbo new --route-block=tcp <image>
# Isolate all tcp and udp services, but allow container tcp port 3486
# be bound to port 80 on local machine
> turbo new --route-block=tcp,udp --route-add=tcp://3486:80 <image>
If you decided to not expose any services running in a container to the public by specifying the --route-block flag and not --route-add, you may still want to be able to connect to the services in your container from another container on the same machine. Although this is best achieved by running the containers in the same virtual network using the --network flag, container linking can be used for this purpose as well.
When creating a container with the turbo new command, you can use the --link flag to link it to any existing containers and the new container will be able to connect to any services exposed by the linked containers. Such connection creates a parent-child relationship where the newly created container is the parent.
With each link, an alias name must be specified. Name resolution overrides are added to the parent container so it can refer to its children by these names. Note how with container links the name that a container will use to refer to another container is defined by the former (the parent) using a parameter, instead of by the name of the container as is the case with virtual networks (the --network flag).
Container links also work between containers running in different virtual networks.
First create two containers, each exposing web sites on private port 80, but with no services exposed outside the containers. Run them in detached mode.
> turbo new --route-block=tcp,udp -d <image>
image#05bf1aa4
> turbo new --route-block=tcp,udp -d <image>
image#94a38820
Then create a web browser container linked to the previously created containers.
> turbo new --link=05bf:web1 --link=94a3:web2 myself/webbrowser http://web1 http://web2
You will be able to browse websites served by the linked containers even though they are not publically available.
The --route-add and --route-block not only provide a way to create rules that apply to inbound network traffic with the tcp and udp protocols, but also rules that apply to outbound network traffic. For the outbound rules, the ip protocol is used. The rules can be implemented using a whitelist or a blacklist approach. It is also possible to reroute traffic from one IP address/host to another, effectively defining an IP address alias.
Routes can be defined using IPv4, IPv6 addresses, or based on hostnames. 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.
Routes cannot be used to restrict traffic to loopback addresses like 127.0.0.1.
If your container requires several routing rules then we recommend creating a route-file. A route-file is an INI based, line-delimited text file that lists all the routing rules to add to the container. It can be added with --route-file flag.
Create a PuTTY container with all outbound access blocked except to IP address 10.0.0.34 (whitelist approach):
> turbo new --route-block=ip --route-add=ip://10.0.0.34 putty
In addition to the above, reroute all traffic to 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 --route-block=ip --route-add=ip://10.0.0.34 --route-add=ip://1.1.1.1:10.0.0.34 putty
It is also possible to use IP ranges using the CIDR notation. The following command allows PuTTY in the container to connect only to hosts in the 192.168.1.0/24 network:
> turbo new --route-block=ip --route-add=ip://192.168.1.0/24 putty
To disallow the app to connect to a set of specific IP addresses (blacklist approach), simply specify them in the --route-block flags:
> turbo new --route-block=ip://192.168.1.55 --route-block=ip://192.168.1.57 putty
When working with IPv6 addresses, it is necessary to enclose them in square brackets:
Block an IPv6 address:
> turbo new --route-block=ip://[2001:4860:4860::8888] putty
Block all IP traffic, except link local IPv6 space:
> turbo new --route-block=ip --route-add=ip://[fe80::c218:85ff:febd:5c01/64] putty
Reroute traffic to an IPv6 address to localhost:
> turbo new --route-block=ip --route-add=ip://[2001:cdba::3257:9652]:[::1] putty
To simplify working with mutliple IP addresses it is possible to use hostnames on the left side of all commands. When a hostname is specified with ip --route-add or --route-block, it is resolved to an IP address when the container starts, and the behavior is effectively the same as if the IP address was specified in place of the hostname. Additionally, all DNS resolves are intercepted and whenever a known hostname resolves to a previously unknown IP address, the IP address is added to the appropriate route table. This feature is what allows wildcard hostnames to work, since otherwise it would not be possible to infer the IP addresses of all possible subdomains.
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. So, for example, to unblock turbo.net and all of its subdomains, use the expression:
> turbo new --route-block=ip --route-add=ip://*.turbo.net chrome https://blog.turbo.net
Or, 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
Another option is to use an INI based route-file which defines rules for blocking and allowing network traffic. The example below blocks all network traffic and then unblocks 192.168.198.0/24 and all turbo.net and spoon.net subdomains:
[ip-block]
*
[ip-add]
192.168.198.0/24
*.turbo.net
*.spoon.net
To create a firefox container with above route-file use this command:
turbo new --route-file=c:\turbo-rules.txt firefox https://turbo.net
If a large list of hostnames is used, such as in the turbobrowsers/block-ad-routes image, the default behavior as described above of resolving all of them to IP addresses at the start of the container would cause container startup to take too long. It can be overriden with the PreResolveHostNames=false setting in a route file, as shown below:
[settings]
PreResolveHostNames=false`
[ip-block]
adserver1.com
adserver2.com
...
All containers use name resolution provided by the host operating system. You can add specific name resolution overrides using the --hosts flag. The syntax is similar to that of the hosts file of the operating system.
# Make name my-test-service resolve to whatever the name
# test-service-43 resolves
> turbo new --hosts=my-test-service:test-service-43 <image>
# Make name mysite.net resolve to IPv4 address 127.0.0.1 and
# name ipv6.mysite.net resolve to IPv6 address ::1
> turbo new --hosts=127.0.0.1:mysite.net --hosts=::1:ipv6.mysite.net <image>
Images can be created with TurboScript that have multiple startup files. Collections of startup files can be linked together by a trigger name and executed together.
# in turbo.me file to create "test-trigger" image...
startup file ["c:\windows\system32\notepad.exe", "c:\windows\regedit.exe"]
startup file doc=[("c:\windows\system32\notepad.exe", "c:\doc\welcome.txt"), ("c:\windows\system32\notepad.exe", "c:\doc\howto.txt")]
# from command-prompt...
# launch both notepad and regedit are launched
> turbo new test-trigger
# launch welcome.txt and howto.txt in notepad
> turbo new test-trigger --trigger=doc
The mount option provides a way to mount folders from the host into the container, giving access to resources from the host system.
The mounted folder's content is not committed to the image nor synchronized to the Turbo Hub and therefore is not available when using the continue command.
If the source folder doesn't exist, the mount option is ignored. If the target folder doesn't exist, it is created.
Example for mounting a folder.
turbo new --mount "C:\FolderOnHostSystem=C:\FolderInContainer" clean
Mounts are useful to share a cache folder, like a local Maven repository:
turbo new --mount "%USERPROFILE%\.m2=%USERPROFILE%\.m2" jdk,maven
Mounting multiple folder is done by repeating the mount parameter:
turbo new --mount "C:\Mount1=C:\InContainer1" --mount "C:\Mount2=C:\InContainer2" clean
It is also possible to mount a folder from another container:
turbo new --mount <containerid>:"C:\FolderInSourceContainer=C:\FolderInTargetContainer" clean
The isolate parameter enables different levels of visibility and access from the vm to the host environment. The full isolation setting prevents read and write to the host system and registry. This is the preferred setting if you want the vm to run like a clean, completely isolated system.
The write-copy isolation setting allows the vm to read the host file system and registry but not write to the host. This is the preferred setting if you want the vm to be able to access host applications and settings, but not alter the host in any way.
The merge isolation setting allows read and write access to the host system.
Note that the vm isolation setting does not override more restrictive isolation settings that already exist in the image. For example, if you created an image in Turbo Studio and set specific folders and keys to full isolation, those settings would be preserved even if the vm isolation is set to merge.
For applications like Gimp or Notepad++ where you want to allow the vm to edit and save files you work with to the host file system, but otherwise do not want to let the application litter the host system for example with settings stored in the file system or the registry, there is the +merge-user isolation modifier. Used as full+merge-user or write-copy+merge-user, it uses merge isolation for user folders like Desktop or Documents, but keeps the base full or write-copy isolation for the rest of the system, making sure that the host system is kept clean. The preferred mode is full+merge-user.
The well-known root folders affected by the +merge-user modifier are: @DESKTOP@, @DESKTOPCOMMON@, @DOCUMENTS@, @PICTURES@, @DOWNLOADS@, @MUSIC@, @VIDEOS@, and @TEMPLATES.
As a separate convenience feature, if the startup verb is not empty, the startup file of the container is set to merge isolation, regardless of the isolation level that it would otherwise have. This way, when executing a shell operation like opening a file on the host system through a Turbo application that has host system file associations set, it is possible for the virtualized application to access and make changes to the file. The MergeStartupDir vm flag takes this feature one step further and sets the isolation level to merge for the whole parent folder of the startup file and all its subfolders except well-known root folders. For example, if the startup file was C:\myproject.proj and the flag was enabled, the folder C:\myproject-files would have merge isolation, but e.g., C:\Windows or C:\Program Files, being well-known root folders, would have isolation level unchanged.
When the container stops, the exit code of startup file is displayed in decimal form.
A specific VM version can be selected by using the --vm=version flag. If the selected version is lower than the minimum version that is required by turbo.exe, then the minimum version will be used instead.
When --format=json option was passed this command will provide output in JSON format. It will contain either a container array with information about created container or an error object if command failed.
The new command checks once a day for new image releases. Specify the --pull option to force checking for the latest release.
Updates are download within the specified release: turbo new firefox updates to the latest Firefox.
turbo new firefox:42 updates to the Firefox within release 42, like 42.0, 42.1 42.2 etc.
The ps command returns a list of all the processes running in containers on the local machine.
Usage: turbo ps <options> [<container>]
<options> available:
--csv Print output with tab-separated columns
--format=VALUE Use json format for output
-l Display long format
--no-trunc Don't truncate output
# View all processes running in containers
> turbo ps
PID Name Container User
--- ---- --------- ----
2252 cmd.exe f1ea9fe59eeb Administrator
# View the "long-format" results for additional information
> turbo ps -l
PID Name Container User UTime KTime Command
--- ---- --------- ---- ----- ----- -------
2252 cmd.exe f1ea9fe59eeb Administrator 00:01:05 00:01:10 "C:\Windows\system32\cmd.exe"
The UTime is the amount of CPU time the process spent in user-mode code.
The KTime is the amount of time spent in system calls within the kernel.
When --format=json option was passed this command will provide output in JSON format. It will contain processes array with information about running processes or an error object if command failed.
The pull command syncs an image from a remote registry to your local registry.
Usage: turbo pull <options> [<namespace>/]<image>[:<tag>]
<options> available:
--format=VALUE Use json format for output
--wait-after-error Leave program open after error
--wait-after-exit Leave program open after exit
The image to pull can be specified with up to 3 identifiers, only 1 of which (the name) is mandatory:
If a namespace is not specified then it will default to that of the current user.
If a tag is not specified then the head tag is applied.
When --format=json option was passed this command will provide output in JSON format. It will contain either an image object with information about pulled image or an error object if command failed.
The push command syncs an image from your local registry to the remote registry.
Usage: turbo push <options> <image> [<remote image>]
<options> available:
--format=VALUE Use json format for output
--no-default-namespace Does not use your username as the default namespace if not explicitly specified
--wait-after-error Leave program open after error
--wait-after-exit Leave program open after exit
If the namespace is not specified then Turbo will look for a repository belonging to the current user that corresponds to the image name. If this does not exist, a new, public repository will be created and the image will be pushed there.
When --format=json option was passed this command will provide output in JSON format. It will contain either an image object with information about pushed image or an error object if command failed.
The release command applies a new release to an image.
Usage: turbo release <image> <release>
<options> available:
--format=VALUE Use json format for output
Apply a new release to the head version of an image.
> turbo release my-image 1.0
Output image: my-image:1.0
When --format=json option was passed this command will provide output in JSON format. It will contain either image object with information about newly released image or an error object if command failed.
The releases command returns all the available releases for an image.
Usage: turbo releases <image>
<options> available:
--format=VALUE Use json format for output
All the available releases are displayed.
> turbo releases my-image
All available releases of my-image:
head (local)
1.0 (local)
0.1.29
When --format=json option was passed this command will provide output in JSON format. It will contain either releases array with list of available releases or an error object if command failed.
The resume command resumes a paused container.
Usage: turbo resume <container>
<options> available:
--format=VALUE Use json format for output
If the container specified is not paused then no action will be taken.
When --format=json option was passed this command will provide output in JSON format. It will contain container object with information about resumed container or an error object if command failed.
The revert command is used to undo all changes to a container.
Usage: turbo revert <container>
<options> available:
--format=VALUE Use json format for output
Configuration settings and metadata will be maintained but all changes to the container's filesystem and registery will be reverted.
When --format=json option was passed this command will provide output in JSON format. It will contain either a container array with information about reverted container or an error object if command failed.
The rm command removes containers from the local machine.
Usage: turbo rm <options> <container>
<options> available:
-a, --all Remove all containers on the local machine
--format=VALUE Use json format for output
Use the -a flag to remove all containers at one time. Note that this operation cannot be undone.
# Remove a single container by specifying the ID
> turbo rm f1ea9fe
Container f1ea9fefjdkaslfh324fdadfshjkl3cndkj3 has been removed
# Remove all containers on the local machine with the -a flag
> turbo rm -a
All containers have been removed
When --format=json option was passed this command will provide output in JSON format. It will contain either an containers array with information about removed containers or an error object if command failed.
The rmi command removes images from the local registry.
<options> available:
-a, --all Remove all images from the local machine or all matching images if argument is specified
--all-users Applies command to images stored in all users folder
-f, --force Attempts to stop running images
--format=VALUE Use the specified format for output. Supported values: json
Use the -a flag to remove all images at one time. Note that this operation cannot be undone.
# Remove an image by specifying it by name
> turbo rmi my-image
Image my-image was removed
# Remove all images with the -a flag
> turbo rmi -a
All images have been removed
If the same image is forked or tagged multiple times then the rmi command will only untag the specified name, not remove the image itself.
> turbo images
ID Name Tag Created Size
-- ---- --- ------- ----
7a85fe8f7ad1 chocolatey/chocolatey 8/22/2014 11:34:19 AM 3.6 MB
7a85fe8f7ad1 chocolatey-forked 1.0 8/22/2014 12:00:01 PM 3.6 MB
> turbo rmi chocolatey/chocolatey
Image chocolatey/chocolatey was untagged
> turbo images
ID Name Tag Created Size
-- ---- --- ------- ----
7a85fe8f7ad1 chocolatey-forked 1.0 8/22/2014 12:00:01 PM 3.6 MB
> turbo rmi chocolatey-forked:1.0
Image chocolatey-forked:1.0 was removed
When --format=json option was passed this command will provide output in JSON format. It will contain either an images array with information about removed images or an error object if command failed.
The run command creates a new container from an image or starts the container with the same name and images.
Usage: run <options> [<image>][+skin(color)] [<parameters>...]
<options> available:
-- Parameters after -- are passed directly to the container process
-a, --attach Attach to stdin, stdout, and stderr of the container. This setting is not saved in the container.
--ad-domain-allow=VALUE Allow execution from the Active Directory domain
--ad-domain-deny=VALUE Disallow execution from the Active Directory domain
--ad-group-allow=VALUE Allow execution for members of the Active Directory group
--ad-group-deny=VALUE Disallow execution for members of the Active Directory group
--admin Run the container with administrative permissions
--app=VALUE Run the application specified by an URI
-d, --detach Run the container in the background
--diagnostic Enable diagnostic logging
--disable=VALUE Disable the specified Turbo VM setting. This setting is not saved in the container.
-e, --env=VALUE Set an environment variable inside the container. This setting is not saved in the container.
--enable=VALUE Enable the specified Turbo VM setting. This setting is not saved in the container.
--enable-sync Enable container synchronization. This setting is not saved in the container.
--env-file=VALUE Read in a line delimited file of environment variables. This setting is not saved in the container.
--format=VALUE Use the specified format for output. Supported values: json
--hide-drive=VALUE Hide specified drives. This setting is not saved in the container. Format: <*|V:|-V:>[,...]
--hosts=VALUE Add an entry to the virtual /etc/hosts file (<redirect>:<name>). This setting is not saved in the container.
-i, --isolate=VALUE Set isolation level: full, write-copy, merge or merge-user.
--link=VALUE Add link to another container (<container>:<alias>). This setting is not saved in the container.
--mount=VALUE Mount a host folder into the container. This setting is not saved in the container. Format: [other-container:]SourceFolder[=TargetFolder]
--mount-if=VALUE Mount a host folder into the container but does not fail if the mount point doesn't exist. This setting is not saved in the container. Format: [other-container:]SourceFolder[=TargetFolder]
-n, --name=VALUE Name of created container
--network=VALUE Run container in specified named network. This setting is not saved in the container.
--no-pull Uses local images to run the container if possible. If not present, will pull from the hub.
--proxy-password=VALUE Password used to connect to the proxy server. It is not required when using Tnlr. This setting is not saved in the container.
--proxy-server=VALUE Proxy or Tnlr server (Tnlr requires TLS). This setting is not saved in the container. Format: [socks5|http|https|tnlr]://proxy-address:port.
--proxy-targets=VALUE A list of addresses (separated by semicolons) which will be proxied. If not set, all traffic will go through the proxy. The address could be either a DNS name or an IP address.
--proxy-username=VALUE Username used to connect to the proxy server. It is not required when using Tnlr. This setting is not saved in the container.
--pull Pulls base images from hub before running, if they exist
--route-add=VALUE Add route mapping. Supported protocols: ip, pipe, tcp, and udp. This setting is not saved in the container.
--route-block=VALUE Block specified route or protocol. Supported protocols: ip, tcp, and udp. This setting is not saved in the container.
--route-file=VALUE Read in a INI file of routing configuration. This setting is not saved in the container.
--set-startup-file=VALUE Override the default startup file permanantly
--set-startup-verb=VALUE Override the default startup verb permanantly
--show-window=VALUE Controls how window is shown. Supported values: max, default
--startup-file=VALUE Override the default startup file. This setting is not saved in the container.
--startup-verb=VALUE Override the default startup verb. This setting is not saved in the container.
--stream Enable streaming of the image if available
--temp Remove container when it exits
--trigger=VALUE Execute named group of startup files. This setting is not saved in the container.
--use-dll-cache Use image DLL cache as created by the precache command. This setting is not saved in the container.
--using=VALUE Use specified images as a temporary dependency
--vm=VALUE Use the specified Turbo VM version for execution
-w, --working-dir=VALUE Set the initial working directory inside the container. This setting is not saved in the container.
--wait-after-error Leave process open after error
--wait-after-exit Leave process open after it exits
Turbo run can be used to specify multiple images by separating each image with a comma. If the same file, registry entry, or environment variable exists in multiple images, then the one from whichever image was specified last will win the conflict and be used in the virtual environment. Virtual machine settings are taken from the last specified image. Due to this "layering" approach, it is a good practice to specify images with newer versions of applications or libraries after images with older versions.
# Create a container with the apache/apache image
> turbo run apache/apache
# Create a container with apache and mysql
> turbo run apache/apache,mysql/mysql
# Create a container with .NET 3 and 4
> turbo run microsoft/dotnet:3.5.1,microsoft/dotnet:4.0.3
To use images temporarily, without committing them to the final image, use the --using switch. This is handy for a tool like 7zip and Git that may only needed during the build process. Using images will be used with the highest overriding priority of files and registry keys.
# Create a container using git temporarily to get a project
# Note that the using images are layered last, which will
# means its files and registries will override all others.
> turbo run --using git/git clean
Using VM 20.5.1515 from local
Using image clean:30 from local
Using image git:2.23.0.windows.1 from local
Running new container clean#0x3842xd
# Clone a git project
(0x3842xd) C:\> git clone https://github.com/JodaOrg/joda-time.git C:\root
# Build project...
# Exit and commit image
(0x3842xd) C:\> exit
# Git will not be part of the container after shutdown
Containers are started with the startup file specified in the first passed image that is not a modifier layer. A modifier layer is an image that has no startup file or auto-start services defined. Regardless of its position on the command line, it is never used as the entry point to the container.
# Chrome will be used as the startup file image and virtual machine settings.
# However, the files in Firefox will be layered on top (overriding) any files
# or registry keys in Chrome.
> turbo run google/chrome,mozilla/firefox
If a startup file is not set in the base image then cmd.exe /k is used.
# Default startup file is used to start container
> turbo run oracle/jdk
# Override the startup file to use the command prompt
> turbo run --startup-file=cmd.exe oracle/jdk
When passing arguments to a startup file or command, we recommend separating these arguments from the rest of the command with a --. Arguments specified after the -- mark are passed directly to the startup file/command.
If a -- mark is not used, any argument matching a run command flag will be interpreted by Turbo which may lead to unexpected behavior.
# Turbo will interpret the /d flag and execute a container in detached mode
> turbo run spoonbrew/clean /d
# /d flag is passed to cmd.exe, disabling execution of AutoRun commands from the registry
> turbo run spoonbrew/clean -- /d
A container's standard streams (stdin/out/err) can be redirected to either the current command prompt or the background using the --attach and --detach flags.
# Redict standard streams to current command prompt
> turbo run -a <image>
# Detach the container from the native prompt
> turbo run -d <image>
Detaching from a container will allow further work to be done in the native prompt while the container is running.
The initial working directory for the container can be set with the workdir instruction or the -w flag. The current directory will be used if workdir was not specified and no --startup-file parameter was provided when building the image.
# By default, a container's working directory matches the host's working directory
C:\Users> turbo run git/git
(0x3842xd) C:\Users>
# This sets the working directory to the root of the C drive
C:\Users> turbo run -w="C:\" git/git
(0x3842xd) C:\>
Containerized applications can be distinguished from normal apps with skin layering. Passing +skin(color) switch after image names pulls skin layer from hub. Skin layer paints colored border around all containerized application windows.
# Opens detached, containerized notepad with blue border around its window
turbo run --startup-file=notepad -d clean+skin(blue)
Turbo VM settings can be enabled or disabled with the --enable and --disable flags, respectively. For a list of Turbo VM settings, see VM Settings section of the documentation.
When the --diagnostic flag is used, the container will generate diagnostic logs that detail all of the operations that occur within the container. These diagnostic logs can later be viewed using the turbo logs command and be used to troubleshoot errors and configuration issues.
Please note that turbo.exe always runs outside of the container on the host even if executed from within the container.
Environment variables from the host system will be seen inside the container, unless they were isolated or set image in which the image's value will be used over the host systems. Add or override them in the container with the -e or --env-file flags. Setting evironment variables in the container will persist them in the container but not on the host system regardless of the isolation mode.
# Add environment variable 'foo' with value 'bar'
> turbo run -e=foo=bar <image>
# Specify multiple env vars with multiple flags
> turbo run -e=foo=bar -e=x=2 <image>
If your container requires several environment variables then we recommend creating an env-file. An env-file is a line-delimited text file that lists all the environment variables to add to the container. The example file below lists 3 environment variables:
foo=bar
utensil=turbo
my-var=10
Environment variables are expanded on the host system before they are added to the container.
> echo %PATH%
C:\Windows\system32;C:\Windows;
> turbo run -e=%PATH%;C:\Users <image>
(2fedfja3) > echo %PATH%
C:\Windows\system32;C:\Windows;C:\Users
By default, containers run in the host network, meaning that any services exposed by a container can be accessible to the outside world just as if the application was running natively on the host. However, it is possible to run containers in virtualized network environments by specifying a network name other than "host" with the --network flag. Running a container in virtualized network environment prevents it from exposing services to the outside world (unless --route-add flag is used appropriately) while allowing for easy communication between containers running in the same virtualized network environment. In a virtual network, containers can connect to each other using their names as specified with the --name flag if there was any or auto-generated from the image name otherwise.
# Launch a new container in the host network context (the default)
> turbo run --network=host <image>
# Launch two containers in a "mynet" virtual network
> turbo run -d --network=mynet --name=web <image>
web#88e3bb0e
> turbo run -d --network=mynet myself/webbrowser http://web
webbrowser#dd73e48a
# The former will accessible by its name "web" within the network,
# and the latter by its auto-generated name: "webbrowser"
Note: When connecting, always use the container name and not the network name. After all, what should your application connect to if there were two separate containers exposing the same services on the same virtual network if you connected by network name instead of container name?
Proxy settings allows the virtual application to route network traffic to the specified proxy server --proxy-server with --proxy-password as the proxy password (if required). You may also specify addresses using the --proxy-targets to proxy only the specified addresses within the application.
If the user omits the --proxy-server flag when executing in a Turbo Server domain while specifying --proxy-targets, the application will proxy using the built in Portal proxy in the domain using a Turbo's custom tnrl proxy protocol.
For example, turbo run firefox --proxy-targets=https://internaladdress.com will attempt to proxy any connections to internaladdr.com to the Portal domain's network. The equivalent command is turbo run firefox --proxy-server=tnrl://<PortalDomain>/tnrl --proxy-targets=http://internaladdress.com
All network operations (opening/closing ports, for example) are passed through to the local machine when running in the host network context. To remap container ports to other ports on the local machine, use the --route-add flag. This flag also works when running in a virtualized network environment (by specifying the --network flag).
# Map container tcp port 8080 to local port 80
> turbo run --route-add=tcp://8080:80 <image>
# Map udp traffic on container port 8080 to local port 80
> turbo run --route-add=udp://8080:80 <image>
# Map container tcp port 80 to random port on local machine
# The random port can be later queried using the netstat command
> turbo run --route-add=tcp://80:0 <image>
The default policy of allowing containers to bind to any port on the local machine can be changed with the --route-block flag. It isolates all services bound to container ports on specified protocols (tcp or udp). They can only be opened using the --route-add flag.
# Isolate all tcp services of a container
> turbo run --route-block=tcp <image>
# Isolate all tcp and udp services, but allow container tcp port 3486
# be bound to port 80 on local machine
> turbo run --route-block=tcp,udp --route-add=tcp://3486:80 <image>
If you decided to not expose any services running in a container to the public by specifying the --route-block flag and not --route-add, you may still want to be able to connect to the services in your container from another container on the same machine. Although this is best achieved by running the containers in the same virtual network using the --network flag, container linking can be used for this purpose as well.
When creating a container with the turbo new command, you can use the --link flag to link it to any existing containers and the new container will be able to connect to any services exposed by the linked containers. Such connection creates a parent-child relationship where the newly created container is the parent.
With each link, an alias name must be specified. Name resolution overrides are added to the parent container so it can refer to its children by these names. Note how with container links the name that a container will use to refer to another container is defined by the former (the parent) using a parameter, instead of by the name of the container as is the case with virtual networks (the --network flag).
Container links also work between containers running in different virtual networks.
First create two containers, each exposing web sites on private port 80, but with no services exposed outside the containers. Run them in detached mode.
> turbo run --route-block=tcp,udp -d <image>
image#05bf1aa4
> turbo run --route-block=tcp,udp -d <image>
image#94a38820
Then create a web browser container linked to the previously created containers.
> turbo run --link=05bf:web1 --link=94a3:web2 myself/webbrowser http://web1 http://web2
You will be able to browse websites served by the linked containers even though they are not publically available.
The --route-add and --route-block not only provide a way to create rules that apply to inbound network traffic with the tcp and udp protocols, but also rules that apply to outbound network traffic. For the outbound rules, the ip protocol is used. The rules can be implemented using a whitelist or a blacklist approach. It is also possible to reroute traffic from one IP address/host to another, effectively defining an IP address alias.
Routes can be defined using IPv4, IPv6 addresses, or based on hostnames. 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.
If your container requires several routing rules then we recommend creating a route-file. A route-file is an INI based, line-delimited text file that lists all the routing rules to add to the container. It can be added with --route-file flag.
Create a PuTTY container with all outbound access blocked except to IP address 10.0.0.34 (whitelist approach):
> turbo run --route-block=ip --route-add=ip://10.0.0.34 putty
In addition to the above, reroute all traffic to 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 run --route-block=ip --route-add=ip://10.0.0.34 --route-add=ip://1.1.1.1:10.0.0.34 putty
It is also possible to use IP ranges using the CIDR notation. The following command allows PuTTY in the container to connect only to hosts in the 192.168.1.0/24 network:
> turbo run --route-block=ip --route-add=ip://192.168.1.0/24 putty
To disallow the app to connect to a set of specific IP addresses (blacklist approach), simply specify them in the --route-block flags:
> turbo run --route-block=ip://192.168.1.55 --route-block=ip://192.168.1.57 putty
When working with IPv6 addresses, it is necessary to enclose them in square brackets:
Block an IPv6 address:
> turbo run --route-block=ip://[2001:4860:4860::8888] putty
Block all IP traffic, except link local IPv6 space:
> turbo run --route-block=ip --route-add=ip://[fe80::c218:85ff:febd:5c01/64] putty
Reroute traffic to an IPv6 address to localhost:
> turbo run --route-block=ip --route-add=ip://[2001:cdba::3257:9652]:[::1] putty
To simplify working with mutliple IP addresses it is possible to use hostnames on the left side of all commands. When a hostname is specified with ip --route-add or --route-block, it is resolved to an IP address when the container starts, and the behavior is effectively the same as if the IP address was specified in place of the hostname. Additionally, all DNS resolves are intercepted and whenever a known hostname resolves to a previously unknown IP address, the IP address is added to the appropriate route table. This feature is what allows wildcard hostnames to work, since otherwise it would not be possible to infer the IP addresses of all possible subdomains.
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 run --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. So, for example, to unblock turbo.net and all of its subdomains, use the expression:
> turbo run --route-block=ip --route-add=ip://*.turbo.net chrome https://blog.turbo.net
Or, to run a Chrome container disallowing access to the facebook.com domain and all of its subdomains:
> turbo run --route-block=ip://*.facebook.com chrome
Another option is to use an INI based route-file which defines rules for blocking and allowing network traffic. The example below blocks all network traffic and then unblocks 192.168.198.0/24 and all turbo.net and spoon.net subdomains:
[ip-block]
*
[ip-add]
192.168.198.0/24
*.turbo.net
*.spoon.net
To create a firefox container with above route-file use this command:
turbo run --route-file=c:\turbo-rules.txt firefox https://turbo.net
If a large list of hostnames is used, such as in the turbobrowsers/block-ad-routes image, the default behavior as described above of resolving all of them to IP addresses at the start of the container would cause container startup to take too long. It can be overriden with the PreResolveHostNames=false setting in a route file, as shown below:
[settings]
PreResolveHostNames=false`
[ip-block]
adserver1.com
adserver2.com
...
All containers use name resolution provided by the host operating system. You can add specific name resolution overrides using the --hosts flag. The syntax is similar to that of the hosts file of the operating system.
# Make name my-test-service resolve to whatever the name
# test-service-43 resolves
> turbo run --hosts=my-test-service:test-service-43 <image>
# Make name mysite.net resolve to IPv4 address 127.0.0.1 and
# name ipv6.mysite.net resolve to IPv6 address ::1
> turbo run --hosts=127.0.0.1:mysite.net --hosts=::1:ipv6.mysite.net <image>
Images can be created with TurboScript that have multiple startup files. Collections of startup files can be linked together by a trigger name and executed together.
# in turbo.me file to create "test-trigger" image...
startup file ["c:\windows\system32\notepad.exe", "c:\windows\regedit.exe"]
startup file doc=[("c:\windows\system32\notepad.exe", "c:\doc\welcome.txt"), ("c:\windows\system32\notepad.exe", "c:\doc\howto.txt")]
# from command-prompt...
# launch both notepad and regedit are launched
> turbo run test-trigger
# launch welcome.txt and howto.txt in notepad
> turbo run test-trigger --trigger=doc
The mount option provides a way to mount folders from the host into the container, giving access to resources from the host system.
The mounted folder's content is not committed to the image nor synchronized to the Turbo Hub and therefore is not available when using the continue command.
If the source folder doesn't exist, the mount option is ignored. If the target folder doesn't exist, it is created.
Example for mounting a folder.
turbo run --mount "C:\FolderOnHostSystem=C:\FolderInContainer" clean
Mounts are useful to share a cache folder, like a local Maven repository:
turbo run --mount "%USERPROFILE%\.m2=%USERPROFILE%\.m2" jdk,maven
Mounting multiple folder is done by repeating the mount parameter:
turbo run --mount "C:\Mount1=C:\InContainer1" --mount "C:\Mount2=C:\InContainer2" clean
It is also possible to mount a folder from another container:
turbo run --mount <containerid>:"C:\FolderInSourceContainer=C:\FolderInTargetContainer" clean
The isolate parameter enables different levels of visibility and access from the vm to the host environment. The full isolation setting prevents read and write to the host system and registry. This is the preferred setting if you want the vm to run like a clean, completely isolated system.
The writecopy isolation setting allows the vm to read the host file system and registry but not write to the host. This is the preferred setting if you want the vm to be able to access host applications and settings, but not alter the host in any way.
The merge isolation setting allows read and write access to the host system.
Note that the vm isolation setting does not override more restrictive isolation settings that already exist in the image. For example, if you created an image in Turbo Studio and set specific folders and keys to full isolation, those settings would be preserved even if the vm isolation is set to merge.
For applications like Gimp or Notepad++ where you want to allow the vm to edit and save files you work with to the host file system, but otherwise do not want to let the application litter the host system for example with settings stored in the file system or the registry, there is the +merge-user isolation modifier. Used as full+merge-user or write-copy+merge-user, it uses merge isolation for user folders like Desktop or Documents, but keeps the base full or write-copy isolation for the rest of the system, making sure that the host system is kept clean. The preferred mode is full+merge-user.
The well-known root folders affected by the +merge-user modifier are: @DESKTOP@, @DESKTOPCOMMON@, @DOCUMENTS@, @PICTURES@, @DOWNLOADS@, @MUSIC@, @VIDEOS@, and @TEMPLATES.
As a separate convenience feature, if the startup verb is not empty, the startup file of the container is set to merge isolation, regardless of the isolation level that it would otherwise have. This way, when executing a shell operation like opening a file on the host system through a Turbo application that has host system file associations set, it is possible for the virtualized application to access and make changes to the file. The MergeStartupDir vm flag takes this feature one step further and sets the isolation level to merge for the whole parent folder of the startup file and all its subfolders except well-known root folders. For example, if the startup file was C:\myproject.proj and the flag was enabled, the folder C:\myproject-files would have merge isolation, but e.g., C:\Windows or C:\Program Files, being well-known root folders, would have isolation level unchanged.
When the container stops, the exit code of startup file is displayed in decimal form.
A specific VM version can be selected by using the --vm=version flag. If the selected version is lower than the minimum version that is required by turbo.exe, then the minimum version will be used instead.
When --format=json option was passed this command will provide output in JSON format. It will contain either a container array with information about created container or an error object if command failed.
The run command checks once a day for new image releases. Specify the --pull option to force checking for the latest release.
Updates are download within the specified release: turbo run firefox updates to the latest Firefox.
turbo run firefox:42 updates to the Firefox within release 42, like 42.0, 42.1 42.2 etc.
The behavior is to prioritize locally cached images over remote, unless the update check triggers an update of the repositories image.
# Start with an empty local image cache
> turbo run firefox
Downloading image firefox:3.5 from https://turbo.net/users/mozilla
Pull complete
# If the update check has not been done for firefox repository, run will update to the latest version
> turbo run firefox
Using VM 18.7.1306 from local
Using image clean:26 from local
Upgrading image firefox to version 61.0.2
Upgrading image firefox-base to version 61.0.2
Running new container firefox#165115f7
# Remove the created container and the latest image
> turbo rm firefox
Removing container firefox#165115f7
> turbo rmi firefox:61
Image mozilla/firefox:61.0.2 was removed
# Running firefox again will use the local image with the older version because the update check has already been done in the previous run
> turbo run firefox
Using VM 18.7.1306 from local
Using image clean:26 from local
Using image firefox:3.5 from local
Running new container firefox#9afe83e2
If the user does not want to trigger the update to the latest firefox, specify the release explicitly:
> turbo run firefox:3.5
Using VM 18.7.1306 from local
Using image clean:26 from local
Using image firefox:3.5 from local
Running new container firefox:3.5#a524349c
If the user issues a run or start command targeting an already running virtual application session, then the process will start under the existing virtual session.
# Open a command prompt, detached
> turbo run clean -d
Running new container clean#a7b31817
# Open another command prompt, using the existing session
> turbo run clean
Running existing container clean#a7b31817
The application was started inside a running container
# Exit the second command prompt window, the turbo command unblocks
Running a process in an existing session will wait until the process exits before completing the turbo command. The wait for exit does not include child processes. Often an application's startup file such as firefox or notepad++ will immediately exit when another instance of the application is running. The turbo command will immediately exit. Persisted session data will be synchronized in the original turbo session.
The save command saves specified container to the hub.
Usage: turbo.exe save <options> <container>
<options> available:
--format=VALUE Use the specified format for output. Supported values: json
--wait-after-error Leave process open after error
--wait-after-exit Leave process open after it exits
Use the continue command to restore the saved container.
The search command is used to search the remote registry for images.
Usage: turbo search <query> [<query>...]
<options> available:
--format=VALUE Use json format for output
Only public repositories are listed in search results.
Multiple queries can be added to make searches more specific. The search command will return the set intersection of multiple queries (AND not OR). For example, the command below will only return images with Java and Maven.
> turbo search java maven
When --format=json option was passed this command will provide output in JSON format. It will contain either an images array with information about found images or an error object if command failed.
The start command restarts a stopped container or starts an application inside an already running container.
Usage: start <options> <container>
<options> available:
-- Parameters after -- are passed directly to the container process
-a, --attach Attach to stdin, stdout, and stderr of the container. This setting is not saved in the container.
--ad-domain-allow=VALUE Allow execution from the Active Directory domain
--ad-domain-deny=VALUE Disallow execution from the Active Directory domain
--ad-group-allow=VALUE Allow execution for members of the Active Directory group
--ad-group-deny=VALUE Disallow execution for members of the Active Directory group
--admin Run the container with administrative permissions
-d, --detach Run the container in the background
--diagnostic Enable diagnostic logging
--disable=VALUE Disable the specified Turbo VM setting. This setting is not saved in the container.
-e, --env=VALUE Set an environment variable inside the container. This setting is not saved in the container.
--enable=VALUE Enable the specified Turbo VM setting. This setting is not saved in the container.
--enable-sync Enable container synchronization. This setting is not saved in the container.
--env-file=VALUE Read in a line delimited file of environment variables. This setting is not saved in the container.
--format=VALUE Use the specified format for output. Supported values: json
--hide-drive=VALUE Hide specified drives. This setting is not saved in the container. Format: <*|V:|-V:>[,...]
--hosts=VALUE Add an entry to the virtual /etc/hosts file (<redirect>:<name>). This setting is not saved in the container.
-i, --isolate=VALUE Set isolation level: full, write-copy, merge or merge-user.
--link=VALUE Add link to another container (<container>:<alias>). This setting is not saved in the container.
--mount=VALUE Mount a host folder into the container. This setting is not saved in the container. Format: [other-container:]SourceFolder[=TargetFolder]
--mount-if=VALUE Mount a host folder into the container but does not fail if the mount point doesn't exist. This setting is not saved in the container. Format: [other-container:]SourceFolder[=TargetFolder]
--network=VALUE Run container in specified named network. This setting is not saved in the container.
--no-pull Uses local images to run the container if possible. If not present, will pull from the hub.
--proxy-password=VALUE Password used to connect to the proxy server. It is not required when using Tnlr. This setting is not saved in the container.
--proxy-server=VALUE Proxy or Tnlr server (Tnlr requires TLS). This setting is not saved in the container. Format: [socks5|http|https|tnlr]://proxy-address:port.
--proxy-targets=VALUE A list of addresses (separated by semicolons) which will be proxied. If not set, all traffic will go through the proxy. The address could be either a DNS name or an IP address.
--proxy-username=VALUE Username used to connect to the proxy server. It is not required when using Tnlr. This setting is not saved in the container.
--pull Pulls base images from hub before running, if they exist
--route-add=VALUE Add route mapping. Supported protocols: ip, pipe, tcp, and udp. This setting is not saved in the container.
--route-block=VALUE Block specified route or protocol. Supported protocols: ip, tcp, and udp. This setting is not saved in the container.
--route-file=VALUE Read in a INI file of routing configuration. This setting is not saved in the container.
--set-startup-file=VALUE Override the default startup file permanantly
--set-startup-verb=VALUE Override the default startup verb permanantly
--show-window=VALUE Controls how window is shown. Supported values: max, default
--startup-file=VALUE Override the default startup file. This setting is not saved in the container.
--startup-verb=VALUE Override the default startup verb. This setting is not saved in the container.
--stream Enable streaming of the image if available
--trigger=VALUE Execute named group of startup files. This setting is not saved in the container.
--use-dll-cache Use image DLL cache as created by the precache command. This setting is not saved in the container.
--using=VALUE Use specified images as a temporary dependency
--vm=VALUE Use the specified Turbo VM version for execution
-w, --working-dir=VALUE Set the initial working directory inside the container. This setting is not saved in the container.
--wait-after-error Leave process open after error
--wait-after-exit Leave process open after it exits
If the start command is run against an already-running container then no action will be taken.
To enable diagnostic logging for the container, specify the --diagnostic flag.
To run the container in the background then specify the -d or --detach flag.
To temporarily alter the startup file, specify it with --startup-file parameter. The change overrides the original startup files and does not apply to a subsequent container starts or commits.
When the container stops, the exit code of startup file is displayed in decimal form.
When --format=json option was passed this command will provide output in JSON format. It will contain container object with information about started container or an error object if command failed.
The stop command stops containers which are currently running.
Usage: turbo stop <options> <container>
<options> available:
-a, --all Stop all running containers
--format=VALUE Use json format for output
--wait-after-error Leave program open after error
--wait-after-exit Leave program open after exit
start command accepts either a container to close or -a parameter to close all running containers.
If the stop command is run against a non-running container then no action will be taken.
When --format=json option was passed this command will provide output in JSON format. It will contain container object with information about stopped container or an error object if command failed.
The subscribe command is used to subscribe to a workspace, or an organization's repositories.
Usage: subscribe <options> <organization | workspace>
<options> available:
--all-users Subscribe all users on the machine. Requires Administrator privileges
--format=VALUE Use the specified format for output. Supported values: json
--wait-after-error Leave process open after error
--wait-after-exit Leave process open after it exits
Subscribing to an organization will add all available repositories to the desktop by executing the installi command on each repository. When a workspace is specified (using the url friendly id such as default), the workspace applications are installed by installi the workspace application which includes the application configuration. This allows the installed application to run with the workspace application settings. The initial subscribe does not pull the images to the local machine cache. The image pull is done by the update task.
In addition to installing each repository, a subscription will periodically update the install to the latest workspace application configuration, and the local image to the specified revision. The update is done by registering a Windows Task that runs the subscription update command once a day at 12:00 AM. You can change the frequency of the update task using the built in Windows Task Scheduler. The task will be under the turbo-net folder.
Use the subscription command to control the subscription. To view all subscriptions use the subscriptions command. To remove the subscription use the unsubscribe command.
When --all-users is specified, the subscription will be installed for all users on the machine. This command requires Administrator privileges and that the Turbo client is installed for all users. See the install options for the Turbo installer for more information on how to install for all users.
Subscribing to a channel creates a Windows task that executes a daily update of the subscription. To avoid automatic updates, the subscription command has a suspend action or the scheduled task can be disabled or modified to suit the desired update process.
The subscription command is used to update, suspend, resume and print the details of a subscription.
Usage: subscription <options> [action] <name>
sub <options> [action] <name>
<options> available:
--format=VALUE Use the specified format for output. Supported values: json
--no-pull Update the subscription without pulling images
--wait-after-error Leave process open after error
--wait-after-exit Leave process open after it exits
The available actions are update, suspend, resume and print.
The update action updates all of the images in the subscription to the latest version.
Use the --no-pull option to update the subscription without pulling new image versions, instead the images will be streamed on demand.
The suspend action suspends updates for the specified subscription. The resume command will resume updates.
The print action shows details about the subscription.
> turbo subscription print example-channel
Subscription example-channel for the current user
Created 08.02.2016 17:20:23, last updated never (automatic)
Name Repo Status Release Layers
---- ---- ------ ------- ------
Mozilla Firefox & Flash Latest mozilla/firefox Installed 44.0 adobe/flash:20.0.0.267
Mozilla Firefox Latest mozilla/firefox Installed 44.0
The subscriptions command lists the subscriptions that are currently registered on the device.
Usage: subscriptions <options>
subs <options>
<options> available:
--format=VALUE Use the specified format for output. Supported values: json
--no-trunc Don't truncate output
The subscriptions command provides some basic information about the subscriptions registered on the device including the name, last updated time and a list of applications.
For more detailed information about a specific subscription, use the subscription command.
The suspend command is used to suspend a running container.
Usage: turbo suspend <container>
<options> available:
--format=VALUE Use json format for output
This will suspend all processes and threads within the specified container.
When --format=json option was passed this command will provide output in JSON format. It will contain container object with information about paused container or an error object if command failed.
The try command creates a new, temporary container which is removed once it is closed.
Usage: turbo.exe try <options> <image>[+skin(color)] [<parameters>...]
<options> available:
-- Parameters after -- are passed directly to the container process
-a, --attach Attach to stdin, stdout, and stderr of the container. This setting is not saved in the container.
--ad-domain-allow=VALUE Allow execution from the Active Directory domain
--ad-domain-deny=VALUE Disallow execution from the Active Directory domain
--ad-group-allow=VALUE Allow execution for members of the Active Directory group
--ad-group-deny=VALUE Disallow execution for members of the Active Directory group
--admin Run the container with administrative permissions
--app=VALUE Run the application specified by an URI
-d, --detach Run the container in the background
--diagnostic Enable diagnostic logging
--disable=VALUE Disable the specified Turbo VM setting. This setting is not saved in the container.
-e, --env=VALUE Set an environment variable inside the container. This setting is not saved in the container.
--enable=VALUE Enable the specified Turbo VM setting. This setting is not saved in the container.
--enable-sync Enable container synchronization. This setting is not saved in the container.
--env-file=VALUE Read in a line delimited file of environment variables. This setting is not saved in the container.
--format=VALUE Use the specified format for output. Supported values: json
--hide-drive=VALUE Hide specified drives. This setting is not saved in the container. Format: <*|V:|-V:>[,...]
--hosts=VALUE Add an entry to the virtual /etc/hosts file (<redirect>:<name>). This setting is not saved in the container.
-i, --isolate=VALUE Set isolation level: full, write-copy, merge or merge-user.
--link=VALUE Add link to another container (<container>:<alias>). This setting is not saved in the container.
--mount=VALUE Mount a host folder into the container. This setting is not saved in the container. Format: [other-container:]SourceFolder[=TargetFolder]
--mount-if=VALUE Mount a host folder into the container but does not fail if the mount point doesn't exist. This setting is not saved in the container. Format: [other-container:]SourceFolder[=TargetFolder]
-n, --name=VALUE Name of created container
--network=VALUE Run container in specified named network. This setting is not saved in the container.
--no-pull Uses local images to run the container if possible. If not present, will pull from the hub.
--proxy-password=VALUE Password used to connect to the proxy server. It is not required when using Tnlr. This setting is not saved in the container.
--proxy-server=VALUE Proxy or Tnlr server (Tnlr requires TLS). This setting is not saved in the container. Format: [socks5|http|https|tnlr]://proxy-address:port.
--proxy-targets=VALUE A list of addresses (separated by semicolons) which will be proxied. If not set, all traffic will go through the proxy. The address could be either a DNS name or an IP address.
--proxy-username=VALUE Username used to connect to the proxy server. It is not required when using Tnlr. This setting is not saved in the container.
--route-add=VALUE Add route mapping. Supported protocols: ip, pipe, tcp, and udp. This setting is not saved in the container.
--route-block=VALUE Block specified route or protocol. Supported protocols: ip, tcp, and udp. This setting is not saved in the container.
--route-file=VALUE Read in a INI file of routing configuration. This setting is not saved in the container.
--set-startup-file=VALUE Override the default startup file permanantly
--set-startup-verb=VALUE Override the default startup verb permanantly
--show-window=VALUE Controls how window is shown. Supported values: max, default
--startup-file=VALUE Override the default startup file. This setting is not saved in the container.
--startup-verb=VALUE Override the default startup verb. This setting is not saved in the container.
--stream Enable streaming of the image if available
--temp Remove container when it exits
--trigger=VALUE Execute named group of startup files. This setting is not saved in the container.
--use-dll-cache Use image DLL cache as created by the precache command. This setting is not saved in the container.
--using=VALUE Use specified images as a temporary dependency
--vm=VALUE Use the specified Turbo VM version for execution
-w, --working-dir=VALUE Set the initial working directory inside the container. This setting is not saved in the container.
--wait-after-error Leave process open after error
--wait-after-exit Leave process open after it exits
Turbo try can be used to specify multiple images by separating each image with a comma. If the same file, registry entry, or environment variable exists in multiple images, then the one from whichever image was specified last will win the conflict and be used in the virtual environment. Virtual machine settings are taken from the last specified image. Due to this "layering" approach, it is a good practice to specify images with newer versions of applications or libraries after images with older versions.
# Create a container with the apache/apache image
> turbo try apache/apache
# Create a container with apache and mysql
> turbo try apache/apache,mysql/mysql
# Create a container with .NET 3 and 4
> turbo try microsoft/dotnet:3.5.1,microsoft/dotnet:4.0.3
Containers are started with the startup file specified in the last passed image that is not a modifier layer. A modifier layer is an image that has no startup file or auto-start services defined. Regardless of its position on the command line, it is never used as the entry point to the container.
If a startup file is not set in the base image then cmd.exe /k is used.
# Default startup file is used to start container
> turbo try oracle/jdk
# Override the startup file to use the command prompt
> turbo try --startup-file=cmd.exe oracle/jdk
The initial working directory for the container can be set with the workdir instruction or the -w flag. The current directory will be used if workdir was not specified and no --startup-file parameter was provided when building the image.
# By default, a container's working directory matches the host's working directory
C:\Users> turbo try git/git
(0x3842xd) C:\Users>
# This sets the working directory to the root of the C drive
C:\Users> turbo try -w="C:\" git/git
(0x3842xd) C:\>
Turbo VM settings can be enabled or disabled with the --enable and --disable flags, respectively. For a list of Turbo VM settings, see VM Settings section of the documentation.
Please note that turbo.exe always runs outside of the container on the host even if executed from within the container.
Environment variables can be added to a container with the -e or --env-file flags.
# Add environment variable 'foo' with value 'bar'
> turbo try -e=foo=bar <image>
# Specify multiple env vars with multiple flags
> turbo try -e=foo=bar -e=x=2 <image>
If your container requires several environment variables then we recommend creating an env-file. An env-file is a line-delimited text file that lists all the environment variables to add to the container. The example file below lists 3 environment variables:
foo=bar
utensil=turbo
my-var=10
Environment variables are always expanded on the host system before they are added to the container.
> echo %PATH%
C:\Windows\system32;C:\Windows;
> turbo try -e=%PATH%;C:\Users <image>
(2fedfja3) > echo %PATH%
C:\Windows\system32;C:\Windows;C:\Users
By default, containers run in the host network, meaning that any services exposed by a container can be accessible to the outside world just as if the application was running natively on the host. However, it is possible to run containers in virtualized network environments by specifying a network name other than "host" with the --network flag. Running a container in virtualized network environment prevents it from exposing services to the outside world (unless --route-add flag is used appropriately) while allowing for easy communication between containers running in the same virtualized network environment. In a virtual network, containers can connect to each other using their names as specified with the --name flag if there was any or auto-generated from the image name otherwise.
# Launch a new container in the host network context (the default)
> turbo try --network=host <image>
# Launch two containers in a "mynet" virtual network
> turbo try -d --network=mynet --name=web <image>
web#88e3bb0e
> turbo try -d --network=mynet myself/webbrowser http://web
webbrowser#dd73e48a
# The former will accessible by its name "web" within the network,
# and the latter by its auto-generated name: "webbrowser"
Note: When connecting, always use the container name and not the network name. After all, what should your application connect to if there were two separate containers exposing the same services on the same virtual network if you connected by network name instead of container name?
All network operations (opening/closing ports, for example) are passed through to the local machine when running in the host network context. To remap container ports to other ports on the local machine, use the --route-add flag. This flag also works when running in a virtualized network environment (by specifying the --network flag).
# Map container tcp port 8080 to local port 80
> turbo try --route-add=tcp://8080:80 <image>
# Map udp traffic on container port 8080 to local port 80
> turbo try --route-add=udp://8080:80 <image>
# Map container tcp port 80 to random port on local machine
# The random port can be later queried using the netstat command
> turbo try --route-add=tcp://80:0 <image>
The default policy of allowing containers to bind to any port on the local machine can be changed with the --route-block flag. It isolates all services bound to container ports on specified protocols (tcp or udp). They can only be opened using the --route-add flag.
# Isolate all tcp services of a container
> turbo try --route-block=tcp <image>
# Isolate all tcp and udp services, but allow container tcp port 3486
# be bound to port 80 on local machine
> turbo try --route-block=tcp,udp --route-add=tcp://3486:80 <image>
If you decided to not expose any services running in a container to the public by specifying the --route-block flag and not --route-add, you may still want to be able to connect to the services in your container from another container on the same machine. Although this is best achieved by running the containers in the same virtual network using the --network flag, container linking can be used for this purpose as well.
When creating a container with the turbo new command, you can use the --link flag to link it to any existing containers and the new container will be able to connect to any services exposed by the linked containers. Such connection creates a parent-child relationship where the newly created container is the parent.
With each link, an alias name must be specified. Name resolution overrides are added to the parent container so it can refer to its children by these names. Note how with container links the name that a container will use to refer to another container is defined by the former (the parent) using a parameter, instead of by the name of the container as is the case with virtual networks (the --network flag).
Container links also work between containers running in different virtual networks.
First create two containers, each exposing web sites on private port 80, but with no services exposed outside the containers. Run them in detached mode.
> turbo try --route-block=tcp,udp -d <image>
image#05bf1aa4
> turbo try --route-block=tcp,udp -d <image>
image#94a38820
Then create a web browser container linked to the previously created containers.
> turbo try --link=05bf:web1 --link=94a3:web2 myself/webbrowser http://web1 http://web2
You will be able to browse websites served by the linked containers even though they are not publically available.
The --route-add and --route-block not only provide a way to create rules that apply to inbound network traffic with the tcp and udp protocols, but also rules that apply to outbound network traffic. For the outbound rules, the ip protocol is used. The rules can be implemented using a whitelist or a blacklist approach. It is also possible to reroute traffic from one IP address/host to another, effectively defining an IP address alias.
Routes can be defined using IPv4, IPv6 addresses, or based on hostnames. 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.
If your container requires several routing rules then we recommend creating a route-file. A route-file is an INI based, line-delimited text file that lists all the routing rules to add to the container. It can be added with --route-file flag.
Create a PuTTY container with all outbound access blocked except to IP address 10.0.0.34 (whitelist approach):
> turbo try --route-block=ip --route-add=ip://10.0.0.34 putty
In addition to the above, reroute all traffic to 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 try --route-block=ip --route-add=ip://10.0.0.34 --route-add=ip://1.1.1.1:10.0.0.34 putty
It is also possible to use IP ranges using the CIDR notation. The following command allows PuTTY in the container to connect only to hosts in the 192.168.1.0/24 network:
> turbo try --route-block=ip --route-add=ip://192.168.1.0/24 putty
To disallow the app to connect to a set of specific IP addresses (blacklist approach), simply specify them in the --route-block flags:
> turbo try --route-block=ip://192.168.1.55 --route-block=ip://192.168.1.57 putty
When working with IPv6 addresses, it is necessary to enclose them in square brackets:
Block an IPv6 address:
> turbo try --route-block=ip://[2001:4860:4860::8888] putty
Block all IP traffic, except link local IPv6 space:
> turbo try --route-block=ip --route-add=ip://[fe80::c218:85ff:febd:5c01/64] putty
Reroute traffic to an IPv6 address to localhost:
> turbo try --route-block=ip --route-add=ip://[2001:cdba::3257:9652]:[::1] putty
To simplify working with mutliple IP addresses it is possible to use hostnames on the left side of all commands. When a hostname is specified with ip --route-add or --route-block, it is resolved to an IP address when the container starts, and the behavior is effectively the same as if the IP address was specified in place of the hostname. Additionally, all DNS resolves are intercepted and whenever a known hostname resolves to a previously unknown IP address, the IP address is added to the appropriate route table. This feature is what allows wildcard hostnames to work, since otherwise it would not be possible to infer the IP addresses of all possible subdomains.
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 try --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. So, for example, to unblock turbo.net and all of its subdomains, use the expression:
> turbo try --route-block=ip --route-add=ip://*.turbo.net chrome https://blog.turbo.net
Or, to run a Chrome container disallowing access to the facebook.com domain and all of its subdomains:
> turbo try --route-block=ip://*.facebook.com chrome
Another option is to use an INI based route-file which defines rules for blocking and allowing network traffic. The example below blocks all network traffic and then unblocks 192.168.198.0/24 and all turbo.net and spoon.net subdomains:
[ip-block]
*
[ip-add]
192.168.198.0/24
*.turbo.net
*.spoon.net
To create a firefox container with above route-file use this command:
turbo try --route-file=c:\turbo-rules.txt firefox https://turbo.net
If a large list of hostnames is used, such as in the turbobrowsers/block-ad-routes image, the default behavior as described above of resolving all of them to IP addresses at the start of the container would cause container startup to take too long. It can be overriden with the PreResolveHostNames=false setting in a route file, as shown below:
[settings]
PreResolveHostNames=false`
[ip-block]
adserver1.com
adserver2.com
...
All containers use name resolution provided by the host operating system. You can add specific name resolution overrides using the --hosts flag. The syntax is similar to that of the hosts file of the operating system.
# Make name my-test-service resolve to whatever the name
# test-service-43 resolves
> turbo try --hosts=my-test-service:test-service-43 <image>
# Make name mysite.net resolve to IPv4 address 127.0.0.1 and
# name ipv6.mysite.net resolve to IPv6 address ::1
> turbo try --hosts=127.0.0.1:mysite.net --hosts=::1:ipv6.mysite.net <image>
Images can be created with TurboScript that have multiple startup files. Collections of startup files can be linked together by a trigger name and executed together.
# in turbo.me file to create "test-trigger" image...
startup file ["c:\windows\system32\notepad.exe", "c:\windows\regedit.exe"]
startup file doc=[("c:\windows\system32\notepad.exe", "c:\doc\welcome.txt"), ("c:\windows\system32\notepad.exe", "c:\doc\howto.txt")]
# from command-prompt...
# launch both notepad and regedit are launched
> turbo try test-trigger
# launch welcome.txt and howto.txt in notepad
> turbo try test-trigger --trigger=doc
The mount option provides a way to mount folders from the host into the container, giving access to resources from the host system.
If the source folder doesn't exist, the mount option is ignored. If the target folder doesn't exist, it is created.
Example for mounting a folder.
turbo try --mount "C:\FolderOnHostSystem=C:\FolderInContainer" clean
Mounts are useful to share a cache folder, like a local Maven repository:
turbo try --mount "%USERPROFILE%\.m2=%USERPROFILE%\.m2" jdk,maven
Mounting multiple folder is done by repeating the mount parameter:
turbo try --mount "C:\Mount1=C:\InContainer1" --mount "C:\Mount2=C:\InContainer2" clean
It is also possible to mount a folder from another container:
turbo try --mount <containerid>:"C:\FolderInSourceContainer=C:\FolderInTargetContainer" clean
When the container stops, the exit code of startup file is displayed in decimal form.
A specific VM version can be selected by using the --vm=version flag. If the selected version is lower than the minimum version that is required by turbo.exe, then the minimum version will be used instead.
When --format=json option was passed this command will provide output in JSON format. It will contain either a container array with information about created container or an error object if command failed.
The try command checks once a day for new image releases. Specify the --pull option to force checking for the latest release.
Updates are download within the specified release: turbo try firefox updates to the latest Firefox.
turbo try firefox:42 updates to the Firefox within release 42, like 42.0, 42.1 42.2 etc.
The uninstall command will remove the Start Menu shortcut for the specified container
Usage: turbo.exe uninstall <options> <container>
<options> available:
--format=VALUE Use json format for output
If the specified container has not been previously registered to the host device using the turbo install command, then no action will be taken.
When --format=json option was passed this command will provide output in JSON format. It will contain exit code and an error object if command failed.
The uninstalli removes the Start menu shortcuts for the image and disables the update process for the images registered with installi or subscribe commands.
Usage: uninstalli <options> <image>
<options> available:
-a, --all Uninstalls all images on the local machine
--all-users Subscriptions for all users on this machine. Requires admin privilege.
--format=VALUE Use the specified format for output. Supported values: json
--wait-after-error Leave process open after error
--wait-after-exit Leave process open after it exits
An image removed by uninstalli will not be updated or reinstalled during the subscription update process. However, it can be reinstalled by running the subscribe command again.
If an installi becomes corrupted and is unable to uninstall from Windows Settings or uninstalli command you may choose to manually remove the data and entries.
HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Uninstall or HKEY_CURRENT_USER\SOFTWARE\Microsoft\Windows\CurrentVersion\UninstallThe unsubscribe command unsubscribes a specified subscription or all subscriptions. It uninstalls shortcuts and removes the update task.
Usage: unsubscribe <options> <subscription>
<options> available:
-a, --all Unsubscribes all subscriptions on the local machine
--format=VALUE Use the specified format for output. Supported values: json
--wait-after-error Leave process open after error
--wait-after-exit Leave process open after it exits
If the --all-users option was used during, the unsubscribe command will unsubscribe all users. In this case, the command needs to be run as an Administrator.
To unsubscribe from all subscriptions, use the --all option.
The version command shows the current version of Turbo.
Usage: turbo version
<options> available:
--format=VALUE Use json format for output
When --format=json option was passed this command will provide output in JSON format. It will contain version string with current version number.
The vm command displays the most recent version of the Turbo VM which is available on the local machine.
Usage: turbo vm
<options> available:
--format=VALUE Use json format for output
If there is a user logged in to a remote registry then this command will also display the latest version of the Turbo VM available in that registry.
> turbo vm
The latest local version of the Turbo VM is 11.6.213
The latest version of the Turbo VM is 11.6.215
When --format=json option was passed this command will provide output in JSON format. It will contain either vms array with one tag item for local VM and one for latest VM available on hub or an error object if command failed.
The vms command lists all the available versions of the Turbo VM.
Usage: turbo vms
<options> available:
--format=VALUE Use json format for output
If a user is logged in to a remote registry then all versions which are available both locally and remotely will be displayed.
If no user is logged in then only local versions of the Turbo VM are displayed.
When --format=json option was passed this command will provide output in JSON format. It will contain either vms array with list of available VM versions or an error object if command failed.
Turbo command processor can act as an automated builder by reading instructions from a .me file to create a new image. Turbo Shell can act as an interactive interpreter of TurboScript.
A .me script is a text file containing a set of instructions that the Turbo command processor or the Turbo Shell follows to create a container. In Turbo command processor, at the end of the script, a new image is created from the container and the container is deleted.
The syntax of a TurboScript generally follows the pattern:
instruction <arg 1> <arg 2> ...
instruction <arg 1> <arg 2> ...
instruction <arg 1> <arg 2> ...
The script is read and executed top-to-bottom and is not case-sensitive.
All scripts have an implicit commit at the end of the script. After the last instruction in the script, it executes turbo commit on the container. If a name was not provided to the build command (via the -n or --name flag) then the new image will be created with its ID as its name.
instruction <args>Comments are denoted by the # character.
# This is a comment
Comments cannot be made inline with a command. Comments must be specified at the beginning of a line.
# This is a valid comment
layer nodejs/nodejs # This is not a valid comment
Any TurboScript instruction can have an optional when clause at the end of the line to specify the conditions which must be met before the instruction will be executed. The general form is instruction when expression.
cmd "echo This is Windows7" when host has os:Windows7
These are the currently supported expressions:
Note that client OSes are not differentiated from server OSes so "Windows7" is equivalent to "Windows2008r2", etc.
Expressions can be combined with AND, OR, NOT, and parenthesis.
layer clean when (not host has os:windows7 and not host has os:windows8.1)
layer spoonbrew/iis7-base when host has os:windows7
layer spoonbrew/iis8-base when host has os:windows8.1
The batch instruction is used for joining multiple commands of the same type in TurboScript.
batch <command>
<line 1>
<line 2>
<...>
If <command> is cmd or empty then all following indented lines will be put into a single batch file. Otherwise, these lines will be turned into separate commands.
The first non-indented line terminates the batch section and resumes normal command processing.
You can use the batch instruction to execute a series of commands that share their state.
# Create a new directory with a text file inside of it.
batch cmd
mkdir c:\new_folder
cd c:\new_folder
echo text content > text_file.txt
# Set several environment variables
batch env
var1="value 1"
var2="value 2"
var3="value 3"
The cmd instruction is used to run a command in the container.
The instruction has three forms:
# Execute the application directly
cmd ("executable", "param1", "param2")
# Interpret the command by cmd.exe, defaults to using cmd.exe /c
cmd <command> <param1> <param2>
# Pass parameters to the image's startup file
cmd <param1> <param2>
Please note that turbo.exe always runs outside of the container on the host even if passed as cmd parameter.
If you wish to launch an executable and optionally supply parameters to that executable, you must express the desired executable as a tuple of strings and give the full path to the executable (unless it is on the local system or container's PATH). Using this syntax, parameters are passed directly to the executable.
# Open foo.txt in notepad
cmd ("c:\windows\system32\notepad.exe", "c:\users\user\desktop\foo.txt")
Using this syntax, each command is executed in its own command prompt -- a new command prompt being spawned for each instruction. Any stateful commands (cd, for example), must be chained to other commands with an ampersand to have their desired effect.
For example, to read C:\turbo\text-file.txt:
# Does not work
cmd cd C:\turbo
cmd more text-file.txt
# Works!
cmd cd C:\turbo & more text-file.txt
Note: If you wish to use cd functionality in your script, consider using the WORKDIR instruction.
Using this syntax, the parameters are sent to the default startup file in the base image. If multiple base images are specified, the startup file from last image listed will be used.
The copy instruction is used to copy a file or directory from a TurboScript or an XAPPL configuration directory.
copy <source> <destination>
# There is also an alias:
cp <source> <destination>
The source path may point to an inner subdirectory of the one mentioned above, but must not point above it. This restriction does not apply to the Turbo Shell.
The destination may either be an absolute path, or a relative path. In the latter case, the file is copied into a location relative to the current working directory.
Examples:
copy turbo.me .
copy setup\installer.msi C:\setup\
cp app-1.2.3.4.msi setup\installer.msi
The disable instruction disables the specified VM setting inside the container.
disable <vm setting>
Only one setting can be disabled per instruction. To disable multiple VM settings, use multiple disable instructions.
See VM Settings section for details on available options.
The echo instruction simply echoes a string argument.
echo "Hello, world"
The enable instruction enables the specified VM setting inside the container.
enable <vm setting>
Only one setting can be enabled per instruction. To enable multiple VM settings, use multiple enable instructions.
See VM Settings section for details on available options.
The env instruction creates a new environment variable inside the working container.
env <name>="<value>"
This environment variable will be persisted to the output image by the build command.
Only one environment variable can be added per env instruction. To add multiple environment variables to the working container, use multiple env instructions. Well known system paths like C:\Windows\System32 will be replaced by a variable that will be converted at runtime to the appropriate path for the execution environment.
When multiple environment variables with the same name are defined in set of images used to run a container, the value from last image is used. For two environment variables, PATH and PATHEXT, special behavior is defined. All values are concatenated together using the semicolon as the joining character. The value from the last image appears first and the host value is at the end.
env foo="bar"
env path="c:\path to executables\"
In the container these variables will have the following values:
foo="bar"
path="c:\path to executables;C:\WINDOWS\system32;C:\WINDOWS"
Variables can be reset within the same TurboScript by repeating the env command for the same variable name. The last value will be stored in the image. To remove the variable from the image, use the following command:
env foo=
Please note that if variable foo is also defined in one of layer images and final image is created with --no-base flag then it will be still loaded into containers created with it.
Environment variables can be overridden in a container by explicitly setting the variable to a new value or when an application or installer sets a new value.
The hosts instruction modifies host name resolution within a container.
hosts <ip address|local host name> <host name>
The syntax for this command matches that of the hosts file in Windows where the first parameter is a host name or IP address and the second parameter is the name to resolve the host name/IP address to.
This setting is persisted to the output image so that any containers created from that image will have these DNS settings applied.
# Make the loopback ip resolve to mydomain.net
hosts 127.0.0.1 mydomain.net
# Redirect requests to google.com to localhost
hosts localhost google.com
The import instruction imports content of specified file into current image.
import <import type> <path to file>
Supported import types:
The isolate instruction sets the isolation setting of a named object.
isolate "<objectType>:<name or path>" <isolation>
Supported object types:
Supported isolation types:
The layer instruction creates a new container and sets the base image(s) for that container.
layer <image>
The layer instruction can be omitted if a clean base image is desired. Multiple layer instructions are additive.
Multiple images can be specified in a single layer instruction by separating each image with a comma or space. If the same file, registry entry, or environment variable exists in multiple images added via the layer instruction, then the one from whichever image was specified last will win the conflict and be used in the virtual environment. Virtual machine settings are taken from the last image specified in the layer instruction.
Due to this "layering" approach, it is a good practice to specify images with newer versions of applications or libraries after images with older versions.
layer <image 1> <image 2>
# Start container with git and node.js
layer git/git nodejs/nodejs
Note: To initialize an empty container, use the clean image
layer clean
The meta instruction sets the metadata value for the output image.
meta <name>="<value>"
Standard metadata properties are listed below:
Additionally, metadata can be used to control namespace, name, and tag of the output image.
Custom metadata can be specified using other name-value pairs.
# Add a title
meta title="application name"
meta namespace="organization"
meta name="application"
meta tag="0.1"
# Add custom metadata
meta internal-name="new-name"
The require instruction defines a runtime requirement which should be checked and enforced before the output image is launched. If the requirement cannot be satisfied, the image will not be run.
require <requirement>
The following requirements are supported:
Example:
# Fail if image is not launched on 64-bit machine
require architecture:x64
The requires instruction defines a build time requirement which should be enforced immediately. If the requirement cannot be satisfied, the build will fail.
requires <requirement>
See the require instruction for the list of supported requirements.
Example:
# Run TurboScript in elevated command prompt
requires privilege:admin
The route instruction adds a route mapping.
route add <route-specifiation>
route block <route-specifiation>
The route add and route block instructions are equivalent to --route-add and --route-block flags to the turbo new command, respectively. They use the same syntax for route-specifiation.
Examples:
# Block all tcp ports
route block tcp
# Map container port 80 to local port 8080
route add tcp://80:8080
# Block access to IP address 192.168.1.123
route block ip://192.168.1.123
The setworkdir instruction sets the working directory which is used by the output image at runtime.
setworkdir <path>
If a setworkdir command is not specified then all commands will be executed from the same working directory as the native command prompt. The <path> specified must exist on host or be created within the container.
The shellextension instruction is used to enable a shell extension in the output image.
shellextension <context menu handler CLSID> <extension dll> <executable>
If an image contains shell extensions, the MergeStartupDir VM setting should be enabled to allow operations on file system items using the context menu in Windows Explorer.
Examples:
enable MergeStartupDir
# shellextension <context menu handler CLSID> <extension dll> <executable>
shellextension "{B41DB860-64E4-11D2-9906-E49FADC173CA}" "@PROGRAMFILES@\WinRAR\rarext.dll" "@PROGRAMFILESX86@\WinRAR\winrar.exe"
shellextension "{B41DB860-8EE4-11D2-9906-E49FADC173CA}" "@PROGRAMFILESX86@\WinRAR\rarext.dll" "@PROGRAMFILESX86@\WinRAR\winrar.exe"
Values required to enable the shell extension were copied from the following locations in the system registry:
| Parameter | Value | Registry path |
|---|---|---|
|
context menu handler CLSID |
{B41DB860-64E4-11D2-9906-E49FADC173CA} |
@HKCR@\WinRAR32\shellex\ContextMenuHandlers |
|
extension dll |
@HKCR@\CLSID\{B41DB860-64E4-11D2-9906-E49FADC173CA}\InProcServer32 |
@PROGRAMFILES@\WinRAR\rarext.dll @PROGRAMFILESX86@\WinRAR\rarext.dll |
|
executable |
@HKCR@\WinRAR\shell\open\command |
@PROGRAMFILES@\WinRAR\rarext.dll @PROGRAMFILESX86@\WinRAR\rarext.dll |
The startup file instruction is used to specify the startup file or script to run when a new container is created from this image (using turbo run).
The instruction has multiple forms:
startup file <command> <param1> <param2> (executes the application directly)startup file ("executable", "param1", "param2") (executes the application directly)startup file [("executable1", "param1", "param2"), ("executable2", "param1", "param2"), ...] (executes the list of applications directly)startup file trigger=("executable", "param1", "param2") (assigns a trigger name to a startup file)startup file trigger=[("executable1", "param1", "param2"), ("executable2", "param1", "param2"), ...] (assigns a trigger name to a collection of startup files)This instruction is only applied to the output image and does not affect the intermediate container.
If startup file is not specified then the startup file setting is inherited from last image listed in the layer command. Well known system paths like C:\Windows\System32 will be replaced by a variable that will be converted at runtime to the appropriate path for the execution environment.
If you wish to launch a process from an executable and optionally supply parameters to that executable, you must express the desired executable as a tuple of strings and give the full path to the executable (unless it is on the local system or container's PATH). Using this syntax, parameters are passed directly to the executable.
# "clone" and "https://github.com/turboapps/docs" are passed to git.exe
startup file ("git.exe", "clone", "https://github.com/turboapps/docs")
You may also launch a process using basic command prompt syntax. To open a Command Prompt window with a message:
# Hello world is passed to the 'echo' shell command
startup file cmd.exe /k echo hello world
It is possible to specify multiple startup files which will be launched simultaneously using the array syntax.
# set multiple default startup files for "test-shotgun" image
startup file [("c:\windows\system32\notepad.exe"), ("c:\windows\regedit.exe")]
# launch both notepad and regedit
turbo run test-shotgun
A startup file, or collection of startup files, can be assigned a trigger name. When this is done, the startup file(s) specified will only launch when using turbo run with the --trigger flag. This can be useful when setting up shortcuts to multiple applications inside the same image.
# in turbo.me file to create "test-trigger" image...
startup file [("c:\windows\system32\notepad.exe"), ("c:\windows\regedit.exe")]
startup file doc=[("c:\windows\system32\notepad.exe", "c:\doc\welcome.txt"), ("c:\windows\system32\notepad.exe", "c:\doc\howto.txt")]
# from command-prompt...
# launch both notepad and regedit are launched
> turbo run test-trigger
# launch welcome.txt and howto.txt in notepad
> turbo run test-trigger --trigger=doc
The sync instruction enables or disables synchronization for a specific path.
By default all directories except the @LOCALAPPDATA@ directories are synchronized.
The sync instruction is applied recursively to all sub directories.
sync enable|diable "<path>"
# Disable synchronization for the app-settings directory
sync disable C:\apps-settings
# Enable synchronization for the sub directory
sync enable C:\app-settings\important-settings
The using instruction adds an additional, temporary image(s) for that container.
using <image>
Multiple images can be specified in a single using instruction by separating each image with a comma or space. If the same file, registry entry, or environment variable exists in multiple images added via the using instruction, then the one from whichever image was specified last will win the conflict and be used in the virtual environment. If the same file, registry entry, or environment variable exists in two images, one added via the using instruction and one added via the using instruction, then the one in the using image will win the conflict. Virtual machine settings are taken from the last image specified in the using instruction.
Due to this "layering" approach, it is a good practice to specify images with newer versions of applications or libraries after images with older versions.
If the next instruction after using is indented, a scope is defined and the images specified in the using instruction are available only in this scope.
using python
cmd python --version
cmd python --version || echo Python not available!
Note: Images added with using keyword are NOT included in final image
The var instruction sets value of a variable.
var <name>="<value>"
The value can be an expression involving strings and other variables.
var foo="bar"
var myvar=foo + "baz"
A few special variables are implicitly defined:
last - Output of last executed commandspoonversion - Version string of the binaryyear - Current yearmonth - Current month numberday - Curent day numberhour - Current hourminute - Current minutesecond - Current seconddateiso - Current date in yyyyMMdd formatdate - Current datetime - Current timeFor programs started in the build container, variables are available as environment variables.
var version = ""
using python
cmd python getLatestVersion.py
var version = last
using wget
cmd wget https://example.com/application-%version%.exe
meta name = "application"
meta tag = version
The workdir instruction sets the working directory inside the container.
workdir <path>
If a workdir command is not specified then all commands will be executed from the same working directory as the native command prompt. The <path> specified must exist on host or be created within the container before this instruction.
Unlike cmd cd <path>, the workdir instruction will persist the working directory to all subsequent instructions.
Turbo Shell, spsh, is a REPL-like interactive interface that understands TurboScript syntax.
When Turbo Shell starts, it creates a working container and starts an interactive prompt. Optionally, given a path to a TurboScript file as an argument, it can instead start by executing the TurboScript and only giving up execution control when the script issues a yield instruction. At the end of a Turbo Shell session, the working container is removed unless keep on instruction has been issued.
Turbo Shell scripting capabilities are superset of capabilities offered by turbo build. The differences:
copy instruction can be used to copy from anywhere on the host OSThe commit command commits the working container to an image.
commit [no base] [overwrite]
If no base is specified, base image(s) are not merged into the new image.
If overwrite is specified, any existing images of this name are overwritten.
The name and tag of the image can be controlled by setting meta namespace, name, and tag.
The push command pushes last committed image to the hub.
push [<remote image>]
If the name of remote image is not specified, the image is pushed with the same name as committed locally.
Newly created images are usually based on a existing image. For example, a Wordpress image is based on a PHP, MySQL and Apache image. How are these dependencies handled?
By default all base images are baked into the new image. The newly created image includes everything it needs.
For information purpose the used images will show up in the Hub under the Dependencies tab of the repository.
If a image is created with the --no-base option, the newly created image will not contain the base images.
Instead the images are downloaded and loaded when the image is used.
Example, a Wordpress image based on a PHP, MySQL and Apache. If this image was build with --no-base, and then launched,
the PHP, MySQL and Apache image are downloaded as well. Transitive dependencies are downloaded recursively.
A Image build with --no-base cannot be pushed, if the base images are not available on Hub.
An error will indicate which images have to be pushed first, before the main image can be pushed.
The latest Turbo Client may be downloaded from https://turbo.net/download.
Installing Turbo Client for a Single User
To install the Turbo Client using default settings, double-click on the installer. This will configure the client for the current user and place the client components in the %LOCALAPPDATA%\Turbo user directory. Shortcuts will be added to the Start Menu in the Turbo.net folder for quick access to the Turbo.net Preferences. In addition, shortcuts will be added to the Startup folder to automatically start the Turbo Client.
The Turbo Client launches applications from the workspace portal using the turbo:// protocol, so a browser extension is not required for application launches.
The Turbo.net Extension is required when using the redirector feature with the Chrome browser. It may be found in the Chrome Web Store at https://chrome.google.com/webstore/detail/turbonet-extension/ldibmiofagdkgiphkcokpooepankmacl.
Installing Turbo Client for All Users
The Turbo Client can be installed for all users on the machine with the --all-users flag, which will place the client components in the %PROGRAMFILES(x86)%\turbo directory and register the shortcuts for all users on the system.
Note that if users on the machine already have the Turbo Client installed in their user directories, then their single user installs will be overriden by the all user install. Additional updates to the Turbo Client will occur for the all users installation even if the --all-users flag is omitted.
For all user installs in environments using the Chrome browser, the Turbo.net Extension may be enabled via group policy. See the [Enable the Turbo.net Extension for All Chrome Users] (https://blog.turbo.net/deploying-turbo-browser-url-redirection-via-group-policy/) section on the Turbo.net Blog.
Turbo Client Unattended Installation
Pass the --silent flag to the client installer to suppress the UI popups that may block unattended installs.
Passing Config Flags to Turbo Client Installer
Pass turbo config flags to the Turbo Client installer to configure the client at install time, such as setting the Turbo Server as the Domain URL and a trusted source.
# Install Turbo Client with a configured Domain URL and trusted source.
> Turbo-Plugin.exe --all-users --silent --domain=https://my.turboserver/ --add-trusted-source=https://my.turboserver/
If you are using the MSI installer, pass the config flags in CMDLINE:
# Install Turbo Client MSI with a configured Domain URL and trusted source.
> msiexec /i Turbo-Plugin.msi cmdline="--domain=https://my.turboserver/ --add-trusted-source=https://my.turboserver/" /qn
Turbo Client Installer Flags
Running the Turbo Client installer with these command line flags can change the install behavior.
|
Flag |
Behavior |
|---|---|
--app-server |
Installs client and provisions the server to be used as an Application Server in an onpremise streaming pool. |
--all-users |
Installs the Turbo Client to %PROGRAMFILES(x86)%\turbo so that it is accessible for all users on the machine. This is required for running certain Turbo command for all users (such as `subscribe` or `installi`) |
--hide-gui |
Disables the Turbo Launcher from being visible. |
--no-auto-start |
Stops the Turbo Launcher from starting when logging into your machine. |
--no-auto-update |
Disables the check to see if new versions of the client are available. |
--no-redirector |
Doesn't install the Turbo Redirector Internet Explorer plugin when installing for all users. |
--no-shell-ext |
Disables the Turbo Launcher from being visible. |
--shutdown-period |
Specifies the number of minutes that the Turbo Sandbox Manager is idle before shutting down. |
--silent |
Turbo Client installs without any UI popups. |
turbo config flags |
Turbo Client installs with the specified turbo config setting. See turbo config for available flags. |
Uninstalling Turbo Client via Control Panel
You can uninstall the Turbo Client or the TurboLauncher specifically from the Windows Uninstall or change a program screen (previously called Add/Remove Programs).
Uninstalling Turbo Client via the Command Line
To uninstall the Turbo.net Sandbox Manager, you may pass the /uninstall flag to the Turbo-Sandbox.exe in the %LOCALAPPDATA%\turbo[client-version] directory for single user installs or %PROGRAMFILES(x86)%\turbo[client-version] for all user installs.
# Uninstall for single user
C:\> "%LOCALAPPDATA%\Turbo\[client-version]\Turbo-Sandbox.exe" /uninstall /silent
# Uninstall for all users
C:\> "C:\Program Files (x86)\Turbo\[client-version]\Turbo-Sandbox.exe" /uninstall /silent
For unattended or scripted uninstalls, pass the /silent flag in addition.
Note that if the client is installed for all users, you would have to run from an elevated command prompt or the command will fail with insufficient privileges.
Turbo-Sandbox.exe Uninstall Flags
Pass the following flags to the Turbo-Sandbox.exe to uninstall specific components or the whole Turbo Client.
|
Parameter |
Behavior |
|---|---|
|
/uninstall |
Uninstalls the Turbo Client. Close all web browsers before uninstalling. |
|
/silent |
Used with /uninstall to perform a silent uninstall. |
|
/delete-user-data |
Used with /uninstall and /silent to remove user container data during uninstall. |
|
/uninstall-launcher |
Uninstalls the TurboLauncher but leaves the rest of the client. |
|
/uninstall-redirector |
Uninstalls the TurboRedirector but leaves the rest of the client. |
There are several ways to control how containers can be run on your machine.
Trusted sources control which hub locations are allowed to have containers be started from web locations. By default, only https://turbo.net is trusted. A new hub can be added to the list with turbo config --add-trusted-source=[hub-authority].
Any untrusted hub will result in a warning dialog that will ask the user if the container execution is desired. The user will have the option to trust future containers from the location.
A hub location can also be blocked which will prevent users from executing containers from those locations. A hub source can be blocked with turbo config --block-trusted-source=[hub-authority].
The trusted sources can be set for all users on the machine with the --all-users flag. These will either set the defaults or the overrides depending on how the shared settings are configured.
# view current trusted sources
> turbo config
Hub server: https://turbo.net/
Turbo Drive is enabled (mounted as a T: drive)
Trusted Hub Sources:
turbo.net
# add a trusted hub
> turbo config --add-trusted-source=my-hub.com
Hub server: https://turbo.net/
Turbo Drive is enabled (mounted as a T: drive)
Trusted Hub Sources:
turbo.net
my-hub.com
# block a hub
> turbo config --block-trusted-source=dangerous-hub.net
Hub server: https://turbo.net/
Turbo Drive is enabled (mounted as a T: drive)
Trusted Hub Sources:
turbo.net
my-hub.com
Blocked Hub Sources:
dangerous-hub.net
Containers which are executed remotely may require access to local resources (such as local network). If the container requires access but is not allowed globally then a security dialog will be shown to request permission.
To allow access to the local network automatically, use turbo config --enable=LocalNetworkAccess.
Turbo Play is a command line based window wrapper application to Turbo applications.
Users may execute turbo commands from turboplay which will provide windows graphical interface instead of the command prompt.
> turboplay turbo run --format=rpc my-image
User can also pass in a text file as the argument which contains a turbo command.
> turboplay turbo C:\Users\[user]\AppData\Local\Turbo\Containers\shortcuts\My App.txt
Additional flags:
--quiet Hide all graphical user interfaces until the application launches
--start-progress-ui-immediately Shows the status dialog immediately before any events are detected from the underlying Turbo.exe
--wait-for-window Status dialog remains until the application's main UI shows
--delete-cmd-file Deletes the cmd file if specified immediately after reading it. Todo: remove
--enable-full-removal Todo: remove
--app-title Sets the title of the status dialog
--debug-vm Overrides the path to the vm
--log Specifies location of log file
--startup-file Passes through startup file to turbo.exe
--startup-verb Passes through startup verb to turbo.exe
--isolate Passes through isolation setting to turbo.exe
--merge-file Passes through merge file setting to turbo.exe
Additional Notes:
--wait-after-(error|exit) is ignored because it causes the process to hang waiting for input that will never come.--format=rcp is automatically passed in in order to parse the output.--show-eula-for-rpc is automatically passed and displayed to the user in a window if a EULA exists for an application.The Turbo protocol directs Turbo Play to execute a local execution of an application, or connects to a remote application server capable of launching a Turbo application.
turbo://{portalAuthority}/{configPath}?t={type}&h={hash}&v={version}
portalAuthority domain which must be trusted by the user from which the configuration comes from
path path of the service, typically 'config'
type config for launching a local application or remoteAppConfig for connecting to a remote application
hash hash of the configuration, to ensure its contents are not tampered with
version currently at 1
Configuration type example:
turbo://turbo.net/config?t=config&h=sha256:e28dd1863f82e6b2f46303311540ae194045a58756cd1c4fbbbc4c778021bc84&v=1
The json format of a config type is
{
"id":"2b68b3de-51e2-4a60-b822-bd810a55146f",
"repoId":"mozilla/firefox",
"appTitle":"Firefox",
"verb":"try",
"isolation":"full",
"isolateNetwork":false,
"routes":[],
"redirectedDomains":[],
"adGroupPermissions":[],
"startupFile":"",
"vm":"",
"layers":[],
"using":[],
"sync":false,
"tnlr":false,
"enableRemoteCommands":true,
"v":"1"
}
RemoteAppConfig type example:
turbo://turbo.net/config?t=remoteAppConfig&h=sha256:51d021ef9da4ee6c7910a4d5f19325fba77888ba94255ab67e0e4c0d8053fa6d&v=1
The json format of the remoteAppConfig type is
{
"v":1,
"sessionId":"e3e9df43-8f1e-4b0c-a371-8080b67cbc66",
"host":"192.0.2.1",
"auth":{
"user":"randomWindowsUser",
"password":"randomWindowsPassword"
},
"app":"turboplay",
"args":"turbourl turbo://config.to/run"
}
The legacy Turbo URI scheme is in the format of turbo://[Ip]?[query].
The query parameters are:
type rdp or local
rdpUsername the username on the remote system executing turbo
rdpPassword the password on the remote system executing turbo
remoteAppMode set value to 1 for RemoteApp rdp
remoteAppProgram set this to %7C%7Cturboplay
remoteAppCmdLine the arguments sent to the remote TurboPlay
tnlrUrl URL of the remote tnlr service which allows the remote application to connect to the local network
tnrlUsername tnlr username
tnlrPassword tnlr password
Turbo Play can connect and execute a Turbo Play command on the remote desktop without a Turbo URI scheme.
> turboplay rdp --rdp-host=<hostname> --rdp-program=<remoteAppProgram> --rdp-user=<rdpUsername> --rdp-password=<rdpPassword>
Required parameters:
--rdp-host=<hostname>
Optional parameters:
--rdp-domain=<logon user's domain>
--rdp-user=<logon user>
--rdp-password=<logon password>
--rdp-program=<program to run, defaults to cmd.exe>
--rdp-cmd=<remoteapp cmdline args>
--rdp-port=<rdp port, default 3389>
Turbo Play can execute Legacy Turbo applications from a config or model URL
/config The URL to an application configuration to execute
/model The UNC path to a streaming model to execute
/xsandboxname
/xsandboxpath The path to the app sandbox (required with the /model flag)
/register
/cachemode The local path where the fully streamed application is to be cached (only valid with the /model flag and is required).
/clientconfig
/xvm
Turbo allows you to package applications and their dependencies into a lightweight, isolated virtual environment called a "container." Containerized applications can then be run on any Windows machine that has Turbo installed, no matter the underlying infrastructure. This eliminates installs, conflicts, breaks, and missing dependencies.
Turbo containers are built on top of the Turbo Virtual Machine, an application virtualization engine that provides lightweight namespace isolation of core operating system objects such as the filesystem, registry, process, networking, and threading subsystems.
Turbo dramatically simplifies and makes more reliable all phases of the software creation and deployment lifecycle:
With Turbo, developers can:
With Turbo, testers can:
With Turbo, system administrators can:
Turbo containers are built on top of the Turbo Virtual Machine Engine, an application virtualization engine which provides lightweight implementation of core operating system APIs, including the filesystem, registry, process, networking, and threading subsystems. Applications executing within the Turbo virtual machine interact with a virtualized filesystem, registry, network, and process environment supplied by the SVM, rather than directly with the host device operating system.
The image below illustrates how the SVM is isolated from the host environment.
The Turbo VM is required to implement containerization on the Windows platform since the underlying OS does not provide appropriate containerization primitives. Put another way, Turbo VM plays the same role for Turbo containers as LXC does for Docker containers.
Unlike hardware virtualization systems like Microsoft Virtual PC and VMWare, or hypervisor systems such as Hyper-V, Turbo VM operates on top of the base operating on the execution stack and virtualizes specific operating system features required for application execution. This enables virtualized applications to operate efficiently, with the same performance characteristics as native executables.
There are several advantages in choosing Turbo containers over hardware virtualization systems:
Optimal performance: Turbo containers run at the same speed as applications running natively against the host hardware, with a minimal memory footprint. In contrast, applications running within hardware-virtualized environments experience significant slow-downs and impose a large memory footprint due to the need to run multiple instances of a base operating system.
Dramatically reduced virtual environment size: Turbo containers require a footprint proportional to the size of the virtualized application, data, and included components. As a result, Turbo containers are small enough to be quickly downloaded by end-users. Hardware virtualization requires an entire host operating system image, including many basic subsystems that are already present on the end-user device. Each virtual machine may occupy several gigabytes of storage.
Application density: You can run multiple simultaneous Turbo environments per processor. Due to the high overhead of hardware virtualization, only a small number of hardware-virtualized environments per processor can run simultaneously.
Reduced licensing costs: Turbo does not require the purchase of separate operating system licenses to use a container. Hardware virtualization systems require a host operating system in order to function, which can impose additional licensing costs and restrictions.
User mode implementation: The Turbo application virtualization engine is implemented entirely in user mode and does not require administrative privileges. Note that applications requiring hardware device drivers or other non-user-mode software may require a hardware-virtualized environment to function properly.
Do Turbo containers work by running a full OS virtual machine?
No. Turbo containers use a special, lightweight application-level VM called Turbo VM. Turbo VM runs in user mode on top of a single instance of the base operating system.
How long does it take to start Turbo containers?
Turbo container startup time is very fast -- on the order of seconds or less. (Startup time excludes any time required to download images.)
What is the performance overhead of running inside a Turbo container?
Containerized applications consume only a small percentage of additional CPU and memory consumption relative to native applications. In nearly all cases, Turbo overhead is negligible.
When I run a container with multiple base images, does it link multiple containers or make a single new container?
Running with multiple base images creates a single container with all of the base images combined. However, this is implemented in an optimized way that avoids explicit copying of the base image container contents into the new container.
Turbo then stores deltas on top of the base images as the container state evolves. The , operator works left-to-right, so files or settings in later arguments override files or settings in previous arguments.
Does Turbo support virtual networking?
Yes. Controlling both inbound and outbound traffic is supported. See the --route-add, --route-block, --link, --hosts, and --network commands. For details relating to binding and routing container ports or IPs see IP Routing in Turbo Containers, part 2, and part 3.
Does Turbo support linking multiple containers?
Yes. See the --link and --network commands.
Is there a difference between server and desktop application containers?
No, there is no special distinction. And desktop containers can contain services/servers and vice versa.
How does Turbo handle licensing?
Turbo does not modify the licensing behavior of any applications running virtualized or within a container. Running on Turbo is identical to running on a regular PC, or running on virtual hardware such as Virtual PC or VMware. And Turbo runs on a single instance of a base operating system.
Does Turbo provide a mechanism to track licenses?
Turbo Server includes a licensing module which will actively track and/or enforce licensing. For example, you can grant/deny privileges based on Active Directory or LDAP membership and define licensing constraints on a total user, total device, concurrent user, or concurrent device basis. Turbo Server also provides an analytics module that allows administrators to track application consumption and validate compliance with licensing requirements.
Where is the Turbo container hub?
The public Turbo Hub is hosted at https://turbo.net/hub.
What is the Turbo.net pricing model?
Turbo.net is a subscription service and can be purchased for individuals or an organization. There is a seven day trial period on all new accounts. See Pricing and Plans for more information on Turbo.net plan options.
What if I don't want to host my repositories hosted on Turbo.net?
Turbo is also available as an on-premises enterprise server. Please see Turbo Server for more information or to request an evaluation license.
Does Turbo support file associations and shell extensions?
Yes. Turbo images and containers with shell extensions or file associations can be installed onto the host operation system. Use the installi or install command with the --register-extensions flag.
**How do I pass parameters/arguments to the underlying container's cli?
Pass the arguments directly after the image or containers name: turbo run clean ping google.com. If the command line interface uses dash flags which requires escaping use -- to pass parameters directly: turbo run chrome -- -incognito. This applies to the run, try, and start commands.
The Turbo platform includes both an application virtualization engine and a containerization engine. The Turbo container implementation is built on top of the Turbo application virtualization (usually called "app virtualization") engine, but includes many additional components.
Turbo's traditional app virtualization tool is called Turbo Studio. As with other app virtualization systems, Turbo Studio is based on a "static" model of virtual application configuration. Virtual machine state is created by capturing snapshots of a physical (or virtual physical) system. This is similar to the processes used by other products in this category such as Microsoft App-V and VMware ThinApp. A major disadvantage of this approach is the requirement to have a clean physical or virtual machine available to use as a target for "sequencing" (App-V) or "capture" (ThinApp).
Turbo containers offer a "dynamic" configuration model -- the user is presented with a clean base image (or a base image created by combining a set of pre-configured source images) and the user installs, configures, and runs applications within that container. The container model offers a significant advantage over the traditional app virtualization model in that a clean machine is not required to create virtual environments. Turbo containers are lightweight and can be quickly instantiated, committed, and shared to the hub over the web.
In addition, containers support concepts such as commit, push/pull, and rollback, allowing container state to be captured at specific points in time and shared with collaborators. Turbo also supports a powerful, unique primitive called continuation, which allows execution container state to be moved between devices. Continuation is linked to a state identifier which is a hash value computed from the dynamic state of a container.
The Turbo containerization system includes:
turbo console command provides a command-line interface for standard container
operations such as creating, stopping, committing, and pushing containers.continue
command for more information on continuation.)In addition, the Turbo VM has been substantially enhanced to support the additional primitives required by the containerization engine. Turbo's application compatibility footprint was expanded to provide support for additional server applications.
How is Turbo different from App-V or ThinApp?
Turbo provides an app virtualization engine and associated tooling, as do App-V and ThinApp. However, the underlying implementations between the three systems are very different. For example, App-V uses device drivers (and therefore requires administrative privileges on the desktop) and requires additional backend infrastructure such as Active Directory and SQL Server. ThinApp is a user mode implementation but differs in many details impacting compatibility coverage and available delivery modes. Both App-V and ThinApp require "sequencing" or "capture" of setups on a clean machine in order to create virtual environment packages.
Neither App-V nor ThinApp offer a containerization system supporting essential container primitives such as image storage, versioning, rollback, network virtualization, or container linking. While app virtualization engines share some characteristics in common with containers, such as the ability to run software in an isolated namespace from the host device, containerization requires additional components such as the container storage system, command processor, scripting engine, and hub, as well as additional core app virtualization engine capabilities to support dynamic configuration of application packages. Critically, neither App-V nor ThinApp support the ability to install software within a container without requiring a "sequencing" or "capture" process on an external operating system instance.
Docker is a new containerization technology built on top of the LXC kernel container system, a component of the Linux OS. While there are some similarities between the Docker and Turbo platforms, there are also significant differences.
This section summarizes some of the substantial differences for those that are familiar with Docker.
Turbo was designed for the Windows platform and its containerization system is built on top of the Turbo application virtualization engine. Docker was designed for use on Linux environments and is built on top of the LXC application virtualization system. Put another way, the Turbo VM plays the same role for Turbo containers as LXC does for Docker. In fact, LXC can be viewed as a type of application virtualization implementation.
Turbo supports both desktop and server Windows applications, and works on all desktop and server editions of Windows from Windows Vista forward. Turbo does not require modifications to the base operating system kernel and Turbo does not execute a parallel copy of the base operating system.
For more information about the differences between application and OS virtualization, see the article How Turbo is different from hardware virtualization.
Via the Turbo VM, Turbo containers support many Windows-specific constructs, such as Windows Services, COM/DCOM components, named kernel object isolation, WinSxS side-by-side versioning, shell registration, clipboard data, and other mechanisms that do not directly apply to Linux operating systems.
Turbo also provides a desktop client with many features (GUI tool to launch applications, file extension associations, Start Menu integration) that allow containerized applications to interact with the user in the same way as traditionally installed desktop applications. Turbo also provides a small browser plugin that allows users to launch and stream containerized applications directly from any web browser.
Turbo containers are designed to operate in a layered virtual application engine architecture. Layers can be thought of as "transparent sheets" of virtual environment configuration that can be stacked on top of one another to build many distinct configurations out of discrete components.
For example, to build a container for a Java application that uses a MongoDB database, a Turbo user could combine a Java runtime layer with a MongoDB database layer, then stack the application code and content in an application layer on top of its dependency layers. Layers make it extremely easy to re-use shared components such as runtimes, databases, and plugins.
Layers can also be used to apply application configuration information. For example, one might have a layer that specifies the default homepage, favorites, and security settings for a browser. This can be applied on top of a base browser layer to impose those settings onto a non-customized browser environment.
Layers can be applied dynamically and programmatically, so you can present distinct application configurations to specific groups of users without rebuilding the base application container. Continuing the browser example, one might create a base browser layer with a particular configuration layer for the development team, then use the same base browser with a different configuration layer for the sales team.
Turbo layering also enables partial rollback during container builds via the using command. This is especially useful when an external tool is required during the build process, but is not desired in the ultimate container. For example:
using git
# pull in content using git
# (git content no longer present in the container)
# use the content to complete container setup
In this code, the contents of the git container will not be present in the output container. By contrast, Docker does not distinguish between content that is imported for use only during the build process and content required by the application container at runtime.
Layering can be used in the turbo.me automated build script to build containers on top of multiple base images. For example, in TurboScript the following is valid:
layer java, mongodb, redis
By contrast, Docker does not support creation of images from multiple base images. In other words, Turbo supports "multiple inheritance" through source layering, and "polymorphism" through post-layering.
In addition to images and containers, Turbo supports an additional abstraction level called a state. Unlike image and container identifiers, which are arbitrary, a state is identified with a hash value that aggregates the state of all objects within the container at a specific point in time. States are volatile in that they vary continuously as execution occurs in the underlying container, and are indepenent of commit points. By default, the Turbo container engine captures state information at container startup and shutdown.
Turbo's unique continue command allows execution to be continued from a specified state identifier. Importantly, the state identifier encodes all
information about a container and, in particular, allows for continuation of container execution across different devices.
When a container is stopped or suspended, the Turbo container engine will report a state identifier for the container, such as 6aac21bf. You can
then continue execution of the container from that state with the command:
turbo continue 6aac21bf
and this command can be executed from any device, not necessarily the original device hosting the container. Continuation can be used with any state, not necessarily the latest state, creating the effect of an inter-commit rollback; and multiple continuations can be executed from a single state, allowing forking of execution, potentially across multiple devices.
Unlike Docker, Turbo containers are not required to be completely isolated from the host device resources. Turbo can fully or partially isolate objects as needed at a fine granularity.
The Turbo mount command allows a specific path in a container to be mapped to a (possibly different) path in another container or on the
host device. This is extremely useful, for example, to allow cached data to be persisted across resets of an application container image.
At an even finer granularity, a Turbo isolation mode may be specified on a per-object basis. For example, it is possible to specify that one directory subtree should be fully isolated while another one is visible from the host device. Supported isolation modes include Full, Merge, Hide, and Write Copy.
For more information on isolation modes, please see the Isolation Modes section of this documentation.
By default, all Turbo container ports are exposed on the host device network adapter, just as if the containerized application had been executed natively. If desired, all ports can be closed with a single command and then reopened or remapped on an individual basis. Like Docker, Turbo supports mapping of TCP, UDP, and DNS, as well as container-level remapping and IPC linking.
Importantly, this contrasts with Docker, which isolates all ports by default. With Turbo, a server container will work by default on the host device (ports open) and requires a separate command to close or relink the ports. Closing ports may be desired for various reasons, such as minimizing the network surface area in production environments.
Docker relies on root access to the host device at two levels. First, the LXC/libcontainer containerization engine that Docker is built on is
implemented within the Linux kernel. Second, the Docker daemon itself runs with root privileges. Containers themselves are not run with root privileges
when used in accordance with recommended practices. The use of code with kernel or root privileges opens the possibility of "break out" into privileged
system resources.
By contrast, Turbo is designed to run entirely in user mode with no privileges. Turbo containerization inherits this ability from the user mode Turbo app virtualization engine, which operates on top of (rather than within) the OS kernel. This approach has two critical advantages: Turbo can be used by unprivileged users on locked down desktops without elevation, improving accessibility and reducing administrative complexity; and, in the event of malware execution or a vulnerability in the Turbo implementation, the affected process does not have access to root privileges on the device.
Like Docker, Turbo provides command-line interfaces (turbo) and a scripting language (TurboScript) for automating build processes. Turbo also provides a number of rich GUI- and web-based tools and services for building, configuring, and managing virtual environments.
Turbo Studio provides a visual design environment and easy-to-use wizards for creating images.
Turbo Server is an on-premises version of Turbo.net that provides the same functionality in a behind-firewall environment. In addition, Turbo Server provides enterprise-specific such as a web application portal, Active Directory and LDAP integration, centralized management, user data synchronization, license management, and usage analytics.
Turbo also maintains an online database of validated application templates and images for thousands of popular software applications.
In addition to dynamic configuration via a console or script, Turbo also supports configuration via a static XML-based specification that declares the files, registry keys, environment variables, and other virtual machine states that will be presented to the container.
To assist in building static configurations, Turbo offers a graphical Turbo Studio interface, as well as both a graphical- and command line-based snapshot configuration.
For more information on Turbo Studio and snapshot tools, see the Studio section in this documentation.
Turbo, like Docker, supports the use of local containers and the ability to push and pull containers from a central repository.
In addition, Turbo provides the ability to efficiently stream containers over the Internet. The Turbo system includes a predictive streaming engine to launch containers efficiently over wide area networks (WANs) without requiring the endpoint to download the entire VM image. Because many applications can be multiple gigabytes in size, this prevents a large startup latency for remote end users. Turbo predictive streaming uses statistical techniques to predict application resource access patterns based on profiles of previous user interactions. Turbo then adapts the stream data flow based on predictions of subsequent required resources.
Turbo provides a fully hosted application hosting service at Turbo.net, which hosts application streams, provides application and user portals, automatically synchronizes user settings and application state to the cloud, and provides file synchronization and shared folders.For more information, visit the Turbo.net homepage.
Turbo provides commercial support for all official Turbo repositories. Professional services are also available for organizations needing assistance with virtualizing specific applications or building customized solutions on top of Turbo.
Turbo technology is integrated into select third-party enterprise application delivery platforms, including Novell ZENworks Suite, Novell ZENworks Application Virtualization, and LANDesk Management Suite. Novell and LANDesk provide commercial support for Turbo when purchased via these channels.
Welcome to the Turbo community!
All build scripts for Turbo images are open sourced, so please contribute!
You can contribute image build scripts here.
Things we love to see:
If you have an idea for an improvement but lack the time to make a pull request, tweet @turbohq, or email us at support@turbo.net.
If you want to join the Turbo team, check out our jobs page! We're hiring ;)