Citrix Provisioning

Configuring a vDisk for Microsoft Volume Licensing

Configure a vDisk for Microsoft Key Management Service (KMS) or Multiple Activation Key (MAK) volume licensing when running the Imaging Wizard. If the vDisk was not configured using the Imaging Wizard, it can still be configured from the Citrix Provisioning console.

Important:

Citrix Provisioning does not support MAK activation for Microsoft Office products.

Using MCLI and SOAP server command line interfaces for Microsoft volume licensing

MCLI and SOAP Server command-line interfaces can be used to configure Microsoft Volume Licensing using the following procedure:

  1. Select the vDisk in the Citrix Provisioning console, then right-click and select File Properties. The vDisk File Properties dialog appears.
  2. Click the Microsoft Volume Licensing tab, then select the MAK or KMS licensing method.
  3. Click OK.

Configuring Microsoft KMS volume licensing

This section describes how to use KMS license access codes with Citrix Provisioning.

Note:

Support for KMS licensing requires the SOAP Server user account is a domain user with the right to perform volume maintenance tasks. The domain user is typically found in Local\\Computer Configuration\\Windows Settings\\Security Settings\\Local Policies\\User Rights Assignment. By default, a member of the local administrators group has this right.

KMS volume licensing utilizes a centralized activation server. This server runs in the data center, and serves as a local activation point (opposed to having each system activate with Microsoft over the internet).

Note:

Preparing or updating a KMS configured vDisk that is copied or cloned includes completing the final configuration task. Change the vDisk mode from Private Image Mode to Shared Image Mode. Prepare the vDisk before copying or cloning the vDisk to other Provisioning Servers. Copy the pvp and vhdx file to retain the properties and KMS configuration of the original vDisk.

The tasks involved in configuring a vDisk image to use KMS volume licensing and managing that vDisk in a Citrix Provisioning farm includes:

Note: If KMS licensing was not configured on the vDisk when running the Imaging Wizard, alternatively configure it using the Console. You can also configure it using the MCLI and PowerShell command-line interface.

Preparing the new base vDisk image for KMS volume licensing

After you create a vDisk using the Imaging Wizard, it must be reset to a non-activated state using the rearm command.

Perform this operation on a system booted from the vDisk in Private Image Mode. This process ensures that the master target device hard disk’s rearm count is not reduced.

Tip: Microsoft limits the number of times you can run rearm on an installed OS image. Reinstall the operating system if you exceed the number of allowed rearm attempts.

  1. Boot the target device from the vDisk in private image mode to rearm.

    Note:

    OSPPPREARM.EXE must be run from an elevated command prompt.

  2. A message prompts you to reboot the system, DO NOT REBOOT. Instead shut down the target device.
  3. If the KMS option was not selected when the vDisk image was created, click the Microsoft Volume Licensing tab and set the licensing option to KMS.
  4. Set the vDisk mode to standard image mode.
  5. Stream the vDisk to one or more target devices.

Use the information in the following sections to configure various KMS scenarios.

Maintaining or upgrading a vDisk image that uses KMS volume licensing

To maintain or upgrade a vDisk image that is configured to use KMS volume licensing:

  1. Set the vDisk mode to Private Image mode.
  2. Stream the vDisk to a target device.
  3. Apply the OS/application service pack/update, then shut down the target device.
  4. Set the vDisk mode back to Shared Image mode.
  5. Stream the vDisk to the target device in shared image mode. Note: If Office 2010 is installed as a vDisk update, or after the vDisk has gone through the base disk preparation process once, repeat the base disk preparation using the following procedure:
    1. In the Citrix Provisioning console, right-click on the vDisk, then select the File Properties menu option. The vDisk File Properties dialog appears.
    2. Click the Microsoft Volume Licensing tab, then change the licensing option from KMS to None.
    3. On the Mode tab, set the vDisk access mode to Private Image mode.
    4. PXE boot to the vDisk in private image mode to rearm. Note: OSPPPREARM.EXE must be run from an elevated command prompt.
    5. A message prompts you to reboot the system, DO NOT REBOOT. Instead shut down the target device.
    6. In the console, right-click the vDisk you are configuring, then select the File Properties menu option. The vDisk Properties dialog appears.
    7. Click the Microsoft Volume Licensing tab, then change the license option from None to KMS.
    8. On the Mode tab, set the vDisk access mode to Shared Image mode.
    9. Stream the vDisk to the target devices.

Maintaining or upgrading a vDisk image enabled with versioning that is currently using KMS

In this scenario, a vDisk is already configured for KMS and is deployed successfully. The disk is enabled to use vDisk versioning, so versions can exist. Consider:

  • For both Microsoft Windows and Microsoft Office: A vDisk is already configured for KMS and is deployed successfully.
  • For environments with only Microsoft Windows or only Microsoft Office: The vDisk is already configured for KMS Only Windows or Only Office and is deployed successfully.

To maintain or upgrade the vDisk:

  1. In the Citrix Provisioning console, right-click the virtual disk, and select Versions.
  2. Create a disk version.
  3. Access the target device properties and set Type to Maintenance.
  4. Start the target device.
  5. Access the target device machine and select Maintenance from the Boot menu when prompted.
  6. Select the required operating system in Application/Service Pack/Update.
  7. Shut down the target device.
  8. Access the Citrix Provisioning console, select the vDisk and right-click to display the contextual menu.
  9. Select Versions. Promote the vDisk from Maintenance to Production or Test.
  10. Access the Citrix Provisioning console. Under Target device properties, change the Type to Production or Test.

Stream the vDisk with this version to one or more target devices.

Installing Microsoft Office to an existing KMS configured vDisk during Maintenance

A vDisk already uses KMS, is configured for Microsoft Windows and is deployed successfully.

To install Microsoft Office to a vDisk during maintenance:

  1. In the Citrix Provisioning console, right-click on the vDisk and select Properties.
  2. Select the Microsoft Volume Licensing tab and change the licensing option from KMS to None.
  3. On the General tab, set the vDisk access mode to Private Image mode.
  4. PXE boot to the vDisk in Private Image mode to rearm:
    1. For Office (for 64-bit client): Program Files(x86)\Common Files\microsoft shared\OfficeSoftwareProtectionPlatform\OSPPREARM.EXE
    2. For Office (for 32-bit client): Program Files\Common Files\microsoft shared\OfficeSoftwareProtectionPlatform\OSPPREARM.EXE
    3. Repeat for other Windows versions: Run cscript.exe slmgr.vbs –rearm
  5. A message is displayed to reboot the system. Do not reboot. Instead, shut down the target device.
  6. In the console, right-click the vDisk and select Properties.
  7. Select the Microsoft Volume Licensing tab and change the license option from None to KMS.
  8. On the General tab, set the vDisk access mode to Standard Image mode.
  9. Stream the vDisk to one or more target devices.

Tip:

You can validate the KMS configuration by verifying that the CMID for each device is unique. For Windows versions, run cscript.exe slmgr.vbs –dlv. For Office versions, run C:\Program Files\Microsoft Office\Office14\cscript ospp.vbs /dcmid.

Important information on rearm

Consider the following when rearming:

  • Microsoft limits the number of times you can run rearm on an installed operating system image and Microsoft Office. The operating system and Office image must be reinstalled accordingly if you exceed the number of allowed rearm attempts.
  • For a successful KMS configuration using a Citrix Provisioning vDisk, you are not required to rearm the disk except the first time when you configure it.
  • Citrix recommends that you rearm the system that is started from the vDisk in Private Image mode. This ensures that the rearm count of the master target device hard disk is not reduced.

Installing Microsoft Office to an existing KMS configured for a Windows vDisk

A vDisk is already configured for KMS using Microsoft Windows and is deployed successfully. To install Microsoft Office to an existing KMS that is configured for Microsoft Windows:

  1. In the Citrix Provisioning console, right-click the vDisk and select Properties.
  2. Select the Microsoft Volume Licensing tab and change the licensing option from KMS to None.
  3. On the General tab, set the vDisk Access Mode to Private Image mode.
  4. PXE boot to the vDisk in Private Image mode to rearm. An OS rearm is required along with the Microsoft Office rearm.
    1. For Microsoft Windows, run cscript.exe slmgr.vbs -rearm.
    2. For Microsoft Office 2010, run %ProgramFiles%\Common Files\MicrosoftShared\OfficeSoftwareProtectionPlatform\OSPPREARM.EXE.
    3. For Microsoft Office 2013 and 2016, run %ProgramFiles%\Microsoft Office\%Office%\OSPPREARM.EXE.
  5. A message is displayed to reboot the system. Do not reboot. Instead, shut down the target device.
  6. In the console, right-click the vDisk and select Properties.
  7. Select the Microsoft Volume Licensing tab and change the license option from None to KMS.
  8. On the General tab, set the vDisk Access Mode to Standard Image mode.
  9. Stream the vDisk to one or more target devices.

You can validate the KMS configuration by verifying that the CMID for each device is unique. For Windows versions, run cscript.exe slmgr.vbs –dlv. For Office versions, change the directory to %ProgramFiles%\Microsoft Office\%Office% and then run:

  • cscript ospp.vbs /dcmid
  • cscript ospp.vbs /dstatus. The OS and Microsoft Office discovery of KMS is independent from each other. /dstatus appears if Microsoft Office has located KMS on the network.
  • cscript ospp.vbs /act. This command expedites the activation process.

Upgrading Microsoft Office on an existing KMS configured for a Microsoft Windows vDisk

A vDisk is already configured for KMS that uses Microsoft Windows and Microsoft Office. To upgrade:

  1. In the Citrix Provisioning console, right-click on the vDisk and select Properties.
  2. On the General tab, set the vDisk Access Mode to Private Image mode.
  3. Start the target device.
  4. Run the new Microsoft Office setup. Choose to perform an upgrade.
  5. Reboot the target device as required by the installation.
  6. Shut down the target device.
  7. Connect to the Citrix Provisioning Server. In the console, right-click on the vDisk and select Properties.
  8. On the General tab, set the vDisk Access Mode to Standard Image mode.
  9. Stream the vDisk to one or more target devices.

Important information on rearm

  • Microsoft limits the number of times you can run rearm on an installed operating system image and Microsoft Office. The operating system and Office image must be reinstalled accordingly if you exceed the number of allowed rearm attempts.
  • For Windows and Office products utilizing KMS activation, the available rearm count increments from 0 to 1 on a successful activation against a KMS host server.
  • If you run out of rearms, activating by using a KMS host lets you rearm once. This ensures that once you activate a KMS client, they can issue a rearm. For example, a KMS client with a rearm count of 1 issues a rearm using the remaining single rearm, and reboots. Upon reboot after the KMS client activates, the rearm count will return to a count of 1.

Tip:

A successful KMS configuration for a Citrix Provisioning vDisk does not require you to rearm the vDisk except the first time when it is configured.

Configuring Microsoft MAK volume licensing

This section describes the use of Multiple Activation Keys (MAK). A MAK corresponds to some purchased OS licenses. The MAK is entered during the installation of the OS on each system. The installation activates the OS and decrements the count of purchased licenses centrally with Microsoft. Alternatively, a process of proxy activation is done using the Volume Activation Management Toolkit (VAMT). Proxy activation works on systems that do not have access to the Internet. Citrix Provisioning applies this proxy activation mechanism for standard image mode vDisks that have the MAK licensing mode selected when creating the disk.

The Volume Activation Management Tool (VAMT) version 3.1 must be installed and configured on all provisioning servers within a farm. This tool is available from the Microsoft Windows Assessment and Deployment Kit (Windows ADK). For more information, see Install VAMT.

When you first run the VAMT, a VAMT database is created. This database caches all device activations and allows for the reactivation of Citrix Provisioning.

Volume Activation Management Tool 3.1 requires:

  • PowerShell 3.0 or later – the OS is newer than Windows Server 2012 or Windows 8
  • SQL 2012 express or newer

Citrix Provisioning MAK activation requires you to configure one of three user types:

  • Volume Activation Management Tool/Provisioning Services installation user — This user is a local administrator possessing rights on SQL 2012 or newer (VAMT 3.1 requirement). These rights are used to create a database for VAMT.
  • MAK user — The user defined in the site’s properties. This user handles the MAK activation on both server and client side. This user is a local administrator on both the provisioning server and the master client. This user requires full access to the VAMT database.
  • Citrix Provisioning SOAP/stream services user — the stream process handles the reactivation when the target device restarts. This user requires read access to the VAMT database.

Provisioning servers use PowerShell to interface with the VAMT. These manual configuration steps are required one time per server:

  1. Install PowerShell 3.0 or later.
  2. Install VAMT 3.1 on every provisioning server system using a Volume Activation Management Tool/Provisioning Services installation user.
  3. Configure a VAMT database as prompted during the initial run of VAMT 3.1. Make this database accessible to all provisioned servers used to stream VAMT activated Citrix Provisioning target devices.
  4. If the user who created the VAMT database is not the SOAP/stream service user, copy the VAMT configuration file C:\\Users\\\<VAMT installation user (dB creator)\>\\AppData\\Roaming\\Microsoft\\VAMT\\VAMT.config to C:\\Users\\\<Provisioning Services soap/stream services user\>\\AppData\\Roaming\\Microsoft\\VAMT\\VAMT.config.
  5. Set the provisioning server security configuration to use PowerShell to interface with VAMT.
    1. Set-ExecutionPolicy -Scope \ (the Provisioning Services services user) to unrestricted – see Set-ExecutionPolicy for more information.
    2. WinRM quickconfig.
    3. Enable-WSManCredSSP -Role Client -DelegateComputer <this server fqdn> -Force
    4. Enable-WSManCredSSP -Role Server –Force.
  6. Configure the Windows firewall on the client for VAMT 3.1 – see Configure Client Computers for more information. Citrix Provisioning target devices cannot be activated or reactivated if the firewall is not configured for VAMT.

Common activation errors

Error: Failed to create PSSession — Reason: MAK user is not a local administrator on the Citrix Provisioning server.

Error: Index was out of range. Must be non-negative and less than the size of the collection. Parameters name: Index.

Reason: MAK user does not have full access (read\write) permission to the VAMT database.

Setting the vDisk licensing mode for MAK

A vDisk can be configured to use Microsoft Multiple Activation Key (MAK) licensing when running the Imaging Wizard. If MAK licensing was not configured when running the Imaging Wizard, the vDisk’s licensing mode property can be set using the console, MCLI, or PowerShell user interface. The licensing mode is set before activating target devices.

Note: For information on using the command-line interfaces, see the MCLI or PowerShell Programmers Guide.

Entering MAK user credentials

Before target devices that use MAK-enabled vDisks can be activated, MAK user credentials must be entered for a site.

Note: The user must have administrator rights on all target devices that use MAK-enabled vDisks, and on all Provisioning Servers that stream the vDisks to target devices.

To enter credentials:

  1. Right-click on the site where the target devices exist, then select the Properties menu option.
  2. On the MAK tab, enter the user and password information in the appropriate text boxes, then click OK.

Activating target devices that use MAK-enabled vDisks

After a vDisk is configured for MAK volume licensing, each target device assigned to the vDisk must be activated with a MAK.

Note: After all licenses for a given MAK are used, a new key is required to allow more target devices to share this vDisk image.

To activate target devices that use MAK volume licensing from the Console:

  1. Boot all target devices that are to be activated.

  2. In the Console, right-click on the collection or view of the individual device including those target devices requiring MAK license activation. Select the Manage MAK Activations… menu option. The Manage MAK Activations dialog appears.

  3. In the Multiple activation key text box, enter the MAK to activate the target devices.

  4. The number of booted target devices requiring activation display on the dialog. From the list of booted devices, check the box next to each target device that you want to activate.

  5. Click OK to activate licensing for all selected target devices. Do not close the dialog until the activation process is completed. The process can be stopped by clicking the Cancel button. Closing the dialog before the activation process completes stops the process might result in some target devices not being activated. The Status column indicates if a target device is being activated or failed. If all target devices were activated successfully, click OK to close the dialog. If one or more target devices are not activated, or if devices were not activated successfully, the dialog displays any unactivated devices. After resolving any issues, repeat this step to activate the remaining target devices.

    Note:

    The Manage MAK Activations option does not display after all currently booted target devices have been successfully activated.

Maintaining MAK activations

Typically, devices and their assigned vDisk activations are preserved automatically. When a different target device is assigned a MAK activated vDisk, it removes any saved existing MAK reactivation information. If the vDisk is reassigned in the future, the target device fails to reactivate. To prevent the loss of MAK activation, do not unassign the activated disk from the target device.

To change a target device’s vDisk, without losing the MAK activation, select one of the following methods:

  • Assign more vDisks to the target device, without removing any, then set the default booting vDisk accordingly.
  • Assign more vDisks to the target device and temporarily disable the MAK activated vDisk.

For you to update a MAK activated vDisk, the Auto Update feature must be used so that the MAK activation information is maintained. This process is required for the shared device reactivation.

More MAK considerations:

  • Manual vDisk updates (unassigning one vDisk and reassigning another vDisk) results in the loss of the required MAK activation information. This process requires a new activation, which would consume another license.
  • Using auto update to deploy a new vDisk from a different OS results in mismatched MAK activation information. In this case, a new activation must be performed from the command line interface, as only unactivated target devices can be activated from the Citrix Provisioning console.