Apply updates by using the xe CLI

Apply updates to your XenServer 8.4 hosts and pools by using the xe CLI.

Complete the following steps to update your XenServer® pools:

1. Configure updates for your pool.

   You can configure updates for a pool or standalone host from the following locations:

   • An update channel on the content delivery network (CDN). This method is recommended for internet-connected pools.
   • An offline update from a downloaded bundle This alternative method is intended for use when internet connectivity to your XenServer hosts is unavailable or restricted

   In addition, you can configure updates for a standalone host from the following location:

   • An existing pool. This method enables you to bring a standalone host up to the same level of updates as a pool. It is recommended for joining a newly installed host to a pool that is not at the latest level of updates.

2. Synchronize your pool with your configured update channel.

3. View available updates for your pool.

4. Understand the guidance categories and update tasks.

5. Apply updates to your pool.

6. Complete any pending update tasks.

Updates from the CDN

To update from the CDN, your environment must meet the following prerequisites:

• Ensure that your XenServer hosts have internet access and can connect to the required update domains.
• If your hosts are behind a firewall, allow access to subdomains of ops.xenserver.com. For more information, see Connectivity requirements.

Note:

Applying updates is only assured to work when the previous state of the pool is less than six months old. If you haven’t applied updates for more than six months, updating to the latest update level is not tested and is not assured.

Configure a CDN updates channel

Follow these steps to configure your hosts for applying updates from the CDN:

1. Create and enable the Early Access update channel for your pool:

   pool_uuid=$(xe pool-list --minimal)
   
   base_binary_url="https://repo.ops.xenserver.com/xs8/base"
   base_source_url="https://repo-src.ops.xenserver.com/xs8/base"
   base_repo_uuid=$(xe repository-introduce name-label=base_repo name-description=Base binary-url=<base_binary_url> source-url=<base_source_url> update=false)
   
   update_binary_url="https://repo.ops.xenserver.com/xs8/earlyaccess"
   update_source_url="https://repo-src.ops.xenserver.com/xs8/earlyaccess"
   update_repo_uuid=$(xe repository-introduce name-label=early_access_repo name-description="Early Access" binary-url=<update_binary_url> source-url=<update_source_url> update=true)
   
   xe pool-param-set uuid=$pool_uuid repositories=<base_repo_uuid>,<update_repo_uuid>
   <!--NeedCopy-->
   

   Alternatively, create and enable the Normal update channel for your pool:

   pool_uuid=$(xe pool-list --minimal)
   
   base_binary_url="https://repo.ops.xenserver.com/xs8/base"
   base_source_url="https://repo-src.ops.xenserver.com/xs8/base"
   base_repo_uuid=$(xe repository-introduce name-label=base_repo name-description=Base binary-url=<base_binary_url> source-url=<base_source_url> update=false)
   
   update_binary_url="https://repo.ops.xenserver.com/xs8/normal"
   update_source_url="https://repo-src.ops.xenserver.com/xs8/normal"
   update_repo_uuid=$(xe repository-introduce name-label=normal name-description="Normal" binary-url=<update_binary_url> source-url=<update_source_url> update=true)
   
   xe pool-param-set uuid=$pool_uuid repositories=<base_repo_uuid>,<update_repo_uuid>
   <!--NeedCopy-->
   

2. Retrieve a list of the currently enabled repository UUIDs:

   pool_uuid=$(xe pool-list --minimal)
   xe pool-param-get uuid=$pool_uuid param-name=repositories
   <!--NeedCopy-->
   

3. Using the repository UUID, view more details about a particular repository:

   xe repository-param-list uuid=<UUID>
   <!--NeedCopy-->
   

4. (Optional) Configure and enable an HTTP connect proxy server that is used for communication between the host and the public CDN that hosts the repositories:

   xe pool-configure-repository-proxy proxy-url=<http://proxy.example.com> proxy-username=<proxy-user> proxy-password=<proxy-password>
   <!--NeedCopy-->
   

   Disable the proxy server configuration:

   xe pool-disable-repository-proxy
   <!--NeedCopy-->
   

   View the proxy server configuration:

   pool_uuid=$(xe pool-list --minimal)
   xe pool-param-get uuid=$pool_uuid param-name=repository-proxy-url
   xe pool-param-get uuid=$pool_uuid param-name=repository-proxy-username
   <!--NeedCopy-->
   

Synchronize new updates for your pool

Enable your pool to automatically synchronize with the update channel by configuring a synchronization schedule. You can schedule a synchronization to take place daily or weekly on a certain day of the week. Synchronizing your pool with the update channel downloads all available updates to the pool coordinator and you can then apply all downloaded updates to your pool.

1. Set your pool to synchronize daily:

   xe pool-configure-update-sync update-sync-frequency=daily update-sync-day=0
   xe pool-set-update-sync-enabled value=true
   <!--NeedCopy-->
   

   Alternatively, set your pool to synchronize weekly:

   xe pool-configure-update-sync update-sync-frequency=weekly update-sync-day=1 (# 0 is Sunday, 1 is Monday, etc)
   xe pool-set-update-sync-enabled value=true
   <!--NeedCopy-->
   

2. View your synchronization configuration:

   pool_uuid=$(xe pool-list --minimal)
   xe pool-param-get uuid=$pool_uuid param-name=update-sync-frequency
   xe pool-param-get uuid=$pool_uuid param-name=update-sync-day
   xe pool-param-get uuid=$pool_uuid param-name=update-sync-enabled
   <!--NeedCopy-->
   

3. Get the timestamp of your pool’s last successful synchronization with the update channel:

   pool_uuid=$(xe pool-list --minimal)
   xe pool-param-get param-name=last-update-sync uuid=$pool_uuid
   <!--NeedCopy-->
   

Alternatively, you can manually synchronize your XenServer pool with the update channel:

pool_uuid=$(xe pool-list --minimal)
update_checksum=$(xe pool-sync-updates uuid=$pool_uuid --minimal)
<!--NeedCopy-->

The update_checksum unique identifier indicates the level of the updates installed. It changes whenever new updates are made available in the public CDN. This checksum is later used when applying updates to your pool to ensure that you are always applying the latest available updates. The value of update_checksum can also provide useful information if you need to contact Technical Support.

Note:

After synchronizing, apply the updates to your pool as soon as possible to benefit from the latest updates.

If you designate a new pool coordinator after synchronizing but before applying updates to the hosts in the pool, you must synchronize again with the new pool coordinator before you can update the pool.

Do not synchronize your XenServer pool while the pool is in the process of being updated.

Now that your pool is synchronized with the channel, you can view and apply the available updates. Next step: View available updates for your pool.

Offline updates

Offline updates have the following prerequisites:

• Your host must be installed with the ISO published on October 7, 2024, or later.
• You must use XenCenter version 2024.4.0 or later to apply update bundles.

Configure the offline updates channel

Follow these steps to configure your pool to use an offline updates channel:

1. Create the offline update channel for your pool:

   xe repository-introduce-bundle name-label=<name-label> [name-description=<name-description>]
   <!--NeedCopy-->
   

   This command creates a bundle repository that acts as the Offline update channel and stores the update bundle for offline application. It returns the repository UUID. Note this UUID to use later in Install updates.

2. Enable the offline update channel for your pool:

   xe pool-param-set repositories=<bundle-repository-uuid> uuid=<pool_uuid>
   <!--NeedCopy-->
   

   This command enables the bundle repository as the offline update channel for your pool.

Synchronize a new update bundle for your pool

After configuring your pool to use the offline update channel, you can follow these steps every time you want to synchronize and update from a new bundle.

1. Download the latest update bundle from the following page using your dedicated internet-connected machine: Download XenServer update bundles.

2. Transfer the update bundle to the system where you run xe CLI commands. If you are transferring the bundle file onto a host in your pool, ensure that you delete it after synchronizing to reclaim disk space.

3. Upload and synchronize the update bundle file.

   xe pool-sync-bundle filename=<bundle-file-path>
   <!--NeedCopy-->
   

4. Delete the bundle file:

   rm <bundle-file-path>
   <!--NeedCopy-->
   

Note:

If you designate a new pool coordinator after synchronizing but before applying updates to the hosts in the pool, you must synchronize again with the new pool coordinator before you can update the pool.

Do not synchronize your XenServer pool while the pool is in the process of being updated.

Now that your pool is synchronized with the update bundle, you can view and apply the available updates. Next step: View available updates for your pool.

Update a host to pool level

This method enables you to update a standalone XenServer 8.4 host to the same level of updates as a XenServer 8.4 pool. The pool must be at a more recent level of updates than the standalone host. Use this process to more easily join a new host to an existing pool without having to update every host in the pool.

Pool-level update synchronizes the standalone host with the pool and updates from update files held on the pool coordinator. However, if the pool coordinator has changed since the pool was last updated, this capability might not be available for your pool because the current pool coordinator does not hold the update files.

Configure a pool as an update channel

Follow these steps to configure your host to use another pool as an updates channel:

1. On the coordinator of the pool you are using as the updates channel, get the server certificate:

   xe host-get-server-certificate uuid=<remote_pool_coordinator_uuid>
   <!--NeedCopy-->
   

   The command outputs the certificate. Copy this information to your clipboard or keep it where you can access it in the next step.

2. On the host that you want to update, create a temporary file and copy into it the output from the previous command.

   For example:

   vi ~/tmp/certificate.pem
   <!--NeedCopy-->
   

3. Check that the remote pool has the latest synchronized updates applied to it, before configuring it as an update channel. The following command must return true:

   xe host-param-get uuid=<remote_pool_coordinator_uuid> param-name=latest-synced-updates-applied
   <!--NeedCopy-->
   

   If the command returns false, apply the synchronized updates to the remote pool before continuing to the next step.

4. Create the remote pool update channel for your host:

   xe repository-introduce-remote-pool name-label=<name_label> binary-url=https://<url_to_pool_coordinator>/repository/enabled certificate-file=<path_to_certificate> [name-description=<name-description>]
   <!--NeedCopy-->
   

   • The value of the binary-url parameter is the URL address to the pool coordinator, either as an FQDN or IP address, with the path /repository/enabled appended.
   • The value of the certificate-file parameter is the path to the temporary certificate file that you created in the previous step.

The command returns the repository UUID. Note the UUID for later use when installing updates.

1. Enable the remote pool update channel for your pool:

   xe pool-param-set repositories=<remote_pool_repository_uuid>
   <!--NeedCopy-->
   

   This command enables the repository information on the remote pool coordinator as the update channel for your pool.

Synchronize the host with the pool

Manually synchronize your XenServer host with the remote pool update channel.

1. Run the following command on your standalone host:

   xe pool-sync-updates username=root password=<password>
   <!--NeedCopy-->
   

   Provide the user name and password for the coordinator of the pool you are updating from.

The command returns a checksum that acts as a unique identifier indicating the level of the updates available to be installed.

Note:

After synchronizing, apply the updates to your pool as soon as possible to benefit from the latest updates.

Do not synchronize your XenServer host while the host is in the process of being updated.

Now that your host is synchronized with the pool, you can view and apply the available updates. Next step: View available updates for your pool.

View available updates for your pool

Before applying updates, view the available updates for your pool and complete any required pre-update tasks. For more information about the different update tasks, see Understand the guidance categories and update tasks.

Check for available updates for a particular host

To check if there are any available updates for a particular host after, run the following command:

xe host-param-get param-name=latest-synced-updates-applied uuid=<host_uuid>
<!--NeedCopy-->

This command returns yes if all the synchronized updates are applied to the host and no if there are synchronized updates available to be applied.

Note:

This command checks only synchronized updates. There might be newer updates available on the update channel that haven’t yet been synchronized to the pool. For information about how to synchronize, see Synchronize new updates for your pool for CDN updates or Synchronize a new update bundle for your pool for offline updates.

Check for available updates for all hosts

1. Check for available updates for all hosts by making a GET request on the HTTP endpoint /updates. This retrieves the metadata for available updates. You can access the endpoint by sending a request to https://<myserver>/updates.

   Use the wget utility:

   wget -O - --no-check-certificate https://<user name>:<password>@<coordinator IP address>/updates
   <!--NeedCopy-->
   

   You can also use an HTTP client library with the following parameters:

   HTTP GET
   session_id: <XAPI session ID returned from login>
   host_refs: <host XAPI reference>
   <!--NeedCopy-->
   

2. Inspect the JSON response returned by the request. The response contains metadata about the available updates, including:

   • hosts: Lists the available updates for individual hosts.

   • updates: Lists the details of the available updates.

   • hash: The update_checksum (used to ensure that you are always applying the latest available updates).

3. Review the guidance object within the hosts and updates objects. This object includes the following keys:

   • mandatory
   • recommended
   • full
   • livepatch

   These categories outline all the update tasks associated with the updates that you are applying. Perform the necessary pre-update tasks based on the guidance categories. For more information about these categories, see Understand the guidance categories and update tasks.

Next step: Apply updates to your pool

Understand the guidance categories and update tasks

Some tasks (such as evacuating or rebooting your hosts) might be required before and after applying updates to your pool. Sometimes, there are no update tasks required.

Guidance categories

XenServer tries to minimize the disruption to your VMs that these tasks might cause by categorizing the tasks into Mandatory, Recommended, Full-effectiveness, and Live patch. These categorizations enable you to judge whether an update task that might cause downtime or minor disruption for your hosts or VMs is necessary for your environment and risk profile.

Updates can have tasks listed in more than one of these categories. For example, an update might require that you restart the host to get the full-effectiveness of the update, but recommend restarting the toolstack to get most of the benefit of the update with less potential disruption to the pool.

During the update process, you can choose to carry out one of the following three levels of tasks:

1. Mandatory
2. Mandatory + Recommended
3. Mandatory + Recommended + Full-effectiveness

Mandatory

Mandatory tasks must be performed after an update otherwise the system might fail at runtime. These actions are required to enable critical fixes and ensure that your environment is secure and stable. You cannot opt out of mandatory tasks.

Recommended

Recommended tasks are the tasks that we recommend you perform to get the benefit from most of the features and fixes delivered in the updates. If you choose not to perform these tasks now, they are listed in the pending update tasks for the applicable pool, host, or VM.

Why perform the recommended tasks:

• These tasks are the ones that ensure a secure, stable XenServer environment.

Why opt out of the recommended tasks:

• After reviewing the detailed information for the updates, you judge that the risk of not fully applying these updates now is acceptable.
• The recommended tasks cause unwanted disruption to your VMs now.

Full-effectiveness

Full effectiveness tasks are required to get the benefit of the related update. The updates that have full-effectiveness tasks associated with them are relevant only to users on certain hardware or using specific features.

Review the update information to understand whether these tasks are required for your environment. If you choose not to perform these tasks now, they are listed in the pending tasks for the applicable pool, host, or VM.

Why perform the full-effectiveness tasks:

• The updates that have full-effectiveness tasks are relevant to your hardware, environment, or configuration.

Why opt out of the full-effectiveness tasks:

• The updates that have full-effectiveness guidance are not relevant to your hardware, environment, or configuration.
• The full-effectiveness tasks cause unwanted disruption to your VMs now.
• You do not need the benefits of these updates right now.

If the full-effectiveness tasks apply to your environment, but you have opted to defer them, plan to complete these tasks during a suitable maintenance window to maintain the stability of your environment.

Live patches

Updates to certain components can include a live patch. A live patch enables updates to be applied to core components without requiring a host reboot.

Whether a live patch can be applied to your hosts depends on the version of the component that was installed when the hosts were last rebooted. If an update can be applied as a live patch to your hosts, the live patch guidance replaces the recommended guidance.

Example:

You have two pools. Pool A is updated to a recent level. Pool B has not been updated for some time. We release a new update that has the recommended update task “Restart host” and the live patch update task “Restart toolstack”.

In pool A, the live patch can be applied to these more up-to-date hosts. The recommended guidance shows “Restart toolstack”. The less disruptive task from the live patch guidance overrides the recommended guidance.

In pool B, the live patch cannot be applied to the hosts as they are at an older level. The recommended guidance shows “Restart host”. The recommended guidance remains applicable. The live patch guidance is irrelevant in this case.

Sometimes only some of the fixes in an update are enabled when the update is applied as a live patch. In this situation, you might still see a recommended reboot for an update even though the live patch applies. Review the update details to understand whether you need all fixes in the update or just those fixes enabled by the live patch. You can then use this information to choose whether to perform the tasks. For more information, see View available updates for your pool.

Update tasks

Applying updates might require you to complete one or more tasks, either before or after the updates are applied. These tasks can appear in any guidance category. The following tables outline these tasks, their associated xe CLI commands, and descriptions of what they involve.

Update tasks for hosts

Tasks required before applying updates:

Tasks required after applying updates:

Update tasks for VMs

Some updates introduce new features for VMs, requiring the following tasks:

Apply updates to your pool

Before you start

• Ensure that all the hosts in your pool are online before carrying out the pool update.

• Ensure that there are no pending mandatory update tasks on any host or VM. Any mandatory update tasks pending from previous updates must be carried out before starting a new pool update. For more information, see View the update tasks required for your host and View the update tasks required for your VM.

• Disable High Availability (HA) if it is enabled:

   pool_uuid=$(xe pool-list --minimal)
   xe pool-ha-disable uuid=$pool_uuid
   <!--NeedCopy-->
  

• Disable Workload Balancing (WLB) if it is enabled:

   pool_uuid=$(xe pool-list --minimal)
   xe pool-param-set wlb-enabled=false uuid=$pool_uuid
   <!--NeedCopy-->
  

Install updates

To perform an update to your pool, you must apply updates on every host in the pool, starting with the pool coordinator first. Follow these steps, starting with the pool coordinator:

1. Disable the host:

   xe host-disable uuid=<host_uuid>
   <!--NeedCopy-->
   

2. If one of the update tasks required for the update is ‘Evacuate host’ or ‘Reboot host’, evacuate the host:

   xe host-evacuate uuid=<host_uuid>
   <!--NeedCopy-->
   

   If you can’t migrate a VM to other hosts during the host evacuation, shut down or suspend the VM.

3. Apply updates to the host:

   1. Get the update checksum of the updates to apply:

      xe repository-param-get uuid=<repository UUID> param-name=hash
      <!--NeedCopy-->
      

   2. Use this checksum to apply the set of updates:

      xe host-apply-updates uuid=<host_uuid> hash=<update_checksum>
      <!--NeedCopy-->
      

4. Get a list of the host update tasks required. For more information, see Update tasks for your host.

   Carry out the host’s update tasks in the list in the following order:

   1. Restart toolstack (can be skipped if there is a ‘Reboot host’ to be carried out)
   2. Reboot host

5. For every running VM on the host, get a list of the VM update tasks required. For more information, see Update tasks for your VM.

   Carry out the VM’s update tasks in the list in the following order:

   1. Restart device model (can be skipped if there is a ‘Restart VM’ to be carried out)
   2. Restart VM

6. Enable the host if it is still in a disabled state:

   xe host-enable uuid=<host_uuid>
   <!--NeedCopy-->
   

7. For every VM which you migrated to another host using host-evacuate before the host update, get a list of the update tasks. For more information, see Update tasks for your VM.

   If ‘Restart VM’ is in the list of update tasks, shut down the VM and start it on the current updated host. Otherwise, migrate the VM back to the current updated host.

8. Resume or start the VMs that you shut down or suspended before you applied updates.

9. View the host update status:

   xe host-param-get param-name=last-software-update uuid=<host_uuid>
   xe host-param-get param-name=latest-synced-updates-applied uuid=<host_uuid>
   xe host-param-get param-name=last-update-hash uuid=<host_uuid>
   <!--NeedCopy-->
   

Repeat the preceding steps to update every host in your pool.

After updating your hosts

After updating each host in your pool, carry out any remaining update tasks.

1. For every VM in your pool, get a list of the update tasks. For more information, see Update tasks for your VM.

   If ‘Restart VM’ is in the list of update tasks, carry it out.

2. Enable HA if you disabled it before applying updates:

   pool_uuid=$(xe pool-list --minimal)
   xe pool-ha-enable uuid=$pool_uuid
   <!--NeedCopy-->
   

3. Enable WLB if you disabled it before applying updates:

   pool_uuid=$(xe pool-list --minimal)
   xe pool-param-set wlb-enabled=true uuid=$pool_uuid
   <!--NeedCopy-->
   

4. If you chose to carry out only the mandatory update tasks required for a pool update, the update tasks that have not been carried out are appended to the list of pending update tasks required for your hosts. To view this list and carry out these tasks, see Complete any pending update tasks.

Complete any pending update tasks

After applying updates, complete any pending update tasks to ensure your hosts and VMs operate as expected. Use the following commands to view the required tasks.

View pending tasks for a host

Get a list of the mandatory tasks for your host:

xe host-param-get param-name=pending-guidances uuid=<host_uuid>
<!--NeedCopy-->

Get a list of the recommended tasks for your host:

xe host-param-get param-name=pending-guidances-recommended uuid=<host_uuid>
<!--NeedCopy-->

Get a list of the full-effectiveness tasks for your host:

xe host-param-get param-name=pending-guidances-full uuid=<host_uuid>
<!--NeedCopy-->

View pending tasks for a VM

Get a list of the mandatory tasks for your VM:

xe vm-param-get param-name=pending-guidances uuid=<VM UUID>
<!--NeedCopy-->

Get a list of the recommended tasks for your VM:

xe vm-param-get param-name=pending-guidances-recommended uuid=<VM UUID>
<!--NeedCopy-->

Get a list of the full-effectiveness tasks for your VM:

xe vm-param-get param-name=pending-guidances-full uuid=<VM UUID>
<!--NeedCopy-->