Working with Turbo Studio

Working with Turbo Studio

Turbo Studio is a desktop application that allows you to convert any Windows application into a self-contained virtual application. Virtual applications can be delivered as standalone executables, MSIs or Turbo images.

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 also provides three unique methods for creating images and virtual applications:

  1. 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. This method is ideal for virtualizing off-the-shelf applications or ones that use complex MSI installer packages that would be incompatible with the command-line interface.

  2. Build application from a template: Download configurations from the Turbo.net Hub, allowing you to quickly customize and build working applications.

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

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

System requirements and download

Turbo Studio runs on any Windows operating system, including systems running within VMware and Microsoft hardware virtualization and hypervisor environments. 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.

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.

Note: Turbo Studio does not support creation 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: Turbo Studio cannot access the turbo.net hub on Windows XP or Windows Server 2003 because the platforms do not support TLS1.2 which is required to access the web resources. Snapshot, build, and other features are not affected.

Download a free 30-day trial here or try the free, express version.

Basics

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.

Title Bar

  • The Start Menu button, or the circle at the top left of the window, enables container configurations to be created, opened, saved, imported, applied, and closed.
  • The Options bar provides Turbo Studio customization options, the ability to set proxy settings, and install certificates.
  • The Help bar provides access to Turbo Studio documentation.

Ribbon Bar

  • The Virtual Application tab provides access to the snapshot, build features, and output configuration options such as the startup file, output directory, and diagnostic-mode selection.
  • The Runtimes tab provides a selection of auto-configurable runtime engines which can be embedded into your application. These include .NET Framework, Java, Flash, Shockwave, Acrobat Reader, and SQL Server 2005 Express.
  • The Advanced tab provides functions such as viewing embedded layers and platform merge.
Snapshot
  • Capture Before button is to capture the machine state before you install your application for a snapshot.
  • Capture and Diff button is to capture the machine state after you install your application for a snapshot.

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

Build
  • Build button is to build your container image output.
  • Build and Run button is to build your container image output and then execute it for testing purposes.
  • Run and Merge button builds your container image and then executes it within the Turbo Client Runtime environment. Any changes made while inside the container environment will be added back to the configuration after the application is shutdown. This can be used to quickly set defaults in your container image.
Output
  • Startup File field is to set the path to the application which runs when starting your container. The Multiple button shows the Startup File manager dialog where additional settings can be specified.

  • Output File field is the name of the file that is created when your container image configuration is built.

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

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

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

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

Tools
  • Configuration Wizard button shows the startup wizard where there are quick links to common process wizards; building from template, snapshot, install into a container, or manual configuration.
  • Snapshot Merge button allows a container sandbox changes to be imported into the configuration.
  • Import Configuration button allows a container image to be imported from an external source, such as: a ThinApp configuration, MSI package, Zenworks package, the Turbo.net Hub, or from the local Turbo.net Client Runtime image repository.
Publish
  • Publish to Server button allows an output container image to be pushed directly to the Turbo.net Hub or a Turbo Server instance.
  • Publish to Local Repository button allows an output container image to be pushed to the local Turbo.net Client Runtime repository.

Left-side Button Panes

  • The Filesystem pane displays the application virtual filesystem and enables you to add and remove virtual files and directories.
  • The Registry pane displays the application virtual registry and enables you to add and remove virtual registry keys and data values.
  • The Settings pane enables you to configure container metadata, startup image, startup/shutdown shims, and process configuration options.
  • The Layers pane enables you to add external container components.
  • The Install pane enables you to configure the MSI setup package, shortcuts, and other shell integration options.
  • The Expiration pane enables you to configure application expiration options.
  • The Network pane enables you to configure container proxy and DNS settings.

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

Virtual Filesystem

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

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

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

Isolation Modes

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

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

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

File Attributes

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

To reduce executable size, Turbo Studio can compress virtual filesystem contents. This reduces container size by approximately 50% but also prevents profiling and streaming of the application. By default, the Compress Payload option in the Process Configuration area of the Settings panel is unchecked. Leave this box unchecked during the build process if the application will be optimized for streaming from Turbo Virtual Desktop Server.

Note: Disabling payload compression may significantly increase the size of the container binary.

Virtual Registry

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

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

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

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

Isolation Modes

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

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

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

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

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

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

Key Attributes

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

Turbo Studio can import registry hive (.reg) files into the virtual registry. To import a .reg file, select the Import button in the Registry panel, then choose the registry hive file to import.

Runtimes and Components

Many components and runtime systems consist of large, complex sets of filesystem entries and registry settings. Turbo Studio contains a collection of pre-configured component settings which can be added to your container with a single click. For example, if your application is a .NET Framework 4.0 application, then selecting the .NET Framework 4.0 component will allow your executable to run on machines without the .NET Framework installed.

Additional runtimes and components are added to the container during the snapshot process, before the after snapshot is taken.

To add a runtime or component:

  1. Select the Runtimes tab on the ribbon bar.
  2. Select the appropriate runtime or component. Selected components are indicated with a highlighted button. To remove a component, click on the button again. The button will no longer be highlighted and the component will not be included.

Note: The displayed runtimes apply to the currently selected target architecture (see process settings). If the target architecture is changed, architecture specific runtimes, like .NET 2 or .NET 3.x will still be included but will not display as selected. To deselect them, the target architecture must be changed back, and the runtimes can be deselected.

Note: Depending on the size of the component, the executable size can significantly increase. Only select components that are required for proper execution of your application.

Note: You are responsible for compliance with licensing for any third-party redistributable components included in your containerized application.

Using .NET Runtimes

To limit conflicts with installed .NET runtimes, the .NET runtime packages are isolated from the native file system. If the application requires access to multiple .NET versions, it is necessary to include all of the required runtimes in the virtual package. For example, including only the .NET 4 runtime will hide visibility to the .NET 3.5 runtime on the native file system. This is fine if the application only requires the .NET 4 components, but would be problematic if it also requires earlier versions of .NET.

An alternative approach would be to use the snapshot feature of Turbo Studio to build a custom .NET component for the application. This approach provides visibility into the files and registry keys that are available and allows for custom isolation settings.

Configuring the Java Runtime

Turbo Studio provides specialized support for the Java runtime. If your application is based on Java runtime, select the Sun Java Runtime button on the Runtimes ribbon bar. This displays the Java configuration menu.

Select the appropriate version of the Java runtime from the Java runtime version drop-down menu. If you deploy your application as a set of .class files, select Class from the Startup Type drop-down menu; if you deploy within a .jar file, select Jar. Enter the startup class name or Jar name in the appropriate textbox, along with any additional Java runtime options.

Snapshotting

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.

Process

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

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

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

Complete the following steps to use the Snapshot feature:

  1. Prepare the host device: remove the target application and all dependencies or copy Turbo Studio onto a clean machine.

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

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

  4. Install your application: also install any other files, settings, runtimes, and components you want to include in the image. Refer to Add Runtimes and Components for more information. If the application setup requests a reboot, save the before snapshot, then proceed with the reboot.

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

  6. Review the filesystem and registry entries: also remove any files or settings which are not required for proper execution of your container. Removing unused entries will reduce image size. Avoid accidental removal of required resources, as it will cause your image to no longer function properly.

Capture Application Updates via Snapshot

Container updates can be captured within Turbo Studio via snapshots.

Complete the following steps to capture an update via snapshots:

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

  2. Select Capture Before.

  3. Install necessary updates to the native application.

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

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

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

For more information on updating containers using SVMs, refer to Create and Use Shared Virtual Components and Specify Additional SVMs for a container.

Best Practices

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

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

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

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

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

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

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

  • Remove uninstall shortcuts during the pruning process.

Snapshotting Google Chrome Install

Below is a walkthrough of the steps required to snapshot Google Chrome.

Start with a Clean Virtual Machine

When using the snapshot method to containerize an application, it is important to start with a clean system so that no components are missed during the capture and diff process.

The snapshot process can be performed on a virtual machine or a physical machine. Typically a virtual machine is used so that the system can easily be reset in case the process needs to be repeated.

There are many options for virtual machine software including VMWare Workstation, Oracle Virtual Box (free) and Microsoft Virtual PC. In this example I will be using Oracle Virtual Box.

Turbo Studio can be downloaded from https://turbo.net/studio.

In this example we will be creating a snapshot of Google Chrome.

Using the Wizard to Capture the Application Install

Select the third option in the Wizard, Snapshot a third-party application or component.

Select Next on the following screen to capture the "before" snapshot.

Chrome can be installed in two different locations on the system. The standard location is underneath the Current User profile. There is another enterprise installer available on the Google website for installing Chrome under Program Files. In this example the enterprise location will be used, but both approaches will be discussed in the following steps.

Launch Chrome.

Close the open tabs and then exit Chrome (ensure it is not running in the background by checking the system tray and task manager) .

Navigate to Services. Disable both Google Chrome update services.

Open %LOCALAPPDATA%\Google\Chrome\User Data\Default\Preferences with Notepad. Configure the preferences as you see fit. In this example, we set the following configuration:

{ 
  "homepage" : "http://www.google.com", 
  "homepage_is_newtabpage" : true, 
  "browser" : { 
	"show_home_button" : true, 
	"check_default_browser" : false
  },

	"download": {
	"directory_upgrade": true,
	"extensions_to_open": "",
	"prompt_for_download": true

  },
  "bookmark_bar" : { 
	"show_on_all_tabs" : true 
  }, 
  "distribution" : { 
	"msi" : true,
	"system_level" : true,
	"verbose_logging" : true,
	"skip_first_run_ui" : true, 
	"show_welcome_page" : true, 
	"import_search_engine" : true, 
	"import_history" : false, 
	"create_all_shortcuts" : false,   
	"do_not_launch_chrome" : true, 
	"make_chrome_default" : false 
  }, 
  "first_run_tabs" : [ 
	"welcome_page", 
	"new_tab_page" 
  ] 
}

Return to the Turbo Studio wizard. Click Next.

Click Next.

Create a folder named Chrome and Click OK.

Click Next.

Click Next.

Click Next.

Enter filename as chrome49 and then click Save.

Navigate to FileSystem and delete the Update folder found in the install directory.

Delete the Installer folder.

Navigate to Local Application Data (Low Integrity). Delete the Microsoft folder, if it exists.

Navigate to Application Data. Delete the Microsoft folder, if it exists.

Navigate to Registry then navigate to current user root > software. Delete the Microsoft folder.

Repeat this step for:

local machine root\SOFTWARE\Wow6432Node\Microsoft local machine root\SOFTWARE\Microsoft

Navigate to Registry then navigate to current user root > SOFTWARE and set the Google key's isolation setting to Full.

Repeat this for: local machine root\SOFTWARE\Wow6432Node\Google

Navigate to Settings->Process Configuration.

Check the checkboxes for Enable windows class isolation and Always launch child processes as current user.

Set the project type to component and then click Build.

Click Ok to finish and close Turbo Studio.

Copy the created Chrome foldeer that contains the svm file from your VM to a fileshare.

Read http://stage.turbo.net/docs/deploying for information about deploying the application.

Container Settings

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.

Output Settings

  • Startup File field is to set the path to the application which runs when starting your container. The Multiple button shows the Startup File manager dialog where additional settings can be specified.
  • Output File field is the name of the file that is created when your container image configuration is built.
  • Project Type dropdown allows you to set the type of output to generate. The following values are possible:
    • Layer (.svm) is a bare Turbo container image file that can be pushed to Turbo.net Hub, used in Turbo Server, imported into the Turbo.net Client Runtime environment, or used as a dependency in another project.
    • Portable Application (.exe) is a packaged executable file which contains the Turbo.net Client Runtime components and integrates with the Turbo.net Hub or an on-premise Turbo Server.
    • Standalone/ISV Application (.exe) is a standalone executable file with no dependence on the Turbo.net Client Runtime or Turbo.net Hub. This output type requires an Enterprise or ISV license for Turbo Studio.
  • Options button shows the Output Options dialog. This is used to enable diagnostics for .exe outputs or configure Portable Executable settings.
Application Properties

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

  • Splash Image can assign an image that is displayed while the container is loading. Startup images improve application branding and are useful when the application requires several seconds to initialize. The Transparency key enables the splash image to contain transparent regions which can improve the visual effectiveness of your splash. The splash image can be shown for a specific amount of time or until the first application window appears. The splash image can always be dismissed by clicking it with the mouse.
  • Shims and Scripts settings allow you to run custom code to configure or clean up environments before and after a container is executed. See Startup/Shutdown Scripts and Shims for more information.
  • Active Directory fields enable you to limit where the container can run based on queries to the Active Directory Domain Controller.
  • Platform allows you to specify the minimum required version of the Windows Operating System where the container will be allowed to run.
Process Configuration

  • Command line arguments will be passed to the startup file when the container is executed by default. You can override and specify a fixed set of command line arguments to pass to the startup executable. For example, you can specify Java virtual machine behavior.
  • Application sandbox location field specifies where the container's runtime sandbox will be stored during execution. This only applies to Standalone Executables and containers which are started using the Turbo Client Runtime will override this with its own behavior. This path can use the folder root tokens (ie. @DESKTOP@, @APPDATA@, etc) as well as the following metadata variables: @TITLE@, @PUBLISHER@, @VERSION@, @WEBSITE@, and @BUILDTIME@. The container build time is in a format similar to 2008.02.01T08.00. With the exception of the @BUILDTIME@ variable (which is set automatically), these variables are based on the values specified in the Properties tab of Settings panel.
  • Application stub cache location field specifies where the container stubexe files are stored. By default this is blank and they are stored in the sandbox. Stubexe files are generated .exe files that map to executables which are launched inside the container. In some environment, stubexe files require exclusions for security or anti-virus software so it can be convenient to store them in the same place to reduce the exposure and complexity of exception rules.
  • Application cache location allows you to specify a location to store temporary container files. By default thse are stored in the user's temp directory.
  • Working directory allows you to specify what the default working directory of startup files will be. Options include the directory that the startup file is in (default), the directory that the container was executed from (useful for tooling that might take relative paths to files as parameters), or a specific location.
  • Application type controls the Windows executable subsystem that is employed when starting the container. The default inherits this value from the startup file itself. This can be overridden to be Console or GUI if required.
  • Target architecture controls how wow64 redirection functions inside the virtual environment. If the configuration file was generated from a snapshot of an x86 machine then this should be set to x86. Otherwise this should be left as x64.
  • Environment variables allows to define custom environment variables that will be seen by applications inside the container. Options exist to control how variables are merged or overridden inside the container.
  • Virtual services allow Windows services to be defined inside the container. Windows services are specialized applications that run in the background. They are typically responsible for providing system services such as database services, network traffic handling, web request processing, and other server functionality. Many applications install and require specific services in order to function properly.
  • SVMs allow runtime dependencies to other SVM files to be defined. These dependencies can be required (ie. in cases where large executables are split between multiple files) or optional (ie. in cases where patch layers may be present).
  • Spawn child processes within virtualized environment sets the default behavior for how native executables (those that are not inside the container configuratino) are handled in the container. They can either be spawned inside the container and therefore be subject to the configuration of the container environment, or they can be spawned outside the container and therefore not have access to files or registry inside the container.
  • Spawn COM servers within virtualized environment specifies whether COM servers in the container are isolated from the native environment.
  • Child process exception list is a list of executable files that will be excluded from the default spawn behavior. This is useful if certain system processes need to be spawned outside the container while everything else is kept inside (ie. print spooler, etc).
  • Virtual environment is read-only makes it so that all write attempts to files inside the container will return access denied errors.
  • Delete sandbox on application shutdown makes it so that the sandbox folder is removed once the container stops. This may have performance implications as there are many files that can be cached in the sandbox between runs.
  • Shutdown process tree on root process exit make is so that all child processes of the startup file will automatically be killed when the startup file exists.
  • Compress payload makes it so that the files stored in the container at build time will be compressed. This can greatly reduce the size of the container image or executable file. This may have performance implications as files must be decompressed at runtime.
  • Enable startup executable optimization makes it so that if there is a single startup file, then it will be run directly rather than being spawned from the virtual machine boostrap executable. This will reduce the number of processes that are required to start the container.
  • Enable Turbo command line arguments makes it so that the container runtime parameters can be used (ie. /XEnable, /XShellEx, etc). See building standalone executables for more information.
  • Enable window class isolation enables isolation for window classes. Window classes are a fundamental set of attributes that are assigned to an application window in the Windows operating system. These are often used to detect the presence of applications that are already running.
  • Enhanced DEP compatibility for legacy applications hides DEP settings on modern operating systems which can allow older applications to run in a container. Be aware of your company security policies before enabling this setting.
  • Enhanced DRM compatibility allows some DRM software (ie. Armadillo variants) to function inside the container.
  • Trace process starts in debug output will display a message in the debug output stream whenever a process is started. The debug output stream can be viewed with dbgview.
  • Force read-share files makes it so that all files in the container are opened in a way that doesn't block other processes from opening for read.
  • Always launch child processes as current user makes it so that any processes spawn inside the container will inherit the current user's account privileges rather than any custom privileges that the parent process might assign.
  • Emulate elevated security privileges makes it so that the processes in the container think they are running as admin when they are not. Since processes are running in a sandbox, writes to secure locations won't require administrative access.
  • Isolate clipboard makes it so that the Windows clipboard (ie. copy/paste) is isolated within a container. Isolated clipboards cannot copy/paste information between container or with the native system. Only within the same container will this work.

Standalone Executables

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

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

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

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

Command Line Options

Standalone executables have many command line options to change settings at runtime. The following is a list of available options. Note that these are case sensitive and must be specified before any command line options to the application itself.

Setting Description
/XEnv=VariableName=Value Specifies additional environment variables. Multiple /XEnv arguments can add additional environment variables.
/XLayerPath=LayerPath Adds the given SVM into the virtual environment. Multiple /XLayerPath arguments can add additional virtual layers. Refer to 'Specify Additional SVMs for a Container' for more information.
/XSandboxPath=SandboxPath Specifies the path for the application sandbox.
/XShellEx=Command Specifies a shell execute command to launch from within the virtual application environment. This option overrides any startup files specified in the virtual application configuration. Only one /XShellEx argument can be specified.
/XShellExVerb=CommandVerb Specifies the verb to use in conjunction with the XShellEx command. The default verb is OPEN.
/XLogPath=LogPath Specifies the destination path for generated log files (only applies to executables running in diagnostic-mode). This path can include a custom file name pattern (ie. "/XLogPath=c:\logs\mylog*.log"). The output directory must exist for the logs to be written.
/XSpawnVmExceptions=ProcessExceptions Accepts a semi-colon delimited list of processes add to the child process exception list.
/XRegRoot=RegistryCacheRoot Specifies an override to the runtime-registry-cache portion of the sandbox.
/XEnable=Setting and /XDisable=Setting Enables or disables specific process configuration options. These options include: ChildProcAsUser DeleteSandbox DEPCompat Diagnostics DRMCompat ExeOptimization IndicateElevated IndicateVirtualization IsolateWindowClasses NotifyProcStarts ReadOnly ReadShare ShutdownProctree SpawnComServers SpawnVM SuppressCollisionCheck

See VM Settings for details on the available settings.

/XCollisionCheck=FALSE Disables detection of multiple apps attempting to use the same sandbox at the same time. This should only be used to support legacy behavior.

Specify Additional SVMs for a Container

When you have updates or patches you can use Turbo Studio to specify additional SVMs for applications. Studio provides two mechanisms to accomplish this. Both methods support path tokens (ie. @APPDIR@) and must specify the full path to SVM dependencies.

Using Studio

One mechanism is to specify the SVM dependencies in Turbo Studio.

The SVMs dependency editor can be accessed by clicking on 'Settings' button, then 'Process Configuration' tab, then 'SVMs' button.

The first field is the 'SVM Search Pattern' field. Here users can enter the complete path to where multiple SVMs are located using a wildcard. An example of using a wildcard in the search field is '@APPDIR@\patches*.svm'.

Multiple SVMs may be specified for the 'SVM Search Pattern' field in a semi-colon delimited list. SVMs specified first in the list will take precedence over SVMs specified later in the list. If multiple SVMs match a search pattern through the use of the '*' wildcard, the SVMs are applied in reverse-alphabetical priority (ie. items in patch_002.svm would have higher priority than items in patch_001.svm).

The second field allows required SVMs to be specified. Wildcard characters are not valid for this and a specific path must be used. If the file is not found during application launch, an error will be reported and the launch will be aborted.

Using Command Line

Another mechanism is by using the /XLayerPath= command line option. This parameter takes a path to additional SVMs to load. This can be useful for dynamically creating container environments depending on other user settings. These runtime settings augment any which are built into the SVM.

An example of a specified SVM path using full path:

# look for 'patches.svm' in the same directory as 'virtual-app.exe'
> virtual-app.exe /XLayerPath=@APPDIR@\patches.svm

# look for 'patches.svm' in a specific location on the local machine
> virtual-app.exe /XLayerPath=c:\path\to\patches.svm

# look for 'patches.svm' on a unc share
> virtual-app.exe /XLayerPath=\\server\dir\patches.svm

An example of specifying SVMs from multiple locations:

> virtual-app.exe /XLayerPath=@APPDIR@\patches.svm /XLayerPath=@APPDIR@\officepatches.svm

An example using a path with wildcard:

> virtual-app.exe /XLayerPath=c:\path\to\patches\*.svm

This performs a wildcard match finding any files that match the pattern, such as 'c:\path\to\patches\patch_001.svm'.

Note: SVMs that are discovered by wildcard are applied in reverse-alphabetical priority. For example, items in 'patch_002.svm' have higher priority than items in 'patch_001.svm'.

Large Executables

Where creating container packages, it is possible that the virtual .exe packages exceed 4GB in size. This is a problem because Windows has a hard limit of 4GB for .exe files and will not allow them to be executed and you will get an error message like this:

The solution for this is to split your package into two pieces, one small .exe and one large .svm. Then, at runtime, combine them using the above mentioned techniques (either with /XLayerPath or specifying required layers in Turbo Studio).

Follow these steps to convert your existing container image xappl:

  • Save a copy of your xappl as data.xappl.

  • Open data.xappl in Turbo Studio

    • Change the Project Type to Component

    • Change the Output File to data.svm

    • Save the file and build

  • Open your existing xappl in Turbo Studio

    • Add @APPDIR@\data.svm to the SVM Search Pattern and data.svm to the list of required layers

    • Remove everything from <Filesystem> and <Registry> nodes. If you have multiple layers, you can remove all layers other than the default layer. If your application is configured to inherit metadata and icons from the startup file, then you will need to keep the startup file .exe in the <Filesystem> node (including its full directory hierarchy).

    • Save the file and build
  • To deploy, place your .exe and your .svm in the same directory.

Startup File Triggers

A container package can define several startup files. These can all be activated on launch or they can be configured to only be launched given a specified trigger. This is useful for suite applications (like Microsoft Office) where most of the container package is shared.

In Turbo Studio, the startup file triggers are managed in the 'Startup Files' dialog.

In this example, an application package is defined with three startup files; word, excel, and access. Any startup files that don't have a specific trigger or have Auto Start enabled will be launched by default. Any startup file that has a trigger (but not 'auto start') will not be launched unless the trigger is specified. Multiple startup files can have the same trigger to enable grouped launching.

To launch a startup file by its trigger, specify its trigger as the first parameter to the container .exe:

# to launch word
> virtual-app.exe WORD

# to launch access
> virtual-app.exe ACCESS

# to launch excel
> virtual-app.exe EXCEL

# to launch excel as the default
> virtual-app.exe

To create an easy-to-access shortcut for a trigger, right-click on your packaged executable and select Create shortcut. Then, right-click on the newly created shortcut and append the trigger to the Target field. Change the shortcut name and icon to differentiate the application entry point that will be launched when the user runs the shortcut.

Building from the Command Line

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.

Command Usage Description
<path to XAPPL configuration file> /l <path to license file> [/o <path to output>] [/component] [/d] [/compressed] [/uncompressed] [/deletesandbox] [/v <version>] [/startupfile <virtual path to file>]

Builds the virtual application based on the application configuration file.

/l - Path the the license file. The license file needs to be stored in Unicode format.

/o - Path to the output file. This will override the setting in the XAPPL configuration file.

/component - Sets the Project Type to Component resulting in an SVM output rather than EXE output. 

/d - Enables the Generate diagnostic-mode executable setting.

/compressed - Enables the Compress payload setting.

/uncompressed - Disables the Compress payload setting.

/deletesandbox - Enables the Delete sandbox on application shutdown setting.

/v - Sets the Version of the output exe.

/startupfile - Sets the Startup File of the virtual application.

/before

/beforepath <path to where snapshot file is saved>

Performs a before snapshot and saves the snapshot to the specified folder.

/beforepath - Path to the where the snapshot file is saved.

/after

/beforepath <path to where snapshot is saved> /o <path to where XAPPL configuration file is saved>

Performs an after snapshot using the specified before snapshot path.

/beforepath - Path to the before snapshot file.

/o - Path to where the XAPPL configuration file is saved.

/import

/i <path to the configuration file to be imported> /o <path to where XAPPL configuration file is saved>

Import MSI, AXT, or ThinApp configurations.

/i - Path to the configuration file to import.

/o - Path to where the XAPPL configuration file is saved.

/sandboxmerge

/i <input-config> /o <output-config> <sandbox-path>

Merge configuration and sandbox.

/i - Path to source configuration file.

/o - Path to output merged configuration file.

sandbox-path - Path to sandbox.

/vmsettings

/i <input-file-xappl-exe-svm> [name]

Getting virtualization settings from the configurations file or application.

/i - Path to the configuration file (xappl, exe or svm).

name - Name of settings or empty for all settings.

/pathreplace

[/reg] [/revert] <path>

Replace path from native to virtual format.

/reg - Path is a register path instead of filesystem path.

/revert - Revert path from virtual to native format.

path - Path to replace.

/nologo

Switch for suppress printing copyrigth and logo information.


**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.

Note: If running XStudio displays the error, " is missing from the string table", it is because the XStudio application cannot be run while Turbo Studio is also running. Turbo Studio must be closed before running XStudio via the command line.

Startup/Shutdown Scripts and Shims

Turbo Studio allows for custom operations to be performed at the beginning and end of a container's life. This allows for application specific configuration steps to be performed before a container starts (ie. install a necessary driver) or clean up to be performed afterward.

Container Life Cycle

Containers are managed with a root parent process known as a "boostrap 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 container bootstrap process is started but before the startup files are started. 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 container bootstrap process is closed.

Note that because of the nature of mulitple possible bootstrap processes for standalone executables, multiple executions of the shims and scripts may occur if multiple invocations are possible. Therefore they must be written handle that case.

Scripts

For simple tasks, a .bat or .cmd script can be configured.

Put the script in the container file system (a full isolated folder in @SYSDRIVE@ such as "scripts" is recommended). Specify the full path to the script in studio. Note that the untokenized form of the path must be used here ("c:\scripts\init.cmd" rather than "@SYSDRIVE@\scripts\init.cmd").

An example startup script might look like this:

    @ECHO Initializing environment
    if exist C:\workspace\first goto Skip
    
    :Create-Workspace
    @ECHO Preparing Workspace
    mkdir C:\workspace\first
    echo print("Hello World!") > C:\workspace\first\helloworld.py
    goto Done
    
    :Skip
    @ECHO Workspace already created, skipping step
    
    :Done
    @ECHO Done.    
    exit

A common use of startup scripts is to install some required component (driver, etc) to the native system if not already present. Such installers will require admin privileges so will require UAC elevation. Below is one way this can be accomplished using a runtime generated VBS script:

    # create vbs script to ShellExecute a command with "runas" verb to show the UAC prompt if required
    echo Set UAC = CreateObject^("Shell.Application"^) > "%temp%\elevate.vbs"
    echo UAC.ShellExecute "cmd.exe", "/c ""c:\path\to\installer.exe", "", "runas", 1 >> "%temp%\elevate.vbs"
    
    # execute the vbs script and wait until it completes
    start /b /wait >nul cscript /nologo "%temp%\elevate.vbs" 2>&1
    
    # clean up
    del "%temp%\elevate.vbs"

To troubleshoot script issues, set the "__DEBUGINITSCRIPTSHIM" environment variable to "true". This will show the command window that is executing the script so you can see output and any generated errors.

Shims

For complex tasks, a DLL can be written to be executed. DLLs can be written in any programming language that supports them but do note any framework requirements must be configured inside the container.

The shim must conform to Turbo Studio interface in order to be loaded properly. Startup shims must be compiled with an exported OnInitialize function. Shutdown shims must be compiled with an exported OnShutdown function. The same DLL can be used for both if both functions are exported.

Shim function signatures: typedef BOOL (__stdcall *FnOnInitialize) (LPCWSTR pwcsInitializationToken); typedef void (__stdcall *FnOnShutdown)(LPCWSTR pwcsShutdownToken);

The return value of the startup shim indicates to the bootstrap process whether it should proceed with execution of the container.

The functions are acquired by the virtual machine with ::LoadLibrary and ::GetProcAddress calls.

    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.

MSI

You can build your standalone executable into an MSI that is ready to deploy in your environment. The MSI can be configured to include applicaion shortcuts and file associations.

MSI Settings

The following table includes descriptions of the settings that you can use for MSI outputs.

Setting Description
Output location Name and location of the MSI file output.
Product Info Meta data that will go into Add/Remove Programs when the application is installed.
  • Product Name
  • Product Version
  • Company Name
Installation Parameters Specifies where to install the application and if it will be installed for all users or in the current user profile.
Shortcuts List of Start Menu and Desktop shortcuts that are created when the MSI is installed.
ProgIds List of ProgIds that are created on the host system when the MSI is installed.
Extensions List of file extensions that are configured on the host system when the MSI is installed.

MSI Example

Here we will show the steps required to configure a simple container to be deployed via MSI with shortcuts and file associations.

Start by creating an empty container configuration file. Add "c:\windows\syswow64\notepad.exe" from your machine to the @SYSWOW64@ directory in the Filesystem panel. Set the startup file to @SYSWOW64@\notepad.exe, set the project type to Standalone/ISV Application, and set the output file location. Save the configuration file.

Go to the Settings panel. By default the metadata will be inherited automatically from the startup file.

In our case, we will want to change some of these values to something more appropriate. Unselect the Inherit properties checkbox. Set the Product Title field to "Notepad Container".

Note that the custom value of the Product Title field is shown in the Open With... menu in Windows when file associations are configured. If you choose to inherit metadata then the value shown may not be what you want. To override what is displayed in the Open With... menu while still inheriting the other values, click the Custom Metadata... button and add the FileDescription field.

Go to the Install panel. Set the location where the MSI output will be written. Assign Product Info values. These values affect where the container files will be deployed on the machine and will show up in the uninstall entry on the machine where the MSI is installed.

If the container is to be installed for all users on the machine, then select the Install application for All Users checkbox. Note that this will require administrative privileges to install.

You can control how different versions of the same container MSI are handled. They can either be allowed to run versions of the container side-by-side or upgrade existing versions. Note that this is controlled by the Product Version field on this panel and not by the container version metadata on the Settings panel. Also note that for this to work properly, the MSI version must be changed inside Turbo Studio and not updated in an external editor.

Now we will add a shortcut that gets created on the desktop. Click on Desktop in the Shortcuts tree. Click Add Shortcut.... Set the name of the shortcut as it will appear on the desktop, in our example we will use "Notepad Container". The Target dropdown list will show all available startup files that can be executed by the shortcut. If there is something that is not included here, click the Edit List... button to add a new startup file for it. Select the icon to use for the shortcut and press ok.

Next we will add a file assocation to allow this container to be easily used to open .txt files from the Windows shell. Click on ProgIds and then Add ProgId.... A ProgId is a programatic identifier that the Windows Shell uses to associate an application with a file type. We will add one here for textfile which is the ProgId for all text file types. You can also assign an icon which will be used by associated files.

Next we will define actions that are available for the file type from the Windows context menu (when you right-click on a file). Common verbs include "open", "edit", or "print" but you can define any that you wish. Click on the newly added textfile ProgId and click the Add Verb... button. Set the verb name to "open" and check the Default box. Default verbs will be used when a user double-click the file. Set the Command field to what the user will see in the context menu.

If you created your container from a snapshot or otherwise defined the file association settings in the virtual registry, then you can select the Inherit checkbox to use that configuration. Otherwise, set the Target to a startup file and specify the arguments. In most cases you will want to pass the selected file as a parameter to the application so that it can be opened. Use %1 as a placeholder for the selected file path. Make note to properly quote this value as paths can contain spaces that may be incorrectly parsed by your application.

The final step is to define a file extension that will use this new ProgId. Click on Extensions and then on Add Extension.... Set the Extension to ".txt" and ProgId to "textfile". MIME Type is optional.

Now you're done. Save the configuration file and build the container. When the build completes, go to the Install panel and click the Build MSI button to produce the MSI package for the container. Copy the MSI to a test machine and run it.

After installation is complete, you will notice that the shortcut that we configured is now on the desktop.

You will notice, however, that the file icon is the default and not what we assigned. This is because Windows 10 doesn't allow file associations to be changed except by direct user input to prevent malware attacks. Since there were changes to the system file associations, Windows will prompt you the next time the file type is opened to confirm which application should be used. You will notice that "Notepad Container" is now in the list.

Select Notepad Container from the list and check Always use this app to open .txt files. Press OK. Now the file will be permenantly linked to your container. You will notice also that the icon is now updated to that of the ProgId icon that we selected earlier. In addition, you will now see all your defined verbs in the file's context menu.

In the Windows Programs and Features panel, you will find an entry for our Notepad Container deployment. Uninstalling it from here will remove all shortcuts and file associations that were added.

Troubleshooting

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.

Turbo.net Professional Services

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.

Diagnostic Mode

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.

There are three ways to enable diagnostic mode. With all methods, the log files will be written to the same directory as the container .exe unless the /XLogPath command line parameter is used.

The first way is to create a diagnostic mode build of your container. This is done in studio by selecting the 'Generate diagnostic mode executable' build option.

The second way is using a command line parameter. This allows access to diagnostic information without rebuilding your container package.

> virtual-app.exe /XEnable=Diagnostics

The third way is using an environment variable. This allows access to diagnostic information when the command line options are not easily modified (ie. service containers, container launched from non-container, etc).

> SET __VMDIAGNOSTICS=true
> virtual-app.exe

NOTE: Can also specify this as a global environment variable.

Analyzing Logs

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

Virtual machine logs show every system function call that comes from the process.

An example of a log 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.

Virtual Machine Analysis Strategies

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.

Network Logs

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.

Viewing Container Environment

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:

> 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:

> 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.

Common Errors

Turbo Virtual Machine 0x0003

This error indicates that there is a problem accessing the 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.

Unable to load a required virtual machine component

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.

Questions? Projects? Talk to us.