Skip to content

Update Machine Catalog to propagate changes applied to the Master Image

Applicable Products

  • XenDesktop


By following the steps provided in this article you will be able to apply changes to the Master Image and propagate those changes to the machines in the Machine Catalogs in question.


Citrix recommends that you save copies or snapshots of master images before you update the machines in the catalog. The database keeps an historical record of the master images used with each machine catalog. You can roll back (revert) machines in a catalog to use the previous version of the master image if users encounter problems with updates you deployed to their desktops, thereby minimizing user downtime. Do not delete, move, or rename master images; otherwise, you will not be able to revert a catalog to use them.

For catalogs that use Provisioning Services, you must publish a new vDisk to apply changes to the catalog. For details, see the Provisioning Services documentation.

After a machine is updated, it restarts automatically.

Update or create a new master image

Before you update the catalog, either update an existing master image or create a new one on your host hypervisor.

  1. On your hypervisor or cloud service provider, take a snapshot of the current VM and give the snapshot a meaningful name. This snapshot can be used to revert (roll back) machines in the catalog, if needed.
  2. If necessary, power on the master image, and log on.
  3. Install updates or make any required changes to the master image.
  4. If the master image uses a personal vDisk, update the inventory.
  5. Power off the VM.
  6. Take a snapshot of the VM, and give the snapshot a meaningful name that will be recognized when the catalog is updated in Studio. Although Studio can create a snapshot, Citrix recommends that you create a snapshot using the hypervisor management console, and then select that snapshot in Studio. This enables you to provide a meaningful name and description rather than an automatically generated name. For GPU master images, you can change the master image only through the XenServer XenCenter console.

Update the catalog

To prepare and roll out the update to all machines in a catalog:

  1. Select Machine Catalogs in the Studio navigation pane.
  2. Select a catalog and then select Update Machines in the Actions pane.
  3. On the Master Image page, select the host and the image you want to roll out.
  4. On the Rollout Strategy page, choose when the machines in the Machine Catalog will be updated with the new master image: on the next shutdown or immediately. See below for details.
  5. Verify the information on the Summary page and then click Finish. Each machine restarts automatically after it is updated.

If you are updating a catalog using the PowerShell SDK directly, rather than Studio, you can specify a hypervisor template (VMTemplates), as an alternative to an image or a snapshot of an image.

Rollout strategy

Updating the image on the next shutdown is provided when you are using the Citrix Connector for System Center Configuration Manager.

If you choose to update the image immediately, configure a distribution time and notifications.

  • Distribution time: You can choose to update all machines at the same time, or specify the total length of time it should take to begin updating all machines in the catalog. An internal algorithm determines when each machine is updated and restarted during that interval.
  • Notification: In the left notification dropdown, choose whether to display a notification message on the machines before an update begins. By default, no message is displayed. If you choose to display a message 15 minutes before the update begins, you can choose (in the right dropdown) to repeat the message every five minutes after the initial message. By default, the message is not repeated. Unless you choose to update all machines at the same time, the notification message displays on each machine at the appropriate time before the update begins, calculated by an internal algorithm.