Apply updates by using the xe CLI

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

Complete the following steps to update your XenServer pools:

1. Install or upgrade to XenServer 8.

2. Configure updates for your pool.

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.

Configure updates for your pool

Updates from the CDN

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 might not work.

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 which 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 of the 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-->

update_checksum is a unique identifier that indicates the level of the updates installed. It changes whenever new updates are made available in the public CDN and is later used when applying updates to your pool to ensure that you are always applying the latest available updates. 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.

Offline Updates

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.

Follow these steps to configure Offline Updates:

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 your air-gapped XenCenter.

3. 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.

4. Enable the Offline update channel for your pool:

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

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

5. Upload and synchronize an update bundle file.

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

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, run the following command:

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

This command returns yes if there are updates available for the host and no if there are no updates available.

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 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.

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 of the majority of 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 usually 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. 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. 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 recommended 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 tables below 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:

   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 steps above 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 Update tasks for your host.

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-->