***Beginning with Agent 2.3, the location of the installation and configuration files for the Agent has been moved. The new location is: C:\ProgramData\WorkspotAgent.” Please use this location when reviewing the documentation and implementing the Agent features. ***
The Workspot Agent [Agent] is software that is installed on VDI and RD Pool Templates. The Agent performs the following tasks:
- enables provisioned virtual machines [VMs] to register with Workspot Control [Control].
- communicates status, session information, and performance data to Control.
- during Pool/VM provisioning, domain-joins VMs to the domain controller.
- auto-updates VMs in persistent VDI Pools and RD Pools.
(*) For VMs in non-persistent Pools, Workspot recommends upgrading to the latest Agent using the process described in this article: Control - Image Refresh of Provisioned Desktops.
Sections in this Article
- Preparing template for Workspot Control provisioning
- Sysprep versus Quickprep
- Special Characters
(*) NOTE: Before installing the Agent, shut down the template VM. Run the clone functionality on the template VM (save the original) and then boot into the new clone template. The Agent registers the template with Control using the MAC address of the VM. Once the template is registered and sysprep, no further changes may be made. If additional changes or updates are required, use the original template VM and clone again for use (saving the original again for future changes). Thus, the process is: Original template > Clone template > Install Agent > Use this template for cloning > when updating or modifying, use the original template for this process again.
Download the Workspot Agent installer from:
As an administrator, run the Workspot Agent installer and use Workspot Control (administrator role credentials required) to register the template.
1. Create a service admin account that can join machines to the domain. Workspot recommends creating a service account that only have permissions for specific OUs in Active Directory where provisioned machines will reside.
2. Copy sample Workspot XML config file provided after the install of the Workspot Agent. Sample file is located in the install folder of the Workspot Agent: c:\Program Files\Workspot Agent\
3. Modify the XML config file with service admin account credentials along with OU info.
(*) NOTE: If password or any other parameters contains special characters, it must be escaped (i.e. OU=Workspot&Co is OU=Workspot&Co). Review table in appendix of this document.
<?xml version="1.0" encoding="utf-8"?>
<component name="Workspot-DomainJoin" language="neutral">
<component name="Workspot-Shell-Setup" language="neutral">
Sample using "UseSecureCredentials":
If credentials are specified using <Password></Password> then use 0 or leave <UseSecureCredentials></UseSecureCredentials> empty. Expected Values: [1 | 0 | empty].
Credentials can be specified using command line instead of clear text in the WorkspotConfig.xml. If you do so, use 1 for UseSecureCredentials and set the AdminDomain, AdminUsername, and Password fields empty:
To setup secure domain join credentials:
- Start Administrative Command Prompt.
- Go to the Agent Install Location. (c:\Program Files\WorkspotAgent\)
- Run "secure_credentials.bat --set domain\admin password"
(*) Make sure special characters are escaped, refer to http://www.robvanderwoude.com/escapechars.php.
With this process, the credentials are stored directly in Windows Credentials Manager instead of being stored in Workspot secured Vault. These credentials are used for Domain Join when clones are created in a VDI Pool or RD Pool.
NOTE: This command can be called multiple times. When run, it overwrites previous credentials if already set. Admin can verify the credentials are properly set by using this test.
- secure_credentials.bat --test <file share>
The credentials last set will be used to connect to given file share. The log file will show the status of the connection. If the connection fails because of wrong name/password reason, see c:\windows\system32\config\systemprofile\appdata\Local\WorkspotAgent\Log. If Admin forgets to set the Secured Credentials, VMs will come up and go into an Error State. The Error in Control is Domain join Read Credentials failure.
Samples for adding Users/Groups to Local Groups:
If this feature is not required, omit <component name="Workspot-Shell-Setup" language="neutral">, or leave the sample empty nodes as they are.
To add domain users/groups to existing Local groups:
If mentioned local group does not exist, it will be created and then user added to it:
To add local User/Group to Local Group, leave <Domain> empty:
<LocalGroup>Remote Desktop Users</LocalGroup>
(*) NOTE: Make sure to choose groups which are not touched by GPO, otherwise changes made by WorkspotConfig.xml could be overwritten by GPO.
4. Copy Workspot XML config file to C:\windows\system32\config\systemprofile\appdata\local\workspot agent\config.
(*) NOTE: The Workspot XML config file will be deleted during provisioning.
Sysprep versus Quickprep
Workspot VDI 2.0 Pools and RD Pools can be either Sysprep or Quickprep.
|Computer name change||YES||YES|
|Generate new SID||YES||NO|
|Customization outside template||YES||NO|
For Quickprep: Shutdown the template VM. Template is now ready for Workspot Control provisioning.
1. Create a sysprep unattend.xml answer file for Windows customization and save it in a location like C:\temp.
The following Windows 10 Sample file:
- Skips welcome screens.
- Creates a local administrator account.
(*) NOTE: You can add parameters as needed (such as time zone, language, etc.).
2. Create SetupComplete.cmd to delete unattended.xml answer file after sysprep. Copy the SetupComplete.cmd to c:\windows\setup\scripts\. Unattend.xml may contain sensitive information.
3. Sysprep the VM with the following command:
C:\Windows\System32\sysprep\sysprep.exe /shutdown /oobe /generalize /unattend:c:\temp\unattend.xml
(*) NOTE: This command will sysprep the VM and then shut down the VM. After the VM is powered on, it will go through the sysprep process.
The template is now ready for Workspot Control provisioning.
- For installation and template registration issues, see the logs file in: C:\Program Files\WorkspotAgent\InstallLog
- For runtime issues, see the log file in: C:\Windows\System32\config\systemprofile\AppData\Local\WorkspotAgent\Log
Special characters in WorkspotConfig.xml
|Original Character||Replacement character|