From e596ffc7c49d971c7cc7a8293f39a8e2c3555aeb Mon Sep 17 00:00:00 2001 From: Joachim Wiberg Date: Fri, 5 Dec 2025 17:46:05 +0100 Subject: [PATCH] doc: relocate support data collection to separate section Does not really fit under "System Configuration". Signed-off-by: Joachim Wiberg --- doc/support.md | 91 ++++++++++++++++++++++++++++++++++++++++++++++++++ doc/system.md | 88 ------------------------------------------------ mkdocs.yml | 1 + 3 files changed, 92 insertions(+), 88 deletions(-) create mode 100644 doc/support.md diff --git a/doc/support.md b/doc/support.md new file mode 100644 index 00000000..4d35a42a --- /dev/null +++ b/doc/support.md @@ -0,0 +1,91 @@ +# Support Data Collection + +When troubleshooting issues or seeking support, the `support` command +provides a convenient way to collect comprehensive system diagnostics. +This command gathers configuration files, logs, network state, and other +system information into a single compressed archive. + +## Collecting Support Data + +To collect support data and save it to a file: + +```bash +admin@host:~$ support collect > support-data.tar.gz +(admin@host) Password: *********** +Starting support data collection from host... +This may take up to a minute. Please wait... +Tailing /var/log/messages for 30 seconds (please wait)... +Log tail complete. +Collection complete. Creating archive... +admin@host:~$ ls -l support-data.tar.gz +-rw-rw-r-- 1 admin admin 508362 nov 30 13:05 support-data.tar.gz +``` + +The command can also be run remotely via SSH from your workstation: + +```bash +$ ssh admin@host support collect > support-data.tar.gz +... +``` + +The collection process may take up to a minute depending on system load +and the amount of logging data. Progress messages are shown during the +collection process. + +## Encrypted Collection + +For secure transmission of support data, the archive can be encrypted +with GPG using a password: + +```bash +admin@host:~$ support collect -p mypassword > support-data.tar.gz.gpg +Starting support data collection from host... +This may take up to a minute. Please wait... +... +Collection complete. Creating archive... +Encrypting with GPG... +``` + +The `support collect` command even supports omitting `mypassword` and +will then prompt interactively for the password. This works over SSH too, +but the local ssh client may then echo the password. + +> [!TIP] +> To hide the encryption password for an SSH session, the script supports +> reading from stdin: +> `echo "$MYSECRET" | ssh user@device support collect -p > +> file.tar.gz.gpg` + +After transferring the resulting file to your workstation, decrypt it +with the password: + +```bash +$ gpg -d support-data.tar.gz.gpg > support-data.tar.gz +$ tar xzf support-data.tar.gz +... +``` + +or + +```bash +$ gpg -d support-data.tar.gz.gpg | tar xz +... +``` + +> [!IMPORTANT] +> Make sure to share `mypassword` out-of-band from the encrypted data +> with the recipient of the data. I.e., avoid sending both in the same +> plain-text email for example. + +## What is Collected + +The support archive includes: + +- System identification (hostname, uptime, kernel version) +- Running and operational configuration (sysrepo datastores) +- System logs (`/var/log` directory and live tail of messages log) +- Network configuration and state (interfaces, routes, neighbors, bridges) +- FRRouting information (OSPF, BFD status) +- Container information (podman containers and their configuration) +- System resource usage (CPU, memory, disk, processes) +- Hardware information (PCI, USB devices, network interfaces) diff --git a/doc/system.md b/doc/system.md index 86648df2..02d9b644 100644 --- a/doc/system.md +++ b/doc/system.md @@ -323,94 +323,6 @@ reference ID, stratum, time offsets, frequency, and root delay. > The system uses `chronyd` Network Time Protocol (NTP) daemon. The > output shown here is best explained in the [Chrony documentation][4]. -## Support Data Collection - -When troubleshooting issues or seeking support, the `support` command -provides a convenient way to collect comprehensive system diagnostics. -This command gathers configuration files, logs, network state, and other -system information into a single compressed archive. - -### Collecting Support Data - -To collect support data and save it to a file: - -```bash -admin@host:~$ support collect > support-data.tar.gz -(admin@host) Password: *********** -Starting support data collection from host... -This may take up to a minute. Please wait... -Tailing /var/log/messages for 30 seconds (please wait)... -Log tail complete. -Collection complete. Creating archive... -admin@host:~$ ls -l support-data.tar.gz --rw-rw-r-- 1 admin admin 508362 nov 30 13:05 support-data.tar.gz -``` - -The command can also be run remotely via SSH from your workstation: - -```bash -$ ssh admin@host support collect > support-data.tar.gz -... -``` - -The collection process may take up to a minute depending on system load -and the amount of logging data. Progress messages are shown during the -collection process. - -### Encrypted Collection - -For secure transmission of support data, the archive can be encrypted -with GPG using a password: - -```bash -admin@host:~$ support collect -p mypassword > support-data.tar.gz.gpg -Starting support data collection from host... -This may take up to a minute. Please wait... -... -Collection complete. Creating archive... -Encrypting with GPG... -``` - -The `support collect` command even supports omitting `mypassword` and -will then prompt interactively for the password. This works over SSH too, -but the local ssh client may then echo the password. - -> [!TIP] -> To hide the encryption password for an SSH session, the script supports reading from stdin: -> `echo "$MYSECRET" | ssh user@device support collect -p > file.tar.gz.gpg` - -After transferring the resulting file to your workstation, decrypt it -with the password: - -```bash -$ gpg -d support-data.tar.gz.gpg > support-data.tar.gz -$ tar xzf support-data.tar.gz -``` - -or - -```bash -$ gpg -d support-data.tar.gz.gpg | tar xz -``` - -> [!IMPORTANT] -> Make sure to share `mypassword` out-of-band from the encrypted data -> with the recipient of the data. I.e., avoid sending both in the same -> plain-text email for example. - -### What is Collected - -The support archive includes: - - - System identification (hostname, uptime, kernel version) - - Running and operational configuration (sysrepo datastores) - - System logs (`/var/log` directory and live tail of messages log) - - Network configuration and state (interfaces, routes, neighbors, bridges) - - FRRouting information (OSPF, BFD status) - - Container information (podman containers and their configuration) - - System resource usage (CPU, memory, disk, processes) - - Hardware information (PCI, USB devices, network interfaces) - [1]: https://www.rfc-editor.org/rfc/rfc7317 [2]: https://github.com/kernelkit/infix/blob/main/src/confd/yang/infix-system%402024-02-29.yang [3]: https://www.rfc-editor.org/rfc/rfc8341 diff --git a/mkdocs.yml b/mkdocs.yml index 5d768c0c..5d179c4f 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -43,6 +43,7 @@ nav: - Hardware Info & Status: hardware.md - Management: management.md - Syslog Support: syslog.md + - Support Data: support.md - Upgrade: upgrade.md - Scripting: - Introduction: scripting.md