VM Configuration Dialog Box

Aug 14, 2017

The Virtual Machine Configuration dialog box is a feature for advanced users to edit virtual machine configurations for use with Install Capture or Forward Path Tasks. Open the Configure Virtual Machine dialog box by clicking Advanced in Install Capture Settings.

Note: Unless you have advanced knowledge of this area, it is recommended that you edit virtual machine configurations by using the Virtual Machine Configuration wizard.

The Configure Virtual Machine dialog box has a number of tabs:

  • Virtual Machine Settings
  • Remote Admin
  • Replaceables
  • Optional Configuration
  • Provider Plugin (only for some providers)

These are documented under separate headings below. The options vary according to the provider you select on the first tab.

Virtual Machine Settings tab

Use the Virtual Machine Settings tab in the Virtual Machine Configuration dialog box to view and define basic settings for the virtual machine configuration.

Name. This identifies the virtual machine configuration. The name must be unique within the list of configurations.

Description. Provide an informative description to help identify the purpose of the configuration in the future.

Provider. This shows the virtual machine technology that is in use for this configuration. The options in the drop-down list correspond to the supported technologies listed in Install Capture. Citrix recommends that you do not change the provider here. If you want to change the provider, it is better to create a new configuration for that provider in the normal way.

Output Location. The location in which the Install Capture output (MSI files, screen shots of the installation, etc.) is stored. How this folder must be configured depends on whether the Stream VM Output check box is selected:

  • When the Stream VM Output check box is selected, this is a folder on the host machine or a network share. The virtual machine does not require access to this folder, but AppDNA does.
  • When the Stream VM Output check box is cleared, this must be a location to which both the host machine and the virtual machine have read and write access. The location can be a mapped network drive or a full UNC path, such as \\AppDNAMachine\AppDNAOutput.

Note: Sometimes the capture output files may require a deep folder structure that can exceed the maximum Windows path length of 260 characters. To overcome this limitation, you can specify a UNC path in the form \\?\UNC\server\share.

Stream VM Output. Select this option if you want Install Capture to stream the output from the virtual machine back to a folder on the host machine or a network share after the capture is complete. This is easier to set up than writing the output to a folder that both the virtual machine and AppDNA can access. However, it is slower. Clear this check box if you want Install Capture to copy the results from the virtual machine to a folder on the host machine or a network share to which both AppDNA and the virtual machine have read and write access.

VM Output Staging Location. When the Stream VM Output check box is selected, this specifies the folder on the virtual machine in which Install Capture temporarily stores the output before streaming it back to the Output Location folder on the host machine or network share. You cannot use the \\?\UNC\ long path notation for this setting.

VM Identifier (Name). (Not relevant for VM Provider Plugins.) The unique name given to the virtual machine when it was created. For a VMware Workstation virtual machine, this is the full path to the VMX file – for example, C:\Virtual Machines\VVMXPSP3-01\VVMXPSP3-01.vmx.

Action Timeout. (Not relevant for VM Provider Plugins.) Specifies the time-out period in seconds for the control of the virtual machine, such as locating it, starting it up and reverting it to a snapshot. The time these actions take depends on the virtualization technology and the size of the virtual machine images. The default is 1,200 seconds.

“Installation Needs Input” Timeout. The period in seconds for which Install Capture should wait for an installation (or any other execution profile command) to complete. When a command does not complete within this time, AppDNA displays a message indicating that you should look at the running virtual machine to see if input is needed. This is useful when trying to do many Install Captures with silent install commands, and one unexpectedly waits for input. The default is 1,200 seconds.

“Abort Installation” Timeout. The period in seconds that Install Capture should wait when there is no activity before ending an installation and continuing to the next one. The default is 2,400 seconds (40 minutes). This is deliberately a long period because some large applications take a considerable amount of time to install. If you are using auto-clicker and leaving batches of captures to run overnight (for example), you may want to reduce this time-out period to speed up progress through the batch if some captures fail. However, this may cause the capture of some large applications to fail. You may therefore want to reduce the period to 1,200 seconds (for example) if you are using auto-clicker and set it back to the default value before doing any manual captures.

Base Snapshot Path. (VMware Workstation only.) This defines the snapshot within the virtual machine that is to be used as the base state of the virtual machine for each Install Capture process. In VMware Workstation, snapshots can form a tree and you specify the path to the snapshot you want to use like this: Snapshot1\InstallCaptureBaselineSnapshot.

Remote Admin tab

Use the Remote Admin tab in the Virtual Machine Configuration dialog box to define how AppDNA communicates with Remote Admin, which is an AppDNA agent that runs within the virtual machine.

VM Guest Machine Name. The IP address or machine name of the virtual machine. AppDNA uses this to make a network connection with the guest OS. Do not include backslashes (\).

VM Control using. The protocol that AppDNA uses to connect with Remote Admin within the virtual machine. The default is TCP. The Named Pipe protocol is deprecated and is supported only for configurations created in previous versions of AppDNA.

Named Pipe Username. The user name for the named pipe, when the Named Pipe protocol is in use. Specify the fully qualified account name of a user. This should have the form VM_MACHINE_NAME\USERNAME for a local administrator account and DOMAIN_NAME\USERNAME for a domain account that can log into the virtual machine. If you leave this value blank, set the local security policy on the virtual machine to allow anonymous access for named pipes.

Named Pipe Password. The password for the named pipe, when the Named Pipe protocol is in use and a named pipe user account is specified above.

TCP Port. The port that Remote Admin listens on. The default is 54593. You can change the port by running Remote Admin (remoteadmin.exe) with the parameter -tcp_port=<port>, where <port> is the new port. For information about changing the port that Remote Admin listens on, see Changing the Remote Admin Port.

Troubleshoot Errors. Select this check box if you want AppDNA to open a troubleshooting user interface if particular errors are encountered while performing an Install Capture. You can use the troubleshooting user interface to connect to Remote Admin, run commands, and perform other troubleshooting steps within the virtual machine. Then when you perform the “Finished” action, AppDNA ends the Install Capture, closes the troubleshooting interface, and moves on to the next Install Capture, if there is one. Errors that relate to connecting to Remote Admin and running the Install Capture commands trigger the troubleshooting interface. Clear this check box for the default behavior.

Replaceables tab

Use the Replaceables tab in the Virtual Machine Configuration dialog box to define replaceable values to be used in the execution profiles that are run on this virtual machine configuration. However, the replaceable values you define here are overridden if values are explicitly defined for those replaceables in the execution profile itself or in the Quick Edit Parameter box in the Import Applications screen.

Replaceables are placeholders that are replaced by a value provided at run time. The syntax for including a replaceable in the execution profile is: $(replaceable_name), where replaceable_name is the name of the replaceable.

The AppToolsFolder replaceable is used to specify the location of the tools installed on the virtual machine by the Citrix AppDNA VM Configuration MSI. By default, these are installed to C:\Program Files\Citrix\AppDNA\VM Configuration. The default value for the AppToolsFolder replaceable uses the %APPDNAVMCONFIG% environment variable, which is created by the AppDNA VM Configuration MSI and stores the actual installed location of the tools.

To define a replaceable value for this virtual machine configuration:

  • If the replaceable whose value you want to change for this virtual machine is in the list, select it and click Edit. This opens the Edit Text dialog box, where you can enter or paste the new value.
  • If the replaceable whose value you want to define does not appear in the list, click New. This opens the Edit Replaceable dialog box, where you can enter the new replaceable and its value.

There are a number of replaceables that are used internally in the execution profiles. AppDNA automatically sets the values of these replaceables and you do not need to do this manually. For a full list of these, see Edit an execution profile.

Optional Configuration tab

Use the Optional Configuration tab in the Virtual Machine Configuration dialog box to view and define Install Capture settings for the virtual machine configuration.

VM Cleanup Action. Defines how Install Capture leaves the virtual machine after completing an Install Capture process. The option you select here affects the capture times. The options are: Suspend, Leave Running and Power Off. Note that Install Capture always reverts the virtual machine to its original state before each capture, regardless which option you select here.

Provider Plugin tab

Use the Provider Plugin tab in the Virtual Machine Configuration dialog box to view and define settings for providers that are based on a plugin, such as the XenServer and vSphere providers. This tab appears only for plugin-based providers.

Provider Assembly Path. The path to the VM provider plugin’s assembly.

Provider Code Type. The class in the VM provider plugin’s assembly that interacts with the virtual machine technology.

Use Remoting. Some VM provider plugins provide support for remoting even when the underlying technology does not. Select this check box to tell the provider to communicate with the remote provider implementation. Note that the listener on the remote machine must be running and listening.

Remote Provider Machine Address. The hostname or IP address of the machine hosting the remote provider implementation. This is relevant only when the Use Remoting check box is selected.

TCP Port. The TCP port that the remote provider implementation is listening on. This is relevant only when the Use Remoting check box is selected.

Configuration Settings. Use this section to define any other settings that are required. These settings have the form of a name and value pair.

  • To define a new configuration setting, click New. This opens the Edit Value dialog box. Enter the name of the setting and its value and then click OK.
  • To edit an existing configuration setting, select it in the list and click Edit. This opens the Edit Value dialog box, where you can edit the existing value.

The Hyper-V plugin settings are as follows:

  • hostname - The IP address or DNS name of the Hyper-V host server.
  • username - The user name of the account that AppDNA uses to access Hyper-V. This is stored in an encrypted form if you entered it through the Virtual Machine Configuration Wizard. If you enter the user name here, it is not encrypted.
  • password - The password of the account that AppDNA uses to access Hyper-V. This is stored in an encrypted form if you entered it through the Virtual Machine Configuration wizard. If you enter the password here, it is not encrypted.
  • virtualmachine - The name of the Hyper-V virtual machine to be used for Install Capture.
  • snapshot - The internal identifier of the snapshot to be used for Install Capture.
  • vmaddress - The machine or DNS name or the IP address of the guest OS.
  • vmstate - The option chosen in the Hyper-V Virtual Machine State step in the Virtual Machine Configuration wizard.

The vSphere plugin settings are as follows:

  • hostname - The IP address or DNS name of the vSphere host server.
  • username - The user name of the account that AppDNA uses to access vSphere. This is stored in an encrypted form if you entered it through the Virtual Machine Configuration Wizard. If you enter the user name here, it is not encrypted.
  • password - The password of the account that AppDNA uses to access vSphere. This is stored in an encrypted form if you entered it through the Virtual Machine Configuration wizard. If you enter the password here, it is not encrypted.
  • virtualmachine - The name of the vSphere virtual machine to be used for Install Capture.
  • snapshot - The name of the snapshot to be used for Install Capture.
  • vmstate - The option chosen in the vSphere Virtual Machine State step in the Virtual Machine Configuration wizard.

The XenServer plugin settings are as follows:

  • hostname - The IP address or DNS name of the XenServer host server.
  • username - The user name of the account that AppDNA uses to access the XenServer. This is stored in an encrypted form if you entered it through the Virtual Machine Configuration Wizard. If you enter the user name here, it is not encrypted.
  • password - The password of the account that AppDNA uses to access the XenServer. This is stored in an encrypted form if you entered it through the Virtual Machine Configuration wizard. If you enter the password here, it is not encrypted.
  • virtualmachine - The name of the XenServer virtual machine to be used for Install Capture.
  • vmstate - The option chosen in the XenServer Virtual Machine State step in the Virtual Machine Configuration wizard.