From 5d24fbc7403c9962fa8da2caf5c245982cb2c249 Mon Sep 17 00:00:00 2001
From: Yuriy Andamasov <yuriy@vyos.io>
Date: Wed, 29 Apr 2026 06:53:34 +0300
Subject: fix: re-add 4 canary md-*.md files deleted by 242b334a
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Commit 242b334a accidentally staged deletions instead of modifications
because the working tree had unprefixed *.md files left over from an
incomplete swap-restore cycle. Re-imports the same 4 files from
origin/myst/current with the xref label fixes applied:

- contributing/md-development.md       — (coding-guidelines)= anchor
- operation/md-upgrade-recovery.md     — how_it_works → how-it-works,
                                         cancelling_recovery → cancelling-recovery
- vpp/configuration/dataplane/md-buffers.md — vpp_config_dataplane_physmem
                                              → vpp-config-dataplane-physmem
- vpp/configuration/dataplane/md-unix.md   — vpp_config_dataplane_interface_rx_mode
                                              → vpp-config-dataplane-interface-rx-mode

Source: origin/myst/current commit 59fbe3ea.

🤖 Generated by [robots](https://vyos.io)
---
 docs/operation/md-upgrade-recovery.md | 63 +++++++++++++++++++++++++++++++++++
 1 file changed, 63 insertions(+)
 create mode 100644 docs/operation/md-upgrade-recovery.md

(limited to 'docs/operation')

diff --git a/docs/operation/md-upgrade-recovery.md b/docs/operation/md-upgrade-recovery.md
new file mode 100644
index 00000000..a8754d3b
--- /dev/null
+++ b/docs/operation/md-upgrade-recovery.md
@@ -0,0 +1,63 @@
+---
+lastproofread: '2025-11-20'
+---
+
+(upgrade-recovery)=
+
+# Recovery after Failed Upgrades
+
+Use **VyOS upgrade recovery** to restore the system to the last working
+version after a failed upgrade.
+
+- {ref}`Configuration:  <configuration>` How to enable upgrade recovery
+- {ref}`How it works: <how-it-works>` Overview of the recovery process
+- {ref}`Cancelling recovery: <cancelling-recovery>` Overview of the recovery
+  process
+
+(configuration)=
+
+## Configuration
+
+:::{warning}
+Upgrade recovery is disabled by default. To use it,
+**enable it first**.
+:::
+
+To enable upgrade recovery, run the following command:
+
+```{cfgcmd} set system option reboot-on-upgrade-failure [timeout \<min\>]
+```
+
+- `timeout <min>:` The time in minutes (5 - 30) to cancel upgrade
+  recovery before VyOS reboots.
+  See {ref}`Cancelling Recovery <cancelling-recovery>`.
+(how-it-works)=
+
+## How it works
+After a VyOS upgrade, the system monitors the boot process. Upon detecting a
+boot failure, VyOS initiates a revert to the last working version and displays
+the following warning:
+```none
+Booting failed, reverting to previous image
+Automatic reboot in xx minutes
+Use "reboot cancel" to cancel
+```
+If no action is taken, the reboot happens automatically after the configured
+timeout. Upon successful recovery and reboot, the following message appears:
+```none
+WARNING: Image update to "VyOS 1.5.xxxx" failed
+Please check the logs:
+/usr/lib/live/mount/persistence/boot/NAME/rw/var/log
+Message is cleared on next reboot!
+```
+(cancelling-recovery)=
+
+## Cancelling recovery
+Upon detecting a boot failure, you have the predefined timeout to cancel
+upgrade recovery. This is useful if you want to troubleshoot the faulty VyOS
+version on your own.
+
+To cancel upgrade recovery, run the following command:
+```none
+reboot cancel
+```
-- 
cgit v1.2.3