docs: how-to guide for Ubuntu with TPM-FDE installer by raimundo-henriques · Pull Request #633 · canonical/snap-docs

raimundo-henriques · 2026-10-09T17:58:39Z

No description provided.

First draft.

ZeyadYasser

This looks great, left some small nitpick comments. Thank you!

ZeyadYasser · 2026-10-12T11:03:33Z

+
+Refer to the {ref}`snapd REST API reference<reference-development-snapd-rest-api>` for a list of all actions and endpoints. For general instructions, refer to the {ref}`guide on how to use the REST API<how-to-guides-manage-snaps-use-the-rest-api>`.
+
+This guide is aimed at developers building a GUI-based custom Ubuntu installer that supports TPM-FDE. While the API can be called directly, this guide assumes that a GUI exists between the API calls and the end user.


The same steps can be utilized by TUI or an opinionated unattended installer, I think we can keep it generic.

Suggested change

This guide is aimed at developers building a GUI-based custom Ubuntu installer that supports TPM-FDE. While the API can be called directly, this guide assumes that a GUI exists between the API calls and the end user.

This guide is aimed at developers building a custom Ubuntu installer that supports TPM-FDE.

ZeyadYasser · 2026-10-12T11:06:18Z

+  "storage-encryption": {
+    "support": "unavailable",
+    "features": ["passphrase-auth", "pin-auth"],
+    "storage-safety": "prefer-encrypted",
+    "unavailable-reason": "cannot use encryption with the gadget, disabling encryption: gadget does not support encrypted data: required partition with system-save role is missing",
+    "requirements": ["volumes-auth"]


I think we can remove features and requirements fields to avoid confusion.

Suggested change

"storage-encryption": {

"support": "unavailable",

"features": ["passphrase-auth", "pin-auth"],

"storage-safety": "prefer-encrypted",

"unavailable-reason": "cannot use encryption with the gadget, disabling encryption: gadget does not support encrypted data: required partition with system-save role is missing",

"requirements": ["volumes-auth"]

"storage-encryption": {

"support": "unavailable",

"storage-safety": "prefer-encrypted",

"unavailable-reason": "cannot use encryption with the gadget, disabling encryption: gadget does not support encrypted data: required partition with system-save role is missing"

ZeyadYasser · 2026-10-12T11:07:54Z

+
+Once the system details show that [encryption is available](#encryption-is-available), you are ready to install Ubuntu with TPM-FDE.
+
+## Add a PIN or passphrase


Header implies that this is about installing with a PIN/Passphrase but then gives examples both with/without.

I think we need a dedicated section for the normal setup that links to the optional or required addition of a PIN/passphrase.

First draft.

ernestl

First pass, direction is looking good. Added a few higher level observations/considerations as well as a few more specific nitpick comments.

Within the schemas, expanding nested fields led to a situation where the Swagger UI only showed one character per line. This made the description impossible to read. These tweaks allow the schema area to expand and use horizontal scrolling to read the description.

…ow-to-tpm-fde

Update the title to reflect the page's content. Add Prerequisites section. Add error-kind tables in dropdowns. Document fix action args. Create general Set up storage encryption section with subsections for auth options. Improve code examples. Improve preseeding prerequisites' description. Update the page metadata description.

to avoid spelling error.

ernestl

Thanks, I think this is a good starting point, we can not provide this to users and react to feedback.

ernestl · 2026-10-19T20:50:38Z

+
+Refer to the {ref}`snapd REST API reference<reference-development-snapd-rest-api>` for a list of all API actions and endpoints. For general instructions, refer to the {ref}`guide on how to use the REST API<how-to-guides-manage-snaps-use-the-rest-api>`.
+
+Follow the steps in order. Some steps are optional. If you skip an optional step, continue with the next applicable one.


If you skip... perhaps not need saying?

ernestl · 2026-10-19T20:52:27Z

+For more information, see:
+- [Create a model](https://documentation.ubuntu.com/core/tutorials/build-your-first-image/create-a-model/)
+- [Create a recovery system from the API](https://documentation.ubuntu.com/core/how-to-guides/manage-ubuntu-core/create-a-recovery-system-from-the-api/)
+- [Ubuntu Core storage layout](https://documentation.ubuntu.com/core/explanation/core-elements/storage-layout/)


Nitpick: Users might wonder how much of UC layout is relevant to a hybrid system.

ernestl · 2026-10-19T20:53:24Z

+
+The table below lists error kinds that snapd might return, with a suggested message to show the user, and example fix actions. The list is not exhaustive: snapd can return error kinds and fix actions that the table does not include. Treat it as a starting point, rather than a specification.
+
+```{dropdown} Recoverable error kinds


What is the source of these? Is the the latest from the Desktop team?

The three tables are taken from here. The content is the same, only it is split into three tables instead of just one. Should I look somewhere else?

Remove redundant instruction on how to follow steps. Explain why Ubuntu Core storage layout is relevant.

ZeyadYasser

Great work, Thank you! left small comments, nothing blocking.

ZeyadYasser · 2026-10-20T07:24:47Z

+
+To get Canonical's reference model for the Ubuntu release used in this guide, run:
+```sh
+snap known model --remote series=16 brand-id=canonical model=ubuntu-classic-2610-amd64


Let's suggest the LTS instead

Suggested change

snap known model --remote series=16 brand-id=canonical model=ubuntu-classic-2610-amd64

snap known model --remote series=16 brand-id=canonical model=ubuntu-classic-2604-amd64

Makes sense! For context, I copied what the desktop team shared here: https://chat.canonical.com/canonical/pl/ngf68kd47ffst8uefo55pyz7sc

ZeyadYasser · 2026-10-20T07:29:03Z

+|------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------|
+| `efi-variable-access`                         | Error occurred when accessing an EFI variable.                                                                                                 | `contact-oem`                                                            |
+| `tpm-device-failure`                          | The TPM device has failed an internal self check.                                                                                              | `reboot`, `contact-oem`                                                  |
+| `tpm-device-disabled`                         | There is a TPM device that is currently disabled.                                                                                              | PPI-based enable/clear actions, `reboot-to-fw-settings`                  |


what is PPI-based? I think the abbreviation should be expanded at least once

I generated the tables from this one. I agree with you, though.
@ernestl , could you please clarify what 'PPI' stands for?

Confirmed with @ernestl : 'PPI' stands for 'Physical Presence Interface'.

ZeyadYasser · 2026-10-20T07:30:15Z

+
+The table below lists error kinds that snapd might return, with a suggested message to show the user, and example fix actions. The list is not exhaustive: snapd can return error kinds and fix actions that the table does not include. Treat it as a starting point, rather than a specification.
+
+```{dropdown} Recoverable error kinds


I like the collapsible dropdown, nice

Thank you! @ernestl discussed also the option of having some sort of appendix, but I am quite happy about this option.

There was a mismatch between these tables and the source. `no-hardware-root-of-trust` was not in the source, but it is returned by snapd and was therefore kept. `ErrorKindEmptyPCRBanks`, `ErrorKindUEFIDebuggingEnabled`, `ErrorKindTPMStartupLocalityNotProtected`, and `ErrorKindPCRUnsupported`, on the other hand, were in the source but are not currently returned by snapd. Therefore, they were not kept.

Add `clear-tpm` and `clear-tpm-simple` to `tpm-hierarchies-owned`. This is not in the doc source, but they are returned by snapd and the former is explicitly mentioned later. Update the title of the table for error kinds returned after fix actions are attempted, as reboot might be required, not because the action failed, but to complete it.

raimundo-henriques · 2026-10-21T09:42:25Z

@ernestl and @ZeyadYasser ,
Following your comments, I realized that the tables had some issues. The commits I've pushed meanwhile fix these. There are, however, a couple of mismatches between the source doc and snapd, that I want to bring to your attention:

no-hardware-root-of-trust is not in the tables in the source doc. However, because secboot defines this error (efi/preinstall/error_kinds.go) and snapd exposes it (secboot/preinstall_sb.go), I kept it in the how-to. The message was taken from the comment to ErrorKindNoHardwareRootOfTrust in snapd (secboot/preinstall_sb.go lines 70-72). The proceed fix action seemed to be secboot's behavior for this kind of error. Can you please confirm?
tpm-hierarchies-owned and insufficient-tpm-storage have fix actions clear-tpm-simple and clear-tpm in the how-to. This was not in the source doc, but it is returned by snapd. Since clear-tpm is used as in an example precisely with tpm-hiearchies-owned, I thought it was better to include them.
ErrorKindEmptyPCRBanks, ErrorKindUEFIDebuggingEnabled, ErrorKindTPMStartupLocalityNotProtected and ErrorKindPCRUnsupported are not documented because snapd does not return them. They are in the source doc, but I decided to follow snapd here.
There was no direct equivalent in the source doc for addon-drivers-present and pre-os-secure-boot-auth-by-enrolled-digests. The closest seem to be ErrorKindVARSuppliedDriversPresent and ErrorKindPreOSDigestVerificationDetected, so those were used. Can you please check the table rows for these error kinds to make sure they make sense, please? Please note that addon-drivers-present is currently used in an example. If we conclude that these should not be in the table, the example needs to be updated.

I'm happy to leave comments on the source code to point out the mismatches with snapd, if that makes sense.

Thank you

valentindavid · 2026-10-21T12:05:47Z

+Present the recovery key to the user and tell them clearly that, in the event of hardware failure, they might lose their data without it.
+```
+
+## Write the boot chain onto the target system


We should not be to specific. Maybe "make the system bootable".

Adapted to 'target system' to keep the usage of the term consistent.

Avoids being too specific.

docs: how-to guide for Ubuntu with TPM-FDE installer

5341058

First draft.

ZeyadYasser reviewed Oct 12, 2026

View reviewed changes

docs: how-to guide for Ubuntu with TPM-FDE installer

f55caa7

First draft.

ernestl reviewed Oct 13, 2026

View reviewed changes

raimundo-henriques added 4 commits October 16, 2026 13:28

Merge remote-tracking branch 'origin/docs/how-to-tpm-fde' into docs/h…

b653ad6

…ow-to-tpm-fde

docs: add exlanatory comments to css

18ef2d8

raimundo-henriques marked this pull request as ready for review October 19, 2026 19:56

docs: add code styling to modeenv

05301b2

to avoid spelling error.

raimundo-henriques requested review from ZeyadYasser, ernestl and valentindavid October 19, 2026 19:59

ernestl approved these changes Oct 19, 2026

View reviewed changes

docs: small improvements after review

4e36787

Remove redundant instruction on how to follow steps. Explain why Ubuntu Core storage layout is relevant.

ZeyadYasser approved these changes Oct 20, 2026

View reviewed changes

raimundo-henriques added 2 commits October 21, 2026 09:37

valentindavid reviewed Oct 21, 2026

View reviewed changes

docs: updated install step section title

e5b2b7d

Avoids being too specific.

raimundo-henriques merged commit 0c11195 into canonical:main Oct 26, 2026
2 checks passed


		Refer to the {ref}`snapd REST API reference<reference-development-snapd-rest-api>` for a list of all actions and endpoints. For general instructions, refer to the {ref}`guide on how to use the REST API<how-to-guides-manage-snaps-use-the-rest-api>`.

		This guide is aimed at developers building a GUI-based custom Ubuntu installer that supports TPM-FDE. While the API can be called directly, this guide assumes that a GUI exists between the API calls and the end user.


		Once the system details show that [encryption is available](#encryption-is-available), you are ready to install Ubuntu with TPM-FDE.

		## Add a PIN or passphrase


		Refer to the {ref}`snapd REST API reference<reference-development-snapd-rest-api>` for a list of all API actions and endpoints. For general instructions, refer to the {ref}`guide on how to use the REST API<how-to-guides-manage-snaps-use-the-rest-api>`.

		Follow the steps in order. Some steps are optional. If you skip an optional step, continue with the next applicable one.


		The table below lists error kinds that snapd might return, with a suggested message to show the user, and example fix actions. The list is not exhaustive: snapd can return error kinds and fix actions that the table does not include. Treat it as a starting point, rather than a specification.

		```{dropdown} Recoverable error kinds

	snap known model --remote series=16 brand-id=canonical model=ubuntu-classic-2610-amd64
	snap known model --remote series=16 brand-id=canonical model=ubuntu-classic-2604-amd64

Conversation

raimundo-henriques commented Oct 9, 2026

Uh oh!

ZeyadYasser left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ernestl left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

ernestl left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ZeyadYasser left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

raimundo-henriques commented Oct 21, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants