Apply updates by using the xe CLI

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

To receive updates, your XenServer hosts require internet access. If your hosts are behind a firewall, ensure that they have access to subdomains of ops.xenserver.com. For more information, see Connectivity requirements.

Complete the following steps to be able to update your XenServer pools:

1. Install or upgrade to XenServer 8.

2. Configure updates for your pool.

3. Synchronize new updates for your pool.

4. Understand the guidance categories and update tasks.

5. View available updates for your pool.

6. Apply updates to your pool.

Configure updates for your pool

Before being able to apply updates to your XenServer hosts and pools, you must configure host updates by subscribing your pool or host to an update channel. These channels control how soon you can access updates that are made available in the content delivery network (CDN).

The two update channels are:

• Early Access - perfect for test environments
• Normal - recommended for production environments

After subscribing your pool to one of the update channels, your pool regularly and automatically synchronizes with the update channel. Alternatively, manually synchronize your pool with the update channel. This synchronization action downloads all available updates to the pool coordinator. You can then apply the downloaded updates by using the xe CLI.

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.

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

One or more of the following tasks might be required when applying an update. Any type of update task can be listed in any guidance category.

Update tasks for your host

You only ever carry this task out before applying updates and you sometimes carry it out as part of the ‘Reboot host’ task:

The following tasks require actions on the updated host:

View the update tasks required for your host

View the tasks required for your host before and after applying updates by using the following commands.

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

Update tasks for your VM

Some updates provide new features for your VMs. These updates might require the following tasks on your VMs:

View the update tasks required for your 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-->

View available updates for your pool

Before installing updates, view the available updates for your pool and review the update tasks required. For more information about the different update tasks that might be required for an update, see Understand the guidance categories and update tasks.

Check for available updates for a particular host

Check if there are any available updates for a particular host:

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

This command returns yes if there are updates available for a particular host and no if there are none available.

Check for available updates for all hosts

Check for available updates for all hosts by making a GET request on the HTTP endpoint /updates.

Get updates for all hosts by using the wget utility:

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

Alternatively, you can use the HTTP client library:

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

The output returned is in JSON format and contains the following objects:

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

The hosts and updates objects also contain the guidance object which consists of the following keys:

• mandatory
• recommended
• full
• livepatch

These keys refer to the different guidance categories for update tasks. They list the update tasks required for your hosts and VMs. For more information about the different tasks that might be required for an update, see Understand the guidance categories and update 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-disable 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.