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:
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.
-
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--> -
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--> -
Using the repository UUID, view more details about a particular repository:
xe repository-param-list uuid=<UUID> <!--NeedCopy--> -
(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.
-
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--> -
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--> -
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:
- Mandatory
- Mandatory + Recommended
- 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:
| Update task | xe CLI command to carry out task | Description |
|---|---|---|
| Evacuate host | xe host-evacuate |
Migrate all VMs off the XenServer host or shut them down. While this task is in progress, the XenServer pool is operating at reduced capacity as one host is temporarily unavailable to run VMs. |
The following tasks require actions on the updated host:
| Update task | xe CLI command to carry out task | Description |
|---|---|---|
| Reboot host | xe host-reboot |
The XenServer host must be restarted. Any VMs are migrated off the host and the host is restarted. While this task is in progress, the XenServer pool is operating at reduced capacity as one host is temporarily unavailable to run VMs. |
| Reboot host on Xen live patch failure | xe host-reboot |
Applying a Xen live patch failed. The XenServer host must be restarted to get the update to take effect. Any VMs are migrated off the host and the host is restarted. While this task is in progress, the XenServer pool is operating at reduced capacity as one host is temporarily unavailable to run VMs. |
| Reboot host on kernel live patch failure | xe host-reboot |
Applying a dom0 kernel live patch failed. The XenServer host must be restarted to get the update to take effect. Any VMs are migrated off the host and the host is restarted. While this task is in progress, the XenServer pool is operating at reduced capacity as one host is temporarily unavailable to run VMs. |
| Restart toolstack | xe-toolstack-restart |
The toolstack on the host must be restarted. Restart the toolstack on the updated host instead of the pool coordinator. When the toolstack is restarted on the pool coordinator, the connection to the pool is lost but when the toolstack is restarted on other pool members, there is no visible effect. |
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:
| Update task | xe CLI command to carry out task | Description |
|---|---|---|
| Restart VM | xe vm-reboot |
The VM must be restarted. While the VM is restarting, the VM is unavailable to the end user. |
| Restart device model | xe vm-restart-device-models |
The device model for VMs on the updated host must be restarted. While the device model is restarting, you can’t stop, start, or migrate the VM. The end user of the VM might see a slight pause and resume in their session. For the restart device model action to be supported on a Windows VM, the VM must have the XenServer VM Tools for Windows installed. |
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: Theupdate_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:
mandatoryrecommendedfulllivepatch
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:
-
Disable the host:
xe host-disable uuid=<host UUID> <!--NeedCopy--> -
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.
-
Apply updates to the host:
xe host-apply-updates uuid=<host UUID> hash=<update_checksum> <!--NeedCopy--> -
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:
- Restart toolstack (can be skipped if there is a ‘Reboot host’ to be carried out)
- Reboot host
-
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:
- Restart device model (can be skipped if there is a ‘Restart VM’ to be carried out)
- Restart VM
-
Enable the host if it is still in a disabled state:
xe host-enable uuid=<host UUID> <!--NeedCopy--> -
For every VM which you migrated to another host using
host-evacuatebefore 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.
-
Resume or start the VMs that you shut down or suspended before you applied updates.
-
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.
-
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.
-
Enable HA if you disabled it before applying updates:
pool_uuid=$(xe pool-list --minimal) xe pool-ha-disable uuid=<pool_uuid> <!--NeedCopy--> -
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--> -
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.