XenDesktop

Citrix XenDesktop 5 – Repair a broken machine catalog

/ LeoStar IT

This is a copy of Citrix KB article available at
http://support.citrix.com/article/CTX127068

It applies to XenDesktop 5.x

CTX127068

How to Resolve a Broken Catalog

Symptoms or Error

This article describes the steps required to resolve issues with catalogs that become unusable in Desktop Studio, where the only option available is to delete the catalog.

Solution

The easiest way to resolve problems with a catalog is to delete the catalog and recreate it. To repair unusable catalogs, the PowerShell SDK can be used to diagnose and repair the catalog.

The following steps provide some general methods to help resolve catalog issues.

Note: These steps assume that the Catalog is of a Pooled or Dedicated type.

  1. Start PowerShell as an administrator who has full access to XenDesktop.
  2. Type the following:
    Add-pssnapin Citrix*
  3. Retrieve the catalog that has an error: 
    Get-BrokerCatalog –Name [CatalogName]
This might return something close to the following:
AdministratorNames        {}
AllocationType            Permanent
AssignedCount            : 0
AvailableAssignedCount    0
AvailableCount            3
AvailableUnassignedCount  3
CatalogKind              : ThinCloned
Description              :
MachinesArePhysical      :
Name                      scriptdga
PvsAddress               :
PvsDomain                :
PvsForVM                  {1f019cef-bc7b-464b-a078-7c0517a60dcf:5c11657d-cb51-4939-b4d7-7145b222c7bb}
Uid                      : 6
UnassignedCount          : 5
UsedCount                : 2
AdministratorNames        {}
AllocationType            Permanent
AssignedCount            : 0
AvailableAssignedCount    0
AvailableCount            3
AvailableUnassignedCount  3
CatalogKind              : ThinCloned
Description              :
MachinesArePhysical      :
Name                      scriptdga
PvsAddress               :
PvsDomain                :
PvsForVM                  {1f019cef-bc7b-464b-a078-7c0517a60dcf:5c11657d-cb51-4939-b4d7-7145b222c7bb}
Uid                      : 6
UnassignedCount          : 5
UsedCount                : 2
  4. One important property to look for here is PvsForVM. This is the Catalog’s reference to the Provisioning Scheme and Host. Does this have a value?
    1. If No, follow the given steps to create a new provisioning scheme.
    2. If Yes, refer to the following section titled Verifying the Provisioning Schemes of a Catalog to verify the provisioning schemes are working correctly.

Creating a Provisioning Scheme

In order to create a provisioning scheme, a Host connection and AD Identity Pool must first be created.

Note: Rather than following these steps, Citrix strongly recommends that you delete the broken Catalog and recreate it in Desktop Studio.

To create the Provisioning Scheme, complete the following steps:

  1. Check that the identity pool exists:
    1. It is very likely that if the catalog creation failed but is still shown in Desktop Studio then the identity pool has already been created. The Identity Pool’s name should be the same as the Catalog’s name.In the PowerShell window, get a list of the identity pools: Get-AcctIdentityPool
    2. Look in the list for the identity pool that represents the details you specified when going through the “Create Catalog” wizard. If there are multiple identity pools with the same name with different numbers on the end (such as Finance_1, Finance_2, and so on), then you must look further into the details of the identity pool to find the right one. If you specified to create the accounts automatically then look at the Identity Pool Naming Scheme. Is it the same?
    3. If the Identity Pool exists, then take a note of the name and unique id. If it does not, then you can create it. See Creating an Identity Pool.
  2. Check that the Host exists
    1. Look for the Host in the PowerShell SDK: dir xdhyp:\hostingunits
    2. If the host does not exist, use Desktop Studio to create one.
    3. Note the name and the ID of the Host that you wish to use: dir xdhyp:\hostingunits | fl -property HostingUnitName, HostingUnitUid
  3. Find the full path of the SnapShot that you wish to use as the master image for all the Virtual Machines. If the Virtual Machine does not have a SnapShot, then you should create one.
    1. cd xdhyp:\hostingunits\[hostunit name] :
    2. dir | fl -property Name. Look for an entry with the name of the Virtual Machine that has your desired snapshot.
    3. cd [Master VM name].vm
    4. dir | fl -property Name, FullPath. Look for the snapshot of the correct name and note the FullPath.
  4. Create the provisioning scheme:
    1. New-ProvScheme -ProvisioningSchemeName [Any Name] –HostingUnitName [The name of the hosting unit from step 2]’ -IdentityPoolName [The name of the identity pool from step 1] -VMCpuCount 1 -VMMemoryMB 1024 -CleanOnBoot -MasterImageVM [The fullPath of the snapshot from step 3]. It takes a while to create the Provisioning Scheme, normally about 15 minutes for large disk sizes.
    2. When this step completes, take note of the Provisioning Scheme ID.
  5. Add the new provisioning scheme reference to the Catalog.

    Set-BrokerCatalog –Name [CatalogName] –PvsForVM  ‘{[ProvisioningScheme ID]:[Host ID]}’

    Example: Set-BrokerCatalog –Name MyCatalog –PvsForVM ‘{b6c977a7-2108-4697-bf8a-c32495efb367:b5dfc59a-8abb-436f-9b53-8eaab3b147b3}’

  1. If you load Desktop Studio, it shows this Catalog entry but still might report some errors. To clear these errors it is necessary to remove the action history of the catalog.

    Get-ProvTask -Active $false | Remove-ProvTask

  1. In Desktop Studio; refresh the Machines node. You should now be able to see the catalog entry without errors. To add machines to the catalog; select it and click “Add Machines” in the actions pane.

Creating an Identity Pool

Create the identity pool, preferably with the same name as the Catalog but this is not essential.

To create an identity pool to automatically create accounts.

New-AcctIdentityPool -IdentityPoolName [PoolName] -NamingScheme [Acc####] -Domain [MyDomain.com] -OU [The OU path, e.g; ‘OU=Finance,DC=MyDomain,DC=Com’] -NamingSchemeType Numeric -AllowUnicode

The naming scheme is the name that the created accounts will have (the hashes; #’s, will be replaced with the numbers of the accounts 1-n).

To create an identity pool where the accounts will be imported

New-AcctIdentityPool -IdentityPoolName ‘importedAccount’

Verifying the Provisioning Schemes of a Catalog

Complete the following steps if you have a catalog that references a Provisioning Scheme that has invalid entries:

To find out the Provisioning Scheme entries for the Catalog:

  1. Get-BrokerCatalog –Name [CatalogName]
  2. This might return something close to the following: 
    AdministratorNames       : {}
AllocationType           : Permanent
AssignedCount            : 0
AvailableAssignedCount   : 0
AvailableCount           : 3
AvailableUnassignedCount : 3
CatalogKind              : ThinCloned
Description              :
MachinesArePhysical      :
Name                     : scriptdga
PvsAddress               :
PvsDomain                :
PvsForVM                 : {1f019cef-bc7b-464b-a078-7c0517a60dcf:5c11657d-cb51-4939-b4d7-7145b222c7bb}
Uid                      : 6
UnassignedCount          : 5
UsedCount                : 2
  1. Look at the PvsForVM field. This consists of the Host ID and the Provisioning Scheme ID; for example {[Provisioning Scheme ID] :[HostID]}
  2. Using the provisioning scheme ID, find the provisioning scheme:
  1. Get-ProvScheme –ProvisioningSchemeUid [ID]

    Example: Get-ProvScheme –ProvisioningSchemeUid 5c11657d-cb51-4939-b4d7-7145b222c7bb

  2. If the provisioning scheme does not exist, then follow the steps in Creating a Provisioning Scheme.
  1. Using the Host ID find the Host
    1. dir ‘xdhyp:\hostingunits\{[HostID}’. Example: dir ‘xdhyp:\hostingunits\{b5dfc59a-8abb-436f-9b53-8eaab3b147b3}’
    2. If this command returns an error, then your host does not exist. To create it, follow the steps in section Repairing a Catalog’s Host Entry.
  2. If the provisioning scheme and the host exist, then it is possible that the provisioning scheme does not have the correct entries, or if there are multiple provisioning schemes, they might reference different identity pools; which is a configuration that is not supported by Desktop Studio.
  3. Check that the identity pool of the provisioning scheme exists.
    1. Get-ProvScheme  -ProvisioningSchemeUid b6c977a7-2108-4697-bf8a-c32495efb367 | fl -Property ProvisioningSchemeName, IdentityPoolName
    2. Note the name of the identity pool
    3. Get the identity pool: Get-AcctIdentityPool -IdentityPoolName Corka
    4. If the identity pool does not exist, then you must delete the provisioning scheme and recreate it. It is best, in this case, to use desktop studio to delete the Catalog and then to recreate it.
  4. If a Catalog references provisioning schemes that use different identity pools, then desktop studio cannot perform any task on the catalog. The only resolution is to delete the catalog and recreate it. To check if the provisioning scheme references different identity pools, look at each provisioning scheme ID in the PvsForVM field of the Catalog and ensure that the identity pool names are the same. 
    $pvsforVM | foreach { $index = $_.IndexOf(':'); $provId = $_.SubString(0, $index); get-provScheme -provisioningSchemeUid $provId | fl -property ProvisioningSchemeUid,ProvisioningSchemeName,IdentityPoolName; }
  1. If different identity pools are referenced, then you can continue to manage the Catalog in the PowerShell window or if you must use Desktop Studio, you must delete and recreate the catalog. Use Desktop Studio to do this.

Repairing a Catalog’s Host Entry

Use this section if you have a catalog that references a nonexistent host.

  1. Use Desktop Studio to create the host.
  2. In the PowerShell window, note the name and the ID of the Host that you wish to use. 
    dir xdhyp:\hostingunits | fl -property HostingUnitName, HostingUnitUid
  1. Find out the Provisioning Scheme entries for the Catalog:
    1. Get-BrokerCatalog –Name [CatalogName]
    2. This might return something close to the following:
    AdministratorNames       : {}
AllocationType           : Permanent
AssignedCount            : 0
AvailableAssignedCount   : 0
AvailableCount           : 3
AvailableUnassignedCount : 3
CatalogKind              : ThinCloned
Description              :
MachinesArePhysical      :
Name                     : scriptdga
PvsAddress               :
PvsDomain                :
PvsForVM                 : {1f019cef-bc7b-464b-a078-7c0517a60dcf:5c11657d-cb51-4939-b4d7-7145b222c7bb}
Uid                      : 6
UnassignedCount          : 5
UsedCount                : 2
  1. Look at the PvsForVM field. This consists of the Host ID and the Provisioning Scheme ID; such as {[Provisioning Scheme ID]:[HostID]}. Note the Provisioning Scheme ID.
  1. Add the provisioning scheme and host reference to the Catalog. 
    Set-BrokerCatalog –Name [CatalogName] –PvsForVM  ‘{[ProvisioningScheme ID]:[The new Host ID]}’
Example: Set-BrokerCatalog –Name MyCatalog –PvsForVM ‘{b6c977a7-2108-4697-bf8a-c32495efb367:b5dfc59a-8abb-436f-9b53-8eaab3b147b3}’
  2. In Desktop Studio; refresh the Machines node. You should now be able to see the catalog entry without errors. To add machines to the catalog; select it and click Add Machines in the Actions pane.

Problem Cause

There are several reasons for why the catalog can become unusable. Following are some of the most common reasons for catalog corruption:

  • An error occurred while creating or updating the catalog:

    The master image failed to be copied to the host. This is either because the selected master Virtual Machine image has an invalid configuration, the Host storage ran out of space, or that Host is not contactable.

    If you are using XenServer, ensure that the virtual machines hard disk is at position 0. When creating a custom Virtual Machine configuration this HD position is set to 1.

  • The host of the catalog was deleted.

    When a host that is being used by the catalog is deleted, the master image is no longer accessible by the catalog. The catalog cannot create any more machines. The “Delete Host” wizard actually offers to delete catalogs that will be left without a master image. Citrix recommends that this option is chosen before finalizing the wizard.

  • The catalogs configuration has been changed through direct use of the PowerShell SDK and not desktop studio.

    This is a much more complex scenario. The catalog has many dependent objects. A catalog references the following objects:

  • An Identity Pool which contains all the information about the Active Directory (AD) identities of the machines. This can be the information used to create more accounts, or information of the accounts that are in use or are free for use.Note: Only one identity pool can be referenced from a catalog if that catalog is still to be managed using Desktop Studio.
  • A Provisioning Scheme: This contains information about the virtual machines of the catalog, the master image used to provisioning the Virtual Machines, the host(s) that the Virtual Machines reside on, and the identity pool reference.
  • A Host: This is hypervisor, and storage details of where the created Virtual Machines will be located. It also specifies the network that each Virtual Machine will use.

If any of these objects are no longer referenced from the Catalog, then the Catalog shows as having an error. A Catalog can only reference one identity pool, if the catalog points to different identity pools then the Catalog still functions but is not supported in Desktop Studio, further modifications are required using the PowerShell SDK.