Workspot Agent 2.4 Installation for Templates

Robert Plamondon -

Overview

The Workspot Agent is software that is installed on templates for VDI (desktop) Pools and RD Pools. The Agent performs the following tasks:

  • Enables provisioned virtual machines (such as Workspot desktops) to register with Workspot 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.)

Installation

Create a New Workspot Template

The Workspot Template is built from a golden master template that does not yet have the Workspot Agent installed.

Before installing the Agent, create a new template from a golden master template:

1. Shut down the template VM. (Sign into the template VM and use the Windows Shutdown feature.)

2. Run the clone functionality in “Setup > Subscriptions > subscription_name > old_template_name > Actions > Clone” on the old template.

 

3. The new template will boot. The rest of these steps are performed on the new template.

4. Log into the new template VM as a local administrator, using an account included in your base template.

  • For example, use a Remote Desktop connection from another desktop on the same network.
  • Use the address shown by expanding the details on the new template at “Setup > Subscriptions > subscription_name > new_template_name.”

 

Download and Run the Workspot Agent Installer

1. On the new template VM, download the Workspot Agent installer from:
http://download.workspot.com/WorkspotAgentSetup64.exe

2. As an administrator, run the Workspot Agent installer and use Workspot Control (administrator role credentials required) to register the template.

  • On the "Welcome" screen, verify that the release version of the Workspot Agent is what you expected.
  • When prompted to enter your Workspot Control Administrator credentials, this refers to an account on https://control.workspot.com with Administrator privileges.

 agent-2.4-installer-1.png

 agent-2.4-installer-2.png

 agent-2.4-installer-3.png

 

 

XML Template Configuration

When Workspot creates a new desktop from the template, the Workspot Agent performs a number of tasks:

  • It joins the domain you specify (unless you tell it not to).
  • It optionally reboots the desktop after joining the domain.
  • It executes the wsRunOnce.cmd command script after joining the domain and registering the new VM with Workspot Control. You can use this to:
    • Install GPU drivers,
    • Activate Windows via a MAK key,
    • Activate application licenses,
    • Install additional software,
    • Modify registry keys,
    • And so on.
  • If you specified that the VM is not to be joined, the wsRunOnce.cmd script is not executed.
  • And, of course, the Workspot Agent contacts Workspot Control to announce its successful deployment. After that is sends status information, auto-updates itself, and so on.

Creating a Workspot Service Admin Account

When you create a new Workspot desktop, you typically need it to join your domain. For this, you should create a service admin account in Active Directory with permission to join machines to the domain.

Workspot recommends creating a service account with permissions only for the specific organization units (OUs) in Active Directory related to your Workspot deployment.

Not Joining a Domain. Starting with Workspot Agent release 2.4, the domain-joining step is optional, controlled by the DoNotJoinDomain XML option. You can create templates that either do or don’t join the desktops to your domain. If you do not join a domain, wsRunOnce.cmd is not executed. This is often used when third-party tools perform the domain-joining task rather than the Workspot Agent.

Customize the WorkspotConfig.xml File

The Workspot Agent directory in “C:\Program Files\WorkspotAgent” contains the files you will use to customize your template.

The master configuration file is WorkspotConfig.xml.

 

  1. Make a backup copy of the Workspot XML config file provided after the install of the Workspot Agent.

    C:\Program Files\WorkspotAgent\WorkspotConfig.xml
  1. Modify the XML config with domain and user information.

    Note: If password or any other parameters contains special characters, it must be escaped (i.e., “OU=Workspot&Co is OU=Workspot&Co”).

Original Character

Replacement
Character

"

"

'

'

<

>

&

&

 

  1. Modify the XML config with additional information, as required.
  2. Copy the WorkspotConfig.xml to C:\ProgramData\WorkspotAgent\Config.

Note: Make sure to choose groups which are not touched by GPO, otherwise changes made by WorkspotConfig.xml could be overwritten by GPO.  

Note: The Workspot XML config file will be deleted during provisioning.

Listing of WorkspotConfig.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- Check this zendesk link for details : https://workspot.zendesk.com/hc/en-us/articles/115002951363 -->

<WorkspotConfig>

<component name="Workspot-DomainJoin" language="neutral">
  <Identification>
    <Credentials>
      <UseSecureCredentials></UseSecureCredentials>
      <AdminDomain></AdminDomain>
      <AdminUserName></AdminUserName>
      <Password></Password>
    </Credentials>
    <JoinDomain></JoinDomain>
    <MachineObjectOU></MachineObjectOU>
  </Identification>
  <DoNotJoinDomain></DoNotJoinDomain>
</component>

<component name="Workspot-Shell-Setup" language="neutral">
    <DomainAccountList>
    <DomainAccount>
        <Domain></Domain>
        <DomainAccountName></DomainAccountName>
        <LocalGroup></LocalGroup>
    </DomainAccount>
    <DomainAccount>
        <Domain></Domain>
        <DomainAccountName></DomainAccountName>
        <LocalGroup></LocalGroup>
    </DomainAccount>
    </DomainAccountList>
</component>

<component name="Workspot-Script-Setup" language="neutral">
  <SetupCompleteScript>
    <NeedsReboot></NeedsReboot>
    <StopOnFailure></StopOnFailure>
  </SetupCompleteScript>
  <RunOnceScript>
    <NeedsReboot></NeedsReboot>
    <StopOnFailure></StopOnFailure>
  </RunOnceScript>
</component>
</WorkspotConfig>

 

Example Using "UseSecureCredentials"

The credentials used by the cloned desktops to join the domain can be specified in WorkspotConfig.xml or on the command line of the secure_credentials.bat script.

Workspot recommends using secure_credentials.bat instead of the XML Password option.

If credentials are specified using “<Password></Password>” then use 0 or leave “<UseSecureCredentials></UseSecureCredentials>” empty. Expected Values: [1 | 0 | empty].

For example, “<UseSecureCredentials>0</UseSecureCredentials>”

Credentials can be specified using command line instead of clear text in the WorkspotConfig.xml (<Password></Password>), use 1.

For example, “<UseSecureCredentials>1</UseSecureCredentials>”

To set these secure credentials:

  • Go to the Agent Install Location.
  • Find the file secure_credentials.bat.
  • Run "secure_credentials.bat --set domain\admin password"
    • e.g. secure_credentials.bat --set corp.contoso.com\workspotadmin SeCur3p@ssw0rd! 
    • Make sure special characters are escaped, refer to http://www.robvanderwoude.com/escapechars.php.
    • This internally calls stop and start on service passing in these parameters to service. The credentials are stored directly in Windows Credentials Manager instead of being stored in Workspot secured Vault. These credentials are used for Domain Join in Cloned VM.
    • 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:\ProgramData\WorkspotAgent\Log. If Admin forgets to set the Secured Credentials, VMs will come up and go into an Error State, shown in Workspot Control as a Domain join Read Credentials failure.

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

  <DomainAccount> 
    <Domain>domain.com</Domain>
    <DomainAccountName>Domain Users</DomainAccountName>
    <LocalGroup>Print Operators</LocalGroup>
  </DomainAccount>

If mentioned local group does not exist, it will be created and then user added to it:

  <DomainAccount> 
    <Domain>domain.com</Domain>
    <DomainAccountName>MyAccountName</DomainAccountName>
    <LocalGroup>MyOwnGroup2</LocalGroup>
  </DomainAccount>

To add local User/Group to Local Group, leave <Domain> empty:

  <DomainAccount> 
    <Domain></Domain>
    <DomainAccountName>localAdmin</DomainAccountName>
    <LocalGroup>Remote Desktop Users</LocalGroup>
  </DomainAccount>

Workspot Agent Scripts

The Workspot Agent supports two scripts:

  • WsRunOnce.cmd. Run after the new VM is rebooted after it has joined the domain successfully.
  • WsSetupComplete.cmd. Run immediately after cloning is complete and the VM is registered with Workspot Control. This occurs before the domain is joined.

These scripts can be used to:

  • Install GPU drivers,
  • Activate Windows via a MAK key,
  • Activate application licenses,
  • Install additional software,
  • Modify registry keys,
  • And so on.

File Locations

The Workspot Agent looks for these scripts in %programdata%\WorkspotAgent\Config\

The echo commands from these .cmd files are written to .log files in c:\ProgramData\WorkspotAgent\Scriptlogs\scriptname.cmd.log

Scripts and the WorkspotConfig.xml File

The two .cmd scripts are controlled by this section of the WorkspotConfig.xml file:

<component name="Workspot-Script-Setup" language="neutral">
  <SetupCompleteScript>
    <NeedsReboot></NeedsReboot>
    <StopOnFailure></StopOnFailure>
  </SetupCompleteScript>
  <RunOnceScript>
    <NeedsReboot></NeedsReboot>
    <StopOnFailure></StopOnFailure>
  </RunOnceScript>
</component>


To enable a feature, such as StopOnFailure, set it to 1:

<StopOnFailure>1</StopOnFailure>

To disable a feature, set it to zero or leave it blank (default).

Script Programming Guidelines

  • Full paths must be specified for any .exe or .msi files invoked by the script. UNC paths (\\hostname\sharename\...) are not allowed.
  • Everything executed by WsSetupComplete.cmd must be silent, unattended, or automated. That is, it must not require user input. If something waits for user input, the script will fail and the VM will not ready for use.
  • For security, each script should delete itself and any one-time-use scripts it calls.
  • Reminders:
    • The wsSetupComplete.cmd script is called before the VM is joined to the domain, so no domain resources are available.
    • The User context is SYSTEM, so the “current user” (HKCU) is not viable for modification.
    • UNC network paths are not usable.
  • If something needs to be run under specific local user/admin account, use the PowerShell credential store
  • Do not shutdown or restart a VM during the execution of one of these scripts, except by the <NeedsReboot> option. Any other restarts will interfere with the normal Agent setup/registration process

Programmed Restarts

The VM can be restarted in a controlled way with the NeedsReboot option. By default, no restart is done.

Note: Do not restart the VM from within a script.

To restart the VM after the WsSetupComplete.cmd script and before the domain join, specify NeedsReboot in WorkspotConfig.xml as shown:

<component name="Workspot-Script-Setup" language="neutral">
  <SetupCompleteScript>
    <NeedsReboot>1</NeedsReboot>
    <StopOnFailure></StopOnFailure>
  </SetupCompleteScript>

 

To restart the VM after the WsRunOnce.cmd script, specify NeedsReboot as shown:

<component name="Workspot-Script-Setup" language="neutral">
  <RunOnceScript>
    <NeedsReboot>1</NeedsReboot>
    <StopOnFailure></StopOnFailure>
  </RunOnceScript>

 

Exit Codes and Error Handling

Workspot Agent assumes that if a script exits with an exit code of zero, it was successful. Any other exit code is a failure, but by default this is ignored, and Workspot Agent and Workspot Control treat any value as a success.

Non-zero values can be treated as fatal errors with <StopOnFailure>, as shown below:

    <StopOnFailure>1</StopOnFailure>

StopOnFailure is set independently for <SetupCompleteScript> and <RunOnceScript>.

When a fatal error (non-zero exit code) is detected, Workspot Control will mark the VM as failed and log a VM error status, preventing it from being assigned to a user:

control-vm-fata-error.png

This fatal error is non-recoverable. The VM needs to be reimaged after the script error is corrected.

Sysprep versus Quickprep

Workspot VDI 2.0 Pools and RD Pools can be either Sysprep or Quickprep.

Task

Sysprep

Quickprep

Computer name change

YES

YES

Join domain

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

For Sysprep:

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.

agent-2.4-sysprep-1.png

3. Sysprep the VM with the following command:
C:\Windows\System32\sysprep\sysprep.exe /shutdown /oobe /generalize /unattend:c:\temp\unattend.xml

agent-2.4-sysprep-2.png

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

Troubleshooting

  • For installation and template registration issues, see the logs file in: C:\ProgramData\WorkspotAgent\InstallLog.
  • For runtime issues, see the log file in: C:\ProgramData\WorkspotAgent\Log.



Have more questions? Submit a request

Comments

Powered by Zendesk