Product Documentation

Outils

May 28, 2016

You can use the following tools and utilities to tailor, expedite, and monitor PvD operations.

Custom rules files

The custom rule files provided with PvD let you modify the default behavior of PvD image updates in the following ways:
  • The visibility of files on the PvD
  • How changes made to the files are merged
  • Whether the files are writable

For detailed instructions on the custom rules files and the CoW feature, refer to the comments in the files located in C:\ProgramData\Citrix\personal vDisk\Config on the machine where PvD is installed. The files named "custom_*" describe the rules and how to enable them.

Resize and poolstats scripts

Two scripts are provided to monitor and manage the size of PvDs; they are located in the Support\Tools\Scripts folder on the XenDesktop installation media. You can also use the PvD Image Update Monitoring Tool, which is located in the Support\Tools\Scripts\PvdTool folder; see http://blogs.citrix.com/2014/06/02/introducing-the-pvd-image-update-monitoring-tool/ for details.

Use resize-personalvdisk-pool.ps1 to increase the size of the PvDs in all of the desktops in a catalog. The following snap-ins or modules for your hypervisor must be installed on the machine running Studio:
  • XenServer requires XenServerPSSnapin
  • vCenter requires vSphere PowerCli
  • System Center Virtual Machine Manager requires the VMM console

Use personal-vdisk-poolstats.ps1 to check the status of image updates and to check the space for applications and user profiles in a group of PvDs. Run this script before updating an image to check whether any desktop is running out of space, which helps prevent failures during the update. The script requires that Windows Management Instrumentation (WMI-In) firewall is enabled on the PvD desktops. You can enable it on the master image or through GPO.

If an image update fails, the entry in the Update column gives the reason.

Reset the application area

If a desktop becomes damaged or corrupted (by installing a broken application or some other cause), you can revert the application area of the PvD to a factory-default (empty) state. The reset operation leaves user profile data intact.

To reset the application area of the PvD, use one of the following methods:
  • Log on to the user's desktop as Administrator. Launch a command prompt, and run the command C:\Program Files\Citrix\Personal vDisk\bin\CtxPvD.exe -s Reset.
  • Locate the user's desktop in Citrix Director. Click Reset Personal vDisk and then click OK.

Export and import a PvD inventory

The image update process is an integral part of rolling out new images to PvD desktops; it includes adjusting the existing Personal vDisk to work with the new base image. For deployments that use Machine Creations Services (MCS), you can export an inventory from an active VM to a network share, and then import it into a master image. A differential is calculated using this inventory in the master image. Although using the export/import inventory feature is not mandatory, it can improve the performance of the overall image update process.

To use the export/import inventory feature, you must be an administrator. If required, authenticate to the file share used for the export/import with “net use.” The user context must be able to access any file shares used for the export/import.
  • To export an inventory, run the export command as an administrator on a machine containing a VDA with PvD enabled (minimum version 7.6):

    Ctxpvdsvc.exe exportinventory “<path-to-export-location>”

    The software detects the current inventory’s location and exports the inventory to a folder named “ExportedPvdInventory” to the specified location. Here’s an excerpt from the command output:
    C:\Program Files\Citrix\personal vDisk\bin> .\CtxPvDSvc.exe exportinventory  
    \\share location\ExportedInventory 
    Current inventory source location C:\CitrixPvD\Settings\Inventory\VER-LAS 
    ... 
    Exporting current inventory to location \\ …. 
    ... 
    Deleting any pre-existing inventory folder at \\ …. 
    .Successfully exported current inventory to location \\ …. Error code = OPS 
  • To import a previously-exported inventory, run the import command as an administrator on the master image:

To import

Run the import command as an administrator on the master image.

Ctxpvdsvc.exe importinventory “<path-to-exported-inventory>”

The <path to exported inventory> should be the full path to the inventory files, which is usually <network location\ExportedPvdInventory>.

The inventory is obtained from the import location (where it was previously exported using the exportinventory option) and imports the inventory to the inventory store on the master image. Here’s an excerpt of the command output:
C:\Program Files\Citrix\personal vDisk\bin> .\CtxPvDSvc.exe importinventory  
\\share location\ExportedInventory\ExportedPvdInventory 
Importing inventory \\share location\ExportedInventory\ExportedPvdInventory 
… 
Successfully added inventory \\share location\ExportedInventory\ExportedPvdInventory to the  
store at c:\ProgramData\Citrix\personal vDisk\InventoryStore
After the export, the network share should include the following filenames. After the import, the inventory store on the master image should include the same file names.
  • Components.DAT
  • files_rules
  • folders_rules
  • regkey_rules
  • RINGTHREE.DAT
  • S-1-5-18.DAT
  • SAM.DAT
  • SECURITY.DAT
  • SNAPSHOT.DAT
  • SOFTWARE.DAT
  • SYSTEM.CurrentControlSet.DAT
  • VDCATALOG.DAT
  • vDiskJournalData

Back up and restore

Important: The scripts do not move PvDs to the new storage location. You must perform that operation in some other way.
Two PowerShell scripts supplied on the product installation media (in the Support\Tools\Scripts folder) allow you to back up and restore Personal vDisks. Use the backup and restore scripts to migrate existing PvDs and user associations from one catalog to another. This can be useful if you are changing your PvD storage. The backup script creates an .xml file with metadata from an existing catalog. The metadata contains the current location of the PvDs on the storage, and the user associations with the PvDs. The restore script uses the .xml file to associate the PvDs with a new catalog and assign the correct users to them.
  • migration-backup.ps1 captures the mapping between each user and their Personal vDisk in a machine catalog and stores this information in an .xml file
  • migration-restore.ps1 uses the .xml file to re-create a user's desktop in a machine catalog
Before backing up and restoring, note the following:
  • The scripts work with the hypervisor API so the hypervisor’s PowerShell snap-in must be installed on the Controller where the scripts are executed
  • Run the scripts from a location that has access to the Controller where the machine catalog was created
  • The scripts are supported on the following hypervisor platforms: Citrix XenServer, Microsoft Hyper-V, and VMware ESX

Back up a machine catalog

Perform a backup when a change is made to a machine catalog. You can perform a backup while the machines in the catalog are active.

Use migration-backup.ps1 to back up any machine catalog containing Personal vDisks. The script asks for the name of the machine catalog and connection information for the hypervisor. It then iterates through all of the user-assigned machines in the machine catalog and, for each machine, stores the mapping between the Personal vDisk storage and the assigned user. This information is located in an .xml file, which has the following structure:
<PVDMigration> 
	<hypervisor> 
		<type></type> 
	</hypervisor> 
	<PVD> 
		<DiskId></DiskId> 
		<DiskName></DiskName> 
		<SRName></SRName> 
		<SRID></SRID> 
		<UserName></UserName> 
		<UserSid></UserSid> 
		<State></State> 
	</PVD> 
</PVDMigration>
  • PvDMigration.hypervisor.Type supports VMware ESX, Citrix XenServer, and Microsoft Hyper-V.
  • PvDMigration.PVD stores information on where the Personal vDisk is stored and the user associated with it.
  • PvDMigration.PVD.DiskId is the unique identifier of the vDisk on the hypervisor on which the backup was taken.
  • PvDMigration.PVD.DiskName is the name of the .vhd or .vmdk file.
  • PvDMigration.PVD.SRName is the name of the storage provider when the backup was taken.
  • PvDMigration.PVD.SRID is the unique identifier of the storage provider on the hypervisor on which the backup was taken.
  • PvDMigration.PVD.UserName is the name of the user associated with this vDisk.
  • PvDMigration.PVD.UserSid is the SID of the user associated with this vDisk.
  • PvDMigration.PVD.State indicates the state of this vDisk. This can be either "backed up" or "processed." It is "backed up" after the initial backup; the state changes to "processed" after the .xml file is used for restoring from the backup.

Restore a machine catalog

Before restoring, note the following:
  • You can only restore a machine catalog that shares the same master image as that of the backed-up machine catalog
  • You must create a new master image by updating the inventory of the master image that the backed-up machine catalog was created from
Use migration-restore.ps1 to restore any machine catalog containing Personal vDisks. The script takes the following inputs:
  • The .xml file created during the backup process
  • The name of the machine catalog to restore
  • The name of the location where the unattached Personal vDisks are stored. This is listed in the .xml file
  • Hypervisor connection information

The migration-restore.ps1 script finds any unassigned machines in the machine catalog and assigns users to them. It also attaches users' Personal vDisks to the machines.

Example scenario 1: Restore a machine catalog and its Personal vDisks using new machine names

In this scenario, an entire machine catalog and the Personal vDisks attached to the machines in it are restored. The machines are given new names. This scenario might occur when your hypervisor or a storage host has failed, or when you migrate users to a new infrastructure.
  1. Run migration-backup.ps1 to capture the user-to-Personal-vDisk mapping in the .xml file.
  2. Using a backup solution, move or capture the Personal vDisks from the original machine catalog on to a disk:
    • VMware ESX or Microsoft Hyper-V: Personal vDisks are located on the storage specified by the Controller, in a folder containing the name of the machine to which the vDisk is attached.
    • Citrix XenServer: Personal vDisks are located in the root of the storage specified by the Controller. The name of each vDisk is a GUID.
  3. Restore the Personal vDisks from the original machine catalog using a storage backup solution:
    • ESX or Hyper-V: Locate the vDisks in a new folder of the new storage resource. Alternatively, leave the vDisks in the original path on the new storage resource.
    • XenServer: Locate the vDisks in the root of the new storage resource.
  4. Create a Provisioning Services vDisk or a Machine Creation Services snapshot from the master image, which you used to create the failed machine catalog.
  5. Run Update Inventory from the Start menu on the vDisk or snapshot.
  6. Re-create the machine catalog in Studio using a different naming convention as the failed (original) machine catalog. This generates a catalog of new machines, each with a new Personal vDisk, that the site database recognizes.
  7. Verify that the re-created machine catalog is assigned to the correct Delivery Group.
  8. Verify that the Delivery Group is in maintenance mode and the machines in it are shut down.
  9. Edit the .xml file generated by the backup script:
    • ESX or Hyper-V: If you restored the vDisks to a new folder on the new storage resource in Step 3, for every PVD section in the file, replace the folder name in DiskName with the location of the restored vDisks. If you restored the vDisks to the original path on the new storage, skip this step.
    • XenServer: Skip this step.
  10. On the Controller, run migration-restore.ps1, specifying the name of the .xml file and the location where the backed-up vDisks are stored.

Example scenario 2: Restore a machine catalog and its Personal vDisks reusing existing machine names

In this scenario, an entire machine catalog and the Personal vDisks attached to the machines in it are restored. Existing (failed) machine names are reused. This scenario might occur when your hypervisor or a storage host has failed.
  1. Run migration-backup.ps1 to capture the user-to-Personal-vDisk mapping.
  2. Using a backup solution, move or capture the Personal vDisks from the original machine catalog on to a disk:
    • ESX or Hyper-V: Personal vDisks are located on the storage specified by the Controller, in a folder containing the name of the machine to which the vDisk is attached.
    • XenServer: Personal vDisks are located in the root of the storage specified by the Controller. The name of each vDisk is a GUID.
  3. Restore the Personal vDisks from the original machine catalog using a storage backup solution:
    • ESX or Hyper-V: Locate the vDisks in a new folder of the new storage resource.
    • XenServer: Locate the vDisks in the root of the new storage resource.
  4. Create a Provisioning Services vDisk or a Machine Creation Services snapshot from the master image that you used to create the failed machine catalog.
  5. Run Update Inventory from the Start menu on the vDisk or snapshot.
  6. Re-create the machine catalog in Studio using the same naming convention as the failed machine catalog. This generates a catalog of new machines, each with a new Personal vDisk, that the site database recognizes.
  7. Verify that the re-created machine catalog is assigned to the correct Delivery Group.
  8. Verify that the Desktop Group is in maintenance mode and the machines in it are shut down.
  9. Edit the .xml file generated by the backup script:
    • ESX or Hyper-V: For every PVD section in the file, replace the folder name in DiskName with the location of the restored vDisks.
    • XenServer: Skip this step.
  10. Run the migration-restore.ps1 script on the Controller with the modified .xml file as an input. The script attaches the vDisks without moving them.
  11. Verify the users' data has been successfully restored.

Example scenario 3: Restore a subset of Personal vDisks in a machine catalog

In this scenario, some, but not all, of the Personal vDisks in a machine catalog have failed and are restored. The virtual machines in the catalog have not failed.
  1. Run migration-backup.ps1 to capture the user-to-Personal-vDisk mapping in the .xml file.
  2. The .xml file has a PVD section for each user in the machine catalog. For any users whose Personal vDisks do not need restoring, remove the users and their associated sections from the file.
  3. Restore the Personal vDisks from the original machine catalog using a backup solution, as described in the one of the other scenarios:
    • To use new machine names, follow example scenario 1.
    • To preserve machine names, follow example scenario 2.
  4. Ensure there are enough unassigned machines in the catalog. Add machines if necessary. You need one new machine for each user whose vDisk you want to restore.
  5. Verify that the Desktop Group is in maintenance mode and the machines in it are shut down.
  6. On the Controller, run migration-restore.ps1 with the modified .xml file as an input.
  7. Verify the users' data has been successfully restored.