From 642c8d6cda257846db44f1b1e18fc84194a6a978 Mon Sep 17 00:00:00 2001
From: Christian Breunig <christian@breunig.cc>
Date: Wed, 28 Oct 2026 22:02:56 +0100
Subject: secure-boot: T9496: document Secure Boot signature check on "add
 system image"

With Secure Boot enabled, "add system image" now aborts if the Linux Kernel
of the new image is not signed by an enrolled Machine Owner Key, since that
image would not boot. Describe the check, its error message and when it is
skipped, and point to it from the image update page.
---
 docs/installation/secure-boot.md | 22 ++++++++++++++++++++++
 docs/installation/update.md      |  7 +++++++
 2 files changed, 29 insertions(+)

diff --git a/docs/installation/secure-boot.md b/docs/installation/secure-boot.md
index 63814c19..dd5798bb 100644
--- a/docs/installation/secure-boot.md
+++ b/docs/installation/secure-boot.md
@@ -157,6 +157,28 @@ error: bad shim signature
 error: you need to load the kernel first
 ```
 
+To prevent this, {opcmd}`add system image` verifies the Linux Kernel of the
+new image when the running system has Secure Boot enabled. The Kernel must be
+signed by one of the {abbr}`MOK (Machine Owner Key)` keys enrolled in UEFI.
+If it is not, the installation is aborted before any files are copied:
+
+% stop_vyoslinter
+
+```none
+vyos@vyos:~$ add system image /tmp/vyos-unsigned-amd64.iso
+Validating image compatibility
+Validating image checksums
+Validating Secure Boot signature
+Secure Boot is enabled, but the Linux Kernel "vmlinuz" of the new image is not signed by an enrolled key. The new image would not boot.
+Exiting from VyOS installation
+```
+
+% start_vyoslinter
+
+Enroll the key the new image is signed with before you add the image. On
+systems with Secure Boot disabled, or booted in legacy BIOS mode, the check is
+skipped.
+
 
 ## Linux Kernel
 
diff --git a/docs/installation/update.md b/docs/installation/update.md
index cdc8b20d..6bcaa134 100644
--- a/docs/installation/update.md
+++ b/docs/installation/update.md
@@ -30,6 +30,13 @@ For example: /tmp/vyos-1.2.3-amd64.iso.
 If there isn't enough free disk space, the installation will be canceled.
 To delete images, use the {opcmd}`delete system image` command.
 
+:::{note}
+If the running system has UEFI Secure Boot enabled, the Linux Kernel of the
+new image must be signed by an enrolled Machine Owner Key. Otherwise the
+installation is canceled, because the new image would not boot. See
+{ref}`secure-boot` for details.
+:::
+
 
 VyOS associates configuration with each image, and each image has its own
 unique configuration copy. This differs from traditional network routers where
-- 
cgit v1.2.3