Update your XenServer hosts by using the XenServer PowerShell module
Overview
Complete the following steps to update your XenServer pools:
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 may not work.
Configure updates for your pool
Updates from the Content Delivery Network
To receive updates from the Content Delivery Network (CDN), 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.
Before being able to apply updates to your XenServer hosts and pools, you must subscribe your hosts or pools to the Early Access or Normal update channel. These channels control how soon you can access updates that are made available in the CDN. Follow these steps to configure updates:
-
Create and enable the Early Access update channel for your pool:
$baseBinUrl = "https://repo.ops.xenserver.com/xs8/base" $baseSrcUrl = "https://repo-src.ops.xenserver.com/xs8/base" $baseRepo = Invoke-XenRepository -Name "dummy" -XenAction Introduce` -BinaryUrl $baseBinUrl -SourceUrl $baseSrcUrl -Update $false ` -NameLabel "base_repo" -NameDescription "Base" -GpgkeyPath "" -PassThru $eaBinUrl = "https://repo.ops.xenserver.com/xs8/earlyaccess" $eaSrcUrl = "https://repo-src.ops.xenserver.com/xs8/earlyaccess" $updateRepo = Invoke-XenRepository -Name "dummy" -XenAction Introduce` -BinaryUrl $eaBinUrl -SourceUrl $eaSrcUrl -Update $true ` -NameLabel "early_access_repo" -NameDescription "Early Access" -GpgkeyPath "" -PassThru Get-XenPool | Add-XenPool -Repository $updateRepo.opaque_ref <!--NeedCopy-->Alternatively, create and enable the Normal update channel for your pool:
$baseBinUrl = "https://repo.ops.xenserver.com/xs8/base" $baseSrcUrl = "https://repo-src.ops.xenserver.com/xs8/base" $baseRepo = Invoke-XenRepository -Name "dummy" -XenAction Introduce` -BinaryUrl $baseBinUrl -SourceUrl $baseSrcUrl -Update $false ` -NameLabel "base_repo" -NameDescription "Base" -GpgkeyPath "" -PassThru $normBinUrl = "https://repo.ops.xenserver.com/xs8/normal" $normSrcUrl = "https://repo-src.ops.xenserver.com/xs8/normal" $updateRepo = Invoke-XenRepository -Name "dummy" -XenAction Introduce` -BinaryUrl $normBinUrl -SourceUrl $normSrcUrl -Update $true ` -NameLabel "normal_repo" -NameDescription "Normal" -GpgkeyPath "" -PassThru Get-XenPool | Add-XenPool -Repository $updateRepo.opaque_ref <!--NeedCopy-->Note:
If you want to switch from the Early Access to the Normal channel, or vice versa, you need to disable the previous update channel before enabling the new one:
Get-XenPool | Remove-XenPoolProperty -Repository $updateRepo.opaque_ref <!--NeedCopy--> -
Retrieve a list of the currently enabled repositories:
Get-XenPool | select -ExpandProperty repositories <!--NeedCopy--> -
View more details about the currently enabled repositories:
Get-XenPool | select -ExpandProperty repositories | Get-XenRepository <!--NeedCopy--> -
Optionally, you can configure and enable a proxy server to use for communication between your server and the CDN that hosts the repositories:
Get-XenPool | Invoke-XenPool -XenAction ConfigureRepositoryProxy -Url "http://proxy.example.com" ` -Username $proxyUser -Password $proxyPassword <!--NeedCopy-->View the proxy server configuration:
Get-XenPool | select repository_proxy_url,repository_proxy_username <!--NeedCopy-->Disable the proxy server configuration:
Get-XenPool | Invoke-XenPool -XenAction DisableRepositoryProxy <!--NeedCopy-->
Offline updates using update bundles
Before being able to apply offline updates, you must configure your host or pool to use the Offline update channel. Follow these steps:
-
Create the Offline update channel for your pool:
$offlineRepo = Invoke-XenRepository -Name "dummy" -XenAction IntroduceBundle ` -NameLabel "offline_repo" -NameDescription "Offline" -PassThru <!--NeedCopy-->This cmdlet creates a bundle repository that acts as the Offline update channel and stores the update bundle for offline application.
-
Enable the Offline update channel for your pool:
Get-XenPool | Add-XenPool -Repository $offlineRepo.opaque_ref <!--NeedCopy-->This cmdlet enables the bundle repository as the Offline update channel for your pool.
Note:
If you want to switch from one of the CDN channels (Early Access or Normal) to the Offline channel, or vice versa, you need to disable the previous channel before enabling the new one:
Get-XenPool | Remove-XenPoolProperty -Repository $repoToDisable.opaque_ref <!--NeedCopy-->
Obtain updates for your pool
Synchronize updates for your pool from CDN
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 them to your pool.
-
Set your pool to synchronize daily:
$pool = Get-XenPool Invoke-XenPool -Pool $pool -XenAction ConfigureUpdateSync -UpdateSyncFrequency daily Set-XenPool -Pool $pool -UpdateSyncEnabled $true <!--NeedCopy-->Alternatively, set your pool to synchronize weekly:
$pool = Get-XenPool Invoke-XenPool -Pool $pool -XenAction ConfigureUpdateSync -UpdateSyncFrequency weekly -UpdateSyncDay 0 # (0 is Sunday, 1 is Monday, etc.) Set-XenPool -Pool $pool -UpdateSyncEnabled $true <!--NeedCopy--> -
View your synchronization configuration:
Get-XenPool | select update_sync_frequency,update_sync_day,update_sync_enabled <!--NeedCopy--> -
Get the timestamp of your pool’s last successful synchronization with the update channel:
Get-XenPool | select last_update_sync <!--NeedCopy-->
Alternatively, you can manually synchronize your XenServer pool with the update channel:
$updateChecksum = Invoke-XenPool -Pool $pool -XenAction SyncUpdates -PassThru
<!--NeedCopy-->
$updateChecksum 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. $updateChecksum can also provide useful information if you need to contact Technical Support.
If you have configured a synchronization schedule, you can retrieve the update checksum at any time by querying the update channel used for the synchronization:
Get-XenPool | select -ExpandProperty repositories | Get-XenRepository | select hash
<!--NeedCopy-->
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.
Upload an update bundle to your pool
Upload an update bundle file:
$coordinator = Get-XenPool | select -ExpandProperty master | Get-XenHost
$task = New-XenTask -PassThru -Label "MyBundleUploadTask"
Send-XenBundle -XenHost $coordinator.address -Path $xsbundleFile -TaskRef $task.opaque_ref
$task | Wait-XenTask -ShowProgress
<!--NeedCopy-->
You can view the checksum of the uploaded bundle at any time by querying the Offline channel using the following cmdlet:
Get-XenPool | select -ExpandProperty repositories | Get-XenRepository | select hash
<!--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.
Quick check for available updates for a particular host
Check if there are any available updates for a particular host:
Get-XenHost -Uuid $hostUuid | select latest_synced_updates_applied
<!--NeedCopy-->
This cmdlet returns yes if there are updates available for a particular host and no if there are none available. See View available updates and required update tasks for all hosts for more information on how to view details on the available updates.
View available updates and required update tasks for all hosts
Check for available updates for all hosts by sending a GET request to the pool coordinator’s HTTP(S) endpoint /updates. This is achieved using the following cmdlets:
$jsonPath = $env:TEMP + [System.IO.Path]::GetRandomFileName()
$coordinator = Get-XenPool | select -ExpandProperty master | Get-XenHost
$task = New-XenTask -PassThru -Label "MyReceiveTask"
Receive-XenUpdates -XenHost $coordinator.address -Path $jsonPath -TaskRef $task.opaque_ref
$task | Wait-XenTask -ShowProgress
$jsonOutput = Get-Content -Raw -Path $jsonPath | ConvertFrom-Json
<!--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$updateChecksum(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.
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 hosts
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 | Cmdlet to carry out task | Description |
|---|---|---|
| Evacuate host | Invoke-XenHost -XenAction 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 | Cmdlet to carry out task | Description |
|---|---|---|
| Reboot host | Invoke-XenHost -XenAction 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 | Invoke-XenHost -XenAction 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 | Invoke-XenHost -XenAction 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 | Invoke-XenHost -XenAction RestartAgent |
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 hosts
See View available updates for your pool for information on how to review update tasks required for your hosts prior to applying updates to your pool.
After applying updates, view the mandatory, recommended, and full-effectiveness tasks required for your hosts by using the following cmdlet:
Get-XenHost -Uuid $hostUuid | `
select pending_guidances,pending_guidances_recommended,pending_guidances_full
<!--NeedCopy-->
Update tasks for your VMs
Some updates provide new features for your VMs. These updates might require the following tasks on your VMs:
| Update task | Cmdlet to carry out task | Description |
|---|---|---|
| Restart VM | Invoke-XenVM -XenAction CleanReboot |
The VM must be restarted. While the VM is restarting, the VM is unavailable to the end user. |
| Restart device model | Invoke-XenVM -XenAction RestartDeviceModels |
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 VMs
See View available updates for your pool for information on how to review update tasks required for your VMs prior to applying available updates to your pool.
After applying updates, view the mandatory, recommended, and full-effectiveness tasks required for your VMs by using the following cmdlet:
Get-XenVM -Uuid $vmUuid | `
select pending_guidances,pending_guidances_recommended,pending_guidances_full
<!--NeedCopy-->
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 pending update tasks required for your hosts and View the pending update tasks required for your VMs.
-
Disable High Availability (HA) if it is enabled:
Get-XenPool | Invoke-XenPool -XenAction DisableHa <!--NeedCopy--> -
Disable Workload Balancing (WLB) if it is enabled:
Get-XenPool | Set-XenPool -WlbEnabled $false <!--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:
Invoke-XenHost -Ref $hostRef -XenAction Disable <!--NeedCopy--> -
If one of the update tasks required for the update is ‘Evacuate host’ or ‘Reboot host’, evacuate the host:
Invoke-XenHost -Ref $hostRef -XenAction Evacuate <!--NeedCopy-->If you can’t migrate any VMs to other hosts during the host evacuation, shut down or suspend the VMs.
-
Apply updates to the host:
Invoke-XenHost -Ref $hostRef -XenAction ApplyUpdates ` -Hash $updateChecksum -Async -PassThru | Wait-XenTask <!--NeedCopy-->
View and carry out the required update tasks
-
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 post-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:
Invoke-XenHost -Ref $hostRef -XenAction Enable <!--NeedCopy--> -
For every VM which you migrated to another host using
Invoke-XenHost -XenAction 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:
Get-XenHost | select last_software_update,latest_synced_updates_applied,last_update_hash <!--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:
Get-XenPool | Invoke-XenPool -XenAction EnableHa <!--NeedCopy--> -
Enable WLB if you disabled it before applying updates:
Get-XenPool | Set-XenPool -WlbEnabled $true <!--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.