From c34d2fc1173eec08b5e976b698c3730def104b99 Mon Sep 17 00:00:00 2001 From: Thomas Moraine Date: Tue, 14 Apr 2026 14:11:46 +0200 Subject: [PATCH 1/6] doc(ha.md): explain how to prevent automatic reboots By default, HA-protected VMs reboot automatically after being shut down. This commit updates the XCP-ng documentation to explain how to disable HA features on a VM or an entire pool, to prevent VMs from restarting automatically after getting shut down. Signed-off-by: Thomas Moraine --- docs/management/ha.md | 34 ++++++++++++++++++++++++++++++++++ 1 file changed, 34 insertions(+) diff --git a/docs/management/ha.md b/docs/management/ha.md index 1fc5a182..8fbe18c6 100644 --- a/docs/management/ha.md +++ b/docs/management/ha.md @@ -175,6 +175,8 @@ The **default timeout is 60 seconds**, but you can adjust this value using the f xe pool-param-set uuid= other-config:default_ha_timeout= ``` + + ## 🔧 Updates/maintenance Before any update or host maintenance, planned reboot and so on, **ALWAYS** put your host in maintenance mode. If you don't do that, XAPI will think it's an unplanned failure, and will act accordingly. @@ -204,6 +206,38 @@ As a result, VMs that are shut down internally or through the API will restart t ::: +#### Configure VM shutdown behavior + +If you don't want a VM to reboot automatically when it has been shut down from the guest OS: +1. Disable its HA protection. +2. Adjust the VM reboot behavior with the parameter called `Pool.ha_reboot_vm_on_internal_shutdown` (see below). + +:::warning +Applying these changes on your entire VM pool means that your VMs will stay off after they have been shut down, until you restart them yourself. Your VMs will no longer be protected from accidental shutdowns. +::: + +##### Disabling HA on specific VMs + +You can adjust the reboot behavior for a specific HA-protected VM: + +- **Using the `xe` cli:** : + - To disable HA features, run `xe vm-param-set uuid= ha-restart-priority=`. + - To (re-)enable HA features, run `xe vm-param-set uuid= ha-restart-priority=restart` or `xe vm-param-set uuid= ha-restart-priority=best-effort`. +- **Using Xen Orchestra**: + To change the VM reboot behavior from Xen Orchestra, check out the instructions in the [Xen Orchestra documentation](https://docs.xen-orchestra.com/manage_infrastructure#vm-high-availability-ha). + +:::tip +Once HA features have been disabled on your VM, shut the VM down. Once you have started the VM again, feel free to enable HA again. +::: + +##### Disabling HA on the whole pool + +You can prevent automatic reboots on your entire pool. To do this, use the `xe` CLI to run this command: + +`xe pool-param-set uuid=$UUID ha-reboot-vm-on-internal-shutdown=false`. + +To enable automatic reboots again, set the parameter to `true` instead of `false`. + ### Host failure We'll see 3 different scenarios for the host, with an example on 2 hosts, **lab1** and **lab2**: From dab078cfb85e9305a6882799bc17c25cb1f3a74b Mon Sep 17 00:00:00 2001 From: Thomas Moraine Date: Tue, 14 Apr 2026 15:03:02 +0200 Subject: [PATCH 2/6] split and clarify warnings, as suggested by psafont Signed-off-by: Thomas Moraine --- docs/management/ha.md | 16 +++++++++------- 1 file changed, 9 insertions(+), 7 deletions(-) diff --git a/docs/management/ha.md b/docs/management/ha.md index 8fbe18c6..9290b075 100644 --- a/docs/management/ha.md +++ b/docs/management/ha.md @@ -208,13 +208,7 @@ As a result, VMs that are shut down internally or through the API will restart t #### Configure VM shutdown behavior -If you don't want a VM to reboot automatically when it has been shut down from the guest OS: -1. Disable its HA protection. -2. Adjust the VM reboot behavior with the parameter called `Pool.ha_reboot_vm_on_internal_shutdown` (see below). - -:::warning -Applying these changes on your entire VM pool means that your VMs will stay off after they have been shut down, until you restart them yourself. Your VMs will no longer be protected from accidental shutdowns. -::: +If you don't want a VM to reboot automatically when it has been shut down from the guest OS: disable its HA protection, then adjust the VM reboot behavior with the parameter called `Pool.ha_reboot_vm_on_internal_shutdown` (see below). ##### Disabling HA on specific VMs @@ -226,6 +220,10 @@ You can adjust the reboot behavior for a specific HA-protected VM: - **Using Xen Orchestra**: To change the VM reboot behavior from Xen Orchestra, check out the instructions in the [Xen Orchestra documentation](https://docs.xen-orchestra.com/manage_infrastructure#vm-high-availability-ha). +:::warning +Applying these changes means that your VMs will stay off after they have been shut down, until you restart them yourself. +::: + :::tip Once HA features have been disabled on your VM, shut the VM down. Once you have started the VM again, feel free to enable HA again. ::: @@ -238,6 +236,10 @@ You can prevent automatic reboots on your entire pool. To do this, use the `xe` To enable automatic reboots again, set the parameter to `true` instead of `false`. +:::warning +By applying these changes to your entire pool, you disable the protection that prevents VMs from being shut down by their own guest OS. +::: + ### Host failure We'll see 3 different scenarios for the host, with an example on 2 hosts, **lab1** and **lab2**: From 1c6bbe1b9612215df26416f53e52b95132491d34 Mon Sep 17 00:00:00 2001 From: Thomas Moraine Date: Wed, 15 Apr 2026 13:59:57 +0200 Subject: [PATCH 3/6] apply changes suggested by stormi Signed-off-by: Thomas Moraine --- docs/management/ha.md | 42 +++++++++++++----------------------------- 1 file changed, 13 insertions(+), 29 deletions(-) diff --git a/docs/management/ha.md b/docs/management/ha.md index 9290b075..78184f4b 100644 --- a/docs/management/ha.md +++ b/docs/management/ha.md @@ -175,8 +175,6 @@ The **default timeout is 60 seconds**, but you can adjust this value using the f xe pool-param-set uuid= other-config:default_ha_timeout= ``` - - ## 🔧 Updates/maintenance Before any update or host maintenance, planned reboot and so on, **ALWAYS** put your host in maintenance mode. If you don't do that, XAPI will think it's an unplanned failure, and will act accordingly. @@ -195,9 +193,13 @@ If you shut the VM down with `Xen Orchestra` or `xe`, the VM will be stopped nor However, if you halt the VM directly in the guest OS (via the console or in SSH), XCP-ng is NOT aware of what's going on. The system will think the VM is down and will consider that an anomaly. As a result, the VM will be **started automatically!**. This behavior prevents an operator from shutting down the system and leaving the VM unavailable for a long time. +#### Configure VM shutdown behavior + +##### For an entire pool + :::tip -Starting with XAPI 25.16.0, VM restart behavior can be changed. To do this, run this command: +Starting with XAPI 25.16.0, VM restart behavior can be changed on a pool-wide basis. To do this, run this command: ``` xe pool-param-set uuid=... ha-reboot-vm-on-internal-shutdown=false @@ -206,39 +208,21 @@ As a result, VMs that are shut down internally or through the API will restart t ::: -#### Configure VM shutdown behavior - -If you don't want a VM to reboot automatically when it has been shut down from the guest OS: disable its HA protection, then adjust the VM reboot behavior with the parameter called `Pool.ha_reboot_vm_on_internal_shutdown` (see below). - -##### Disabling HA on specific VMs - -You can adjust the reboot behavior for a specific HA-protected VM: +##### For specific VMs -- **Using the `xe` cli:** : - - To disable HA features, run `xe vm-param-set uuid= ha-restart-priority=`. - - To (re-)enable HA features, run `xe vm-param-set uuid= ha-restart-priority=restart` or `xe vm-param-set uuid= ha-restart-priority=best-effort`. -- **Using Xen Orchestra**: - To change the VM reboot behavior from Xen Orchestra, check out the instructions in the [Xen Orchestra documentation](https://docs.xen-orchestra.com/manage_infrastructure#vm-high-availability-ha). +If you don't want a VM to reboot automatically when it has been shut down from the guest OS, adjust the VM reboot behavior with the parameter called `Pool.ha_reboot_vm_on_internal_shutdown`. :::warning Applying these changes means that your VMs will stay off after they have been shut down, until you restart them yourself. ::: -:::tip -Once HA features have been disabled on your VM, shut the VM down. Once you have started the VM again, feel free to enable HA again. -::: - -##### Disabling HA on the whole pool - -You can prevent automatic reboots on your entire pool. To do this, use the `xe` CLI to run this command: - -`xe pool-param-set uuid=$UUID ha-reboot-vm-on-internal-shutdown=false`. - -To enable automatic reboots again, set the parameter to `true` instead of `false`. +- **Using the `xe` cli:** : + - To disable automatic reboots, run `xe vm-param-set uuid= ha-restart-priority=`. + - To (re-)enable automatic reboots, run `xe vm-param-set uuid= ha-restart-priority=restart` or `xe vm-param-set uuid= ha-restart-priority=best-effort`. +- **Using Xen Orchestra**: + To change the VM reboot behavior from Xen Orchestra, check out the instructions in the [Xen Orchestra documentation](https://docs.xen-orchestra.com/manage_infrastructure#vm-high-availability-ha). -:::warning -By applying these changes to your entire pool, you disable the protection that prevents VMs from being shut down by their own guest OS. -::: +Once you've changed the reboot parameter, shut the VM down. After you have started the VM again, feel free to re-enable automatic reboots. ### Host failure From c5f94a19b54095898c1872dcca06b12d632e0f09 Mon Sep 17 00:00:00 2001 From: Thomas Moraine Date: Wed, 22 Apr 2026 10:42:27 +0200 Subject: [PATCH 4/6] ha.md: fix instructions for vm reboot behavior The instructions written in the previous commits regarding ha protection and automatic vm reboot behavior were confusing and/or inaccurate. This commit makes the instructions less ambiguous. Thanks stormi for the feedback! Signed-off-by: Thomas Moraine --- docs/management/ha.md | 23 +++++++++-------------- 1 file changed, 9 insertions(+), 14 deletions(-) diff --git a/docs/management/ha.md b/docs/management/ha.md index 78184f4b..509ab10c 100644 --- a/docs/management/ha.md +++ b/docs/management/ha.md @@ -195,8 +195,6 @@ However, if you halt the VM directly in the guest OS (via the console or in SSH) #### Configure VM shutdown behavior -##### For an entire pool - :::tip Starting with XAPI 25.16.0, VM restart behavior can be changed on a pool-wide basis. To do this, run this command: @@ -204,25 +202,22 @@ Starting with XAPI 25.16.0, VM restart behavior can be changed on a pool-wide ba ``` xe pool-param-set uuid=... ha-reboot-vm-on-internal-shutdown=false ``` -As a result, VMs that are shut down internally or through the API will restart the exact same way. - -::: -##### For specific VMs +The `ha-reboot-vm-on-internal-shutdown` parameter indicates whether an HA-protected VM that is shut down from inside (not through the API) should be automatically rebooted when HA is enabled. -If you don't want a VM to reboot automatically when it has been shut down from the guest OS, adjust the VM reboot behavior with the parameter called `Pool.ha_reboot_vm_on_internal_shutdown`. +::: :::warning -Applying these changes means that your VMs will stay off after they have been shut down, until you restart them yourself. +Setting the `ha-reboot-vm-on-internal-shutdown` to `false` means that your VMs will stay off after they have been shut down from the guest OS, until you restart them yourself. + +If you want to restore the default behavior (i.e. HA-protected VMs restart automatically after getting shut down from the guest OS), you will have to set the parameter to `true` again. ::: -- **Using the `xe` cli:** : - - To disable automatic reboots, run `xe vm-param-set uuid= ha-restart-priority=`. - - To (re-)enable automatic reboots, run `xe vm-param-set uuid= ha-restart-priority=restart` or `xe vm-param-set uuid= ha-restart-priority=best-effort`. -- **Using Xen Orchestra**: - To change the VM reboot behavior from Xen Orchestra, check out the instructions in the [Xen Orchestra documentation](https://docs.xen-orchestra.com/manage_infrastructure#vm-high-availability-ha). +:::note +If you don't want a specific VM to reboot automatically, you can also disable HA protection for that VM entirely. To do so, read the instructions at the [Troubleshooting HA section](../troubleshooting/troubleshooting-ha.md#disabling-ha). -Once you've changed the reboot parameter, shut the VM down. After you have started the VM again, feel free to re-enable automatic reboots. +Once you have disabled HA for the VM, shut the VM down. After you start the VM again, feel free to re-enable HA. +::: ### Host failure From 746ba4ae2bad42feb872ea64e87bb42868f32b9e Mon Sep 17 00:00:00 2001 From: Thomas Moraine Date: Thu, 7 May 2026 08:46:03 +0200 Subject: [PATCH 5/6] Reword the explanation of the vm reboot behavior, as suggested by psafont Signed-off-by: Thomas Moraine --- docs/management/ha.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/management/ha.md b/docs/management/ha.md index 509ab10c..8523a8cf 100644 --- a/docs/management/ha.md +++ b/docs/management/ha.md @@ -203,7 +203,7 @@ Starting with XAPI 25.16.0, VM restart behavior can be changed on a pool-wide ba xe pool-param-set uuid=... ha-reboot-vm-on-internal-shutdown=false ``` -The `ha-reboot-vm-on-internal-shutdown` parameter indicates whether an HA-protected VM that is shut down from inside (not through the API) should be automatically rebooted when HA is enabled. +The `ha-reboot-vm-on-internal-shutdown` parameter indicates whether VM-initiated shudotwns will trigger a restart for HA-protected VMs, for example, when a user clicks the shutdown in Windows. ::: From cda82c7e0218a1648772557bc1b446312c816b78 Mon Sep 17 00:00:00 2001 From: Thomas Moraine Date: Mon, 11 May 2026 16:01:33 +0200 Subject: [PATCH 6/6] ha.md: implement text fixes suggested by stormi Signed-off-by: Thomas Moraine --- docs/management/ha.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/management/ha.md b/docs/management/ha.md index 8523a8cf..8d396316 100644 --- a/docs/management/ha.md +++ b/docs/management/ha.md @@ -203,18 +203,18 @@ Starting with XAPI 25.16.0, VM restart behavior can be changed on a pool-wide ba xe pool-param-set uuid=... ha-reboot-vm-on-internal-shutdown=false ``` -The `ha-reboot-vm-on-internal-shutdown` parameter indicates whether VM-initiated shudotwns will trigger a restart for HA-protected VMs, for example, when a user clicks the shutdown in Windows. +The `ha-reboot-vm-on-internal-shutdown` parameter indicates whether VM-initiated shutdowns will trigger a restart for HA-protected VMs, for example, when a user clicks the shutdown in Windows. ::: :::warning -Setting the `ha-reboot-vm-on-internal-shutdown` to `false` means that your VMs will stay off after they have been shut down from the guest OS, until you restart them yourself. +Setting the `ha-reboot-vm-on-internal-shutdown` parameter to `false` means that your VMs will stay off after they have been shut down from the guest OS, until you restart them yourself. -If you want to restore the default behavior (i.e. HA-protected VMs restart automatically after getting shut down from the guest OS), you will have to set the parameter to `true` again. +If you want to restore the default behavior (i.e. HA-protected VMs restart automatically after getting shut down from the guest OS), set the parameter to `true` again. ::: :::note -If you don't want a specific VM to reboot automatically, you can also disable HA protection for that VM entirely. To do so, read the instructions at the [Troubleshooting HA section](../troubleshooting/troubleshooting-ha.md#disabling-ha). +If you don't want a specific VM to reboot automatically, without changing the behavior for the whole pool, you can also temporarily disable HA protection for that VM. To do so, read the instructions at the [Troubleshooting HA section](../troubleshooting/troubleshooting-ha.md#disabling-ha). Once you have disabled HA for the VM, shut the VM down. After you start the VM again, feel free to re-enable HA. :::