Citrix App Layering: Desktop Processing Utility

This utility was developed to modify desktop certain settings outside of Unidesk. The script is capable of adding or removing vmx file entries, setting memory and CPU reservations as well as moving the desktops into a particular resource pool or vCenter folder. The utility is designed to perform these actions integrated with the build process of desktops.

There are two ways this can be used. For most use cases the best approach is to during the desktop build add a script to the build process that creates a flag file in a share for the desktop, then it shuts the desktop down. Then the Desktop Processing script reads the flag file, makes changes to the VMX file or VM settings and starts the desktop up so that it can finish the build process. If you use Non-Persistent desktops and VMware View this will only work if you also use Unidesk Power Management because if you are using View’s power management View will start the desktop before the Desktop Processing script has a chance to run and the desktop will be finalized.. This process will always work for XenDesktop and Persistent Desktops.

It is also possible for this script to create the flag file at the very end of the build process. Then enable the script to put the desktop in maintenance mode, shut it down, do the vmx and vm processing and start it up again. This process has some potential issues because the broker may give access to a user before the process runs and the user will be kicked off the desktop when the process runs. We recommend the first process and also provide the script files necessary to implement it.

How the script works:

• The process is integrated into KMSSETUP.CMD right after the machine is rearmed.
• If you are using the script to add settings that add device drivers then there is also a secondary restart added so that the desktop is restarted after the drivers are loadedand plug and play has a chance to run. This ensures that the drivers will be installed before the machine is finalized as non-persistent.
• The Desktop Processing script an be run manually (looping for a defined period of time) or added to a scheduled task to run every 2-20 minutes. The script will monitor the flag share and process any desktops when it finds their flag file.
• Here is what the script does
  • Check a network share for flag files corresponding to newly created desktops
  • Waits a pre-defined time for the mini-setup to complete – This time is defined by the admin and normally can be set to 60 if the preferred process is used.
  • Updates each desktop with all vmx and reservation modifications
  • Moves the desktop into a new Resource Pool and/or vCenter Folder if defined
  • Starts the desktops
  • Deletes the flag file in the network share

If configured to integrate with a broker the process is slightly different. To use broker integration the script must be run on the broker server (either connection server or DDC).

• Here is what the script does
  • Check a network share for flag files corresponding to newly created desktops
  • Waits a pre-defined time for the mini-setup to complete – This time is defined by the admin and normally can be set to 0 if the preferred process is used.
  • If any of the changes require updates to the vmx file (reservations do not) then a flag is set to shut down the desktop
  • If a shutdown is required
    • Sets all the found desktops to maintenance mode in View or XenDesktop
    • Waits 30 seconds for Maintenance Mode
    • Shuts Down all the desktops
    • Waits 2 minutes for the shut downs to complete
  • Updates each desktop with all vmx and reservation modifications
  • Move the desktop into a new Resource Pool and/or vCenter Folder
  • If a shutdown was required
    • Starts the desktops
  • Removes the desktops from Maintenance Mode
  • Deletes the flag file in the network share

The script supports View and XenDesktop using their respective PowerCLI modules. If you use another broker the script can be used but it will not put the desktops in maintenance mode.

• VMware PowerCLI (version 5.5 update 2 or later)
• For View the View PowerCLI modules
  • Required if you are not using this during the build process and the desktop must be put into maintenance mode and shut down.
• If using the broker integration the script must be run on the broker server (Connection Server or DDC)
  • Note Broker Integration is only necessary if updating the vmx file and not shutting down the desktop beforehand.
• The script assumes desktop names are unique across domains and that there is only one desktop with the same name defined in View. This means that cleaning up View when you delete desktops is important.
• The account that runs the utility needs administrator rights on the OS and in the Broker if using broker integration
• The Account used for vSphere must have appropriate rights to modify VMX files, and to move desktop’s into pools or folders if using that feature

The script has several components. There is a simple application to setup the script variables. There are a few PowerShell scripts, and a network share on a file server that must be created.

The following sections will outline the setup and configuration of the script.

PowerCLI

The first thing you must do to use the utility is to download and install the VMware PowerCLI software onto your broker machine.

Unpacking the Script

Installation of the utility is very easy. Create a folder in a path with no spaces for example c:\DesktopProcessing. Unfortunately spaces make it hard to include in a cmd file if you want to schedule a task to run regularly. Then unpack the source zip file into this directory. Before unpacking check the properties of the zip file to see if they may be blocked as shown on the right. If they are click unblock. This will unblock all of the files as long as you unblock the zip before you extract the files.

Once unpacked there is an application called DesktopProcessing.exe. Double click this application and the following screen will open.

Section 1 vCenter Connection Information

To configure the script enter your vCenter credentials and save them. This will create a file in the source directory called cred.xml as shown here. The password is encrypted based on the logged in user and the desktop and cannot be moved to another machine or used by another login. Therefore if you choose to run the backup as a scheduled task you must be logged on as the user you will define to run the scheduled task on the machine that you will run the scheduled task when you create the cred file.

Section 2 Settings

Then set the settings for the “Action Share. This share will be used for flag files created by desktops as they complete mini-setup. The files are created as Domain.ComputerName.txt and the name is parsed to obtain the name and domain for the desktop. The share will have to be created and modify permissions for the local desktops administrator which means “everyone” will require modify permissions on the directory. Remember to allow all share permissions. You can also script in a username and password. See the Creating a Script Layer later in the document.

The next item is Skip Desktop Shutdown. If you want to edit the vmx settings before a desktop is finished building then set this to yes and integrate the flag creation script into the kmssetup.cmd file. Directions for this are shown in the Creating a Script Layer section of the document.

If you plan on running this after desktops are already built, set no here and make sure to integrate with the broker so the machine will be placed in maintenance mode, then shut down to make changes. Next select a wait time. This is the time the script will wait after finding new machine to process before it starts the process. We want to ensure that any changes being performed by the setup process are complete before we shut down the desktop to add the VMX parameters.

Start with 60 or 90 seconds and test to see if that works fine in your environment.

If you selected yes to shutdown during build set this to 60 to leave a little time for the desktop to shut down.

Lastly, choose the appropriate broker. This will define which set of commands are used to place the broker in maintenance mode. Again use other if you don’t need to put the broker in maintenance mode.

Section 3 Rules

In this section you define the rules used for each naming convention. You can set Resource Pool, Folder, Memory and CPU Reservations or to add or change a setting in the VMX file.You define all the settings desired for your rule then click Add Rule.

Remember to add all vmx key-value pairs required for the rule before adding the rule.

 

Desktop Wildcard

This is used for safety. You can use a standard string at the beginning of the desktop name then a *

Examples

Univ*

ClinVDI*

If you don’t use any naming conventions you can use a * (just an asterisk). This is just a safety the process is driven off the flag files stored in the flag share.

 

Resource Pool and or Folder

You can add the desktop to a resource pool or folder or both. If you don’t want to use this feature leave the Do Not Set. To use it first click the Get vCenter Info to retrieve a list of resource pools and folders. Then select the desired ones.

 

VMX Keys and Values

You can add, change or delete value from the vmx file. For Common VMX values and reservations try the Common Entries drop down. Otherwise add the key and value as described by vmware in their documentation.

For example to disable hot plug the key would be devices.hotplug the value false

You can add as many VMX changes as desired after each one click Add VMX value. You can remove mistakes using remove checked.

When you have the entire rule defined click Add Rule

Note: When you add the keys do not use quotes around the values.

 

Memory and CPU Reservations

To modify Memory or CPU reservations for the desktop use the following strings as keys with their associated value

• CpuReservationMhz

• MemReservationMB

If you are only changing reservations the desktop is not shut down because that is not required.

To Remove a reservation set its value to 0.

VMware vGPU

The settings required to support vGPU are provided in the Common Entries as well and include the following:

pciPassthru0.virtualDev:vmiop

pciPassthru0.vgpu:grid_k120q

pciPassthru0.present:TRUE

pciPassthru0.pciSlotNumber:33

sched.mem.pin:TRUE

The two entries in red must be configured based on your requirements. Use the drop down to select the entry then change the NVIDIA profile as desired and the PCI Slot number to match your implementation. You may have to use View or XenDesktop to create once machine integrated with the NVIDIA card to know what the PCI slot is by checking its vmx file.

NVIDIA profiles are used to define how much graphics memory each desktop will be aloted.

NVIDIA profiles are described here: http://www.nvidia.com/object/virtual-gpus.html

To modify the profile select the pciPassthru0.vgpu:grid_k120q and change the k120q to the appropriate value. K120q supported 32 desktops at 512MB of Video RAM.

 

Section 4 Scheduled Task

This section allows you to create a scheduled task on the machine you are running the backup utility on. It is very important to choose appropriate Frequency for the script. If the frequency is less time than the script takes to run, the tasks will often fail. I recommend running the script every 20 minutes. There is very little overhead if the script finds no files in the Action Share.

Also use the same account here that you used when creating the credential file in step 1. This is critical because the cred.xml file is encrypted to the computer and user that created it.

 

Manually Running the Script

Note: The utility also supports running the script manually whenever you are creating desktops. The advantage of this is that it only runs when needed.

To use this feature don’t configure the scheduled task you don’t want two of the script running at the same time. Then check loop continuously for, and pick the time based on how many desktops you will be creating. Its ok for it to run long you can stop it whenever desired.

Start the process either before or soon after launching the create desktops task in the UMC.

 

Create the Action Share

On any server accessible from both the desktops and the system that will run the script create a share to store the flag files. A domain user account will be used to connect to this share. Configure modify permission for this user to the share.

This user will be defined in the script that creates the flag file. This is because the desktops must be able to write to this share when they are running mini-setup. At the point where we write to the share the system is logged on by the local system account on the desktop so the script will map a drive as a domain user in order to access the share.

The share can be hidden from browsing by adding a $ to the end of the share name.

Creating a Layer to script the flag file creation

The strategy here is that at the end of the mini-setup process a command will be run that create a text file in the Action Share defining the name of the Domain and the Name of the desktop that was just created.

To make this easy we crated a new version of the Unidesk Optimizer and a new KSMSETUP.CMD file. Together they make it easy to deploy the scripting required by Desktop Processing.

The best way to deploy the new optimizer and kmssetup.cmd is to add a version to your OS layer and put the optimizer executables in the c:\windows\setup\scripts folder and the kmssetup.cmd in the c:\windows\setup\scripts\kmsdir folder.

Then if you want to modify all desktops run the optimizer in the OS layer and save the settings as discussed below before finalizing. If only some desktops will be modified make finalize the changes to the OS layer then create an application layer to apply the Desktop Processing flag files. These flag files will initiate the vmx update process during the build.

When you run the optimizer there is now a line E that prompts for the required information to create the createflag.cmd file. Fill out the appropriate information and click save A-E.

Note step 5. If the update to the vmx file will cause windows to install a driver set 5 to Yes. This will add an extra reboot during the build process before the removeready.cmd is run causing a NP desktop to be set to non-persistent. A good example of this is if you are using the scripting to setup vGPU.

If you review the createflag.cmd file you will see that it includes the user password in plain text. That file is deleted after it is run. If you are worried about the security of that account take away all permissions so all the account has access to is the Action Share.

When the script runs, if it finds desktops to process it will create a log on the log folder of the script directory. The logs will contain a summary of changes by machine and any errors encountered.