From 22e91145f4fb361a13824691413174fd00609431 Mon Sep 17 00:00:00 2001 From: Nathnael Bekele Date: Thu, 21 May 2026 12:25:54 -0500 Subject: [PATCH 1/3] d/h/snap-development: document snap-debug-info.sh --- .../snap-development/debug-snaps.md | 34 ++++++++++++++++--- docs/how-to-guides/snap-development/index.md | 2 +- 2 files changed, 30 insertions(+), 6 deletions(-) diff --git a/docs/how-to-guides/snap-development/debug-snaps.md b/docs/how-to-guides/snap-development/debug-snaps.md index d7957a5..f4227f0 100644 --- a/docs/how-to-guides/snap-development/debug-snaps.md +++ b/docs/how-to-guides/snap-development/debug-snaps.md @@ -22,7 +22,7 @@ For more details on how AppArmor, seccomp and device permission security policie To investigate and test the confined environment of a snap, you can open a `bash` shell in it. After the snap is installed, use the `--shell .` argument of `snap run`. -``` +```sh $ snap run --shell mysnap.mycommand To run a command as administrator (user "root"), use "sudo ". See "man sudo_root" for details. @@ -44,7 +44,7 @@ Running the standard _strace_ command on a snapped application, however, can pro To use this, you first have to install the [strace-static](https://snapcraft.io/strace-static) snap: -``` +```sh sudo snap install strace-static ``` @@ -58,7 +58,7 @@ You will be asked for your password because the internal strace logic relies on Additionally, you can disable post-processing of the strace output by passing `--raw` to `--strace=`: -``` +```sh snap run --strace=--raw ``` @@ -70,12 +70,37 @@ To help isolate runtime errors when building and testing a snap, a snap can be i To install a snap in developer mode, use the `--devmode` argument: -``` +```sh sudo snap install --devmode mysnap ``` When a snap is installed with developer mode, violations against a snap's security policy are permitted to proceed but logged via journald. +## Generating a system diagnostic report + +[`snap-debug-info.sh`](https://github.com/canonical/snapd/blob/master/debug-tools/snap-debug-info.sh) is a script included in the snapd snap that collects comprehensive information about snapd's state. It contains system details that are useful in bug reports as well as diagnosing snapd behaviour. These include + +- `snap` command's version, +- active model assertion, +- snaps, components, and services installed, +- connections on the system, +- recent changes performed on the system including those in Doing or Error state, +- offline snap changes, +- validation sets, +- uptime, date, and diskspace, +- contents of gadget.yaml (if a gadget snap is present), +- snap system config, +- status of the snapd.service, +- snapd journal entries, +- DENIED log messages from system journal, +- snapd stacktraces. + +Note that the output is expected to be verbose, especially on systems with many snaps installed. Run the script as root or with sudo since some commands used require those permissions. + +```sh +sudo /snap/snapd/current/usr/lib/snapd/snap-debug-info.sh > snapd-debug.log +``` + ## Debugging policy violation logs ### Using snappy-debug to show violations @@ -267,4 +292,3 @@ The above command has changed to snap-device-helper - https://assets.ubuntu.com/v1/66fcd858-ubuntu-core-security-whitepaper.pdf - https://github.com/canonical/snapd/wiki/Snap-Execution-Environment - https://forum.snapcraft.io/t/stracing-snap-commands/1433 - diff --git a/docs/how-to-guides/snap-development/index.md b/docs/how-to-guides/snap-development/index.md index ef69931..04c0fe9 100644 --- a/docs/how-to-guides/snap-development/index.md +++ b/docs/how-to-guides/snap-development/index.md @@ -13,7 +13,7 @@ Extend snap functionality with API access, internal tools, and customised enviro * {ref}`Use snapctl `: use the snapctl tool within a snap application. * {ref}`Use the Secret portal `: how to use the Secret portal * {ref}`Test snapd fixes `: test out the latest release of the snap daemon. -* {ref}`Debug snaps `: solve issues with snapped application. +* {ref}`Debug snaps `: solve issues with snapped application and generate a snapd diagnostic report. * {ref}`snap try `: test a snap package on your system. * {ref}`Using in-development features `: learn how to use cutting edge snap features. From 700eff7972ca2bfbe9dd906fc5421b85135149b8 Mon Sep 17 00:00:00 2001 From: Nathnael Bekele Date: Thu, 21 May 2026 12:29:00 -0500 Subject: [PATCH 2/3] d/h/snap-development: fixups --- docs/how-to-guides/snap-development/debug-snaps.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/how-to-guides/snap-development/debug-snaps.md b/docs/how-to-guides/snap-development/debug-snaps.md index f4227f0..8603235 100644 --- a/docs/how-to-guides/snap-development/debug-snaps.md +++ b/docs/how-to-guides/snap-development/debug-snaps.md @@ -87,18 +87,18 @@ When a snap is installed with developer mode, violations against a snap's securi - recent changes performed on the system including those in Doing or Error state, - offline snap changes, - validation sets, -- uptime, date, and diskspace, +- uptime, date, and disk space, - contents of gadget.yaml (if a gadget snap is present), - snap system config, - status of the snapd.service, - snapd journal entries, - DENIED log messages from system journal, -- snapd stacktraces. +- snapd stack traces. Note that the output is expected to be verbose, especially on systems with many snaps installed. Run the script as root or with sudo since some commands used require those permissions. ```sh -sudo /snap/snapd/current/usr/lib/snapd/snap-debug-info.sh > snapd-debug.log +sudo /snap/snapd/current/usr/lib/snapd/snap-debug-info.sh > snap-debug.log ``` ## Debugging policy violation logs From 43974d9d7f7db36f6667182c6a233a3dd128fb42 Mon Sep 17 00:00:00 2001 From: Nathnael Bekele Date: Fri, 22 May 2026 11:44:05 -0500 Subject: [PATCH 3/3] d/h/snap-development: fixup --- docs/how-to-guides/snap-development/debug-snaps.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/how-to-guides/snap-development/debug-snaps.md b/docs/how-to-guides/snap-development/debug-snaps.md index 8603235..ab97d54 100644 --- a/docs/how-to-guides/snap-development/debug-snaps.md +++ b/docs/how-to-guides/snap-development/debug-snaps.md @@ -78,7 +78,7 @@ When a snap is installed with developer mode, violations against a snap's securi ## Generating a system diagnostic report -[`snap-debug-info.sh`](https://github.com/canonical/snapd/blob/master/debug-tools/snap-debug-info.sh) is a script included in the snapd snap that collects comprehensive information about snapd's state. It contains system details that are useful in bug reports as well as diagnosing snapd behaviour. These include +[`snap-debug-info.sh`](https://github.com/canonical/snapd/blob/master/debug-tools/snap-debug-info.sh) is a script included in the snapd snap that collects comprehensive information about snapd's state. It contains system details that are useful in bug reports as well as diagnosing snapd behaviour. These include: - `snap` command's version, - active model assertion,