From 20b68353db64aa219ff55260f0ae18aaa1b8e141 Mon Sep 17 00:00:00 2001 From: Justin Schneck Date: Fri, 13 Mar 2026 19:14:01 -0400 Subject: [PATCH 1/8] docs: add avocadoctl documentation and remove deprecated avocado-control page Add comprehensive documentation for avocadoctl including commands (ext, runtime, hitl, merge, refresh, serve, status, etc.), configuration, OS bundles, runtime management, and Varlink API reference. Remove the deprecated avocado-control.md page that has been superseded. --- .../avocado-linux/tools/avocado-control.md | 8 - .../tools/avocadoctl/_category_.json | 5 + .../tools/avocadoctl/commands/_category_.json | 6 + .../tools/avocadoctl/commands/disable.md | 36 ++ .../tools/avocadoctl/commands/enable.md | 35 ++ .../avocadoctl/commands/ext/_category_.json | 5 + .../tools/avocadoctl/commands/ext/list.md | 16 + .../tools/avocadoctl/commands/ext/merge.md | 16 + .../tools/avocadoctl/commands/ext/refresh.md | 16 + .../tools/avocadoctl/commands/ext/status.md | 16 + .../tools/avocadoctl/commands/ext/unmerge.md | 26 + .../avocadoctl/commands/hitl/_category_.json | 5 + .../tools/avocadoctl/commands/hitl/mount.md | 36 ++ .../tools/avocadoctl/commands/hitl/unmount.md | 26 + .../tools/avocadoctl/commands/merge.md | 16 + .../tools/avocadoctl/commands/refresh.md | 16 + .../avocadoctl/commands/root-authority.md | 16 + .../commands/runtime/_category_.json | 5 + .../avocadoctl/commands/runtime/activate.md | 34 ++ .../tools/avocadoctl/commands/runtime/add.md | 35 ++ .../avocadoctl/commands/runtime/inspect.md | 26 + .../tools/avocadoctl/commands/runtime/list.md | 16 + .../avocadoctl/commands/runtime/remove.md | 26 + .../tools/avocadoctl/commands/serve.md | 26 + .../tools/avocadoctl/commands/status.md | 29 + .../tools/avocadoctl/commands/unmerge.md | 26 + .../tools/avocadoctl/configuration.md | 82 +++ .../avocadoctl/os-bundles/_category_.json | 6 + .../avocadoctl/os-bundles/bundle-format.md | 218 +++++++ .../tools/avocadoctl/os-bundles/overview.md | 22 + .../avocadoctl/os-bundles/update-process.md | 105 ++++ .../tools/avocadoctl/overview.md | 63 ++ .../runtime-management/_category_.json | 6 + .../runtime-management/activation-process.md | 55 ++ .../runtime-management/manifest-spec.md | 105 ++++ .../runtime-management/runtime-lifecycle.md | 67 +++ .../avocadoctl/varlink-api/_category_.json | 6 + .../varlink-api/org-avocado-extensions.md | 513 ++++++++++++++++ .../varlink-api/org-avocado-hitl.md | 158 +++++ .../varlink-api/org-avocado-root-authority.md | 170 ++++++ .../varlink-api/org-avocado-runtimes.md | 565 ++++++++++++++++++ .../tools/avocadoctl/varlink-api/overview.md | 176 ++++++ 42 files changed, 2832 insertions(+), 8 deletions(-) delete mode 100644 src/docs/avocado-linux/tools/avocado-control.md create mode 100644 src/docs/avocado-linux/tools/avocadoctl/_category_.json create mode 100644 src/docs/avocado-linux/tools/avocadoctl/commands/_category_.json create mode 100644 src/docs/avocado-linux/tools/avocadoctl/commands/disable.md create mode 100644 src/docs/avocado-linux/tools/avocadoctl/commands/enable.md create mode 100644 src/docs/avocado-linux/tools/avocadoctl/commands/ext/_category_.json create mode 100644 src/docs/avocado-linux/tools/avocadoctl/commands/ext/list.md create mode 100644 src/docs/avocado-linux/tools/avocadoctl/commands/ext/merge.md create mode 100644 src/docs/avocado-linux/tools/avocadoctl/commands/ext/refresh.md create mode 100644 src/docs/avocado-linux/tools/avocadoctl/commands/ext/status.md create mode 100644 src/docs/avocado-linux/tools/avocadoctl/commands/ext/unmerge.md create mode 100644 src/docs/avocado-linux/tools/avocadoctl/commands/hitl/_category_.json create mode 100644 src/docs/avocado-linux/tools/avocadoctl/commands/hitl/mount.md create mode 100644 src/docs/avocado-linux/tools/avocadoctl/commands/hitl/unmount.md create mode 100644 src/docs/avocado-linux/tools/avocadoctl/commands/merge.md create mode 100644 src/docs/avocado-linux/tools/avocadoctl/commands/refresh.md create mode 100644 src/docs/avocado-linux/tools/avocadoctl/commands/root-authority.md create mode 100644 src/docs/avocado-linux/tools/avocadoctl/commands/runtime/_category_.json create mode 100644 src/docs/avocado-linux/tools/avocadoctl/commands/runtime/activate.md create mode 100644 src/docs/avocado-linux/tools/avocadoctl/commands/runtime/add.md create mode 100644 src/docs/avocado-linux/tools/avocadoctl/commands/runtime/inspect.md create mode 100644 src/docs/avocado-linux/tools/avocadoctl/commands/runtime/list.md create mode 100644 src/docs/avocado-linux/tools/avocadoctl/commands/runtime/remove.md create mode 100644 src/docs/avocado-linux/tools/avocadoctl/commands/serve.md create mode 100644 src/docs/avocado-linux/tools/avocadoctl/commands/status.md create mode 100644 src/docs/avocado-linux/tools/avocadoctl/commands/unmerge.md create mode 100644 src/docs/avocado-linux/tools/avocadoctl/configuration.md create mode 100644 src/docs/avocado-linux/tools/avocadoctl/os-bundles/_category_.json create mode 100644 src/docs/avocado-linux/tools/avocadoctl/os-bundles/bundle-format.md create mode 100644 src/docs/avocado-linux/tools/avocadoctl/os-bundles/overview.md create mode 100644 src/docs/avocado-linux/tools/avocadoctl/os-bundles/update-process.md create mode 100644 src/docs/avocado-linux/tools/avocadoctl/overview.md create mode 100644 src/docs/avocado-linux/tools/avocadoctl/runtime-management/_category_.json create mode 100644 src/docs/avocado-linux/tools/avocadoctl/runtime-management/activation-process.md create mode 100644 src/docs/avocado-linux/tools/avocadoctl/runtime-management/manifest-spec.md create mode 100644 src/docs/avocado-linux/tools/avocadoctl/runtime-management/runtime-lifecycle.md create mode 100644 src/docs/avocado-linux/tools/avocadoctl/varlink-api/_category_.json create mode 100644 src/docs/avocado-linux/tools/avocadoctl/varlink-api/org-avocado-extensions.md create mode 100644 src/docs/avocado-linux/tools/avocadoctl/varlink-api/org-avocado-hitl.md create mode 100644 src/docs/avocado-linux/tools/avocadoctl/varlink-api/org-avocado-root-authority.md create mode 100644 src/docs/avocado-linux/tools/avocadoctl/varlink-api/org-avocado-runtimes.md create mode 100644 src/docs/avocado-linux/tools/avocadoctl/varlink-api/overview.md diff --git a/src/docs/avocado-linux/tools/avocado-control.md b/src/docs/avocado-linux/tools/avocado-control.md deleted file mode 100644 index 992bd57d..00000000 --- a/src/docs/avocado-linux/tools/avocado-control.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -title: 'Avocado Control' -description: 'CLI tool for managing Avocado Linux system extensions and HITL testing - runtime control for systemd-sysext extensions with NFS-based development workflows.' ---- - -[Source](https://github.com/avocado-linux/avocado-control) - -CLI tool for managing Avocado Linux system extensions and hardware-in-the-loop (HITL) testing. Provides runtime control for systemd-sysext based extensions with commands to merge, unmerge, and refresh system extensions, plus NFS-based HITL mount operations for development workflows. diff --git a/src/docs/avocado-linux/tools/avocadoctl/_category_.json b/src/docs/avocado-linux/tools/avocadoctl/_category_.json new file mode 100644 index 00000000..6fe0db58 --- /dev/null +++ b/src/docs/avocado-linux/tools/avocadoctl/_category_.json @@ -0,0 +1,5 @@ +{ + "label": "avocadoctl", + "collapsible": true, + "collapsed": true +} diff --git a/src/docs/avocado-linux/tools/avocadoctl/commands/_category_.json b/src/docs/avocado-linux/tools/avocadoctl/commands/_category_.json new file mode 100644 index 00000000..09ed18ad --- /dev/null +++ b/src/docs/avocado-linux/tools/avocadoctl/commands/_category_.json @@ -0,0 +1,6 @@ +{ + "label": "Commands", + "position": 3, + "collapsible": true, + "collapsed": true +} diff --git a/src/docs/avocado-linux/tools/avocadoctl/commands/disable.md b/src/docs/avocado-linux/tools/avocadoctl/commands/disable.md new file mode 100644 index 00000000..3be3c435 --- /dev/null +++ b/src/docs/avocado-linux/tools/avocadoctl/commands/disable.md @@ -0,0 +1,36 @@ +--- +title: disable +description: 'Disable extensions for a specific runtime version.' +--- + +Disables extensions by removing symlinks from `/var/lib/avocado/os-releases/{version_id}/`. + +``` +avocadoctl disable [OPTIONS] [EXTENSION]... +``` + +### Options + +| Option | Description | +|---|---| +| `--os-release ` | OS release version. Defaults to the current system version. | +| `--all` | Disable all extensions | + +### Arguments + +| Argument | Description | +|---|---| +| `EXTENSION...` | One or more extension names to disable (required unless `--all` is used) | + +### Examples + +```bash +# Disable a single extension +avocadoctl disable my-app + +# Disable multiple extensions +avocadoctl disable my-app my-config + +# Disable all extensions +avocadoctl disable --all +``` diff --git a/src/docs/avocado-linux/tools/avocadoctl/commands/enable.md b/src/docs/avocado-linux/tools/avocadoctl/commands/enable.md new file mode 100644 index 00000000..9fdfb11d --- /dev/null +++ b/src/docs/avocado-linux/tools/avocadoctl/commands/enable.md @@ -0,0 +1,35 @@ +--- +title: enable +description: 'Enable extensions for a specific runtime version.' +--- + +Enables extensions by creating symlinks in `/var/lib/avocado/os-releases/{version_id}/`. The OS release version defaults to the current system's `VERSION_ID` from `/etc/os-release`. + +``` +avocadoctl enable [OPTIONS] ... +``` + +### Options + +| Option | Description | +|---|---| +| `--os-release ` | OS release version. Defaults to the current system version. | + +### Arguments + +| Argument | Description | +|---|---| +| `EXTENSION...` | One or more extension names to enable (required) | + +### Examples + +```bash +# Enable a single extension +avocadoctl enable my-app + +# Enable multiple extensions +avocadoctl enable my-app my-config + +# Enable for a specific OS release version +avocadoctl enable --os-release 1.2.0 my-app +``` diff --git a/src/docs/avocado-linux/tools/avocadoctl/commands/ext/_category_.json b/src/docs/avocado-linux/tools/avocadoctl/commands/ext/_category_.json new file mode 100644 index 00000000..c23ee9cc --- /dev/null +++ b/src/docs/avocado-linux/tools/avocadoctl/commands/ext/_category_.json @@ -0,0 +1,5 @@ +{ + "label": "ext", + "collapsible": true, + "collapsed": true +} diff --git a/src/docs/avocado-linux/tools/avocadoctl/commands/ext/list.md b/src/docs/avocado-linux/tools/avocadoctl/commands/ext/list.md new file mode 100644 index 00000000..908f9afb --- /dev/null +++ b/src/docs/avocado-linux/tools/avocadoctl/commands/ext/list.md @@ -0,0 +1,16 @@ +--- +title: ext list +description: 'List all available extensions in the extensions directory.' +--- + +Lists all extension images found in the configured extensions directory. Shows the name, version, path, and whether each extension is a sysext (overlays `/usr`, `/opt`) or confext (overlays `/etc`). + +``` +avocadoctl ext list [OPTIONS] +``` + +### Examples + +```bash +avocadoctl ext list +``` diff --git a/src/docs/avocado-linux/tools/avocadoctl/commands/ext/merge.md b/src/docs/avocado-linux/tools/avocadoctl/commands/ext/merge.md new file mode 100644 index 00000000..c4580d0b --- /dev/null +++ b/src/docs/avocado-linux/tools/avocadoctl/commands/ext/merge.md @@ -0,0 +1,16 @@ +--- +title: ext merge +description: 'Merge extensions using systemd-sysext and systemd-confext.' +--- + +Merges all enabled extensions into the running system. System extensions (sysext) overlay `/usr` and `/opt` while configuration extensions (confext) overlay `/etc`. After merging, runs depmod to update kernel module dependencies. Supports streaming progress output. + +``` +avocadoctl ext merge [OPTIONS] +``` + +### Examples + +```bash +avocadoctl ext merge +``` diff --git a/src/docs/avocado-linux/tools/avocadoctl/commands/ext/refresh.md b/src/docs/avocado-linux/tools/avocadoctl/commands/ext/refresh.md new file mode 100644 index 00000000..f0b533d5 --- /dev/null +++ b/src/docs/avocado-linux/tools/avocadoctl/commands/ext/refresh.md @@ -0,0 +1,16 @@ +--- +title: ext refresh +description: 'Unmerge and then merge extensions atomically.' +--- + +Performs an atomic refresh by first unmerging all extensions, then immediately merging them again. This picks up any changes to the set of enabled extensions or updated extension images. + +``` +avocadoctl ext refresh [OPTIONS] +``` + +### Examples + +```bash +avocadoctl ext refresh +``` diff --git a/src/docs/avocado-linux/tools/avocadoctl/commands/ext/status.md b/src/docs/avocado-linux/tools/avocadoctl/commands/ext/status.md new file mode 100644 index 00000000..9bc8a3fd --- /dev/null +++ b/src/docs/avocado-linux/tools/avocadoctl/commands/ext/status.md @@ -0,0 +1,16 @@ +--- +title: ext status +description: 'Show status of merged extensions.' +--- + +Shows detailed status of all extensions including name, version, type (sysext or confext), whether currently merged, origin, and image ID. + +``` +avocadoctl ext status [OPTIONS] +``` + +### Examples + +```bash +avocadoctl ext status +``` diff --git a/src/docs/avocado-linux/tools/avocadoctl/commands/ext/unmerge.md b/src/docs/avocado-linux/tools/avocadoctl/commands/ext/unmerge.md new file mode 100644 index 00000000..a2cb5414 --- /dev/null +++ b/src/docs/avocado-linux/tools/avocadoctl/commands/ext/unmerge.md @@ -0,0 +1,26 @@ +--- +title: ext unmerge +description: 'Unmerge extensions using systemd-sysext and systemd-confext.' +--- + +Unmerges all extensions from the running system. With `--unmount`, also unmounts persistent loop devices used by `.raw` extension images. + +``` +avocadoctl ext unmerge [OPTIONS] +``` + +### Options + +| Option | Description | +|---|---| +| `--unmount` | Also unmount all persistent loops for `.raw` extensions | + +### Examples + +```bash +# Unmerge all extensions +avocadoctl ext unmerge + +# Unmerge and unmount .raw loop devices +avocadoctl ext unmerge --unmount +``` diff --git a/src/docs/avocado-linux/tools/avocadoctl/commands/hitl/_category_.json b/src/docs/avocado-linux/tools/avocadoctl/commands/hitl/_category_.json new file mode 100644 index 00000000..8a91285e --- /dev/null +++ b/src/docs/avocado-linux/tools/avocadoctl/commands/hitl/_category_.json @@ -0,0 +1,5 @@ +{ + "label": "hitl", + "collapsible": true, + "collapsed": true +} diff --git a/src/docs/avocado-linux/tools/avocadoctl/commands/hitl/mount.md b/src/docs/avocado-linux/tools/avocadoctl/commands/hitl/mount.md new file mode 100644 index 00000000..6a39241e --- /dev/null +++ b/src/docs/avocado-linux/tools/avocadoctl/commands/hitl/mount.md @@ -0,0 +1,36 @@ +--- +title: hitl mount +description: 'Mount NFS extensions from a remote development server.' +--- + +Mounts extensions from a remote NFS server for hardware-in-the-loop (HITL) development. This enables live development on target hardware by mounting extension directories from the development host. NFS is mounted with NFSv4, hard timeout, and caching disabled for live updates. + +``` +avocadoctl hitl mount [OPTIONS] -s ... +``` + +### Options + +| Option | Description | +|---|---| +| `-s`, `--server-ip ` | NFS server IP address (required) | +| `-e`, `--server-port ` | NFS server port | + +### Arguments + +| Argument | Description | +|---|---| +| `EXTENSION...` | One or more extension names to mount | + +### Examples + +```bash +# Mount a single extension from a remote server +avocadoctl hitl mount -s 192.168.1.100 my-app + +# Mount multiple extensions +avocadoctl hitl mount -s 192.168.1.100 my-app my-config + +# Mount with a custom NFS port +avocadoctl hitl mount -s 192.168.1.100 -e 2049 my-app +``` diff --git a/src/docs/avocado-linux/tools/avocadoctl/commands/hitl/unmount.md b/src/docs/avocado-linux/tools/avocadoctl/commands/hitl/unmount.md new file mode 100644 index 00000000..4207bfa9 --- /dev/null +++ b/src/docs/avocado-linux/tools/avocadoctl/commands/hitl/unmount.md @@ -0,0 +1,26 @@ +--- +title: hitl unmount +description: 'Unmount NFS extensions.' +--- + +Unmounts previously mounted NFS extensions. Extensions are unmerged before unmounting to avoid dangling references. + +``` +avocadoctl hitl unmount [OPTIONS] ... +``` + +### Arguments + +| Argument | Description | +|---|---| +| `EXTENSION...` | One or more extension names to unmount | + +### Examples + +```bash +# Unmount a single extension +avocadoctl hitl unmount my-app + +# Unmount multiple extensions +avocadoctl hitl unmount my-app my-config +``` diff --git a/src/docs/avocado-linux/tools/avocadoctl/commands/merge.md b/src/docs/avocado-linux/tools/avocadoctl/commands/merge.md new file mode 100644 index 00000000..06e52f4e --- /dev/null +++ b/src/docs/avocado-linux/tools/avocadoctl/commands/merge.md @@ -0,0 +1,16 @@ +--- +title: merge +description: 'Merge extensions using systemd-sysext and systemd-confext. Alias for ext merge.' +--- + +Top-level alias for [`avocadoctl ext merge`](ext/merge). Merges all enabled extensions into the running system using systemd-sysext and systemd-confext. Runs depmod after merge to update kernel module dependencies. + +``` +avocadoctl merge [OPTIONS] +``` + +### Examples + +```bash +avocadoctl merge +``` diff --git a/src/docs/avocado-linux/tools/avocadoctl/commands/refresh.md b/src/docs/avocado-linux/tools/avocadoctl/commands/refresh.md new file mode 100644 index 00000000..3f4a3ce9 --- /dev/null +++ b/src/docs/avocado-linux/tools/avocadoctl/commands/refresh.md @@ -0,0 +1,16 @@ +--- +title: refresh +description: 'Unmerge and then merge extensions atomically. Alias for ext refresh.' +--- + +Top-level alias for [`avocadoctl ext refresh`](ext/refresh). Atomically unmerges and then merges all extensions, picking up any changes to the set of enabled extensions or updated extension images. + +``` +avocadoctl refresh [OPTIONS] +``` + +### Examples + +```bash +avocadoctl refresh +``` diff --git a/src/docs/avocado-linux/tools/avocadoctl/commands/root-authority.md b/src/docs/avocado-linux/tools/avocadoctl/commands/root-authority.md new file mode 100644 index 00000000..0cbd9823 --- /dev/null +++ b/src/docs/avocado-linux/tools/avocadoctl/commands/root-authority.md @@ -0,0 +1,16 @@ +--- +title: root-authority +description: 'Show the trusted signing keys from the TUF root authority.' +--- + +Displays the TUF (The Update Framework) trust anchor for this device. Shows key IDs, key types, and the roles each key is authorized to sign (timestamp, snapshot, targets, delegations). The root authority is stored at `/var/lib/avocado/metadata/root.json`. + +``` +avocadoctl root-authority [OPTIONS] +``` + +### Examples + +```bash +avocadoctl root-authority +``` diff --git a/src/docs/avocado-linux/tools/avocadoctl/commands/runtime/_category_.json b/src/docs/avocado-linux/tools/avocadoctl/commands/runtime/_category_.json new file mode 100644 index 00000000..45fec56c --- /dev/null +++ b/src/docs/avocado-linux/tools/avocadoctl/commands/runtime/_category_.json @@ -0,0 +1,5 @@ +{ + "label": "runtime", + "collapsible": true, + "collapsed": true +} diff --git a/src/docs/avocado-linux/tools/avocadoctl/commands/runtime/activate.md b/src/docs/avocado-linux/tools/avocadoctl/commands/runtime/activate.md new file mode 100644 index 00000000..a3e6f0e3 --- /dev/null +++ b/src/docs/avocado-linux/tools/avocadoctl/commands/runtime/activate.md @@ -0,0 +1,34 @@ +--- +title: runtime activate +description: 'Activate a staged runtime by ID.' +--- + +Activates a staged runtime, making it the current active runtime. The ID can be specified as a prefix as long as it is unambiguous. + +The activation process: + +1. Resolves the runtime by ID prefix. +2. If the runtime includes an OS bundle with a different `os_build_id` than the running system, an OS update is applied and a reboot is required. +3. If no OS change is needed, the `active` symlink is atomically switched and extensions are refreshed. + +See [Activation Process](../../runtime-management/activation-process) for full details. + +``` +avocadoctl runtime activate [OPTIONS] +``` + +### Arguments + +| Argument | Description | +|---|---| +| `ID` | Runtime ID or unambiguous prefix | + +### Examples + +```bash +# Activate by full ID +avocadoctl runtime activate a1b2c3d4e5f6 + +# Activate by ID prefix +avocadoctl runtime activate a1b2 +``` diff --git a/src/docs/avocado-linux/tools/avocadoctl/commands/runtime/add.md b/src/docs/avocado-linux/tools/avocadoctl/commands/runtime/add.md new file mode 100644 index 00000000..ff08581d --- /dev/null +++ b/src/docs/avocado-linux/tools/avocadoctl/commands/runtime/add.md @@ -0,0 +1,35 @@ +--- +title: runtime add +description: 'Add a runtime from a TUF repository or local manifest.' +--- + +Stages a new runtime on the device. There are two mutually exclusive sources: + +- `--url URL` downloads from a TUF-secured repository, verifying the trust chain (`root.json` -> timestamp -> snapshot -> targets). If the repository requires authentication, set the `AVOCADO_TUF_AUTH_TOKEN` environment variable. +- `--manifest PATH` reads a local `manifest.json` file. All extension images referenced in the manifest must already exist in the images directory. + +Both paths create a new runtime directory under `/var/lib/avocado/runtimes/{id}/` and install any new extension images into the shared image pool. + +``` +avocadoctl runtime add [OPTIONS] (--url | --manifest ) +``` + +### Options + +| Option | Description | +|---|---| +| `--url ` | TUF repository URL | +| `--manifest ` | Path to local `manifest.json` file | + +### Examples + +```bash +# Add from a TUF repository +avocadoctl runtime add --url https://tuf.example.com/repo + +# Add from a TUF repository with authentication +AVOCADO_TUF_AUTH_TOKEN=mytoken avocadoctl runtime add --url https://tuf.example.com/repo + +# Add from a local manifest +avocadoctl runtime add --manifest /path/to/manifest.json +``` diff --git a/src/docs/avocado-linux/tools/avocadoctl/commands/runtime/inspect.md b/src/docs/avocado-linux/tools/avocadoctl/commands/runtime/inspect.md new file mode 100644 index 00000000..f07983c9 --- /dev/null +++ b/src/docs/avocado-linux/tools/avocadoctl/commands/runtime/inspect.md @@ -0,0 +1,26 @@ +--- +title: runtime inspect +description: 'Inspect runtime details.' +--- + +Shows detailed information about a runtime including manifest version, build time, runtime name and version, all extensions with their image IDs, and OS bundle information if present. Omit the ID to inspect the currently active runtime. + +``` +avocadoctl runtime inspect [OPTIONS] [ID] +``` + +### Arguments + +| Argument | Description | +|---|---| +| `ID` | Runtime ID or unambiguous prefix. Inspects the active runtime if omitted. | + +### Examples + +```bash +# Inspect the active runtime +avocadoctl runtime inspect + +# Inspect a specific runtime by ID prefix +avocadoctl runtime inspect a1b2 +``` diff --git a/src/docs/avocado-linux/tools/avocadoctl/commands/runtime/list.md b/src/docs/avocado-linux/tools/avocadoctl/commands/runtime/list.md new file mode 100644 index 00000000..4525020c --- /dev/null +++ b/src/docs/avocado-linux/tools/avocadoctl/commands/runtime/list.md @@ -0,0 +1,16 @@ +--- +title: runtime list +description: 'List all staged and active runtimes.' +--- + +Lists all runtime manifests on the device. The active runtime is shown first, followed by other staged runtimes sorted by build time (newest first). Shows runtime name, version, short ID, and active status. + +``` +avocadoctl runtime list [OPTIONS] +``` + +### Examples + +```bash +avocadoctl runtime list +``` diff --git a/src/docs/avocado-linux/tools/avocadoctl/commands/runtime/remove.md b/src/docs/avocado-linux/tools/avocadoctl/commands/runtime/remove.md new file mode 100644 index 00000000..d70fbb41 --- /dev/null +++ b/src/docs/avocado-linux/tools/avocadoctl/commands/runtime/remove.md @@ -0,0 +1,26 @@ +--- +title: runtime remove +description: 'Remove a staged runtime by ID.' +--- + +Removes a staged runtime directory. The runtime ID can be specified as a prefix as long as it is unambiguous. The currently active runtime cannot be removed — activate a different runtime first. Shared extension images in the image pool are not removed. + +``` +avocadoctl runtime remove [OPTIONS] +``` + +### Arguments + +| Argument | Description | +|---|---| +| `ID` | Runtime ID or unambiguous prefix | + +### Examples + +```bash +# Remove by full ID +avocadoctl runtime remove a1b2c3d4e5f6 + +# Remove by ID prefix +avocadoctl runtime remove a1b2 +``` diff --git a/src/docs/avocado-linux/tools/avocadoctl/commands/serve.md b/src/docs/avocado-linux/tools/avocadoctl/commands/serve.md new file mode 100644 index 00000000..9d89b651 --- /dev/null +++ b/src/docs/avocado-linux/tools/avocadoctl/commands/serve.md @@ -0,0 +1,26 @@ +--- +title: serve +description: 'Start the Varlink IPC server daemon.' +--- + +Starts the avocadoctl Varlink daemon, listening for connections from CLI commands and third-party applications. See the [Varlink API](../varlink-api/overview) documentation for details on the exposed interfaces. + +``` +avocadoctl serve [OPTIONS] +``` + +### Options + +| Option | Description | +|---|---| +| `--address
` | Listen address. Default: `unix:/run/avocado/avocadoctl.sock` | + +### Examples + +```bash +# Start the daemon with default socket +avocadoctl serve + +# Start the daemon on a custom address +avocadoctl serve --address unix:/tmp/avocadoctl.sock +``` diff --git a/src/docs/avocado-linux/tools/avocadoctl/commands/status.md b/src/docs/avocado-linux/tools/avocadoctl/commands/status.md new file mode 100644 index 00000000..6fcd3229 --- /dev/null +++ b/src/docs/avocado-linux/tools/avocadoctl/commands/status.md @@ -0,0 +1,29 @@ +--- +title: status +description: 'Show overall system status including active runtime and merged extensions.' +--- + +Displays the active runtime information including its name, version, short ID, rootfs build ID, and initramfs build ID. Also shows the status of all currently merged extensions. + +``` +avocadoctl status [OPTIONS] +``` + +### Global Options + +| Option | Description | +|---|---| +| `-c`, `--config ` | Path to configuration file | +| `-v`, `--verbose` | Enable verbose output | +| `-o`, `--output ` | Output format | +| `--socket
` | Varlink socket address | + +### Examples + +```bash +# Show system status +avocadoctl status + +# Show status with verbose output +avocadoctl status --verbose +``` diff --git a/src/docs/avocado-linux/tools/avocadoctl/commands/unmerge.md b/src/docs/avocado-linux/tools/avocadoctl/commands/unmerge.md new file mode 100644 index 00000000..d4c06be4 --- /dev/null +++ b/src/docs/avocado-linux/tools/avocadoctl/commands/unmerge.md @@ -0,0 +1,26 @@ +--- +title: unmerge +description: 'Unmerge extensions using systemd-sysext and systemd-confext. Alias for ext unmerge.' +--- + +Top-level alias for [`avocadoctl ext unmerge`](ext/unmerge). Unmerges all extensions from the running system. Optionally unmounts persistent loop devices used by `.raw` extension images. + +``` +avocadoctl unmerge [OPTIONS] +``` + +### Options + +| Option | Description | +|---|---| +| `--unmount` | Also unmount all persistent loops for `.raw` extensions | + +### Examples + +```bash +# Unmerge all extensions +avocadoctl unmerge + +# Unmerge and unmount .raw loop devices +avocadoctl unmerge --unmount +``` diff --git a/src/docs/avocado-linux/tools/avocadoctl/configuration.md b/src/docs/avocado-linux/tools/avocadoctl/configuration.md new file mode 100644 index 00000000..73e0d09d --- /dev/null +++ b/src/docs/avocado-linux/tools/avocadoctl/configuration.md @@ -0,0 +1,82 @@ +--- +title: Configuration +sidebar_position: 2 +description: 'Configuration reference for avocadoctl including config file format, extension mutability modes, and environment variable overrides.' +--- + +avocadoctl is configured via a TOML file at `/etc/avocado/avocadoctl.conf`. All settings have sensible defaults and the config file is optional. + +## Configuration File + +```toml +[avocado.ext] +dir = "/var/lib/avocado/images" +sysext_mutable = "ephemeral" +confext_mutable = "ephemeral" + +[avocado] +runtimes_dir = "/var/lib/avocado" +socket = "unix:/run/avocado/avocadoctl.sock" + +[avocado.update] +stream_os_to_partition = false +``` + +## Extension Settings + +The `[avocado.ext]` section controls how extensions are stored and merged. + +| Key | Type | Default | Description | +|-----|------|---------|-------------| +| `dir` | string | `/var/lib/avocado/images` | Directory where extension images are stored | +| `sysext_mutable` | string | `ephemeral` | Mutability mode for system extensions (sysext) overlaying `/usr` and `/opt` | +| `confext_mutable` | string | `ephemeral` | Mutability mode for configuration extensions (confext) overlaying `/etc` | +| `mutable` | string | - | **Deprecated.** Legacy option that applies to both sysext and confext. Use the specific options above instead. | + +### Mutability Modes + +These values control how systemd-sysext and systemd-confext handle writes to the overlaid directories. + +| Value | Description | +|-------|-------------| +| `no` | Overlaid directories are read-only | +| `auto` | Let systemd decide based on the underlying filesystem | +| `yes` | Overlaid directories are writable (persistent) | +| `import` | Import the upper directory contents into the base on unmerge | +| `ephemeral` | Overlaid directories are writable but changes are discarded on unmerge | +| `ephemeral-import` | Like `ephemeral`, but imports upper contents on unmerge | + +## General Settings + +The `[avocado]` section controls base paths and daemon communication. + +| Key | Type | Default | Description | +|-----|------|---------|-------------| +| `runtimes_dir` | string | `/var/lib/avocado` | Base directory for runtimes, images, and the active symlink | +| `socket` | string | `unix:/run/avocado/avocadoctl.sock` | Varlink daemon socket address | + +## Update Settings + +The `[avocado.update]` section controls OS update behavior. + +| Key | Type | Default | Description | +|-----|------|---------|-------------| +| `stream_os_to_partition` | bool | `false` | Stream OS bundle artifacts directly from HTTP to partitions without staging to disk. Reduces disk I/O and temporary storage but disables resumable downloads for the OS bundle. | + +## Environment Variable Overrides + +Environment variables take precedence over config file values. + +| Variable | Overrides | Description | +|----------|-----------|-------------| +| `AVOCADO_BASE_DIR` | `avocado.runtimes_dir` | Override the base directory for all avocado data | +| `AVOCADO_EXTENSIONS_PATH` | `avocado.ext.dir` | Override the extensions image directory | + +## Precedence Order + +Settings are resolved in this order (highest priority first): + +1. CLI flags (e.g., `--socket`, `--config`) +2. Environment variables +3. Config file (`/etc/avocado/avocadoctl.conf`) +4. Built-in defaults diff --git a/src/docs/avocado-linux/tools/avocadoctl/os-bundles/_category_.json b/src/docs/avocado-linux/tools/avocadoctl/os-bundles/_category_.json new file mode 100644 index 00000000..6b4dbf50 --- /dev/null +++ b/src/docs/avocado-linux/tools/avocadoctl/os-bundles/_category_.json @@ -0,0 +1,6 @@ +{ + "label": "OS Bundles", + "position": 6, + "collapsible": true, + "collapsed": true +} diff --git a/src/docs/avocado-linux/tools/avocadoctl/os-bundles/bundle-format.md b/src/docs/avocado-linux/tools/avocadoctl/os-bundles/bundle-format.md new file mode 100644 index 00000000..d8d0cd4d --- /dev/null +++ b/src/docs/avocado-linux/tools/avocadoctl/os-bundles/bundle-format.md @@ -0,0 +1,218 @@ +--- +title: Bundle Format +sidebar_position: 2 +description: 'Specification of the OS bundle bundle.json format including update strategies, slot detection, artifacts, and verification.' +--- + +The `bundle.json` file inside an `.aos` archive describes how to apply the OS update. It is parsed by avocadoctl during the [update process](./update-process). + +## Full Example + +```json +{ + "format_version": 1, + "platform": "jetson-orin-nano", + "architecture": "aarch64", + "os_build_id": "avocado-os-20260312", + "initramfs_build_id": "initramfs-20260312", + "update": { + "strategy": "a-b", + "slot_detection": { + "type": "uboot-env", + "var": "boot_slot" + }, + "artifacts": [ + { + "name": "rootfs", + "file": "rootfs.img", + "sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855", + "size": 1073741824, + "slot_targets": { + "a": { "partition": "APP" }, + "b": { "partition": "APP_b" } + } + } + ], + "activate": [ + { + "type": "uboot-env", + "set": { "boot_slot": "b" } + } + ], + "rollback": [ + { + "type": "uboot-env", + "set": { "boot_slot": "a" } + } + ] + }, + "verify": { + "type": "os-release", + "field": "AVOCADO_OS_BUILD_ID", + "expected": "avocado-os-20260312" + }, + "verify_initramfs": { + "type": "os-release", + "field": "AVOCADO_INITRAMFS_BUILD_ID", + "expected": "initramfs-20260312" + } +} +``` + +## Top-Level Fields + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `format_version` | integer | Yes | Bundle format version. | +| `platform` | string | Yes | Target hardware platform identifier. | +| `architecture` | string | Yes | Target CPU architecture (e.g., `aarch64`, `x86-64`). | +| `os_build_id` | string | Yes | Identifier for this rootfs build version. | +| `initramfs_build_id` | string | No | Identifier for this initramfs build version. | +| `update` | object | No | Update configuration. Omit if the bundle is metadata-only. | +| `verify` | object | No | Post-update verification for the rootfs. | +| `verify_initramfs` | object | No | Post-update verification for the initramfs. | +| `layout` | object | No | Partition layout for MBR-based targets. | + +## Slot Detection Strategies + +The `update.slot_detection` object determines how avocadoctl identifies the currently active boot slot. + +### uboot-env + +Reads a U-Boot environment variable to determine the active slot. + +```json +{ + "type": "uboot-env", + "var": "boot_slot" +} +``` + +| Field | Description | +|-------|-------------| +| `var` | U-Boot environment variable name containing the active slot identifier (e.g., "a" or "b"). | + +### command + +Runs a shell command whose stdout output is the active slot identifier. + +```json +{ + "type": "command", + "command": ["/usr/bin/detect-slot"] +} +``` + +| Field | Description | +|-------|-------------| +| `command` | Array of command and arguments to execute. The command's stdout is trimmed and used as the slot name. | + +### sdboot-efi + +Uses systemd-boot EFI partition mappings. Maps slot names to EFI partition device paths. + +```json +{ + "type": "sdboot-efi", + "partitions": { + "a": "/dev/disk/by-partlabel/esp-a", + "b": "/dev/disk/by-partlabel/esp-b" + } +} +``` + +| Field | Description | +|-------|-------------| +| `partitions` | Map of slot names to EFI partition device paths. | + +## Artifacts + +Each entry in `update.artifacts` describes a file to write to a partition. + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `name` | string | Yes | Artifact name (e.g., "rootfs", "initramfs"). | +| `file` | string | Yes | Filename within the `.aos` archive. | +| `sha256` | string | Yes | Expected SHA-256 hash of the artifact file. | +| `size` | integer | No | File size in bytes. | +| `slot_targets` | object | Yes | Map of slot names to target partitions. | +| `slot_targets.{slot}.partition` | string | Yes | Partition identifier (PARTLABEL for GPT, name for MBR layout). | + +## Activation Actions + +The `update.activate` array defines actions executed after artifacts are written to switch the boot target to the new slot. Actions are executed in order. + +### uboot-env + +Set U-Boot environment variables. + +```json +{ "type": "uboot-env", "set": { "boot_slot": "b" } } +``` + +### command + +Run a shell command. + +```json +{ "type": "command", "command": ["/usr/bin/set-boot-slot", "b"] } +``` + +### mbr-switch + +Switch MBR partition layout by rewriting the partition table. + +```json +{ + "type": "mbr-switch", + "devpath": "/dev/mmcblk0", + "slot_layouts": { + "a": ["layout-a.json"], + "b": ["layout-b.json"] + } +} +``` + +### efibootmgr + +Set the EFI boot entry for the target slot. + +```json +{ + "type": "efibootmgr", + "slot_entries": { + "a": "0001", + "b": "0002" + } +} +``` + +## Rollback Actions + +The optional `update.rollback` array has the same format as `activate`. These actions are executed if verification fails after reboot to restore the previous boot slot. + +## Verification + +The `verify` and `verify_initramfs` objects define how to confirm the OS update was successful after reboot. + +| Field | Type | Description | +|-------|------|-------------| +| `type` | string | Verification type (e.g., `os-release`). | +| `field` | string | Field name to check in `/etc/os-release`. | +| `expected` | string | Expected value. Update is considered successful when the field matches. | + +## Partition Layout (MBR) + +The optional `layout` object is used on MBR-based systems where partitions are identified by offset rather than label. + +| Field | Type | Description | +|-------|------|-------------| +| `device` | string | Block device path (e.g., `/dev/mmcblk0`). | +| `block_size` | integer | Optional block size in bytes. | +| `partitions` | array | List of partition definitions. | +| `partitions[].name` | string | Partition name for referencing in `slot_targets`. | +| `partitions[].offset` | number | Partition start offset. | +| `partitions[].offset_unit` | string | Unit for offset (e.g., `MiB`, `sectors`). | +| `partitions[].size` | number | Partition size. | +| `partitions[].size_unit` | string | Unit for size (e.g., `MiB`, `GiB`). | +| `partitions[].expand` | string | Optional expand strategy. | diff --git a/src/docs/avocado-linux/tools/avocadoctl/os-bundles/overview.md b/src/docs/avocado-linux/tools/avocadoctl/os-bundles/overview.md new file mode 100644 index 00000000..19806644 --- /dev/null +++ b/src/docs/avocado-linux/tools/avocadoctl/os-bundles/overview.md @@ -0,0 +1,22 @@ +--- +title: Overview +sidebar_position: 1 +description: 'Introduction to Avocado Linux OS bundles for rootfs and initramfs updates with A/B partition switching.' +--- + +An OS bundle is a self-describing archive containing the base operating system image (rootfs and/or initramfs) along with metadata describing the update strategy, slot detection, verification, and partition layout. + +## When OS Bundles Are Used + +A [runtime manifest](../runtime-management/manifest-spec) may optionally include an `os_bundle` reference. When a runtime with a different `os_build_id` than the running system is activated, the OS bundle [update process](./update-process) is triggered automatically. + +## Relationship to Runtimes + +OS bundles are referenced by `image_id` in the runtime manifest and stored as `.raw` files in the shared image pool (`/var/lib/avocado/images/`) alongside extension images. A runtime may or may not include an OS bundle -- runtimes that only update extensions do not need one. + +## OS Bundle Files + +OS bundles are distributed as `.aos` files (tar.zst compressed archives) containing: + +- **`bundle.json`** -- Update metadata and configuration. See [Bundle Format](./bundle-format) for the full specification. +- **Artifact files** -- The actual rootfs and/or initramfs images to be written to partitions. diff --git a/src/docs/avocado-linux/tools/avocadoctl/os-bundles/update-process.md b/src/docs/avocado-linux/tools/avocadoctl/os-bundles/update-process.md new file mode 100644 index 00000000..58bdd323 --- /dev/null +++ b/src/docs/avocado-linux/tools/avocadoctl/os-bundles/update-process.md @@ -0,0 +1,105 @@ +--- +title: Update Process +sidebar_position: 3 +description: 'Step-by-step walkthrough of the OS bundle update process including extraction, artifact writing, slot activation, and verification.' +--- + +This page describes the end-to-end OS bundle update flow that occurs when a runtime with a different `os_build_id` than the running system is [activated](../runtime-management/activation-process). + +## End-to-End Update Flow + +### 1. Extract Bundle + +The `.aos` file (a tar.zst compressed archive) is extracted to a staging directory at `/var/lib/avocado/.os-update-staging/`. Any previous staging artifacts are cleaned up first. + +### 2. Parse bundle.json + +The `bundle.json` file is read and parsed. See [Bundle Format](./bundle-format) for the full specification. + +### 3. Check If Already Up-to-Date + +If a `verify` configuration is present, avocadoctl checks the current system's `/etc/os-release` (or `/sysroot/etc/os-release` in initrd scope). If the field already matches the expected value, the update is skipped. + +### 4. Detect Current Slot + +The configured slot detection strategy determines the currently active boot slot: + +- **uboot-env** -- Reads the U-Boot environment variable. +- **command** -- Runs the configured command and reads stdout. +- **sdboot-efi** -- Checks which EFI partition is mounted. + +### 5. Determine Inactive Slot + +For an A/B strategy, the inactive slot is the opposite of the current slot (e.g., if current is "a", target is "b"). + +### 6. Write Artifacts + +Each artifact is written to the inactive slot's target partition: + +1. The artifact file's SHA-256 hash is verified against the expected value. +2. For GPT targets: the partition is identified by PARTLABEL. +3. For MBR targets: the partition offset is resolved from the `layout` configuration. +4. The artifact is written to the target device/partition using buffered I/O with fsync. + +### 7. Activate New Slot + +The `activate` actions are executed in order to update the boot configuration: + +- U-Boot environment variables are set. +- Shell commands are executed. +- MBR partition tables are rewritten. +- EFI boot entries are updated. + +### 8. Write Pending Update Marker + +A `pending-update.json` file is written to the avocado base directory containing: + +```json +{ + "os_build_id": "avocado-os-20260312", + "initramfs_build_id": "initramfs-20260312", + "verify": { + "type": "os-release", + "field": "AVOCADO_OS_BUILD_ID", + "expected": "avocado-os-20260312" + }, + "verify_initramfs": { + "type": "os-release", + "field": "AVOCADO_INITRAMFS_BUILD_ID", + "expected": "initramfs-20260312" + }, + "rollback": [], + "previous_slot": "a", + "layout": {}, + "runtime_id": "a1b2c3d4-e5f6-7890-abcd-ef0123456789" +} +``` + +The `runtime_id` field identifies which runtime to activate after successful verification. + +### 9. Reboot + +The system must be rebooted to boot into the new OS image on the inactive slot. + +### 10. Post-Boot Verification + +On the next boot, avocadoctl checks for `pending-update.json`: + +1. If present, reads the verify configuration. +2. Checks `/etc/os-release` for the expected field value. +3. If verification succeeds: activates the runtime (switches the active symlink) and refreshes extensions. +4. If verification fails: executes rollback actions to restore the previous boot slot. + +## Streaming Mode + +When `stream_os_to_partition = true` is set in the [configuration](../configuration), OS bundle artifacts are streamed directly from HTTP to the target partition during a TUF-based update. This skips the intermediate staging step. + +**Trade-offs:** + +- Reduces disk I/O and temporary storage requirements. +- Disables resumable downloads for the OS bundle (the entire artifact must be re-downloaded on failure). +- Extension images are still staged normally. + +## Cleanup + +After a successful update (or skip), the staging directory at `/var/lib/avocado/.os-update-staging/` is removed. diff --git a/src/docs/avocado-linux/tools/avocadoctl/overview.md b/src/docs/avocado-linux/tools/avocadoctl/overview.md new file mode 100644 index 00000000..5220b2b7 --- /dev/null +++ b/src/docs/avocado-linux/tools/avocadoctl/overview.md @@ -0,0 +1,63 @@ +--- +title: Overview +sidebar_position: 1 +description: 'avocadoctl is a CLI tool and Varlink IPC daemon for managing Avocado Linux system extensions, runtimes, OS bundles, and hardware-in-the-loop testing on device.' +--- + +[Source](https://github.com/avocado-linux/avocado-control) + +avocadoctl is the on-device management tool for Avocado Linux. It provides both a command-line interface and a Varlink IPC daemon for programmatic access. avocadoctl is pre-installed on all Avocado runtimes. + +## Capabilities + +- **Extension management** - Merge, unmerge, enable, and disable systemd-sysext and systemd-confext based system extensions +- **Runtime lifecycle** - Stage, activate, inspect, and remove runtime configurations via TUF-secured repositories or local manifests +- **OS bundle updates** - Apply rootfs and initramfs updates using A/B partition switching with integrity verification +- **Hardware-in-the-loop (HITL) testing** - Mount and unmount NFS-based extensions from a remote development server +- **Varlink IPC daemon** - Exposes all functionality over a Unix socket for 3rd party application integration + +## Architecture + +avocadoctl operates in a client-daemon model. The daemon listens on a Unix socket and exposes four Varlink interfaces. It is automatically started at boot by the included `avocadoctl` service extension, which is enabled by default in both the initramfs and system scopes. CLI commands connect to the daemon to execute operations. Third-party applications on the device can also connect to the same socket. + +``` +┌─────────────────┐ ┌─────────────────────────────────────┐ +│ avocadoctl CLI │────▶│ avocadoctl serve (Varlink daemon) │ +└─────────────────┘ │ │ +┌─────────────────┐ │ org.avocado.Extensions │ +│ 3rd party app │────▶│ org.avocado.Runtimes │ +│ (C, Python, etc)│ │ org.avocado.Hitl │ +└─────────────────┘ │ org.avocado.RootAuthority │ + └─────────────────────────────────────┘ + Socket: unix:/run/avocado/avocadoctl.sock +``` + +## On-Device Directory Layout + +``` +/var/lib/avocado/ +├── active # symlink → runtimes/{active_runtime_id} +├── runtimes/ +│ ├── {runtime_id}/ +│ │ └── manifest.json # runtime manifest +│ └── {runtime_id}/ +│ └── manifest.json +├── images/ +│ ├── {image_id}.raw # extension images (content-addressable) +│ └── {image_id}.raw # OS bundle images +├── os-releases/ +│ └── {version_id}/ +│ ├── {ext_name} → symlink # enabled extension symlinks +│ └── {ext_name} → symlink +└── metadata/ + └── root.json # TUF trust anchor +``` + +## Global Flags + +| Flag | Description | +|------|-------------| +| `-c, --config ` | Path to custom config file (default: `/etc/avocado/avocadoctl.conf`) | +| `-v, --verbose` | Enable verbose output | +| `-o, --output ` | Output format: `table` (default) or `json` | +| `--socket
` | Varlink daemon socket address (overrides config) | diff --git a/src/docs/avocado-linux/tools/avocadoctl/runtime-management/_category_.json b/src/docs/avocado-linux/tools/avocadoctl/runtime-management/_category_.json new file mode 100644 index 00000000..5b29471c --- /dev/null +++ b/src/docs/avocado-linux/tools/avocadoctl/runtime-management/_category_.json @@ -0,0 +1,6 @@ +{ + "label": "Runtime Management", + "position": 5, + "collapsible": true, + "collapsed": true +} diff --git a/src/docs/avocado-linux/tools/avocadoctl/runtime-management/activation-process.md b/src/docs/avocado-linux/tools/avocadoctl/runtime-management/activation-process.md new file mode 100644 index 00000000..4bc0193a --- /dev/null +++ b/src/docs/avocado-linux/tools/avocadoctl/runtime-management/activation-process.md @@ -0,0 +1,55 @@ +--- +title: Activation Process +sidebar_position: 3 +description: 'Detailed walkthrough of what happens when a runtime is activated, including OS update detection, symlink switching, and extension refresh.' +--- + +This page describes the full sequence of steps that occur when `avocadoctl runtime activate ` is called. + +## Activation Flow + +### Step 1: Resolve Runtime + +The provided ID (or prefix) is matched against staged runtimes. If the prefix matches multiple runtimes, an `AmbiguousRuntimeId` error is returned with the list of candidates. + +### Step 2: Check for OS Change + +If the target runtime includes an `os_bundle` with an `os_build_id`, it is compared against the running system's `AVOCADO_OS_BUILD_ID` (read from `/etc/os-release`). If they differ, an OS update is required. + +### Step 3a: OS Update Path + +When an OS change is needed: + +1. The OS bundle `.raw` image is extracted and its `bundle.json` parsed. +2. The current boot slot is detected (using uboot-env, command, or sdboot-efi strategy). +3. Artifacts are written to the inactive slot's partitions with SHA-256 verification. +4. Boot activation actions are executed to mark the new slot as bootable. +5. A `pending-update.json` marker is written containing the runtime ID. +6. The system must be rebooted to boot into the new OS. +7. On next boot, the pending update is verified and the runtime is activated. + +See [OS Bundle Update Process](../os-bundles/update-process) for full details. + +### Step 3b: Extension-Only Path + +When no OS change is needed: + +1. The `/var/lib/avocado/active` symlink is atomically switched to point to the target runtime. +2. Extensions are refreshed: all existing extensions are unmerged, then the new runtime's extensions are merged. +3. During merge, extensions are ordered deterministically based on their position in the [manifest](./manifest-spec). +4. `depmod` is run to update kernel module dependencies. + +## Extension Refresh During Activation + +The extension refresh process during activation: + +1. Scan enabled extensions for the current OS release version. +2. Detect sysext vs confext types from extension metadata. +3. Apply deterministic ordering (extensions listed in manifest get merge index prefixes). +4. Execute `systemd-sysext merge` for system extensions. +5. Execute `systemd-confext merge` for configuration extensions. +6. Run `depmod` to rebuild kernel module dependency information. + +## Atomicity + +The symlink switch from the old runtime to the new runtime is atomic on Linux (a single `rename` system call). If the process crashes between the symlink switch and extension refresh, the active runtime is correct but extensions may need a manual refresh with `avocadoctl refresh`. diff --git a/src/docs/avocado-linux/tools/avocadoctl/runtime-management/manifest-spec.md b/src/docs/avocado-linux/tools/avocadoctl/runtime-management/manifest-spec.md new file mode 100644 index 00000000..6c646f09 --- /dev/null +++ b/src/docs/avocado-linux/tools/avocadoctl/runtime-management/manifest-spec.md @@ -0,0 +1,105 @@ +--- +title: Runtime Manifest Specification +sidebar_position: 1 +description: 'Complete specification of the Avocado Linux runtime manifest format including all fields, versioning, and image ID scheme.' +--- + +The runtime manifest is a JSON file that describes a complete runtime configuration, including the runtime identity, extensions, and optional OS bundle. It is stored at `/var/lib/avocado/runtimes/{runtime_id}/manifest.json`. + +## Full Example (with OS bundle) + +```json +{ + "manifest_version": 2, + "id": "a1b2c3d4-e5f6-7890-abcd-ef0123456789", + "built_at": "2026-03-12T10:30:00Z", + "runtime": { + "name": "production", + "version": "1.2.0" + }, + "extensions": [ + { + "name": "my-app", + "version": "2.1.0", + "image_id": "f47ac10b-58cc-5372-8567-0e02b2c3d479" + }, + { + "name": "my-config", + "version": "1.0.0", + "image_id": "7c9e6679-7425-540b-8c36-e23b1e3b1e81" + } + ], + "os_bundle": { + "image_id": "deadbeef-1234-5678-abcd-000000000000", + "sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855", + "os_build_id": "avocado-os-20260312", + "initramfs_build_id": "initramfs-20260312" + } +} +``` + +## Minimal Example (extensions only) + +```json +{ + "manifest_version": 1, + "id": "abc12345-def6-7890-abcd-ef0123456789", + "built_at": "2026-03-12T10:30:00Z", + "runtime": { + "name": "dev", + "version": "0.1.0" + }, + "extensions": [ + { + "name": "my-app", + "version": "0.1.0", + "image_id": "f47ac10b-58cc-5372-8567-0e02b2c3d479" + } + ] +} +``` + +## Field Reference + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `manifest_version` | integer | Yes | Schema version. `1` for extensions-only manifests, `2` adds `initramfs_build_id` support. | +| `id` | string | Yes | Unique identifier for this runtime, typically a UUID. Used as the directory name under `runtimes/`. | +| `built_at` | string | Yes | ISO-8601 timestamp of when the runtime was built. | +| `runtime` | object | Yes | Runtime identity. | +| `runtime.name` | string | Yes | Human-readable runtime name (e.g., "production", "dev"). | +| `runtime.version` | string | Yes | Semantic version of the runtime. | +| `extensions` | array | Yes | List of extension images included in this runtime. May be empty. | +| `extensions[].name` | string | Yes | Extension name. | +| `extensions[].version` | string | Yes | Extension version. | +| `extensions[].image_id` | string | No | UUIDv5 content-addressable image identifier. When present, the image file is `{image_id}.raw`. | +| `os_bundle` | object | No | Optional OS bundle reference for rootfs/initramfs updates. | +| `os_bundle.image_id` | string | Yes* | UUIDv5 identifier for the OS bundle image file. *Required if `os_bundle` is present. | +| `os_bundle.sha256` | string | Yes* | SHA-256 hash of the OS bundle `.raw` file for integrity verification. | +| `os_bundle.os_build_id` | string | No | Identifies the rootfs version. Compared against the running system's `AVOCADO_OS_BUILD_ID` to detect OS changes. | +| `os_bundle.initramfs_build_id` | string | No | Identifies the initramfs version. Requires `manifest_version` >= 2. | + +## Image ID Scheme + +Extension and OS bundle images use UUIDv5 content-addressable identifiers. IDs are generated deterministically from the fixed namespace UUID `7488fa35-6390-425b-bbbf-b156cfe1eed2` and the extension name/version. This provides deduplication: runtimes that share the same extension at the same version reference the same image file. + +## Image Resolution + +When `image_id` is present: + +``` +/var/lib/avocado/images/{image_id}.raw +``` + +When `image_id` is absent (legacy): + +``` +/var/lib/avocado/images/{name}-{version}.raw +``` + +## Manifest Version History + +| Version | Changes | +|---------|---------| +| 1 | Initial format with extensions and optional `os_bundle` (supports `os_build_id`). | +| 2 | Adds `initramfs_build_id` to `os_bundle` for independent initramfs version tracking. | diff --git a/src/docs/avocado-linux/tools/avocadoctl/runtime-management/runtime-lifecycle.md b/src/docs/avocado-linux/tools/avocadoctl/runtime-management/runtime-lifecycle.md new file mode 100644 index 00000000..3dcbfa47 --- /dev/null +++ b/src/docs/avocado-linux/tools/avocadoctl/runtime-management/runtime-lifecycle.md @@ -0,0 +1,67 @@ +--- +title: Runtime Lifecycle +sidebar_position: 2 +description: 'How runtimes are staged, listed, inspected, activated, and removed on an Avocado Linux device.' +--- + +A runtime progresses through several states during its lifecycle on a device. This page describes each state and the operations that transition between them. + +## Runtime States + +- **Staged** -- A runtime manifest exists under `/var/lib/avocado/runtimes/{id}/` but is not the active runtime. All referenced extension images (and optional OS bundle image) are present in the shared image pool. +- **Active** -- The `/var/lib/avocado/active` symlink points to this runtime. Its extensions are merged into the running system. +- **Pending reboot** -- An OS update has been written to the inactive partition slot and a reboot is required to complete activation. A `pending-update.json` marker file is present. + +## Adding a Runtime + +Runtimes can be added to the device through two methods. + +### From a TUF Repository + +Using `runtime add --url`: + +1. Load the local TUF trust anchor (`metadata/root.json`). +2. Download and verify the TUF metadata chain: `timestamp.json` -> `snapshot.json` -> `targets.json`. +3. Walk TUF delegations for extension targets. +4. Download the manifest and all referenced `.raw` extension images to a staging area (`.update-staging/`). +5. Verify SHA-256 hashes of all downloaded files. +6. Install images from staging to the shared image pool (`/var/lib/avocado/images/`), skipping any that already exist (content-addressable deduplication). +7. Create the runtime directory and write `manifest.json`. + +### From a Local Manifest + +Using `runtime add --manifest`: + +1. Read the manifest JSON file from the provided path. +2. Validate that all referenced extension images and optional OS bundle image already exist on disk. +3. Create the runtime directory and copy `manifest.json`. + +## Listing Runtimes + +Runtimes are listed with the active runtime first, then remaining runtimes sorted by build time (newest first). Each entry shows: + +- Runtime name +- Version +- Short ID (first 8 characters) +- Whether it is active + +## Inspecting a Runtime + +Inspect shows full details for a specific runtime or the active runtime (when ID is omitted). Details include: + +- Manifest version +- Full ID +- Build timestamp +- Runtime name and version +- All extensions with their image IDs +- OS bundle information if present + +## Removing a Runtime + +- The active runtime cannot be removed. Activate a different runtime first. +- Removing a runtime deletes the runtime directory (`/var/lib/avocado/runtimes/{id}/`). +- Shared images in `/var/lib/avocado/images/` are not removed, as they may be referenced by other runtimes. + +## The Active Symlink + +The active runtime is tracked by a symlink at `/var/lib/avocado/active` pointing to `runtimes/{active_runtime_id}`. This symlink is switched atomically during [activation](./activation-process). Because it uses a single `rename` system call, there is no window where the symlink is missing or points to an invalid target. diff --git a/src/docs/avocado-linux/tools/avocadoctl/varlink-api/_category_.json b/src/docs/avocado-linux/tools/avocadoctl/varlink-api/_category_.json new file mode 100644 index 00000000..6a4cda06 --- /dev/null +++ b/src/docs/avocado-linux/tools/avocadoctl/varlink-api/_category_.json @@ -0,0 +1,6 @@ +{ + "label": "Varlink API", + "position": 4, + "collapsible": true, + "collapsed": true +} diff --git a/src/docs/avocado-linux/tools/avocadoctl/varlink-api/org-avocado-extensions.md b/src/docs/avocado-linux/tools/avocadoctl/varlink-api/org-avocado-extensions.md new file mode 100644 index 00000000..32b507e5 --- /dev/null +++ b/src/docs/avocado-linux/tools/avocadoctl/varlink-api/org-avocado-extensions.md @@ -0,0 +1,513 @@ +--- +title: org.avocado.Extensions +sidebar_position: 2 +description: 'Varlink interface for managing Avocado Linux system extensions - merge, unmerge, enable, disable, and query status.' +--- + +# org.avocado.Extensions + +Manages Avocado Linux system extensions (sysext and confext images). This interface provides methods to list, merge, unmerge, refresh, enable, disable, and query the status of extensions. + +## Interface Definition + +```varlink +# Extension management for Avocado Linux system extensions +interface org.avocado.Extensions + +type Extension ( + name: string, + version: ?string, + path: string, + isSysext: bool, + isConfext: bool, + isDirectory: bool +) + +type ExtensionStatus ( + name: string, + version: ?string, + isSysext: bool, + isConfext: bool, + isMerged: bool, + origin: ?string, + imageId: ?string +) + +# List all available extensions in the extensions directory +method List() -> (extensions: []Extension) + +# Merge extensions using systemd-sysext and systemd-confext +# Supports streaming: client may set more=true to receive per-message progress +method Merge() -> (message: string, done: bool) + +# Unmerge extensions +# Supports streaming: client may set more=true to receive per-message progress +method Unmerge(unmount: ?bool) -> (message: string, done: bool) + +# Refresh extensions (unmerge then merge) +# Supports streaming: client may set more=true to receive per-message progress +method Refresh() -> (message: string, done: bool) + +# Enable extensions for a specific OS release version +method Enable(extensions: []string, osRelease: ?string) -> (enabled: int, failed: int) + +# Disable extensions for a specific OS release version +method Disable(extensions: ?[]string, all: ?bool, osRelease: ?string) -> (disabled: int, failed: int) + +# Show status of merged extensions +method Status() -> (extensions: []ExtensionStatus) + +error ExtensionNotFound (name: string) +error MergeFailed (reason: string) +error UnmergeFailed (reason: string) +error ConfigurationError (message: string) +error CommandFailed (command: string, message: string) +``` + +## Types + +### Extension + +Represents an extension image or directory available on the filesystem. + +| Field | Type | Description | +|-------|------|-------------| +| `name` | `string` | Extension name (derived from the image filename) | +| `version` | `?string` | Extension version, if embedded in the image metadata | +| `path` | `string` | Absolute path to the extension image or directory | +| `isSysext` | `bool` | `true` if this is a system extension (overlays `/usr`) | +| `isConfext` | `bool` | `true` if this is a configuration extension (overlays `/etc`) | +| `isDirectory` | `bool` | `true` if the extension is a plain directory rather than an image file | + +### ExtensionStatus + +Represents the current status of an extension, including whether it is merged into the running system. + +| Field | Type | Description | +|-------|------|-------------| +| `name` | `string` | Extension name | +| `version` | `?string` | Extension version | +| `isSysext` | `bool` | `true` if this is a system extension | +| `isConfext` | `bool` | `true` if this is a configuration extension | +| `isMerged` | `bool` | `true` if the extension is currently merged into the root filesystem | +| `origin` | `?string` | Origin identifier (e.g., the TUF target name) | +| `imageId` | `?string` | Image digest or build identifier | + +## Methods + +### List + +List all available extensions in the extensions directory. + +**Signature:** `List() -> (extensions: []Extension)` + +**Parameters:** None. + +**Returns:** + +| Field | Type | Description | +|-------|------|-------------| +| `extensions` | `[]Extension` | Array of available extension objects | + +**C Example:** + +```c +VarlinkObject *parameters = NULL; +VarlinkObject *reply = NULL; +long r; + +varlink_object_new(¶meters); +r = varlink_connection_call(connection, "org.avocado.Extensions.List", parameters, 0, &reply); +if (r < 0) { + fprintf(stderr, "Call failed: %s\n", varlink_error_string(-r)); + varlink_object_unref(parameters); + return; +} + +VarlinkArray *extensions; +varlink_object_get_array(reply, "extensions", &extensions); + +for (unsigned long i = 0; i < varlink_array_get_n_elements(extensions); i++) { + VarlinkObject *ext; + varlink_array_get_object(extensions, i, &ext); + + const char *name, *path; + bool is_sysext, is_confext; + + varlink_object_get_string(ext, "name", &name); + varlink_object_get_string(ext, "path", &path); + varlink_object_get_bool(ext, "isSysext", &is_sysext); + varlink_object_get_bool(ext, "isConfext", &is_confext); + + printf("%-30s sysext=%d confext=%d %s\n", name, is_sysext, is_confext, path); +} + +varlink_object_unref(reply); +varlink_object_unref(parameters); +``` + +### Merge + +Merge all enabled extensions into the running system using `systemd-sysext` and `systemd-confext`. + +**Signature:** `Merge() -> (message: string, done: bool)` + +**Parameters:** None. + +**Returns (streaming):** + +| Field | Type | Description | +|-------|------|-------------| +| `message` | `string` | Progress message describing the current step | +| `done` | `bool` | `true` on the final reply | + +**Streaming:** Yes. Call with `VARLINK_CALL_MORE` to receive progress updates. + +**C Example:** + +```c +VarlinkObject *parameters = NULL; +long r; + +varlink_object_new(¶meters); + +r = varlink_connection_call(connection, "org.avocado.Extensions.Merge", + parameters, VARLINK_CALL_MORE, NULL); +if (r < 0) { + fprintf(stderr, "Call failed: %s\n", varlink_error_string(-r)); + varlink_object_unref(parameters); + return; +} + +VarlinkObject *reply = NULL; +while ((r = varlink_connection_reply(connection, &reply)) >= 0) { + const char *message; + varlink_object_get_string(reply, "message", &message); + printf("[merge] %s\n", message); + + bool done; + varlink_object_get_bool(reply, "done", &done); + + varlink_object_unref(reply); + reply = NULL; + + if (done) + break; +} + +varlink_object_unref(parameters); +``` + +### Unmerge + +Unmerge extensions from the running system. + +**Signature:** `Unmerge(unmount: ?bool) -> (message: string, done: bool)` + +**Parameters:** + +| Field | Type | Description | +|-------|------|-------------| +| `unmount` | `?bool` | If `true`, also unmount the extension images. Defaults to `false`. | + +**Returns (streaming):** + +| Field | Type | Description | +|-------|------|-------------| +| `message` | `string` | Progress message describing the current step | +| `done` | `bool` | `true` on the final reply | + +**Streaming:** Yes. Call with `VARLINK_CALL_MORE` to receive progress updates. + +**C Example:** + +```c +VarlinkObject *parameters = NULL; +long r; + +varlink_object_new(¶meters); +varlink_object_set_bool(parameters, "unmount", true); + +r = varlink_connection_call(connection, "org.avocado.Extensions.Unmerge", + parameters, VARLINK_CALL_MORE, NULL); +if (r < 0) { + fprintf(stderr, "Call failed: %s\n", varlink_error_string(-r)); + varlink_object_unref(parameters); + return; +} + +VarlinkObject *reply = NULL; +while ((r = varlink_connection_reply(connection, &reply)) >= 0) { + const char *message; + varlink_object_get_string(reply, "message", &message); + printf("[unmerge] %s\n", message); + + bool done; + varlink_object_get_bool(reply, "done", &done); + + varlink_object_unref(reply); + reply = NULL; + + if (done) + break; +} + +varlink_object_unref(parameters); +``` + +### Refresh + +Unmerge and then re-merge all enabled extensions. This is equivalent to calling `Unmerge` followed by `Merge`. + +**Signature:** `Refresh() -> (message: string, done: bool)` + +**Parameters:** None. + +**Returns (streaming):** + +| Field | Type | Description | +|-------|------|-------------| +| `message` | `string` | Progress message describing the current step | +| `done` | `bool` | `true` on the final reply | + +**Streaming:** Yes. Call with `VARLINK_CALL_MORE` to receive progress updates. + +**C Example:** + +```c +VarlinkObject *parameters = NULL; +long r; + +varlink_object_new(¶meters); + +r = varlink_connection_call(connection, "org.avocado.Extensions.Refresh", + parameters, VARLINK_CALL_MORE, NULL); +if (r < 0) { + fprintf(stderr, "Call failed: %s\n", varlink_error_string(-r)); + varlink_object_unref(parameters); + return; +} + +VarlinkObject *reply = NULL; +while ((r = varlink_connection_reply(connection, &reply)) >= 0) { + const char *message; + varlink_object_get_string(reply, "message", &message); + printf("[refresh] %s\n", message); + + bool done; + varlink_object_get_bool(reply, "done", &done); + + varlink_object_unref(reply); + reply = NULL; + + if (done) + break; +} + +varlink_object_unref(parameters); +``` + +### Enable + +Enable one or more extensions for a specific OS release version. Enabling an extension makes it available for merging. + +**Signature:** `Enable(extensions: []string, osRelease: ?string) -> (enabled: int, failed: int)` + +**Parameters:** + +| Field | Type | Description | +|-------|------|-------------| +| `extensions` | `[]string` | List of extension names to enable | +| `osRelease` | `?string` | Target OS release version. If omitted, the current OS release is used. | + +**Returns:** + +| Field | Type | Description | +|-------|------|-------------| +| `enabled` | `int` | Number of extensions successfully enabled | +| `failed` | `int` | Number of extensions that failed to enable | + +**C Example:** + +```c +VarlinkObject *parameters = NULL; +VarlinkObject *reply = NULL; +long r; + +varlink_object_new(¶meters); + +VarlinkArray *ext_list; +varlink_array_new(&ext_list); +varlink_array_append_string(ext_list, "my-app"); +varlink_array_append_string(ext_list, "my-config"); +varlink_object_set_array(parameters, "extensions", ext_list); + +r = varlink_connection_call(connection, "org.avocado.Extensions.Enable", parameters, 0, &reply); +if (r < 0) { + fprintf(stderr, "Call failed: %s\n", varlink_error_string(-r)); + varlink_object_unref(parameters); + return; +} + +const char *error_name = NULL; +if (varlink_reply_is_error(reply, &error_name)) { + fprintf(stderr, "Error: %s\n", error_name); +} else { + int64_t enabled, failed; + varlink_object_get_int(reply, "enabled", &enabled); + varlink_object_get_int(reply, "failed", &failed); + printf("Enabled: %ld, Failed: %ld\n", enabled, failed); +} + +varlink_object_unref(reply); +varlink_object_unref(parameters); +``` + +### Disable + +Disable extensions for a specific OS release version. Disabled extensions will not be included in subsequent merge operations. + +**Signature:** `Disable(extensions: ?[]string, all: ?bool, osRelease: ?string) -> (disabled: int, failed: int)` + +**Parameters:** + +| Field | Type | Description | +|-------|------|-------------| +| `extensions` | `?[]string` | List of extension names to disable. Omit if using `all`. | +| `all` | `?bool` | If `true`, disable all extensions. | +| `osRelease` | `?string` | Target OS release version. If omitted, the current OS release is used. | + +**Returns:** + +| Field | Type | Description | +|-------|------|-------------| +| `disabled` | `int` | Number of extensions successfully disabled | +| `failed` | `int` | Number of extensions that failed to disable | + +**C Example:** + +```c +VarlinkObject *parameters = NULL; +VarlinkObject *reply = NULL; +long r; + +varlink_object_new(¶meters); +varlink_object_set_bool(parameters, "all", true); + +r = varlink_connection_call(connection, "org.avocado.Extensions.Disable", parameters, 0, &reply); +if (r < 0) { + fprintf(stderr, "Call failed: %s\n", varlink_error_string(-r)); + varlink_object_unref(parameters); + return; +} + +int64_t disabled, failed; +varlink_object_get_int(reply, "disabled", &disabled); +varlink_object_get_int(reply, "failed", &failed); +printf("Disabled: %ld, Failed: %ld\n", disabled, failed); + +varlink_object_unref(reply); +varlink_object_unref(parameters); +``` + +### Status + +Show the current merge status of all extensions. + +**Signature:** `Status() -> (extensions: []ExtensionStatus)` + +**Parameters:** None. + +**Returns:** + +| Field | Type | Description | +|-------|------|-------------| +| `extensions` | `[]ExtensionStatus` | Array of extension status objects | + +**C Example:** + +```c +VarlinkObject *parameters = NULL; +VarlinkObject *reply = NULL; +long r; + +varlink_object_new(¶meters); +r = varlink_connection_call(connection, "org.avocado.Extensions.Status", parameters, 0, &reply); +if (r < 0) { + fprintf(stderr, "Call failed: %s\n", varlink_error_string(-r)); + varlink_object_unref(parameters); + return; +} + +VarlinkArray *extensions; +varlink_object_get_array(reply, "extensions", &extensions); + +for (unsigned long i = 0; i < varlink_array_get_n_elements(extensions); i++) { + VarlinkObject *ext; + varlink_array_get_object(extensions, i, &ext); + + const char *name; + bool is_merged; + + varlink_object_get_string(ext, "name", &name); + varlink_object_get_bool(ext, "isMerged", &is_merged); + + printf("%-30s %s\n", name, is_merged ? "merged" : "not merged"); +} + +varlink_object_unref(reply); +varlink_object_unref(parameters); +``` + +## Errors + +### ExtensionNotFound + +Returned when a referenced extension name does not exist in the extensions directory. + +| Parameter | Type | Description | +|-----------|------|-------------| +| `name` | `string` | The extension name that was not found | + +**Trigger:** Passing an unknown extension name to `Enable` or `Disable`. + +### MergeFailed + +Returned when the merge operation fails. + +| Parameter | Type | Description | +|-----------|------|-------------| +| `reason` | `string` | Human-readable description of the failure | + +**Trigger:** `systemd-sysext merge` or `systemd-confext merge` exits with a non-zero status, or an internal error occurs during the merge process. + +### UnmergeFailed + +Returned when the unmerge operation fails. + +| Parameter | Type | Description | +|-----------|------|-------------| +| `reason` | `string` | Human-readable description of the failure | + +**Trigger:** `systemd-sysext unmerge` or `systemd-confext unmerge` exits with a non-zero status. + +### ConfigurationError + +Returned when the extension configuration is invalid. + +| Parameter | Type | Description | +|-----------|------|-------------| +| `message` | `string` | Description of the configuration problem | + +**Trigger:** Malformed extension metadata, missing required fields, or incompatible OS release versions. + +### CommandFailed + +Returned when an external command executed during extension management fails. + +| Parameter | Type | Description | +|-----------|------|-------------| +| `command` | `string` | The command that failed | +| `message` | `string` | The command's error output or exit status | + +**Trigger:** Any subprocess invoked during merge, unmerge, enable, or disable operations exits with a non-zero status. diff --git a/src/docs/avocado-linux/tools/avocadoctl/varlink-api/org-avocado-hitl.md b/src/docs/avocado-linux/tools/avocadoctl/varlink-api/org-avocado-hitl.md new file mode 100644 index 00000000..65588da2 --- /dev/null +++ b/src/docs/avocado-linux/tools/avocadoctl/varlink-api/org-avocado-hitl.md @@ -0,0 +1,158 @@ +--- +title: org.avocado.Hitl +sidebar_position: 4 +description: 'Varlink interface for hardware-in-the-loop NFS extension mounting and unmounting.' +--- + +# org.avocado.Hitl + +Provides hardware-in-the-loop (HITL) testing support by mounting extension images from a remote NFS server. This allows developers to iterate on extension contents from a development workstation while the device runs the actual hardware, without needing to rebuild and flash extension images for each change. + +## Interface Definition + +```varlink +# Hardware-in-the-loop testing support +interface org.avocado.Hitl + +# Mount NFS extensions from a remote server +method Mount(serverIp: string, serverPort: ?string, extensions: []string) -> () + +# Unmount NFS extensions +method Unmount(extensions: []string) -> () + +error MountFailed (extension: string, reason: string) +error UnmountFailed (extension: string, reason: string) +``` + +## Methods + +### Mount + +Mount one or more extension directories from an NFS server. The server must export the extension directories at paths matching the extension names. Once mounted, the extensions can be merged into the system using `org.avocado.Extensions.Merge`. + +**Signature:** `Mount(serverIp: string, serverPort: ?string, extensions: []string) -> ()` + +**Parameters:** + +| Field | Type | Description | +|-------|------|-------------| +| `serverIp` | `string` | IP address of the NFS server | +| `serverPort` | `?string` | NFS server port. Defaults to the standard NFS port if omitted. | +| `extensions` | `[]string` | List of extension names to mount from the server | + +**Returns:** Empty on success. + +**C Example:** + +```c +VarlinkObject *parameters = NULL; +VarlinkObject *reply = NULL; +long r; + +varlink_object_new(¶meters); +varlink_object_set_string(parameters, "serverIp", "192.168.1.100"); + +VarlinkArray *ext_list; +varlink_array_new(&ext_list); +varlink_array_append_string(ext_list, "my-app"); +varlink_array_append_string(ext_list, "my-config"); +varlink_object_set_array(parameters, "extensions", ext_list); + +r = varlink_connection_call(connection, "org.avocado.Hitl.Mount", parameters, 0, &reply); +if (r < 0) { + fprintf(stderr, "Call failed: %s\n", varlink_error_string(-r)); + varlink_object_unref(parameters); + return; +} + +const char *error_name = NULL; +if (varlink_reply_is_error(reply, &error_name)) { + fprintf(stderr, "Mount error: %s\n", error_name); + + const char *extension, *reason; + varlink_object_get_string(reply, "extension", &extension); + varlink_object_get_string(reply, "reason", &reason); + fprintf(stderr, " Extension: %s\n Reason: %s\n", extension, reason); +} else { + printf("NFS extensions mounted successfully.\n"); +} + +varlink_object_unref(reply); +varlink_object_unref(parameters); +``` + +### Unmount + +Unmount previously mounted NFS extensions. + +**Signature:** `Unmount(extensions: []string) -> ()` + +**Parameters:** + +| Field | Type | Description | +|-------|------|-------------| +| `extensions` | `[]string` | List of extension names to unmount | + +**Returns:** Empty on success. + +**C Example:** + +```c +VarlinkObject *parameters = NULL; +VarlinkObject *reply = NULL; +long r; + +varlink_object_new(¶meters); + +VarlinkArray *ext_list; +varlink_array_new(&ext_list); +varlink_array_append_string(ext_list, "my-app"); +varlink_array_append_string(ext_list, "my-config"); +varlink_object_set_array(parameters, "extensions", ext_list); + +r = varlink_connection_call(connection, "org.avocado.Hitl.Unmount", parameters, 0, &reply); +if (r < 0) { + fprintf(stderr, "Call failed: %s\n", varlink_error_string(-r)); + varlink_object_unref(parameters); + return; +} + +const char *error_name = NULL; +if (varlink_reply_is_error(reply, &error_name)) { + fprintf(stderr, "Unmount error: %s\n", error_name); + + const char *extension, *reason; + varlink_object_get_string(reply, "extension", &extension); + varlink_object_get_string(reply, "reason", &reason); + fprintf(stderr, " Extension: %s\n Reason: %s\n", extension, reason); +} else { + printf("NFS extensions unmounted successfully.\n"); +} + +varlink_object_unref(reply); +varlink_object_unref(parameters); +``` + +## Errors + +### MountFailed + +Returned when an NFS mount operation fails for a specific extension. + +| Parameter | Type | Description | +|-----------|------|-------------| +| `extension` | `string` | The extension name that failed to mount | +| `reason` | `string` | Human-readable failure description | + +**Trigger:** NFS server unreachable, export not found, permission denied, or filesystem error during mount. + +### UnmountFailed + +Returned when an NFS unmount operation fails for a specific extension. + +| Parameter | Type | Description | +|-----------|------|-------------| +| `extension` | `string` | The extension name that failed to unmount | +| `reason` | `string` | Human-readable failure description | + +**Trigger:** Extension not currently mounted, busy filesystem preventing unmount, or filesystem error during unmount. diff --git a/src/docs/avocado-linux/tools/avocadoctl/varlink-api/org-avocado-root-authority.md b/src/docs/avocado-linux/tools/avocadoctl/varlink-api/org-avocado-root-authority.md new file mode 100644 index 00000000..c109e3c8 --- /dev/null +++ b/src/docs/avocado-linux/tools/avocadoctl/varlink-api/org-avocado-root-authority.md @@ -0,0 +1,170 @@ +--- +title: org.avocado.RootAuthority +sidebar_position: 5 +description: 'Varlink interface for querying the TUF trust anchor and signing key information.' +--- + +# org.avocado.RootAuthority + +Provides read-only access to the device's TUF (The Update Framework) trust anchor. The trust anchor is the `root.json` metadata file stored at `/var/lib/avocado/metadata/root.json`. It contains the set of signing keys that the device trusts for verifying the TUF metadata chain: timestamp, snapshot, and targets roles. + +This interface allows applications to inspect the trusted keys without parsing `root.json` directly, enabling integrations such as key rotation monitoring, compliance reporting, and device identity verification. + +## Interface Definition + +```varlink +# Trust anchor / root authority information +interface org.avocado.RootAuthority + +type TrustedKey ( + keyId: string, + keyType: string, + roles: []string +) + +type RootAuthorityInfo ( + version: int, + expires: string, + keys: []TrustedKey +) + +# Show the trusted signing keys for this device +method Show() -> (authority: ?RootAuthorityInfo) + +error NoRootAuthority () +error ParseFailed (reason: string) +``` + +## Types + +### TrustedKey + +A single signing key trusted by this device. + +| Field | Type | Description | +|-------|------|-------------| +| `keyId` | `string` | Hex-encoded key identifier (SHA-256 of the canonical key representation) | +| `keyType` | `string` | Key algorithm (e.g., `ed25519`, `ecdsa-sha2-nistp256`, `rsa`) | +| `roles` | `[]string` | TUF roles this key is authorized for (e.g., `root`, `targets`, `snapshot`, `timestamp`) | + +### RootAuthorityInfo + +The parsed contents of the TUF root metadata. + +| Field | Type | Description | +|-------|------|-------------| +| `version` | `int` | Root metadata version number. Increments on each root key rotation. | +| `expires` | `string` | ISO 8601 expiration timestamp of the root metadata | +| `keys` | `[]TrustedKey` | All trusted signing keys declared in the root metadata | + +## Methods + +### Show + +Return the device's current trust anchor information. If no `root.json` has been provisioned, the `authority` field in the response is `null`. + +**Signature:** `Show() -> (authority: ?RootAuthorityInfo)` + +**Parameters:** None. + +**Returns:** + +| Field | Type | Description | +|-------|------|-------------| +| `authority` | `?RootAuthorityInfo` | Trust anchor information, or `null` if no root metadata exists | + +**C Example:** + +```c +VarlinkObject *parameters = NULL; +VarlinkObject *reply = NULL; +long r; + +varlink_object_new(¶meters); +r = varlink_connection_call(connection, "org.avocado.RootAuthority.Show", parameters, 0, &reply); +if (r < 0) { + fprintf(stderr, "Call failed: %s\n", varlink_error_string(-r)); + varlink_object_unref(parameters); + return; +} + +const char *error_name = NULL; +if (varlink_reply_is_error(reply, &error_name)) { + fprintf(stderr, "Error: %s\n", error_name); + + const char *reason; + if (varlink_object_get_string(reply, "reason", &reason) >= 0) { + fprintf(stderr, "Reason: %s\n", reason); + } + + varlink_object_unref(reply); + varlink_object_unref(parameters); + return; +} + +VarlinkObject *authority; +r = varlink_object_get_object(reply, "authority", &authority); +if (r < 0) { + printf("No root authority provisioned on this device.\n"); + varlink_object_unref(reply); + varlink_object_unref(parameters); + return; +} + +int64_t version; +const char *expires; +varlink_object_get_int(authority, "version", &version); +varlink_object_get_string(authority, "expires", &expires); + +printf("Root metadata version: %ld\n", version); +printf("Expires: %s\n", expires); + +VarlinkArray *keys; +varlink_object_get_array(authority, "keys", &keys); + +printf("Trusted keys:\n"); +for (unsigned long i = 0; i < varlink_array_get_n_elements(keys); i++) { + VarlinkObject *key; + varlink_array_get_object(keys, i, &key); + + const char *key_id, *key_type; + varlink_object_get_string(key, "keyId", &key_id); + varlink_object_get_string(key, "keyType", &key_type); + + printf(" %s (%s)\n", key_id, key_type); + + VarlinkArray *roles; + varlink_object_get_array(key, "roles", &roles); + printf(" Roles: "); + for (unsigned long j = 0; j < varlink_array_get_n_elements(roles); j++) { + const char *role; + varlink_array_get_string(roles, j, &role); + if (j > 0) printf(", "); + printf("%s", role); + } + printf("\n"); +} + +varlink_object_unref(reply); +varlink_object_unref(parameters); +``` + +## Errors + +### NoRootAuthority + +Returned when no `root.json` file exists at `/var/lib/avocado/metadata/root.json`. This typically means the device has not yet been provisioned with a TUF trust anchor. + +**Parameters:** None. + +**Trigger:** Calling `Show` on a device that has not been provisioned with TUF root metadata. + +### ParseFailed + +Returned when `root.json` exists but cannot be parsed. + +| Parameter | Type | Description | +|-----------|------|-------------| +| `reason` | `string` | Description of the parse error | + +**Trigger:** Corrupt or malformed `root.json`, unsupported metadata version, or missing required fields in the root metadata file. diff --git a/src/docs/avocado-linux/tools/avocadoctl/varlink-api/org-avocado-runtimes.md b/src/docs/avocado-linux/tools/avocadoctl/varlink-api/org-avocado-runtimes.md new file mode 100644 index 00000000..07f7ff92 --- /dev/null +++ b/src/docs/avocado-linux/tools/avocadoctl/varlink-api/org-avocado-runtimes.md @@ -0,0 +1,565 @@ +--- +title: org.avocado.Runtimes +sidebar_position: 3 +description: 'Varlink interface for runtime lifecycle management - add, activate, remove, inspect, and list runtimes.' +--- + +# org.avocado.Runtimes + +Manages the lifecycle of Avocado Linux runtimes. A runtime is a versioned bundle comprising an OS image, an initramfs, and a set of extensions described by a manifest. This interface provides methods to list available runtimes, stage new runtimes from remote or local sources, activate a staged runtime, remove staged runtimes, and inspect runtime details. + +## Interface Definition + +```varlink +# Runtime lifecycle management for Avocado Linux +interface org.avocado.Runtimes + +type RuntimeInfo ( + name: string, + version: string +) + +type ManifestExtension ( + name: string, + version: string, + imageId: ?string +) + +type Runtime ( + id: string, + manifestVersion: int, + builtAt: string, + runtime: RuntimeInfo, + extensions: []ManifestExtension, + active: bool, + osBuildId: ?string, + initramfsBuildId: ?string +) + +# List all available runtimes +method List() -> (runtimes: []Runtime) + +# Add a runtime from a TUF repository URL (authToken: optional bearer token for protected endpoints) +# Supports streaming: client may set more=true to receive per-message progress +method AddFromUrl(url: string, authToken: ?string, artifactsUrl: ?string) -> (message: string, done: bool, runtime: ?Runtime) + +# Add a runtime from a local manifest file +# Supports streaming: client may set more=true to receive per-message progress +method AddFromManifest(manifestPath: string) -> (message: string, done: bool, runtime: ?Runtime) + +# Remove a staged runtime by ID (or prefix) +method Remove(id: string) -> () + +# Activate a staged runtime by ID (or prefix) +# Supports streaming: client may set more=true to receive per-message progress +method Activate(id: string) -> (message: string, done: bool, runtime: ?Runtime) + +# Inspect a runtime's details (omit id to inspect the active runtime) +method Inspect(id: ?string) -> (runtime: Runtime) + +error RuntimeNotFound (id: string) +error AmbiguousRuntimeId (id: string, candidates: []string) +error RemoveActiveRuntime () +error StagingFailed (reason: string) +error UpdateFailed (reason: string) +``` + +## Types + +### RuntimeInfo + +Basic identity of a runtime. + +| Field | Type | Description | +|-------|------|-------------| +| `name` | `string` | Runtime name | +| `version` | `string` | Runtime version string | + +### ManifestExtension + +An extension declared in the runtime manifest. + +| Field | Type | Description | +|-------|------|-------------| +| `name` | `string` | Extension name | +| `version` | `string` | Extension version string | +| `imageId` | `?string` | Image digest used to verify the downloaded extension artifact | + +### Runtime + +Full description of a runtime, including its manifest metadata, constituent extensions, and activation state. + +| Field | Type | Description | +|-------|------|-------------| +| `id` | `string` | Unique runtime identifier (hex digest) | +| `manifestVersion` | `int` | Manifest schema version | +| `builtAt` | `string` | ISO 8601 timestamp of when the runtime was built | +| `runtime` | `RuntimeInfo` | Runtime name and version | +| `extensions` | `[]ManifestExtension` | Extensions included in this runtime | +| `active` | `bool` | `true` if this is the currently active runtime | +| `osBuildId` | `?string` | OS image build identifier. A change in this value triggers an OS update on activation. | +| `initramfsBuildId` | `?string` | Initramfs build identifier | + +## Methods + +### List + +List all available runtimes, both staged and active. + +**Signature:** `List() -> (runtimes: []Runtime)` + +**Parameters:** None. + +**Returns:** + +| Field | Type | Description | +|-------|------|-------------| +| `runtimes` | `[]Runtime` | Array of all known runtimes | + +**C Example:** + +```c +VarlinkObject *parameters = NULL; +VarlinkObject *reply = NULL; +long r; + +varlink_object_new(¶meters); +r = varlink_connection_call(connection, "org.avocado.Runtimes.List", parameters, 0, &reply); +if (r < 0) { + fprintf(stderr, "Call failed: %s\n", varlink_error_string(-r)); + varlink_object_unref(parameters); + return; +} + +VarlinkArray *runtimes; +varlink_object_get_array(reply, "runtimes", &runtimes); + +for (unsigned long i = 0; i < varlink_array_get_n_elements(runtimes); i++) { + VarlinkObject *rt; + varlink_array_get_object(runtimes, i, &rt); + + const char *id; + bool active; + varlink_object_get_string(rt, "id", &id); + varlink_object_get_bool(rt, "active", &active); + + VarlinkObject *info; + varlink_object_get_object(rt, "runtime", &info); + + const char *name, *version; + varlink_object_get_string(info, "name", &name); + varlink_object_get_string(info, "version", &version); + + printf("%-12s %s %s%s\n", id, name, version, active ? " [active]" : ""); +} + +varlink_object_unref(reply); +varlink_object_unref(parameters); +``` + +### AddFromUrl + +Stage a new runtime by downloading its manifest and artifacts from a TUF repository. + +**Signature:** `AddFromUrl(url: string, authToken: ?string, artifactsUrl: ?string) -> (message: string, done: bool, runtime: ?Runtime)` + +**Parameters:** + +| Field | Type | Description | +|-------|------|-------------| +| `url` | `string` | TUF repository URL | +| `authToken` | `?string` | Optional bearer token for authenticated endpoints | +| `artifactsUrl` | `?string` | Optional separate URL for artifact downloads. If omitted, artifacts are fetched from the TUF repository URL. | + +**Returns (streaming):** + +| Field | Type | Description | +|-------|------|-------------| +| `message` | `string` | Progress message | +| `done` | `bool` | `true` on the final reply | +| `runtime` | `?Runtime` | The staged runtime object, present only in the final reply | + +**Streaming:** Yes. Call with `VARLINK_CALL_MORE` to receive download and verification progress. + +**C Example:** + +```c +VarlinkObject *parameters = NULL; +long r; + +varlink_object_new(¶meters); +varlink_object_set_string(parameters, "url", "https://tuf.example.com/repo"); +varlink_object_set_string(parameters, "authToken", "my-bearer-token"); + +r = varlink_connection_call(connection, "org.avocado.Runtimes.AddFromUrl", + parameters, VARLINK_CALL_MORE, NULL); +if (r < 0) { + fprintf(stderr, "Call failed: %s\n", varlink_error_string(-r)); + varlink_object_unref(parameters); + return; +} + +VarlinkObject *reply = NULL; +while ((r = varlink_connection_reply(connection, &reply)) >= 0) { + const char *error_name = NULL; + if (varlink_reply_is_error(reply, &error_name)) { + fprintf(stderr, "Error: %s\n", error_name); + varlink_object_unref(reply); + break; + } + + const char *message; + varlink_object_get_string(reply, "message", &message); + printf("[add] %s\n", message); + + bool done; + varlink_object_get_bool(reply, "done", &done); + + if (done) { + VarlinkObject *runtime; + if (varlink_object_get_object(reply, "runtime", &runtime) >= 0) { + const char *id; + varlink_object_get_string(runtime, "id", &id); + printf("Staged runtime: %s\n", id); + } + } + + varlink_object_unref(reply); + reply = NULL; + + if (done) + break; +} + +varlink_object_unref(parameters); +``` + +### AddFromManifest + +Stage a new runtime from a local manifest file. The manifest references artifacts that must already be present on the local filesystem or accessible via the paths declared in the manifest. + +**Signature:** `AddFromManifest(manifestPath: string) -> (message: string, done: bool, runtime: ?Runtime)` + +**Parameters:** + +| Field | Type | Description | +|-------|------|-------------| +| `manifestPath` | `string` | Absolute path to the local manifest file | + +**Returns (streaming):** + +| Field | Type | Description | +|-------|------|-------------| +| `message` | `string` | Progress message | +| `done` | `bool` | `true` on the final reply | +| `runtime` | `?Runtime` | The staged runtime object, present only in the final reply | + +**Streaming:** Yes. Call with `VARLINK_CALL_MORE` to receive progress updates. + +**C Example:** + +```c +VarlinkObject *parameters = NULL; +long r; + +varlink_object_new(¶meters); +varlink_object_set_string(parameters, "manifestPath", "/tmp/runtime-manifest.json"); + +r = varlink_connection_call(connection, "org.avocado.Runtimes.AddFromManifest", + parameters, VARLINK_CALL_MORE, NULL); +if (r < 0) { + fprintf(stderr, "Call failed: %s\n", varlink_error_string(-r)); + varlink_object_unref(parameters); + return; +} + +VarlinkObject *reply = NULL; +while ((r = varlink_connection_reply(connection, &reply)) >= 0) { + const char *message; + varlink_object_get_string(reply, "message", &message); + printf("[add-manifest] %s\n", message); + + bool done; + varlink_object_get_bool(reply, "done", &done); + + if (done) { + VarlinkObject *runtime; + if (varlink_object_get_object(reply, "runtime", &runtime) >= 0) { + const char *id; + varlink_object_get_string(runtime, "id", &id); + printf("Staged runtime: %s\n", id); + } + } + + varlink_object_unref(reply); + reply = NULL; + + if (done) + break; +} + +varlink_object_unref(parameters); +``` + +### Remove + +Remove a staged runtime by its ID or an unambiguous ID prefix. + +**Signature:** `Remove(id: string) -> ()` + +**Parameters:** + +| Field | Type | Description | +|-------|------|-------------| +| `id` | `string` | Runtime ID or unique prefix | + +**Returns:** Empty on success. + +**C Example:** + +```c +VarlinkObject *parameters = NULL; +VarlinkObject *reply = NULL; +long r; + +varlink_object_new(¶meters); +varlink_object_set_string(parameters, "id", "a1b2c3"); + +r = varlink_connection_call(connection, "org.avocado.Runtimes.Remove", parameters, 0, &reply); +if (r < 0) { + fprintf(stderr, "Call failed: %s\n", varlink_error_string(-r)); + varlink_object_unref(parameters); + return; +} + +const char *error_name = NULL; +if (varlink_reply_is_error(reply, &error_name)) { + fprintf(stderr, "Error: %s\n", error_name); + + /* Check for ambiguous ID */ + VarlinkArray *candidates; + if (varlink_object_get_array(reply, "candidates", &candidates) >= 0) { + fprintf(stderr, "Matching runtimes:\n"); + for (unsigned long i = 0; i < varlink_array_get_n_elements(candidates); i++) { + const char *candidate; + varlink_array_get_string(candidates, i, &candidate); + fprintf(stderr, " %s\n", candidate); + } + } +} else { + printf("Runtime removed.\n"); +} + +varlink_object_unref(reply); +varlink_object_unref(parameters); +``` + +### Activate + +Activate a staged runtime. If the runtime's `osBuildId` differs from the currently running OS, this triggers an OS update (writing the new OS image to the inactive partition and configuring the bootloader). A reboot is required to complete the update. + +**Signature:** `Activate(id: string) -> (message: string, done: bool, runtime: ?Runtime)` + +**Parameters:** + +| Field | Type | Description | +|-------|------|-------------| +| `id` | `string` | Runtime ID or unique prefix | + +**Returns (streaming):** + +| Field | Type | Description | +|-------|------|-------------| +| `message` | `string` | Progress message (e.g., writing OS image, enabling extensions) | +| `done` | `bool` | `true` on the final reply | +| `runtime` | `?Runtime` | The activated runtime object, present only in the final reply | + +**Streaming:** Yes. Call with `VARLINK_CALL_MORE` to receive progress updates. This is especially useful during OS updates, which may take significant time. + +**C Example:** + +```c +VarlinkObject *parameters = NULL; +long r; + +varlink_object_new(¶meters); +varlink_object_set_string(parameters, "id", "a1b2c3"); + +r = varlink_connection_call(connection, "org.avocado.Runtimes.Activate", + parameters, VARLINK_CALL_MORE, NULL); +if (r < 0) { + fprintf(stderr, "Call failed: %s\n", varlink_error_string(-r)); + varlink_object_unref(parameters); + return; +} + +VarlinkObject *reply = NULL; +while ((r = varlink_connection_reply(connection, &reply)) >= 0) { + const char *error_name = NULL; + if (varlink_reply_is_error(reply, &error_name)) { + fprintf(stderr, "Activation error: %s\n", error_name); + const char *reason; + if (varlink_object_get_string(reply, "reason", &reason) >= 0) { + fprintf(stderr, "Reason: %s\n", reason); + } + varlink_object_unref(reply); + break; + } + + const char *message; + varlink_object_get_string(reply, "message", &message); + printf("[activate] %s\n", message); + + bool done; + varlink_object_get_bool(reply, "done", &done); + + if (done) { + VarlinkObject *runtime; + if (varlink_object_get_object(reply, "runtime", &runtime) >= 0) { + const char *id; + varlink_object_get_string(runtime, "id", &id); + printf("Activated runtime: %s\n", id); + } + } + + varlink_object_unref(reply); + reply = NULL; + + if (done) + break; +} + +varlink_object_unref(parameters); +``` + +### Inspect + +Inspect the details of a specific runtime. If `id` is omitted, the currently active runtime is inspected. + +**Signature:** `Inspect(id: ?string) -> (runtime: Runtime)` + +**Parameters:** + +| Field | Type | Description | +|-------|------|-------------| +| `id` | `?string` | Runtime ID or unique prefix. Omit to inspect the active runtime. | + +**Returns:** + +| Field | Type | Description | +|-------|------|-------------| +| `runtime` | `Runtime` | The full runtime object | + +**C Example:** + +```c +VarlinkObject *parameters = NULL; +VarlinkObject *reply = NULL; +long r; + +/* Omit "id" to inspect the active runtime */ +varlink_object_new(¶meters); + +r = varlink_connection_call(connection, "org.avocado.Runtimes.Inspect", parameters, 0, &reply); +if (r < 0) { + fprintf(stderr, "Call failed: %s\n", varlink_error_string(-r)); + varlink_object_unref(parameters); + return; +} + +const char *error_name = NULL; +if (varlink_reply_is_error(reply, &error_name)) { + fprintf(stderr, "Error: %s\n", error_name); + varlink_object_unref(reply); + varlink_object_unref(parameters); + return; +} + +VarlinkObject *runtime; +varlink_object_get_object(reply, "runtime", &runtime); + +const char *id, *built_at; +bool active; +varlink_object_get_string(runtime, "id", &id); +varlink_object_get_string(runtime, "builtAt", &built_at); +varlink_object_get_bool(runtime, "active", &active); + +VarlinkObject *info; +varlink_object_get_object(runtime, "runtime", &info); + +const char *name, *version; +varlink_object_get_string(info, "name", &name); +varlink_object_get_string(info, "version", &version); + +printf("Runtime: %s %s\n", name, version); +printf("ID: %s\n", id); +printf("Built: %s\n", built_at); +printf("Active: %s\n", active ? "yes" : "no"); + +VarlinkArray *extensions; +varlink_object_get_array(runtime, "extensions", &extensions); +printf("Extensions:\n"); +for (unsigned long i = 0; i < varlink_array_get_n_elements(extensions); i++) { + VarlinkObject *ext; + varlink_array_get_object(extensions, i, &ext); + + const char *ext_name, *ext_version; + varlink_object_get_string(ext, "name", &ext_name); + varlink_object_get_string(ext, "version", &ext_version); + printf(" %s %s\n", ext_name, ext_version); +} + +varlink_object_unref(reply); +varlink_object_unref(parameters); +``` + +## Errors + +### RuntimeNotFound + +Returned when the specified runtime ID does not match any known runtime. + +| Parameter | Type | Description | +|-----------|------|-------------| +| `id` | `string` | The ID that was not found | + +**Trigger:** Passing an unknown ID to `Remove`, `Activate`, or `Inspect`. + +### AmbiguousRuntimeId + +Returned when the specified ID prefix matches more than one runtime. The response includes the list of matching candidate IDs so the caller can present them to the user or retry with a longer prefix. + +| Parameter | Type | Description | +|-----------|------|-------------| +| `id` | `string` | The ambiguous prefix | +| `candidates` | `[]string` | Full IDs of all matching runtimes | + +**Trigger:** Passing a short ID prefix to `Remove`, `Activate`, or `Inspect` that matches multiple runtimes. + +### RemoveActiveRuntime + +Returned when attempting to remove the currently active runtime. The active runtime cannot be removed. + +**Parameters:** None. + +**Trigger:** Calling `Remove` with the ID of the active runtime. + +### StagingFailed + +Returned when staging a new runtime fails during download, verification, or installation. + +| Parameter | Type | Description | +|-----------|------|-------------| +| `reason` | `string` | Human-readable failure description | + +**Trigger:** TUF metadata verification failure, artifact download error, disk space exhaustion, or corrupt manifest in `AddFromUrl` or `AddFromManifest`. + +### UpdateFailed + +Returned when the OS update triggered by `Activate` fails. + +| Parameter | Type | Description | +|-----------|------|-------------| +| `reason` | `string` | Human-readable failure description | + +**Trigger:** OS image write failure, bootloader configuration error, or extension enable/merge failure during `Activate`. diff --git a/src/docs/avocado-linux/tools/avocadoctl/varlink-api/overview.md b/src/docs/avocado-linux/tools/avocadoctl/varlink-api/overview.md new file mode 100644 index 00000000..0643d4fc --- /dev/null +++ b/src/docs/avocado-linux/tools/avocadoctl/varlink-api/overview.md @@ -0,0 +1,176 @@ +--- +title: Overview +sidebar_position: 1 +description: 'Guide to using the avocadoctl Varlink API for programmatic access to extension management, runtime lifecycle, and OS updates from C programs.' +--- + +# Varlink API Overview + +avocadoctl exposes four Varlink interfaces over a Unix domain socket. Any application on the device can connect to the socket using the Varlink protocol, a JSON-based IPC mechanism, to programmatically manage extensions, runtimes, hardware-in-the-loop testing, and trust anchor information. + +**Socket address:** `unix:/run/avocado/avocadoctl.sock` + +The daemon is automatically started at boot by the included `avocadoctl` service extension, which is enabled by default in both the initramfs and system scopes. This means the Varlink API is available immediately on all Avocado runtimes without any manual setup. + +The daemon can also be started manually if needed: + +```bash +avocadoctl serve +``` + +Once running, any process on the device can open a connection to the socket and invoke methods on the available interfaces. + +## Connecting from C + +The following example demonstrates a minimal C program that connects to the avocadoctl socket, calls `org.avocado.Extensions.List`, and prints the names of all available extensions. + +```c +#include +#include +#include + +int main(void) { + VarlinkConnection *connection = NULL; + VarlinkObject *parameters = NULL; + VarlinkObject *reply = NULL; + long r; + + r = varlink_connection_new(&connection, "unix:/run/avocado/avocadoctl.sock"); + if (r < 0) { + fprintf(stderr, "Failed to connect: %s\n", varlink_error_string(-r)); + return EXIT_FAILURE; + } + + varlink_object_new(¶meters); + + r = varlink_connection_call(connection, "org.avocado.Extensions.List", parameters, 0, &reply); + if (r < 0) { + fprintf(stderr, "Call failed: %s\n", varlink_error_string(-r)); + varlink_connection_free(connection); + return EXIT_FAILURE; + } + + VarlinkArray *extensions; + varlink_object_get_array(reply, "extensions", &extensions); + + for (unsigned long i = 0; i < varlink_array_get_n_elements(extensions); i++) { + VarlinkObject *ext; + varlink_array_get_object(extensions, i, &ext); + + const char *name; + varlink_object_get_string(ext, "name", &name); + printf("Extension: %s\n", name); + } + + varlink_object_unref(reply); + varlink_object_unref(parameters); + varlink_connection_free(connection); + + return EXIT_SUCCESS; +} +``` + +Compile with: + +```bash +gcc -o list_extensions list_extensions.c $(pkg-config --cflags --libs libvarlink) +``` + +## Streaming Methods + +Several methods support streaming via the Varlink `more` flag. When called with the `VARLINK_CALL_MORE` flag, the server sends multiple reply objects as the operation progresses. Each intermediate reply contains a `message` field with a progress string and `done: false`. The final reply has `done: true`. + +The following example calls `org.avocado.Extensions.Merge` with streaming enabled and prints each progress message as it arrives: + +```c +#include +#include +#include + +int main(void) { + VarlinkConnection *connection = NULL; + VarlinkObject *parameters = NULL; + long r; + + r = varlink_connection_new(&connection, "unix:/run/avocado/avocadoctl.sock"); + if (r < 0) { + fprintf(stderr, "Failed to connect: %s\n", varlink_error_string(-r)); + return EXIT_FAILURE; + } + + varlink_object_new(¶meters); + + r = varlink_connection_call(connection, "org.avocado.Extensions.Merge", + parameters, VARLINK_CALL_MORE, NULL); + if (r < 0) { + fprintf(stderr, "Call failed: %s\n", varlink_error_string(-r)); + varlink_connection_free(connection); + return EXIT_FAILURE; + } + + VarlinkObject *reply = NULL; + while ((r = varlink_connection_reply(connection, &reply)) >= 0) { + const char *message; + varlink_object_get_string(reply, "message", &message); + printf("%s\n", message); + + bool done; + varlink_object_get_bool(reply, "done", &done); + + varlink_object_unref(reply); + reply = NULL; + + if (done) + break; + } + + if (r < 0 && r != -VARLINK_REPLY_EOF) { + fprintf(stderr, "Streaming error: %s\n", varlink_error_string(-r)); + } + + varlink_object_unref(parameters); + varlink_connection_free(connection); + + return EXIT_SUCCESS; +} +``` + +## Error Handling + +Varlink errors are returned as structured objects. Each error includes an interface-qualified name (e.g., `org.avocado.Extensions.MergeFailed`) and a set of error parameters providing additional context. + +Use `varlink_reply_is_error` to detect error responses: + +```c +VarlinkObject *reply = NULL; + +r = varlink_connection_call(connection, "org.avocado.Extensions.Merge", + parameters, 0, &reply); +if (r < 0) { + fprintf(stderr, "Transport error: %s\n", varlink_error_string(-r)); + return EXIT_FAILURE; +} + +const char *error_name = NULL; +if (varlink_reply_is_error(reply, &error_name)) { + fprintf(stderr, "Varlink error: %s\n", error_name); + + /* Extract error parameters */ + const char *reason; + if (varlink_object_get_string(reply, "reason", &reason) >= 0) { + fprintf(stderr, "Reason: %s\n", reason); + } + + varlink_object_unref(reply); + return EXIT_FAILURE; +} +``` + +## Available Interfaces + +| Interface | Description | +|-----------|-------------| +| [org.avocado.Extensions](./org-avocado-extensions) | Extension management (merge, unmerge, enable, disable) | +| [org.avocado.Runtimes](./org-avocado-runtimes) | Runtime lifecycle (add, activate, remove, inspect) | +| [org.avocado.Hitl](./org-avocado-hitl) | Hardware-in-the-loop NFS testing | +| [org.avocado.RootAuthority](./org-avocado-root-authority) | TUF trust anchor information | From 40c1de3e4167b684607cbb879e8a64eadd665cee Mon Sep 17 00:00:00 2001 From: Justin Schneck Date: Fri, 13 Mar 2026 19:14:08 -0400 Subject: [PATCH 2/8] docs: update guides and extensions reference for latest avocado-cli changes --- .../guides/hardware-in-the-loop.md | 4 +- src/docs/avocado-linux/guides/sideloading.md | 3 +- .../avocado-linux/references/extensions.md | 107 +++++++++++++++++- 3 files changed, 103 insertions(+), 11 deletions(-) diff --git a/src/docs/avocado-linux/guides/hardware-in-the-loop.md b/src/docs/avocado-linux/guides/hardware-in-the-loop.md index c7d58d8b..dd32b797 100644 --- a/src/docs/avocado-linux/guides/hardware-in-the-loop.md +++ b/src/docs/avocado-linux/guides/hardware-in-the-loop.md @@ -31,9 +31,7 @@ runtimes: - my-app # highlight-added-end packages: - avocado-img-bootfiles: '*' - avocado-img-rootfs: '*' - avocado-img-initramfs: '*' + avocado-runtime: '*' sdk: image: avocadolinux/sdk:apollo-edge diff --git a/src/docs/avocado-linux/guides/sideloading.md b/src/docs/avocado-linux/guides/sideloading.md index 9feffd3d..012540f3 100644 --- a/src/docs/avocado-linux/guides/sideloading.md +++ b/src/docs/avocado-linux/guides/sideloading.md @@ -134,8 +134,7 @@ Installing: ... snip ... Installed: - avocado-img-bootfiles-1.0-r0.avocado_raspberrypi4 avocado-img-initramfs-1.0-r0.avocado_raspberrypi4 - avocado-img-rootfs-1.0-r0.avocado_raspberrypi4 + avocado-runtime-1.0-r0.avocado_raspberrypi4 Complete! [SUCCESS] Successfully installed packages for runtime 'dev' diff --git a/src/docs/avocado-linux/references/extensions.md b/src/docs/avocado-linux/references/extensions.md index 7cd4f210..ca232bac 100644 --- a/src/docs/avocado-linux/references/extensions.md +++ b/src/docs/avocado-linux/references/extensions.md @@ -217,9 +217,7 @@ runtimes: - config - app packages: - avocado-img-bootfiles: '*' - avocado-img-rootfs: '*' - avocado-img-initramfs: '*' + avocado-runtime: '*' prod: extensions: @@ -227,13 +225,13 @@ runtimes: - config-prod - app packages: - avocado-img-bootfiles: '*' - avocado-img-rootfs: '*' - avocado-img-initramfs: '*' + avocado-runtime: '*' ``` This pattern enables you to include development tools, debugging utilities, and verbose logging in `dev` while keeping `prod` minimal and secure. +The rootfs and initramfs images are built automatically from their respective package sysroots during `avocado runtime build`. See [rootfs and initramfs](#rootfs-and-initramfs) for details. + ## Building extensions Extensions are built using the Avocado CLI. For complete build command options, see the [ext build command](../tools/avocado-cli/commands/ext/build) documentation. @@ -760,6 +758,103 @@ Extensions integrate with Avocado's SDK for declarative package selection, custo Learn how to leverage these capabilities with [hardware-in-the-loop development](../guides/hardware-in-the-loop). +## Rootfs and initramfs + +Avocado builds the root filesystem (rootfs) and initial RAM filesystem (initramfs) images from RPM packages during `avocado runtime build`. These are top-level, config-wide concepts — all runtimes produced from a single `avocado.yaml` share the same rootfs and initramfs. + +### Configuration + +The `rootfs` and `initramfs` sections are optional top-level keys in `avocado.yaml`. When omitted, they default to their respective base packages: + +```yaml +# Optional — these are the defaults if omitted +rootfs: + packages: + avocado-pkg-rootfs: '*' + +initramfs: + packages: + avocado-pkg-initramfs: '*' +``` + +You can add additional packages to customize the base system and configure the image format: + +```yaml +rootfs: + filesystem: erofs.lz4 # default + packages: + avocado-pkg-rootfs: '*' + my-custom-base-package: '*' + +initramfs: + filesystem: cpio.zst # default + packages: + avocado-pkg-initramfs: '*' +``` + +The `filesystem` property can also be set by a BSP extension, allowing per-platform defaults. Include the `rootfs` or `initramfs` section from your BSP extension to inherit platform-specific filesystem formats: + +```yaml +extensions: + avocado-bsp-{{ avocado.target }}: + source: + type: package + include: + - rootfs + - initramfs + - provision_profiles.* +``` + +### Filesystem formats + +The `filesystem` property controls the image format and compression algorithm used for the rootfs and initramfs images. + +**Rootfs formats:** + +| Value | Description | +| ----------- | ---------------------------------------------------------------- | +| `erofs.lz4` | EROFS with LZ4 compression (default). Fast decompression, good for boot speed. | +| `erofs.zst` | EROFS with Zstandard compression. Better compression ratio. | + +**Initramfs formats:** + +| Value | Description | +| ---------- | ---------------------------------------------------------------- | +| `cpio.zst` | CPIO archive with Zstandard compression (default). Requires `CONFIG_RD_ZSTD=y`. | +| `cpio.lz4` | CPIO archive with LZ4 compression. Requires `CONFIG_RD_LZ4=y`. | +| `cpio.gz` | CPIO archive with gzip compression. Widest kernel support. | +| `cpio` | Uncompressed CPIO archive. No kernel decompression config required. | + +:::tip +Compressed formats require kernel decompression support built in. For example, `erofs.zst` requires `CONFIG_EROFS_FS_ZIP_ZSTD=y` and `cpio.zst` requires `CONFIG_RD_ZSTD=y`. BSP extensions can set the filesystem format per-platform to match the kernel's decompression capabilities. See the [custom kernel guide](../guides/custom-kernel) for kernel configuration details. +::: + +### How it works + +During `avocado sdk install`, package sysroots are created for both rootfs and initramfs alongside the SDK. These sysroots contain the installed RPM packages and serve as the base for image creation: + +- `$AVOCADO_PREFIX/rootfs/` — rootfs sysroot (also used for extension RPM deduplication) +- `$AVOCADO_PREFIX/initramfs/` — initramfs sysroot + +During `avocado runtime build`, these sysroots are copied to temporary work directories where post-processing is applied: + +1. **Usrmerge symlinks** — `/bin` → `usr/bin`, `/sbin` → `usr/sbin`, `/lib` → `usr/lib` +2. **Systemd presets** — service units are enabled via preset files +3. **Machine ID** — an empty `/etc/machine-id` is created for stateless systemd on read-only rootfs +4. **Linker cache** — `ld.so.cache` is generated for the read-only rootfs +5. **OS identity** — `AVOCADO_OS_BUILD_ID` is injected into `/usr/lib/os-release` +6. **Image creation** — rootfs is packaged using the configured filesystem format (default: `erofs.lz4`), initramfs as cpio (default: `cpio.zst`) + +The shared sysroots are never modified — work copies ensure extensions continue to prime correctly from the rootfs RPM database. + +### Relationship to extensions + +Extensions overlay the rootfs at runtime via systemd-sysext and systemd-confext. The rootfs provides the immutable base system, while extensions deliver user-defined functionality. Extension RPM deduplication uses the rootfs sysroot's RPM database to avoid duplicating packages already present in the base system. + +### Cleaning + +`avocado sdk clean` removes both the rootfs and initramfs sysroots along with the SDK. Use `avocado runtime clean` to remove built images for a specific runtime. + ## Security and composition Extensions maintain security through: From 9595ef9783f81fcbfc3b1871f21d565a1729ec23 Mon Sep 17 00:00:00 2001 From: Justin Schneck Date: Fri, 13 Mar 2026 19:14:17 -0400 Subject: [PATCH 3/8] docs: add rootfs and initramfs command documentation Add docs for the new avocado rootfs and initramfs command groups (install, image, clean) introduced to manage shared sysroots independently from runtime builds. --- .../commands/initramfs/_category_.json | 5 +++++ .../avocado-cli/commands/initramfs/clean.md | 17 +++++++++++++++++ .../avocado-cli/commands/initramfs/image.md | 18 ++++++++++++++++++ .../avocado-cli/commands/initramfs/install.md | 18 ++++++++++++++++++ .../commands/rootfs/_category_.json | 5 +++++ .../tools/avocado-cli/commands/rootfs/clean.md | 17 +++++++++++++++++ .../tools/avocado-cli/commands/rootfs/image.md | 18 ++++++++++++++++++ .../avocado-cli/commands/rootfs/install.md | 18 ++++++++++++++++++ 8 files changed, 116 insertions(+) create mode 100644 src/docs/avocado-linux/tools/avocado-cli/commands/initramfs/_category_.json create mode 100644 src/docs/avocado-linux/tools/avocado-cli/commands/initramfs/clean.md create mode 100644 src/docs/avocado-linux/tools/avocado-cli/commands/initramfs/image.md create mode 100644 src/docs/avocado-linux/tools/avocado-cli/commands/initramfs/install.md create mode 100644 src/docs/avocado-linux/tools/avocado-cli/commands/rootfs/_category_.json create mode 100644 src/docs/avocado-linux/tools/avocado-cli/commands/rootfs/clean.md create mode 100644 src/docs/avocado-linux/tools/avocado-cli/commands/rootfs/image.md create mode 100644 src/docs/avocado-linux/tools/avocado-cli/commands/rootfs/install.md diff --git a/src/docs/avocado-linux/tools/avocado-cli/commands/initramfs/_category_.json b/src/docs/avocado-linux/tools/avocado-cli/commands/initramfs/_category_.json new file mode 100644 index 00000000..2268aa3e --- /dev/null +++ b/src/docs/avocado-linux/tools/avocado-cli/commands/initramfs/_category_.json @@ -0,0 +1,5 @@ +{ + "label": "Initramfs", + "collapsible": true, + "collapsed": true +} diff --git a/src/docs/avocado-linux/tools/avocado-cli/commands/initramfs/clean.md b/src/docs/avocado-linux/tools/avocado-cli/commands/initramfs/clean.md new file mode 100644 index 00000000..fa4acbcc --- /dev/null +++ b/src/docs/avocado-linux/tools/avocado-cli/commands/initramfs/clean.md @@ -0,0 +1,17 @@ +``` +Remove initramfs sysroot + +Usage: avocado initramfs clean [OPTIONS] + +Options: + -C, --config Path to avocado.yaml configuration file [default: avocado.yaml] + -v, --verbose Enable verbose output + -t, --target Target architecture + --container-arg Additional arguments to pass to the container runtime + --dnf-arg Additional arguments to pass to DNF commands + --runs-on Run command on remote host using local volume via NFS (format: user@host) + --nfs-port NFS port for remote execution (auto-selects from 12050-12099 if not specified) + --sdk-arch SDK container architecture for cross-arch emulation via Docker buildx/QEMU (aarch64 or x86-64) + -h, --help Print help + +``` \ No newline at end of file diff --git a/src/docs/avocado-linux/tools/avocado-cli/commands/initramfs/image.md b/src/docs/avocado-linux/tools/avocado-cli/commands/initramfs/image.md new file mode 100644 index 00000000..ffb693a0 --- /dev/null +++ b/src/docs/avocado-linux/tools/avocado-cli/commands/initramfs/image.md @@ -0,0 +1,18 @@ +``` +Build initramfs image from sysroot + +Usage: avocado initramfs image [OPTIONS] + +Options: + -C, --config Path to avocado.yaml configuration file [default: avocado.yaml] + -v, --verbose Enable verbose output + -t, --target Target architecture + --out Output directory on host for the resulting image + --container-arg Additional arguments to pass to the container runtime + --dnf-arg Additional arguments to pass to DNF commands + --runs-on Run command on remote host using local volume via NFS (format: user@host) + --nfs-port NFS port for remote execution (auto-selects from 12050-12099 if not specified) + --sdk-arch SDK container architecture for cross-arch emulation via Docker buildx/QEMU (aarch64 or x86-64) + -h, --help Print help + +``` \ No newline at end of file diff --git a/src/docs/avocado-linux/tools/avocado-cli/commands/initramfs/install.md b/src/docs/avocado-linux/tools/avocado-cli/commands/initramfs/install.md new file mode 100644 index 00000000..9e9ab080 --- /dev/null +++ b/src/docs/avocado-linux/tools/avocado-cli/commands/initramfs/install.md @@ -0,0 +1,18 @@ +``` +Install initramfs sysroot packages via DNF + +Usage: avocado initramfs install [OPTIONS] + +Options: + -C, --config Path to avocado.yaml configuration file [default: avocado.yaml] + -v, --verbose Enable verbose output + -f, --force Force the operation to proceed, bypassing warnings or confirmation prompts + -t, --target Target architecture + --container-arg Additional arguments to pass to the container runtime + --dnf-arg Additional arguments to pass to DNF commands + --runs-on Run command on remote host using local volume via NFS (format: user@host) + --nfs-port NFS port for remote execution (auto-selects from 12050-12099 if not specified) + --sdk-arch SDK container architecture for cross-arch emulation via Docker buildx/QEMU (aarch64 or x86-64) + -h, --help Print help + +``` \ No newline at end of file diff --git a/src/docs/avocado-linux/tools/avocado-cli/commands/rootfs/_category_.json b/src/docs/avocado-linux/tools/avocado-cli/commands/rootfs/_category_.json new file mode 100644 index 00000000..691df15e --- /dev/null +++ b/src/docs/avocado-linux/tools/avocado-cli/commands/rootfs/_category_.json @@ -0,0 +1,5 @@ +{ + "label": "Rootfs", + "collapsible": true, + "collapsed": true +} diff --git a/src/docs/avocado-linux/tools/avocado-cli/commands/rootfs/clean.md b/src/docs/avocado-linux/tools/avocado-cli/commands/rootfs/clean.md new file mode 100644 index 00000000..f8c9e6b5 --- /dev/null +++ b/src/docs/avocado-linux/tools/avocado-cli/commands/rootfs/clean.md @@ -0,0 +1,17 @@ +``` +Remove rootfs sysroot + +Usage: avocado rootfs clean [OPTIONS] + +Options: + -C, --config Path to avocado.yaml configuration file [default: avocado.yaml] + -v, --verbose Enable verbose output + -t, --target Target architecture + --container-arg Additional arguments to pass to the container runtime + --dnf-arg Additional arguments to pass to DNF commands + --runs-on Run command on remote host using local volume via NFS (format: user@host) + --nfs-port NFS port for remote execution (auto-selects from 12050-12099 if not specified) + --sdk-arch SDK container architecture for cross-arch emulation via Docker buildx/QEMU (aarch64 or x86-64) + -h, --help Print help + +``` \ No newline at end of file diff --git a/src/docs/avocado-linux/tools/avocado-cli/commands/rootfs/image.md b/src/docs/avocado-linux/tools/avocado-cli/commands/rootfs/image.md new file mode 100644 index 00000000..de936db1 --- /dev/null +++ b/src/docs/avocado-linux/tools/avocado-cli/commands/rootfs/image.md @@ -0,0 +1,18 @@ +``` +Build rootfs image from sysroot + +Usage: avocado rootfs image [OPTIONS] + +Options: + -C, --config Path to avocado.yaml configuration file [default: avocado.yaml] + -v, --verbose Enable verbose output + -t, --target Target architecture + --out Output directory on host for the resulting image + --container-arg Additional arguments to pass to the container runtime + --dnf-arg Additional arguments to pass to DNF commands + --runs-on Run command on remote host using local volume via NFS (format: user@host) + --nfs-port NFS port for remote execution (auto-selects from 12050-12099 if not specified) + --sdk-arch SDK container architecture for cross-arch emulation via Docker buildx/QEMU (aarch64 or x86-64) + -h, --help Print help + +``` \ No newline at end of file diff --git a/src/docs/avocado-linux/tools/avocado-cli/commands/rootfs/install.md b/src/docs/avocado-linux/tools/avocado-cli/commands/rootfs/install.md new file mode 100644 index 00000000..687f24d8 --- /dev/null +++ b/src/docs/avocado-linux/tools/avocado-cli/commands/rootfs/install.md @@ -0,0 +1,18 @@ +``` +Install rootfs sysroot packages via DNF + +Usage: avocado rootfs install [OPTIONS] + +Options: + -C, --config Path to avocado.yaml configuration file [default: avocado.yaml] + -v, --verbose Enable verbose output + -f, --force Force the operation to proceed, bypassing warnings or confirmation prompts + -t, --target Target architecture + --container-arg Additional arguments to pass to the container runtime + --dnf-arg Additional arguments to pass to DNF commands + --runs-on Run command on remote host using local volume via NFS (format: user@host) + --nfs-port NFS port for remote execution (auto-selects from 12050-12099 if not specified) + --sdk-arch SDK container architecture for cross-arch emulation via Docker buildx/QEMU (aarch64 or x86-64) + -h, --help Print help + +``` \ No newline at end of file From 4fb2c53bc234458a7dcf754cdb5ea6eefbd93542 Mon Sep 17 00:00:00 2001 From: Justin Schneck Date: Fri, 13 Mar 2026 19:14:25 -0400 Subject: [PATCH 4/8] docs: add Avocado Connect platform command documentation Add comprehensive docs for the avocado connect command group covering auth (login/logout/status), init, resource management (orgs, projects, devices, cohorts, claim-tokens), upload, server-key, signing key delegation (register/approve/list/retire), and trust posture management (status/promote-root/rotate-server-key). --- .../commands/connect/_category_.json | 5 ++++ .../commands/connect/auth/_category_.json | 5 ++++ .../commands/connect/auth/login.md | 15 ++++++++++++ .../commands/connect/auth/logout.md | 13 +++++++++++ .../commands/connect/auth/status.md | 13 +++++++++++ .../connect/claim-tokens/_category_.json | 5 ++++ .../commands/connect/claim-tokens/create.md | 19 +++++++++++++++ .../commands/connect/claim-tokens/delete.md | 17 ++++++++++++++ .../commands/connect/claim-tokens/list.md | 15 ++++++++++++ .../commands/connect/cohorts/_category_.json | 5 ++++ .../commands/connect/cohorts/create.md | 18 +++++++++++++++ .../commands/connect/cohorts/delete.md | 18 +++++++++++++++ .../commands/connect/cohorts/list.md | 16 +++++++++++++ .../commands/connect/devices/_category_.json | 5 ++++ .../commands/connect/devices/create.md | 17 ++++++++++++++ .../commands/connect/devices/delete.md | 17 ++++++++++++++ .../commands/connect/devices/list.md | 15 ++++++++++++ .../avocado-cli/commands/connect/init.md | 16 +++++++++++++ .../commands/connect/keys/_category_.json | 5 ++++ .../commands/connect/keys/approve.md | 18 +++++++++++++++ .../avocado-cli/commands/connect/keys/list.md | 16 +++++++++++++ .../commands/connect/keys/register.md | 17 ++++++++++++++ .../commands/connect/keys/retire.md | 18 +++++++++++++++ .../commands/connect/orgs/_category_.json | 5 ++++ .../avocado-cli/commands/connect/orgs/list.md | 13 +++++++++++ .../commands/connect/projects/_category_.json | 5 ++++ .../commands/connect/projects/create.md | 17 ++++++++++++++ .../commands/connect/projects/delete.md | 17 ++++++++++++++ .../commands/connect/projects/list.md | 15 ++++++++++++ .../commands/connect/server-key.md | 15 ++++++++++++ .../commands/connect/trust/_category_.json | 5 ++++ .../commands/connect/trust/promote-root.md | 16 +++++++++++++ .../connect/trust/rotate-server-key.md | 16 +++++++++++++ .../commands/connect/trust/status.md | 15 ++++++++++++ .../avocado-cli/commands/connect/upload.md | 23 +++++++++++++++++++ 35 files changed, 470 insertions(+) create mode 100644 src/docs/avocado-linux/tools/avocado-cli/commands/connect/_category_.json create mode 100644 src/docs/avocado-linux/tools/avocado-cli/commands/connect/auth/_category_.json create mode 100644 src/docs/avocado-linux/tools/avocado-cli/commands/connect/auth/login.md create mode 100644 src/docs/avocado-linux/tools/avocado-cli/commands/connect/auth/logout.md create mode 100644 src/docs/avocado-linux/tools/avocado-cli/commands/connect/auth/status.md create mode 100644 src/docs/avocado-linux/tools/avocado-cli/commands/connect/claim-tokens/_category_.json create mode 100644 src/docs/avocado-linux/tools/avocado-cli/commands/connect/claim-tokens/create.md create mode 100644 src/docs/avocado-linux/tools/avocado-cli/commands/connect/claim-tokens/delete.md create mode 100644 src/docs/avocado-linux/tools/avocado-cli/commands/connect/claim-tokens/list.md create mode 100644 src/docs/avocado-linux/tools/avocado-cli/commands/connect/cohorts/_category_.json create mode 100644 src/docs/avocado-linux/tools/avocado-cli/commands/connect/cohorts/create.md create mode 100644 src/docs/avocado-linux/tools/avocado-cli/commands/connect/cohorts/delete.md create mode 100644 src/docs/avocado-linux/tools/avocado-cli/commands/connect/cohorts/list.md create mode 100644 src/docs/avocado-linux/tools/avocado-cli/commands/connect/devices/_category_.json create mode 100644 src/docs/avocado-linux/tools/avocado-cli/commands/connect/devices/create.md create mode 100644 src/docs/avocado-linux/tools/avocado-cli/commands/connect/devices/delete.md create mode 100644 src/docs/avocado-linux/tools/avocado-cli/commands/connect/devices/list.md create mode 100644 src/docs/avocado-linux/tools/avocado-cli/commands/connect/init.md create mode 100644 src/docs/avocado-linux/tools/avocado-cli/commands/connect/keys/_category_.json create mode 100644 src/docs/avocado-linux/tools/avocado-cli/commands/connect/keys/approve.md create mode 100644 src/docs/avocado-linux/tools/avocado-cli/commands/connect/keys/list.md create mode 100644 src/docs/avocado-linux/tools/avocado-cli/commands/connect/keys/register.md create mode 100644 src/docs/avocado-linux/tools/avocado-cli/commands/connect/keys/retire.md create mode 100644 src/docs/avocado-linux/tools/avocado-cli/commands/connect/orgs/_category_.json create mode 100644 src/docs/avocado-linux/tools/avocado-cli/commands/connect/orgs/list.md create mode 100644 src/docs/avocado-linux/tools/avocado-cli/commands/connect/projects/_category_.json create mode 100644 src/docs/avocado-linux/tools/avocado-cli/commands/connect/projects/create.md create mode 100644 src/docs/avocado-linux/tools/avocado-cli/commands/connect/projects/delete.md create mode 100644 src/docs/avocado-linux/tools/avocado-cli/commands/connect/projects/list.md create mode 100644 src/docs/avocado-linux/tools/avocado-cli/commands/connect/server-key.md create mode 100644 src/docs/avocado-linux/tools/avocado-cli/commands/connect/trust/_category_.json create mode 100644 src/docs/avocado-linux/tools/avocado-cli/commands/connect/trust/promote-root.md create mode 100644 src/docs/avocado-linux/tools/avocado-cli/commands/connect/trust/rotate-server-key.md create mode 100644 src/docs/avocado-linux/tools/avocado-cli/commands/connect/trust/status.md create mode 100644 src/docs/avocado-linux/tools/avocado-cli/commands/connect/upload.md diff --git a/src/docs/avocado-linux/tools/avocado-cli/commands/connect/_category_.json b/src/docs/avocado-linux/tools/avocado-cli/commands/connect/_category_.json new file mode 100644 index 00000000..a3037edc --- /dev/null +++ b/src/docs/avocado-linux/tools/avocado-cli/commands/connect/_category_.json @@ -0,0 +1,5 @@ +{ + "label": "Connect", + "collapsible": true, + "collapsed": true +} diff --git a/src/docs/avocado-linux/tools/avocado-cli/commands/connect/auth/_category_.json b/src/docs/avocado-linux/tools/avocado-cli/commands/connect/auth/_category_.json new file mode 100644 index 00000000..4a07068f --- /dev/null +++ b/src/docs/avocado-linux/tools/avocado-cli/commands/connect/auth/_category_.json @@ -0,0 +1,5 @@ +{ + "label": "Auth", + "collapsible": true, + "collapsed": true +} diff --git a/src/docs/avocado-linux/tools/avocado-cli/commands/connect/auth/login.md b/src/docs/avocado-linux/tools/avocado-cli/commands/connect/auth/login.md new file mode 100644 index 00000000..7bf882a8 --- /dev/null +++ b/src/docs/avocado-linux/tools/avocado-cli/commands/connect/auth/login.md @@ -0,0 +1,15 @@ +``` +Login to the Connect platform + +Usage: avocado connect auth login [OPTIONS] + +Options: + --url API URL (defaults to https://connect.peridio.com or AVOCADO_CONNECT_URL env var) + --profile Profile name (defaults to "default") + --token Use an existing API token instead of browser login + --runs-on Run command on remote host using local volume via NFS (format: user@host) + --nfs-port NFS port for remote execution (auto-selects from 12050-12099 if not specified) + --sdk-arch SDK container architecture for cross-arch emulation via Docker buildx/QEMU (aarch64 or x86-64) + -h, --help Print help + +``` \ No newline at end of file diff --git a/src/docs/avocado-linux/tools/avocado-cli/commands/connect/auth/logout.md b/src/docs/avocado-linux/tools/avocado-cli/commands/connect/auth/logout.md new file mode 100644 index 00000000..a8401cdc --- /dev/null +++ b/src/docs/avocado-linux/tools/avocado-cli/commands/connect/auth/logout.md @@ -0,0 +1,13 @@ +``` +Logout from the Connect platform + +Usage: avocado connect auth logout [OPTIONS] + +Options: + --profile Profile name (defaults to the active default profile) + --runs-on Run command on remote host using local volume via NFS (format: user@host) + --nfs-port NFS port for remote execution (auto-selects from 12050-12099 if not specified) + --sdk-arch SDK container architecture for cross-arch emulation via Docker buildx/QEMU (aarch64 or x86-64) + -h, --help Print help + +``` \ No newline at end of file diff --git a/src/docs/avocado-linux/tools/avocado-cli/commands/connect/auth/status.md b/src/docs/avocado-linux/tools/avocado-cli/commands/connect/auth/status.md new file mode 100644 index 00000000..0e66d80e --- /dev/null +++ b/src/docs/avocado-linux/tools/avocado-cli/commands/connect/auth/status.md @@ -0,0 +1,13 @@ +``` +Show current auth status + +Usage: avocado connect auth status [OPTIONS] + +Options: + --profile Profile name (defaults to the active default profile) + --runs-on Run command on remote host using local volume via NFS (format: user@host) + --nfs-port NFS port for remote execution (auto-selects from 12050-12099 if not specified) + --sdk-arch SDK container architecture for cross-arch emulation via Docker buildx/QEMU (aarch64 or x86-64) + -h, --help Print help + +``` \ No newline at end of file diff --git a/src/docs/avocado-linux/tools/avocado-cli/commands/connect/claim-tokens/_category_.json b/src/docs/avocado-linux/tools/avocado-cli/commands/connect/claim-tokens/_category_.json new file mode 100644 index 00000000..e1951cd3 --- /dev/null +++ b/src/docs/avocado-linux/tools/avocado-cli/commands/connect/claim-tokens/_category_.json @@ -0,0 +1,5 @@ +{ + "label": "Claim Tokens", + "collapsible": true, + "collapsed": true +} diff --git a/src/docs/avocado-linux/tools/avocado-cli/commands/connect/claim-tokens/create.md b/src/docs/avocado-linux/tools/avocado-cli/commands/connect/claim-tokens/create.md new file mode 100644 index 00000000..06460e49 --- /dev/null +++ b/src/docs/avocado-linux/tools/avocado-cli/commands/connect/claim-tokens/create.md @@ -0,0 +1,19 @@ +``` +Create a new claim token + +Usage: avocado connect claim-tokens create [OPTIONS] --name + +Options: + --org Organization ID (or set connect.org in avocado.yaml) + --name Token name + --cohort-id Cohort ID to assign claimed devices to + --max-uses Maximum number of times this token can be used + --no-expiration Disable expiration (default: expires in 24h) + -C, --config Path to avocado.yaml configuration file [default: avocado.yaml] + --profile Profile name (defaults to the active default profile) + --runs-on Run command on remote host using local volume via NFS (format: user@host) + --nfs-port NFS port for remote execution (auto-selects from 12050-12099 if not specified) + --sdk-arch SDK container architecture for cross-arch emulation via Docker buildx/QEMU (aarch64 or x86-64) + -h, --help Print help + +``` \ No newline at end of file diff --git a/src/docs/avocado-linux/tools/avocado-cli/commands/connect/claim-tokens/delete.md b/src/docs/avocado-linux/tools/avocado-cli/commands/connect/claim-tokens/delete.md new file mode 100644 index 00000000..7d1204b4 --- /dev/null +++ b/src/docs/avocado-linux/tools/avocado-cli/commands/connect/claim-tokens/delete.md @@ -0,0 +1,17 @@ +``` +Delete a claim token + +Usage: avocado connect claim-tokens delete [OPTIONS] --id + +Options: + --org Organization ID (or set connect.org in avocado.yaml) + --id Claim token ID to delete + -y, --yes Skip confirmation prompt + -C, --config Path to avocado.yaml configuration file [default: avocado.yaml] + --profile Profile name (defaults to the active default profile) + --runs-on Run command on remote host using local volume via NFS (format: user@host) + --nfs-port NFS port for remote execution (auto-selects from 12050-12099 if not specified) + --sdk-arch SDK container architecture for cross-arch emulation via Docker buildx/QEMU (aarch64 or x86-64) + -h, --help Print help + +``` \ No newline at end of file diff --git a/src/docs/avocado-linux/tools/avocado-cli/commands/connect/claim-tokens/list.md b/src/docs/avocado-linux/tools/avocado-cli/commands/connect/claim-tokens/list.md new file mode 100644 index 00000000..6926406d --- /dev/null +++ b/src/docs/avocado-linux/tools/avocado-cli/commands/connect/claim-tokens/list.md @@ -0,0 +1,15 @@ +``` +List claim tokens in an organization + +Usage: avocado connect claim-tokens list [OPTIONS] + +Options: + --org Organization ID (or set connect.org in avocado.yaml) + -C, --config Path to avocado.yaml configuration file [default: avocado.yaml] + --profile Profile name (defaults to the active default profile) + --runs-on Run command on remote host using local volume via NFS (format: user@host) + --nfs-port NFS port for remote execution (auto-selects from 12050-12099 if not specified) + --sdk-arch SDK container architecture for cross-arch emulation via Docker buildx/QEMU (aarch64 or x86-64) + -h, --help Print help + +``` \ No newline at end of file diff --git a/src/docs/avocado-linux/tools/avocado-cli/commands/connect/cohorts/_category_.json b/src/docs/avocado-linux/tools/avocado-cli/commands/connect/cohorts/_category_.json new file mode 100644 index 00000000..69bee04c --- /dev/null +++ b/src/docs/avocado-linux/tools/avocado-cli/commands/connect/cohorts/_category_.json @@ -0,0 +1,5 @@ +{ + "label": "Cohorts", + "collapsible": true, + "collapsed": true +} diff --git a/src/docs/avocado-linux/tools/avocado-cli/commands/connect/cohorts/create.md b/src/docs/avocado-linux/tools/avocado-cli/commands/connect/cohorts/create.md new file mode 100644 index 00000000..c8243a58 --- /dev/null +++ b/src/docs/avocado-linux/tools/avocado-cli/commands/connect/cohorts/create.md @@ -0,0 +1,18 @@ +``` +Create a new cohort + +Usage: avocado connect cohorts create [OPTIONS] --name + +Options: + --org Organization ID (or set connect.org in avocado.yaml) + --project Project ID (or set connect.project in avocado.yaml) + --name Cohort name + --description Cohort description + -C, --config Path to avocado.yaml configuration file [default: avocado.yaml] + --profile Profile name (defaults to the active default profile) + --runs-on Run command on remote host using local volume via NFS (format: user@host) + --nfs-port NFS port for remote execution (auto-selects from 12050-12099 if not specified) + --sdk-arch SDK container architecture for cross-arch emulation via Docker buildx/QEMU (aarch64 or x86-64) + -h, --help Print help + +``` \ No newline at end of file diff --git a/src/docs/avocado-linux/tools/avocado-cli/commands/connect/cohorts/delete.md b/src/docs/avocado-linux/tools/avocado-cli/commands/connect/cohorts/delete.md new file mode 100644 index 00000000..35ff461c --- /dev/null +++ b/src/docs/avocado-linux/tools/avocado-cli/commands/connect/cohorts/delete.md @@ -0,0 +1,18 @@ +``` +Delete a cohort + +Usage: avocado connect cohorts delete [OPTIONS] --id + +Options: + --org Organization ID (or set connect.org in avocado.yaml) + --project Project ID (or set connect.project in avocado.yaml) + --id Cohort ID to delete + -y, --yes Skip confirmation prompt + -C, --config Path to avocado.yaml configuration file [default: avocado.yaml] + --profile Profile name (defaults to the active default profile) + --runs-on Run command on remote host using local volume via NFS (format: user@host) + --nfs-port NFS port for remote execution (auto-selects from 12050-12099 if not specified) + --sdk-arch SDK container architecture for cross-arch emulation via Docker buildx/QEMU (aarch64 or x86-64) + -h, --help Print help + +``` \ No newline at end of file diff --git a/src/docs/avocado-linux/tools/avocado-cli/commands/connect/cohorts/list.md b/src/docs/avocado-linux/tools/avocado-cli/commands/connect/cohorts/list.md new file mode 100644 index 00000000..153bb01d --- /dev/null +++ b/src/docs/avocado-linux/tools/avocado-cli/commands/connect/cohorts/list.md @@ -0,0 +1,16 @@ +``` +List cohorts in a project + +Usage: avocado connect cohorts list [OPTIONS] + +Options: + --org Organization ID (or set connect.org in avocado.yaml) + --project Project ID (or set connect.project in avocado.yaml) + -C, --config Path to avocado.yaml configuration file [default: avocado.yaml] + --profile Profile name (defaults to the active default profile) + --runs-on Run command on remote host using local volume via NFS (format: user@host) + --nfs-port NFS port for remote execution (auto-selects from 12050-12099 if not specified) + --sdk-arch SDK container architecture for cross-arch emulation via Docker buildx/QEMU (aarch64 or x86-64) + -h, --help Print help + +``` \ No newline at end of file diff --git a/src/docs/avocado-linux/tools/avocado-cli/commands/connect/devices/_category_.json b/src/docs/avocado-linux/tools/avocado-cli/commands/connect/devices/_category_.json new file mode 100644 index 00000000..0015fd89 --- /dev/null +++ b/src/docs/avocado-linux/tools/avocado-cli/commands/connect/devices/_category_.json @@ -0,0 +1,5 @@ +{ + "label": "Devices", + "collapsible": true, + "collapsed": true +} diff --git a/src/docs/avocado-linux/tools/avocado-cli/commands/connect/devices/create.md b/src/docs/avocado-linux/tools/avocado-cli/commands/connect/devices/create.md new file mode 100644 index 00000000..3abf2572 --- /dev/null +++ b/src/docs/avocado-linux/tools/avocado-cli/commands/connect/devices/create.md @@ -0,0 +1,17 @@ +``` +Create a new device + +Usage: avocado connect devices create [OPTIONS] --name --identifier + +Options: + --org Organization ID (or set connect.org in avocado.yaml) + --name Device name + --identifier Device identifier (must be unique per org) + -C, --config Path to avocado.yaml configuration file [default: avocado.yaml] + --profile Profile name (defaults to the active default profile) + --runs-on Run command on remote host using local volume via NFS (format: user@host) + --nfs-port NFS port for remote execution (auto-selects from 12050-12099 if not specified) + --sdk-arch SDK container architecture for cross-arch emulation via Docker buildx/QEMU (aarch64 or x86-64) + -h, --help Print help + +``` \ No newline at end of file diff --git a/src/docs/avocado-linux/tools/avocado-cli/commands/connect/devices/delete.md b/src/docs/avocado-linux/tools/avocado-cli/commands/connect/devices/delete.md new file mode 100644 index 00000000..52027cf6 --- /dev/null +++ b/src/docs/avocado-linux/tools/avocado-cli/commands/connect/devices/delete.md @@ -0,0 +1,17 @@ +``` +Delete a device + +Usage: avocado connect devices delete [OPTIONS] --id + +Options: + --org Organization ID (or set connect.org in avocado.yaml) + --id Device ID to delete + -y, --yes Skip confirmation prompt + -C, --config Path to avocado.yaml configuration file [default: avocado.yaml] + --profile Profile name (defaults to the active default profile) + --runs-on Run command on remote host using local volume via NFS (format: user@host) + --nfs-port NFS port for remote execution (auto-selects from 12050-12099 if not specified) + --sdk-arch SDK container architecture for cross-arch emulation via Docker buildx/QEMU (aarch64 or x86-64) + -h, --help Print help + +``` \ No newline at end of file diff --git a/src/docs/avocado-linux/tools/avocado-cli/commands/connect/devices/list.md b/src/docs/avocado-linux/tools/avocado-cli/commands/connect/devices/list.md new file mode 100644 index 00000000..15c2f78d --- /dev/null +++ b/src/docs/avocado-linux/tools/avocado-cli/commands/connect/devices/list.md @@ -0,0 +1,15 @@ +``` +List devices in an organization + +Usage: avocado connect devices list [OPTIONS] + +Options: + --org Organization ID (or set connect.org in avocado.yaml) + -C, --config Path to avocado.yaml configuration file [default: avocado.yaml] + --profile Profile name (defaults to the active default profile) + --runs-on Run command on remote host using local volume via NFS (format: user@host) + --nfs-port NFS port for remote execution (auto-selects from 12050-12099 if not specified) + --sdk-arch SDK container architecture for cross-arch emulation via Docker buildx/QEMU (aarch64 or x86-64) + -h, --help Print help + +``` \ No newline at end of file diff --git a/src/docs/avocado-linux/tools/avocado-cli/commands/connect/init.md b/src/docs/avocado-linux/tools/avocado-cli/commands/connect/init.md new file mode 100644 index 00000000..ca80877a --- /dev/null +++ b/src/docs/avocado-linux/tools/avocado-cli/commands/connect/init.md @@ -0,0 +1,16 @@ +``` +Initialize connect settings in avocado.yaml (org, project, server key) + +Usage: avocado connect init [OPTIONS] + +Options: + --org Organization ID (skip interactive prompt) + --project Project name or ID (skip interactive prompt) + -C, --config Path to avocado.yaml configuration file [default: avocado.yaml] + --profile Profile name (defaults to the active default profile) + --runs-on Run command on remote host using local volume via NFS (format: user@host) + --nfs-port NFS port for remote execution (auto-selects from 12050-12099 if not specified) + --sdk-arch SDK container architecture for cross-arch emulation via Docker buildx/QEMU (aarch64 or x86-64) + -h, --help Print help + +``` \ No newline at end of file diff --git a/src/docs/avocado-linux/tools/avocado-cli/commands/connect/keys/_category_.json b/src/docs/avocado-linux/tools/avocado-cli/commands/connect/keys/_category_.json new file mode 100644 index 00000000..0fe4beca --- /dev/null +++ b/src/docs/avocado-linux/tools/avocado-cli/commands/connect/keys/_category_.json @@ -0,0 +1,5 @@ +{ + "label": "Keys", + "collapsible": true, + "collapsed": true +} diff --git a/src/docs/avocado-linux/tools/avocado-cli/commands/connect/keys/approve.md b/src/docs/avocado-linux/tools/avocado-cli/commands/connect/keys/approve.md new file mode 100644 index 00000000..a1f13859 --- /dev/null +++ b/src/docs/avocado-linux/tools/avocado-cli/commands/connect/keys/approve.md @@ -0,0 +1,18 @@ +``` +Approve a staged delegate key (admin only) + +Usage: avocado connect keys approve [OPTIONS] + +Arguments: + Key ID of the staged key to approve + +Options: + --org Organization ID (or set connect.org in avocado.yaml) + -C, --config Path to avocado.yaml configuration file [default: avocado.yaml] + --profile Profile name + --runs-on Run command on remote host using local volume via NFS (format: user@host) + --nfs-port NFS port for remote execution (auto-selects from 12050-12099 if not specified) + --sdk-arch SDK container architecture for cross-arch emulation via Docker buildx/QEMU (aarch64 or x86-64) + -h, --help Print help + +``` \ No newline at end of file diff --git a/src/docs/avocado-linux/tools/avocado-cli/commands/connect/keys/list.md b/src/docs/avocado-linux/tools/avocado-cli/commands/connect/keys/list.md new file mode 100644 index 00000000..c9b8df5d --- /dev/null +++ b/src/docs/avocado-linux/tools/avocado-cli/commands/connect/keys/list.md @@ -0,0 +1,16 @@ +``` +List delegate keys registered with the server + +Usage: avocado connect keys list [OPTIONS] + +Options: + --org Organization ID (or set connect.org in avocado.yaml) + --type Filter by key type: content or root + -C, --config Path to avocado.yaml configuration file [default: avocado.yaml] + --profile Profile name + --runs-on Run command on remote host using local volume via NFS (format: user@host) + --nfs-port NFS port for remote execution (auto-selects from 12050-12099 if not specified) + --sdk-arch SDK container architecture for cross-arch emulation via Docker buildx/QEMU (aarch64 or x86-64) + -h, --help Print help + +``` \ No newline at end of file diff --git a/src/docs/avocado-linux/tools/avocado-cli/commands/connect/keys/register.md b/src/docs/avocado-linux/tools/avocado-cli/commands/connect/keys/register.md new file mode 100644 index 00000000..6e57bfb5 --- /dev/null +++ b/src/docs/avocado-linux/tools/avocado-cli/commands/connect/keys/register.md @@ -0,0 +1,17 @@ +``` +Register a local signing key with the Connect server + +Usage: avocado connect keys register [OPTIONS] --type --key + +Options: + --type Key type: content or root + --key Name of the local signing key (from 'avocado signing-keys list') + --org Organization ID (or set connect.org in avocado.yaml) + -C, --config Path to avocado.yaml configuration file [default: avocado.yaml] + --profile Profile name + --runs-on Run command on remote host using local volume via NFS (format: user@host) + --nfs-port NFS port for remote execution (auto-selects from 12050-12099 if not specified) + --sdk-arch SDK container architecture for cross-arch emulation via Docker buildx/QEMU (aarch64 or x86-64) + -h, --help Print help + +``` \ No newline at end of file diff --git a/src/docs/avocado-linux/tools/avocado-cli/commands/connect/keys/retire.md b/src/docs/avocado-linux/tools/avocado-cli/commands/connect/keys/retire.md new file mode 100644 index 00000000..aa0570b9 --- /dev/null +++ b/src/docs/avocado-linux/tools/avocado-cli/commands/connect/keys/retire.md @@ -0,0 +1,18 @@ +``` +Discard a staged delegate key + +Usage: avocado connect keys retire [OPTIONS] + +Arguments: + Key ID of the staged key to discard + +Options: + --org Organization ID (or set connect.org in avocado.yaml) + -C, --config Path to avocado.yaml configuration file [default: avocado.yaml] + --profile Profile name + --runs-on Run command on remote host using local volume via NFS (format: user@host) + --nfs-port NFS port for remote execution (auto-selects from 12050-12099 if not specified) + --sdk-arch SDK container architecture for cross-arch emulation via Docker buildx/QEMU (aarch64 or x86-64) + -h, --help Print help + +``` \ No newline at end of file diff --git a/src/docs/avocado-linux/tools/avocado-cli/commands/connect/orgs/_category_.json b/src/docs/avocado-linux/tools/avocado-cli/commands/connect/orgs/_category_.json new file mode 100644 index 00000000..e3621141 --- /dev/null +++ b/src/docs/avocado-linux/tools/avocado-cli/commands/connect/orgs/_category_.json @@ -0,0 +1,5 @@ +{ + "label": "Orgs", + "collapsible": true, + "collapsed": true +} diff --git a/src/docs/avocado-linux/tools/avocado-cli/commands/connect/orgs/list.md b/src/docs/avocado-linux/tools/avocado-cli/commands/connect/orgs/list.md new file mode 100644 index 00000000..0916b1a5 --- /dev/null +++ b/src/docs/avocado-linux/tools/avocado-cli/commands/connect/orgs/list.md @@ -0,0 +1,13 @@ +``` +List organizations you belong to + +Usage: avocado connect orgs list [OPTIONS] + +Options: + --profile Profile name (defaults to the active default profile) + --runs-on Run command on remote host using local volume via NFS (format: user@host) + --nfs-port NFS port for remote execution (auto-selects from 12050-12099 if not specified) + --sdk-arch SDK container architecture for cross-arch emulation via Docker buildx/QEMU (aarch64 or x86-64) + -h, --help Print help + +``` \ No newline at end of file diff --git a/src/docs/avocado-linux/tools/avocado-cli/commands/connect/projects/_category_.json b/src/docs/avocado-linux/tools/avocado-cli/commands/connect/projects/_category_.json new file mode 100644 index 00000000..4afd515b --- /dev/null +++ b/src/docs/avocado-linux/tools/avocado-cli/commands/connect/projects/_category_.json @@ -0,0 +1,5 @@ +{ + "label": "Projects", + "collapsible": true, + "collapsed": true +} diff --git a/src/docs/avocado-linux/tools/avocado-cli/commands/connect/projects/create.md b/src/docs/avocado-linux/tools/avocado-cli/commands/connect/projects/create.md new file mode 100644 index 00000000..9c53b563 --- /dev/null +++ b/src/docs/avocado-linux/tools/avocado-cli/commands/connect/projects/create.md @@ -0,0 +1,17 @@ +``` +Create a new project + +Usage: avocado connect projects create [OPTIONS] --name + +Options: + --org Organization ID (or set connect.org in avocado.yaml) + --name Project name + --description Project description + -C, --config Path to avocado.yaml configuration file [default: avocado.yaml] + --profile Profile name (defaults to the active default profile) + --runs-on Run command on remote host using local volume via NFS (format: user@host) + --nfs-port NFS port for remote execution (auto-selects from 12050-12099 if not specified) + --sdk-arch SDK container architecture for cross-arch emulation via Docker buildx/QEMU (aarch64 or x86-64) + -h, --help Print help + +``` \ No newline at end of file diff --git a/src/docs/avocado-linux/tools/avocado-cli/commands/connect/projects/delete.md b/src/docs/avocado-linux/tools/avocado-cli/commands/connect/projects/delete.md new file mode 100644 index 00000000..05e0cd17 --- /dev/null +++ b/src/docs/avocado-linux/tools/avocado-cli/commands/connect/projects/delete.md @@ -0,0 +1,17 @@ +``` +Delete a project + +Usage: avocado connect projects delete [OPTIONS] --id + +Options: + --org Organization ID (or set connect.org in avocado.yaml) + --id Project ID to delete + -y, --yes Skip confirmation prompt + -C, --config Path to avocado.yaml configuration file [default: avocado.yaml] + --profile Profile name (defaults to the active default profile) + --runs-on Run command on remote host using local volume via NFS (format: user@host) + --nfs-port NFS port for remote execution (auto-selects from 12050-12099 if not specified) + --sdk-arch SDK container architecture for cross-arch emulation via Docker buildx/QEMU (aarch64 or x86-64) + -h, --help Print help + +``` \ No newline at end of file diff --git a/src/docs/avocado-linux/tools/avocado-cli/commands/connect/projects/list.md b/src/docs/avocado-linux/tools/avocado-cli/commands/connect/projects/list.md new file mode 100644 index 00000000..e846923c --- /dev/null +++ b/src/docs/avocado-linux/tools/avocado-cli/commands/connect/projects/list.md @@ -0,0 +1,15 @@ +``` +List projects in an organization + +Usage: avocado connect projects list [OPTIONS] + +Options: + --org Organization ID (or set connect.org in avocado.yaml) + -C, --config Path to avocado.yaml configuration file [default: avocado.yaml] + --profile Profile name (defaults to the active default profile) + --runs-on Run command on remote host using local volume via NFS (format: user@host) + --nfs-port NFS port for remote execution (auto-selects from 12050-12099 if not specified) + --sdk-arch SDK container architecture for cross-arch emulation via Docker buildx/QEMU (aarch64 or x86-64) + -h, --help Print help + +``` \ No newline at end of file diff --git a/src/docs/avocado-linux/tools/avocado-cli/commands/connect/server-key.md b/src/docs/avocado-linux/tools/avocado-cli/commands/connect/server-key.md new file mode 100644 index 00000000..9d5ca792 --- /dev/null +++ b/src/docs/avocado-linux/tools/avocado-cli/commands/connect/server-key.md @@ -0,0 +1,15 @@ +``` +Retrieve the Connect server's TUF signing public key + +Usage: avocado connect server-key [OPTIONS] + +Options: + --org Organization ID (or set connect.org in avocado.yaml) + -C, --config Path to avocado.yaml configuration file [default: avocado.yaml] + --profile Profile name (defaults to the active default profile) + --runs-on Run command on remote host using local volume via NFS (format: user@host) + --nfs-port NFS port for remote execution (auto-selects from 12050-12099 if not specified) + --sdk-arch SDK container architecture for cross-arch emulation via Docker buildx/QEMU (aarch64 or x86-64) + -h, --help Print help + +``` \ No newline at end of file diff --git a/src/docs/avocado-linux/tools/avocado-cli/commands/connect/trust/_category_.json b/src/docs/avocado-linux/tools/avocado-cli/commands/connect/trust/_category_.json new file mode 100644 index 00000000..b24f3a6a --- /dev/null +++ b/src/docs/avocado-linux/tools/avocado-cli/commands/connect/trust/_category_.json @@ -0,0 +1,5 @@ +{ + "label": "Trust", + "collapsible": true, + "collapsed": true +} diff --git a/src/docs/avocado-linux/tools/avocado-cli/commands/connect/trust/promote-root.md b/src/docs/avocado-linux/tools/avocado-cli/commands/connect/trust/promote-root.md new file mode 100644 index 00000000..9c76a0f9 --- /dev/null +++ b/src/docs/avocado-linux/tools/avocado-cli/commands/connect/trust/promote-root.md @@ -0,0 +1,16 @@ +``` +Promote root trust to user control (Level 1 → 2) + +Usage: avocado connect trust promote-root [OPTIONS] --key + +Options: + --key Name of the local root signing key to use + --org Organization ID (or set connect.org in avocado.yaml) + -C, --config Path to avocado.yaml configuration file [default: avocado.yaml] + --profile Profile name (defaults to the active default profile) + --runs-on Run command on remote host using local volume via NFS (format: user@host) + --nfs-port NFS port for remote execution (auto-selects from 12050-12099 if not specified) + --sdk-arch SDK container architecture for cross-arch emulation via Docker buildx/QEMU (aarch64 or x86-64) + -h, --help Print help + +``` \ No newline at end of file diff --git a/src/docs/avocado-linux/tools/avocado-cli/commands/connect/trust/rotate-server-key.md b/src/docs/avocado-linux/tools/avocado-cli/commands/connect/trust/rotate-server-key.md new file mode 100644 index 00000000..a0de8ca0 --- /dev/null +++ b/src/docs/avocado-linux/tools/avocado-cli/commands/connect/trust/rotate-server-key.md @@ -0,0 +1,16 @@ +``` +Rotate the server signing key + +Usage: avocado connect trust rotate-server-key [OPTIONS] + +Options: + --key Name of the local root signing key (required at security level 2) + --org Organization ID (or set connect.org in avocado.yaml) + -C, --config Path to avocado.yaml configuration file [default: avocado.yaml] + --profile Profile name (defaults to the active default profile) + --runs-on Run command on remote host using local volume via NFS (format: user@host) + --nfs-port NFS port for remote execution (auto-selects from 12050-12099 if not specified) + --sdk-arch SDK container architecture for cross-arch emulation via Docker buildx/QEMU (aarch64 or x86-64) + -h, --help Print help + +``` \ No newline at end of file diff --git a/src/docs/avocado-linux/tools/avocado-cli/commands/connect/trust/status.md b/src/docs/avocado-linux/tools/avocado-cli/commands/connect/trust/status.md new file mode 100644 index 00000000..387da86c --- /dev/null +++ b/src/docs/avocado-linux/tools/avocado-cli/commands/connect/trust/status.md @@ -0,0 +1,15 @@ +``` +Show fleet trust status for an organization + +Usage: avocado connect trust status [OPTIONS] + +Options: + --org Organization ID (or set connect.org in avocado.yaml) + -C, --config Path to avocado.yaml configuration file [default: avocado.yaml] + --profile Profile name (defaults to the active default profile) + --runs-on Run command on remote host using local volume via NFS (format: user@host) + --nfs-port NFS port for remote execution (auto-selects from 12050-12099 if not specified) + --sdk-arch SDK container architecture for cross-arch emulation via Docker buildx/QEMU (aarch64 or x86-64) + -h, --help Print help + +``` \ No newline at end of file diff --git a/src/docs/avocado-linux/tools/avocado-cli/commands/connect/upload.md b/src/docs/avocado-linux/tools/avocado-cli/commands/connect/upload.md new file mode 100644 index 00000000..216eba18 --- /dev/null +++ b/src/docs/avocado-linux/tools/avocado-cli/commands/connect/upload.md @@ -0,0 +1,23 @@ +``` +Upload current runtime build to the Connect platform + +Usage: avocado connect upload [OPTIONS] + +Arguments: + Runtime name to upload + +Options: + --org Organization ID (or set connect.org in avocado.yaml) + --project Project ID (or set connect.project in avocado.yaml) + --version Version string (defaults to runtime name-version from manifest) + --description Description for the upload + -C, --config Path to avocado.yaml configuration file [default: avocado.yaml] + -t, --target Target architecture + --file Path to pre-built tarball or artifact directory (skips export from Docker volume) + --profile Profile name (defaults to the active default profile) + --runs-on Run command on remote host using local volume via NFS (format: user@host) + --nfs-port NFS port for remote execution (auto-selects from 12050-12099 if not specified) + --sdk-arch SDK container architecture for cross-arch emulation via Docker buildx/QEMU (aarch64 or x86-64) + -h, --help Print help + +``` \ No newline at end of file From db18879e834cbd93678c0d591735be2d2e0ffdaf Mon Sep 17 00:00:00 2001 From: Justin Schneck Date: Fri, 13 Mar 2026 19:14:32 -0400 Subject: [PATCH 5/8] docs: update avocado-cli overview, configuration, and ext image docs Add connect, rootfs, and initramfs mentions to the CLI overview. Document connect, rootfs, and initramfs config sections. Add erofs-lz4 and erofs-zst filesystem types to ext image docs. --- .../tools/avocado-cli/commands/ext/image.md | 62 +------------------ .../tools/avocado-cli/configuration.md | 49 +++++++++++++++ .../tools/avocado-cli/overview.md | 4 +- 3 files changed, 54 insertions(+), 61 deletions(-) diff --git a/src/docs/avocado-linux/tools/avocado-cli/commands/ext/image.md b/src/docs/avocado-linux/tools/avocado-cli/commands/ext/image.md index a37da645..3c24c068 100644 --- a/src/docs/avocado-linux/tools/avocado-cli/commands/ext/image.md +++ b/src/docs/avocado-linux/tools/avocado-cli/commands/ext/image.md @@ -1,5 +1,5 @@ ``` -Create a squashfs or erofs image from a system extension +Create squashfs image from system extension Usage: avocado ext image [OPTIONS] [NAME] @@ -9,9 +9,8 @@ Arguments: Options: -C, --config Path to avocado.yaml configuration file [default: avocado.yaml] -v, --verbose Enable verbose output - -e, --extension Extension name (alias for positional NAME) -t, --target Target architecture - --out Output directory on host to copy the resulting .raw image to + --out Output directory on host to copy the resulting image to --container-arg Additional arguments to pass to the container runtime --dnf-arg Additional arguments to pass to DNF commands --runs-on Run command on remote host using local volume via NFS (format: user@host) @@ -19,59 +18,4 @@ Options: --sdk-arch SDK container architecture for cross-arch emulation via Docker buildx/QEMU (aarch64 or x86-64) -h, --help Print help -``` - -## Overview - -`avocado ext image` creates a read-only filesystem image (`.raw`) from a built extension sysroot. The image is stored in the SDK container volume and, if `--out` is specified, copied to the host. - -## Filesystem types - -The image format is controlled by the `filesystem` field in the extension config: - -```yaml -extensions: - my-app: - version: '1.0.0' - filesystem: erofs # or 'squashfs' (default) -``` - -| Value | Tool | Notes | -| ---------- | ------------ | ----------------------------------------------------------------- | -| `squashfs` | `mksquashfs` | Default; broad compatibility | -| `erofs` | `mkfs.erofs` | Better random-read performance; smaller images for many workloads | - -## Reproducible builds - -Set `source_date_epoch` at the top level of your `avocado.yaml` to produce bit-for-bit reproducible images: - -```yaml -source_date_epoch: 1700000000 -``` - -This value is passed as the filesystem timestamp to both `mksquashfs` and `mkfs.erofs`. When unset it defaults to `0`. - -## `var_files` exclusion - -Files matching `var_files` patterns in the extension config are **excluded** from the `.raw` image. They belong on the writable var partition, not the read-only extension image: - -```yaml -extensions: - my-app: - version: '1.0.0' - var_files: - - var/lib/docker/** - - var/lib/myapp/data/ -``` - -See [Seeding the var partition](../../../../guides/seeding-var-partition) for how these files are seeded at build time. - -## Copying the image to the host - -Use `--out` to copy the resulting `.raw` file to a local directory: - -```bash -avocado ext image my-app --out ./dist/ -``` - -The file is named `-.raw`. +``` \ No newline at end of file diff --git a/src/docs/avocado-linux/tools/avocado-cli/configuration.md b/src/docs/avocado-linux/tools/avocado-cli/configuration.md index 421ed987..10c427ce 100644 --- a/src/docs/avocado-linux/tools/avocado-cli/configuration.md +++ b/src/docs/avocado-linux/tools/avocado-cli/configuration.md @@ -43,6 +43,55 @@ The following environment variables are deprecated but still supported as fallba | `AVOCADO_SDK_REPO_URL` | `AVOCADO_REPO_URL` | | `AVOCADO_SDK_REPO_RELEASE` | `AVOCADO_RELEASEVER` | +## Connect configuration + +The `connect` section stores defaults for Avocado Connect platform commands, so you don't need to pass `--org` and `--project` on every invocation. This section is typically populated by running `avocado connect init`. + +```yaml +connect: + org: my-org-id + project: my-project-id + server_key: +``` + +| Field | Description | +| ------------ | ---------------------------------------------------------------------------------------------- | +| `org` | Default organization ID for `avocado connect` commands | +| `project` | Default project ID for `avocado connect` commands | +| `server_key` | Connect server's TUF signing public key (hex). Per-runtime `signing.server_key` overrides this | + +## Rootfs configuration + +The `rootfs` section configures the shared rootfs sysroot used by runtime builds. + +```yaml +rootfs: + filesystem: erofs-lz4 # default + packages: + avocado-pkg-rootfs: '*' +``` + +| Field | Default | Description | +| ------------ | ----------- | ------------------------------------------- | +| `filesystem` | `erofs-lz4` | Image format: `erofs-lz4` or `erofs-zst` | +| `packages` | | Map of package names to version constraints | + +## Initramfs configuration + +The `initramfs` section configures the initramfs sysroot used for the early boot environment. + +```yaml +initramfs: + filesystem: cpio.zst # default + packages: + avocado-pkg-initramfs: '*' +``` + +| Field | Default | Description | +| ------------ | ---------- | ---------------------------------------------------------- | +| `filesystem` | `cpio.zst` | Image format: `cpio`, `cpio.zst`, `cpio.lz4`, or `cpio.gz` | +| `packages` | | Map of package names to version constraints | + ## Examples Example configuration files are available in the [Avocado OS repository](https://github.com/avocado-linux/avocado-os/tree/main/references). These examples demonstrate common configuration patterns for different use cases and target platforms. diff --git a/src/docs/avocado-linux/tools/avocado-cli/overview.md b/src/docs/avocado-linux/tools/avocado-cli/overview.md index 96c24e0f..9d3f0cd6 100644 --- a/src/docs/avocado-linux/tools/avocado-cli/overview.md +++ b/src/docs/avocado-linux/tools/avocado-cli/overview.md @@ -6,6 +6,6 @@ description: 'Avocado CLI tool for initializing, configuring, building, and prov The Avocado CLI is a powerful tool that allows you to initialize, configure, build, and provision Avocado OS projects. -The CLI provides comprehensive functionality for managing the entire Avocado OS development lifecycle. Core capabilities include project initialization with target architecture support, building and managing SDK environments for cross-compilation, creating and packaging system extensions (sysext) and configuration extensions (confext), building runtime images, and deploying to target devices. +The CLI provides comprehensive functionality for managing the entire Avocado OS development lifecycle. Core capabilities include project initialization with target architecture support, building and managing SDK environments for cross-compilation, creating and packaging system extensions (sysext) and configuration extensions (confext), managing rootfs and initramfs sysroots, building runtime images, and deploying to target devices. -Advanced features include hardware-in-the-loop (HITL) testing server support, dependency management with DNF integration, repository metadata fetching and refreshing, container-based development workflows, and flexible provisioning profiles. +Advanced features include Avocado Connect platform integration for fleet management (device provisioning, OTA updates, signing key delegation, and trust posture management), hardware-in-the-loop (HITL) testing server support, dependency management with DNF integration, repository metadata fetching and refreshing, container-based development workflows, and flexible provisioning profiles. From b090ef69abd356ec9b3ab77092044aa4bf3adf19 Mon Sep 17 00:00:00 2001 From: Justin Schneck Date: Fri, 13 Mar 2026 19:14:39 -0400 Subject: [PATCH 6/8] docs: add guide for customizing rootfs and initramfs packages Explain how to add packages to rootfs and initramfs sysroots, including the requirement to always include the base meta-package (avocado-pkg-rootfs / avocado-pkg-initramfs) when specifying packages. Covers filesystem format options, version constraints, and lock file behavior. --- .../guides/customizing-rootfs-initramfs.md | 154 ++++++++++++++++++ 1 file changed, 154 insertions(+) create mode 100644 src/docs/avocado-linux/guides/customizing-rootfs-initramfs.md diff --git a/src/docs/avocado-linux/guides/customizing-rootfs-initramfs.md b/src/docs/avocado-linux/guides/customizing-rootfs-initramfs.md new file mode 100644 index 00000000..665e5f59 --- /dev/null +++ b/src/docs/avocado-linux/guides/customizing-rootfs-initramfs.md @@ -0,0 +1,154 @@ +--- +sidebar_position: 8 +title: 'Customizing the rootfs and initramfs' +description: 'Add packages to the Avocado rootfs and initramfs sysroots to customize the base root filesystem and early boot environment.' +--- + +Avocado builds runtime images from two base sysroots: the **rootfs** (the read-only root filesystem) and the **initramfs** (the early boot environment that runs before the rootfs is mounted). By default each sysroot installs a single meta-package that pulls in everything needed for a standard Avocado system. You can add extra packages to either sysroot to customize what ships on your device. + +## Default behavior + +When no `rootfs` or `initramfs` section is present in your `avocado.yaml`, the CLI installs the default meta-packages automatically: + +| Sysroot | Default package | +| --------- | ----------------------- | +| rootfs | `avocado-pkg-rootfs` | +| initramfs | `avocado-pkg-initramfs` | + +These meta-packages depend on the core set of packages needed for a functional Avocado system. You do not need to add anything to your config if the defaults are sufficient. + +## Adding packages to the rootfs + +To add packages to the rootfs, add a `rootfs` section with a `packages` map to your `avocado.yaml`: + +```yaml +rootfs: + packages: + avocado-pkg-rootfs: '*' + strace: '*' + tcpdump: '>=4.0' +``` + +:::caution + +When you specify `rootfs.packages`, the CLI installs **only** the packages you list — it does **not** automatically include `avocado-pkg-rootfs`. You must always include `avocado-pkg-rootfs` in the package list. Omitting it will produce a rootfs that is missing core Avocado system components. + +::: + +### Version constraints + +Package values are version constraints passed to DNF: + +| Value | Meaning | +| --------- | ------------------------------ | +| `'*'` | Any version (latest available) | +| `'1.2'` | Exact version `1.2` | +| `'>=4.0'` | Version 4.0 or newer | + +## Adding packages to the initramfs + +The initramfs works the same way. Add an `initramfs` section: + +```yaml +initramfs: + packages: + avocado-pkg-initramfs: '*' + e2fsprogs: '*' +``` + +:::caution + +As with the rootfs, when you specify `initramfs.packages` you must always include `avocado-pkg-initramfs`. The CLI installs only the packages you list. + +::: + +## Choosing a filesystem format + +Both sysroots support configuring the output image filesystem: + +```yaml +rootfs: + filesystem: erofs-lz4 # default + packages: + avocado-pkg-rootfs: '*' + +initramfs: + filesystem: cpio.zst # default + packages: + avocado-pkg-initramfs: '*' +``` + +### Rootfs filesystem options + +| Value | Description | +| ----------- | ------------------------------------- | +| `erofs-lz4` | Default. EROFS with LZ4HC compression | +| `erofs-zst` | EROFS with Zstandard compression | + +### Initramfs filesystem options + +| Value | Description | +| ---------- | ------------------------------------------------ | +| `cpio.zst` | Default. cpio archive with Zstandard compression | +| `cpio` | Uncompressed cpio archive | +| `cpio.lz4` | cpio archive with LZ4 compression | +| `cpio.gz` | cpio archive with gzip compression | + +## Complete example + +```yaml +sdk: + image: docker.io/avocadolinux/sdk:2024-edge + +rootfs: + filesystem: erofs-lz4 + packages: + avocado-pkg-rootfs: '*' + strace: '*' + vim-minimal: '*' + +initramfs: + filesystem: cpio.zst + packages: + avocado-pkg-initramfs: '*' + e2fsprogs: '*' + +extensions: + my-app: + version: '1.0.0' + types: [sysext] + +runtimes: + dev: + extensions: [my-app] + packages: + avocado-runtime: '*' +``` + +## Build workflow + +```bash +# Install all sysroots (SDK, rootfs, initramfs, extensions, runtimes) +avocado install + +# Or install sysroots individually +avocado rootfs install +avocado initramfs install + +# Build images +avocado rootfs image +avocado initramfs image + +# Or build everything at once +avocado build +``` + +The `avocado install` and `avocado build` commands handle the rootfs and initramfs automatically as part of the full build pipeline. The individual `avocado rootfs` and `avocado initramfs` commands are useful for iterating on just the sysroot without rebuilding everything. + +## Package removal + +If you remove a package from the `packages` map, the CLI detects the removal on the next `install` and automatically cleans the sysroot before reinstalling. This is because DNF's installroot mode is additive-only — it cannot remove individual packages from an existing sysroot. + +## Lock file + +Installed package versions are recorded in `avocado.lock` after each successful install. This ensures reproducible builds — subsequent installs will pin to the same versions unless you run `avocado unlock` to allow updates. From f7b903796050f88412f163f6276eb5d98a554eeb Mon Sep 17 00:00:00 2001 From: Justin Schneck Date: Fri, 13 Mar 2026 19:14:47 -0400 Subject: [PATCH 7/8] docs: regenerate avocado-cli command help text from latest CLI build Auto-generated updates from build-avocado-cli script reflecting current CLI help output across all existing command docs. --- .../tools/avocado-cli/commands/build.md | 2 +- .../tools/avocado-cli/commands/clean.md | 2 +- .../tools/avocado-cli/commands/deploy.md | 8 +- .../tools/avocado-cli/commands/ext/build.md | 3 +- .../avocado-cli/commands/ext/checkout.md | 6 +- .../tools/avocado-cli/commands/ext/clean.md | 3 +- .../tools/avocado-cli/commands/ext/deps.md | 15 +- .../tools/avocado-cli/commands/ext/dnf.md | 2 +- .../tools/avocado-cli/commands/ext/fetch.md | 3 +- .../tools/avocado-cli/commands/ext/install.md | 3 +- .../tools/avocado-cli/commands/ext/list.md | 2 +- .../tools/avocado-cli/commands/ext/package.md | 3 +- .../tools/avocado-cli/commands/fetch.md | 2 +- .../tools/avocado-cli/commands/hitl/server.md | 2 +- .../tools/avocado-cli/commands/init.md | 2 +- .../tools/avocado-cli/commands/install.md | 65 ++++++--- .../tools/avocado-cli/commands/provision.md | 8 +- .../tools/avocado-cli/commands/prune.md | 2 +- .../avocado-cli/commands/runtime/build.md | 3 +- .../avocado-cli/commands/runtime/clean.md | 3 +- .../avocado-cli/commands/runtime/deploy.md | 7 +- .../avocado-cli/commands/runtime/deps.md | 3 +- .../tools/avocado-cli/commands/runtime/dnf.md | 2 +- .../avocado-cli/commands/runtime/install.md | 3 +- .../avocado-cli/commands/runtime/list.md | 2 +- .../avocado-cli/commands/runtime/provision.md | 3 +- .../avocado-cli/commands/runtime/sign.md | 3 +- .../tools/avocado-cli/commands/sdk/clean.md | 2 +- .../tools/avocado-cli/commands/sdk/compile.md | 2 +- .../tools/avocado-cli/commands/sdk/deps.md | 2 +- .../tools/avocado-cli/commands/sdk/dnf.md | 2 +- .../tools/avocado-cli/commands/sdk/install.md | 2 +- .../tools/avocado-cli/commands/sdk/package.md | 133 +----------------- .../tools/avocado-cli/commands/sdk/run.md | 2 +- .../tools/avocado-cli/commands/sign.md | 8 +- .../commands/signing-keys/create.md | 2 +- .../avocado-cli/commands/signing-keys/list.md | 2 +- .../commands/signing-keys/remove.md | 2 +- .../tools/avocado-cli/commands/uninstall.md | 10 +- .../tools/avocado-cli/commands/unlock.md | 2 +- .../tools/avocado-cli/commands/upgrade.md | 2 +- 41 files changed, 116 insertions(+), 219 deletions(-) diff --git a/src/docs/avocado-linux/tools/avocado-cli/commands/build.md b/src/docs/avocado-linux/tools/avocado-cli/commands/build.md index f7e346aa..241e85e0 100644 --- a/src/docs/avocado-linux/tools/avocado-cli/commands/build.md +++ b/src/docs/avocado-linux/tools/avocado-cli/commands/build.md @@ -16,4 +16,4 @@ Options: --sdk-arch SDK container architecture for cross-arch emulation via Docker buildx/QEMU (aarch64 or x86-64) -h, --help Print help -``` +``` \ No newline at end of file diff --git a/src/docs/avocado-linux/tools/avocado-cli/commands/clean.md b/src/docs/avocado-linux/tools/avocado-cli/commands/clean.md index e3d3985e..2c0c11cd 100644 --- a/src/docs/avocado-linux/tools/avocado-cli/commands/clean.md +++ b/src/docs/avocado-linux/tools/avocado-cli/commands/clean.md @@ -32,4 +32,4 @@ Options: -h, --help Print help -``` +``` \ No newline at end of file diff --git a/src/docs/avocado-linux/tools/avocado-cli/commands/deploy.md b/src/docs/avocado-linux/tools/avocado-cli/commands/deploy.md index bf8af1d2..2a1dc9b6 100644 --- a/src/docs/avocado-linux/tools/avocado-cli/commands/deploy.md +++ b/src/docs/avocado-linux/tools/avocado-cli/commands/deploy.md @@ -1,12 +1,14 @@ ``` Deploy a runtime to a device (shortcut for 'runtime deploy') -Usage: avocado deploy [OPTIONS] --runtime --device +Usage: avocado deploy [OPTIONS] --device [NAME] + +Arguments: + [NAME] Runtime name (must be defined in config) Options: -C, --config Path to avocado.yaml configuration file [default: avocado.yaml] -v, --verbose Enable verbose output - -r, --runtime Runtime name to deploy -t, --target Target architecture -d, --device Device to deploy to as [user@]host[:port] (e.g. root@192.168.1.100:2222) --container-arg Additional arguments to pass to the container runtime @@ -16,4 +18,4 @@ Options: --sdk-arch SDK container architecture for cross-arch emulation via Docker buildx/QEMU (aarch64 or x86-64) -h, --help Print help -``` +``` \ No newline at end of file diff --git a/src/docs/avocado-linux/tools/avocado-cli/commands/ext/build.md b/src/docs/avocado-linux/tools/avocado-cli/commands/ext/build.md index 222f2448..997393d5 100644 --- a/src/docs/avocado-linux/tools/avocado-cli/commands/ext/build.md +++ b/src/docs/avocado-linux/tools/avocado-cli/commands/ext/build.md @@ -9,7 +9,6 @@ Arguments: Options: -C, --config Path to avocado.yaml configuration file [default: avocado.yaml] -v, --verbose Enable verbose output - -e, --extension Extension name (alias for positional NAME) -t, --target Target architecture --container-arg Additional arguments to pass to the container runtime --dnf-arg Additional arguments to pass to DNF commands @@ -18,4 +17,4 @@ Options: --sdk-arch SDK container architecture for cross-arch emulation via Docker buildx/QEMU (aarch64 or x86-64) -h, --help Print help -``` +``` \ No newline at end of file diff --git a/src/docs/avocado-linux/tools/avocado-cli/commands/ext/checkout.md b/src/docs/avocado-linux/tools/avocado-cli/commands/ext/checkout.md index 84ce3388..a36185b8 100644 --- a/src/docs/avocado-linux/tools/avocado-cli/commands/ext/checkout.md +++ b/src/docs/avocado-linux/tools/avocado-cli/commands/ext/checkout.md @@ -1,7 +1,7 @@ ``` Check out files from extension sysroot to source directory -Usage: avocado ext checkout [OPTIONS] [NAME] --ext-path --src-path +Usage: avocado ext checkout [OPTIONS] --ext-path --src-path [NAME] Arguments: [NAME] Extension name @@ -11,8 +11,6 @@ Options: Path to avocado.yaml configuration file [default: avocado.yaml] -v, --verbose Enable verbose output - -e, --extension - Extension name (alias for positional NAME) -t, --target Target architecture --ext-path @@ -30,4 +28,4 @@ Options: -h, --help Print help -``` +``` \ No newline at end of file diff --git a/src/docs/avocado-linux/tools/avocado-cli/commands/ext/clean.md b/src/docs/avocado-linux/tools/avocado-cli/commands/ext/clean.md index 2d60f5e6..a4362cdf 100644 --- a/src/docs/avocado-linux/tools/avocado-cli/commands/ext/clean.md +++ b/src/docs/avocado-linux/tools/avocado-cli/commands/ext/clean.md @@ -9,7 +9,6 @@ Arguments: Options: -C, --config Path to avocado.yaml configuration file [default: avocado.yaml] -v, --verbose Enable verbose output - -e, --extension Extension name (alias for positional NAME) -t, --target Target architecture --container-arg Additional arguments to pass to the container runtime --dnf-arg Additional arguments to pass to DNF commands @@ -18,4 +17,4 @@ Options: --sdk-arch SDK container architecture for cross-arch emulation via Docker buildx/QEMU (aarch64 or x86-64) -h, --help Print help -``` +``` \ No newline at end of file diff --git a/src/docs/avocado-linux/tools/avocado-cli/commands/ext/deps.md b/src/docs/avocado-linux/tools/avocado-cli/commands/ext/deps.md index 770ac523..00c32bc2 100644 --- a/src/docs/avocado-linux/tools/avocado-cli/commands/ext/deps.md +++ b/src/docs/avocado-linux/tools/avocado-cli/commands/ext/deps.md @@ -7,12 +7,11 @@ Arguments: [NAME] Extension name (if not provided, shows all extensions) Options: - -C, --config Path to avocado.yaml configuration file [default: avocado.yaml] - -e, --extension Extension name (alias for positional NAME) - -t, --target Target architecture - --runs-on Run command on remote host using local volume via NFS (format: user@host) - --nfs-port NFS port for remote execution (auto-selects from 12050-12099 if not specified) - --sdk-arch SDK container architecture for cross-arch emulation via Docker buildx/QEMU (aarch64 or x86-64) - -h, --help Print help + -C, --config Path to avocado.yaml configuration file [default: avocado.yaml] + -t, --target Target architecture + --runs-on Run command on remote host using local volume via NFS (format: user@host) + --nfs-port NFS port for remote execution (auto-selects from 12050-12099 if not specified) + --sdk-arch SDK container architecture for cross-arch emulation via Docker buildx/QEMU (aarch64 or x86-64) + -h, --help Print help -``` +``` \ No newline at end of file diff --git a/src/docs/avocado-linux/tools/avocado-cli/commands/ext/dnf.md b/src/docs/avocado-linux/tools/avocado-cli/commands/ext/dnf.md index ce456b8e..a9d48228 100644 --- a/src/docs/avocado-linux/tools/avocado-cli/commands/ext/dnf.md +++ b/src/docs/avocado-linux/tools/avocado-cli/commands/ext/dnf.md @@ -18,4 +18,4 @@ Options: --sdk-arch SDK container architecture for cross-arch emulation via Docker buildx/QEMU (aarch64 or x86-64) -h, --help Print help -``` +``` \ No newline at end of file diff --git a/src/docs/avocado-linux/tools/avocado-cli/commands/ext/fetch.md b/src/docs/avocado-linux/tools/avocado-cli/commands/ext/fetch.md index 4c38e148..33447bda 100644 --- a/src/docs/avocado-linux/tools/avocado-cli/commands/ext/fetch.md +++ b/src/docs/avocado-linux/tools/avocado-cli/commands/ext/fetch.md @@ -10,7 +10,6 @@ Options: -C, --config Path to avocado.yaml configuration file [default: avocado.yaml] -v, --verbose Enable verbose output -f, --force Force re-fetch even if already installed - -e, --extension Extension name (alias for positional NAME) -t, --target Target architecture --container-arg Additional arguments to pass to the container runtime --runs-on Run command on remote host using local volume via NFS (format: user@host) @@ -18,4 +17,4 @@ Options: --sdk-arch SDK container architecture for cross-arch emulation via Docker buildx/QEMU (aarch64 or x86-64) -h, --help Print help -``` +``` \ No newline at end of file diff --git a/src/docs/avocado-linux/tools/avocado-cli/commands/ext/install.md b/src/docs/avocado-linux/tools/avocado-cli/commands/ext/install.md index dde7d96f..3164a21d 100644 --- a/src/docs/avocado-linux/tools/avocado-cli/commands/ext/install.md +++ b/src/docs/avocado-linux/tools/avocado-cli/commands/ext/install.md @@ -10,7 +10,6 @@ Options: -C, --config Path to avocado.yaml configuration file [default: avocado.yaml] -v, --verbose Enable verbose output -f, --force Force the operation to proceed, bypassing warnings or confirmation prompts - -e, --extension Extension name (alias for positional NAME) -t, --target Target architecture --container-arg Additional arguments to pass to the container runtime --dnf-arg Additional arguments to pass to DNF commands @@ -19,4 +18,4 @@ Options: --sdk-arch SDK container architecture for cross-arch emulation via Docker buildx/QEMU (aarch64 or x86-64) -h, --help Print help -``` +``` \ No newline at end of file diff --git a/src/docs/avocado-linux/tools/avocado-cli/commands/ext/list.md b/src/docs/avocado-linux/tools/avocado-cli/commands/ext/list.md index 4598fa68..fb6c3d47 100644 --- a/src/docs/avocado-linux/tools/avocado-cli/commands/ext/list.md +++ b/src/docs/avocado-linux/tools/avocado-cli/commands/ext/list.md @@ -11,4 +11,4 @@ Options: --sdk-arch SDK container architecture for cross-arch emulation via Docker buildx/QEMU (aarch64 or x86-64) -h, --help Print help -``` +``` \ No newline at end of file diff --git a/src/docs/avocado-linux/tools/avocado-cli/commands/ext/package.md b/src/docs/avocado-linux/tools/avocado-cli/commands/ext/package.md index a3fe51c0..c4997fa3 100644 --- a/src/docs/avocado-linux/tools/avocado-cli/commands/ext/package.md +++ b/src/docs/avocado-linux/tools/avocado-cli/commands/ext/package.md @@ -9,7 +9,6 @@ Arguments: Options: -C, --config Path to avocado.yaml configuration file [default: avocado.yaml] -v, --verbose Enable verbose output - -e, --extension Extension name (alias for positional NAME) -t, --target Target architecture --out-dir Output directory on host for the RPM package (relative or absolute path). If not specified, RPM stays in container at $AVOCADO_PREFIX/output/extensions --container-arg Additional arguments to pass to the container runtime @@ -19,4 +18,4 @@ Options: --sdk-arch SDK container architecture for cross-arch emulation via Docker buildx/QEMU (aarch64 or x86-64) -h, --help Print help -``` +``` \ No newline at end of file diff --git a/src/docs/avocado-linux/tools/avocado-cli/commands/fetch.md b/src/docs/avocado-linux/tools/avocado-cli/commands/fetch.md index 4bf73b3c..6140c618 100644 --- a/src/docs/avocado-linux/tools/avocado-cli/commands/fetch.md +++ b/src/docs/avocado-linux/tools/avocado-cli/commands/fetch.md @@ -16,4 +16,4 @@ Options: --sdk-arch SDK container architecture for cross-arch emulation via Docker buildx/QEMU (aarch64 or x86-64) -h, --help Print help -``` +``` \ No newline at end of file diff --git a/src/docs/avocado-linux/tools/avocado-cli/commands/hitl/server.md b/src/docs/avocado-linux/tools/avocado-cli/commands/hitl/server.md index 5c8af9b9..5f071976 100644 --- a/src/docs/avocado-linux/tools/avocado-cli/commands/hitl/server.md +++ b/src/docs/avocado-linux/tools/avocado-cli/commands/hitl/server.md @@ -17,4 +17,4 @@ Options: --sdk-arch SDK container architecture for cross-arch emulation via Docker buildx/QEMU (aarch64 or x86-64) -h, --help Print help -``` +``` \ No newline at end of file diff --git a/src/docs/avocado-linux/tools/avocado-cli/commands/init.md b/src/docs/avocado-linux/tools/avocado-cli/commands/init.md index 17a6b98a..c78623ab 100644 --- a/src/docs/avocado-linux/tools/avocado-cli/commands/init.md +++ b/src/docs/avocado-linux/tools/avocado-cli/commands/init.md @@ -26,4 +26,4 @@ Options: -h, --help Print help -``` +``` \ No newline at end of file diff --git a/src/docs/avocado-linux/tools/avocado-cli/commands/install.md b/src/docs/avocado-linux/tools/avocado-cli/commands/install.md index 923c8f85..ed78a92b 100644 --- a/src/docs/avocado-linux/tools/avocado-cli/commands/install.md +++ b/src/docs/avocado-linux/tools/avocado-cli/commands/install.md @@ -1,28 +1,57 @@ ``` Install all components, or add specific packages to an extension/runtime/SDK -Without packages: syncs all sysroots with avocado.yaml (installs missing, removes extraneous). -With packages: adds them to the specified scope and writes to avocado.yaml. +Without packages: syncs all sysroots with avocado.yaml (installs missing, removes extraneous). With packages: adds them to the specified scope and writes to avocado.yaml. Usage: avocado install [OPTIONS] [PACKAGES]... Arguments: - [PACKAGES]... Packages to install (when provided, adds to config and installs into the specified scope) + [PACKAGES]... + Packages to install (when provided, adds to config and installs into the specified scope) Options: - -C, --config Path to avocado.yaml configuration file [default: avocado.yaml] - -v, --verbose Enable verbose output - -f, --force Force the operation to proceed, bypassing warnings or confirmation prompts - -e, --extension Extension to install packages into (required when adding packages) - -r, --runtime Runtime name to install packages into (or sync when no packages given) - --sdk Install packages into the SDK - --no-save Skip writing packages to avocado.yaml - -t, --target Target architecture - --container-arg Additional arguments to pass to the container runtime - --dnf-arg Additional arguments to pass to DNF commands - --runs-on Run command on remote host using local volume via NFS (format: user@host) - --nfs-port NFS port for remote execution (auto-selects from 12050-12099 if not specified) - --sdk-arch SDK container architecture for cross-arch emulation via Docker buildx/QEMU (aarch64 or x86-64) - -h, --help Print help + -e, --extension + Extension to install packages into (required when adding packages) -``` + -C, --config + Path to avocado.yaml configuration file + + [default: avocado.yaml] + + -v, --verbose + Enable verbose output + + -f, --force + Force the operation to proceed, bypassing warnings or confirmation prompts + + -r, --runtime + Runtime name to install packages into (or sync when no packages given) + + --sdk + Install packages into the SDK + + --no-save + Skip writing packages to avocado.yaml + + -t, --target + Target architecture + + --container-arg + Additional arguments to pass to the container runtime + + --dnf-arg + Additional arguments to pass to DNF commands + + --runs-on + Run command on remote host using local volume via NFS (format: user@host) + + --nfs-port + NFS port for remote execution (auto-selects from 12050-12099 if not specified) + + --sdk-arch + SDK container architecture for cross-arch emulation via Docker buildx/QEMU (aarch64 or x86-64) + + -h, --help + Print help (see a summary with '-h') + +``` \ No newline at end of file diff --git a/src/docs/avocado-linux/tools/avocado-cli/commands/provision.md b/src/docs/avocado-linux/tools/avocado-cli/commands/provision.md index ae0ea4cd..eb2ca354 100644 --- a/src/docs/avocado-linux/tools/avocado-cli/commands/provision.md +++ b/src/docs/avocado-linux/tools/avocado-cli/commands/provision.md @@ -1,13 +1,15 @@ ``` Provision a runtime (shortcut for 'runtime provision') -Usage: avocado provision [OPTIONS] --runtime +Usage: avocado provision [OPTIONS] [NAME] + +Arguments: + [NAME] Runtime name (must be defined in config) Options: -C, --config Path to avocado.yaml configuration file [default: avocado.yaml] -v, --verbose Enable verbose output -f, --force Force the operation to proceed, bypassing warnings or confirmation prompts - -r, --runtime Runtime name to provision -t, --target Target architecture --profile Provision profile to use --env Environment variables to pass to the provision process @@ -19,4 +21,4 @@ Options: --sdk-arch SDK container architecture for cross-arch emulation via Docker buildx/QEMU (aarch64 or x86-64) -h, --help Print help -``` +``` \ No newline at end of file diff --git a/src/docs/avocado-linux/tools/avocado-cli/commands/prune.md b/src/docs/avocado-linux/tools/avocado-cli/commands/prune.md index b08ba2db..d2b8ce72 100644 --- a/src/docs/avocado-linux/tools/avocado-cli/commands/prune.md +++ b/src/docs/avocado-linux/tools/avocado-cli/commands/prune.md @@ -19,4 +19,4 @@ Options: -h, --help Print help -``` +``` \ No newline at end of file diff --git a/src/docs/avocado-linux/tools/avocado-cli/commands/runtime/build.md b/src/docs/avocado-linux/tools/avocado-cli/commands/runtime/build.md index af2a9b6a..e1e5f7ed 100644 --- a/src/docs/avocado-linux/tools/avocado-cli/commands/runtime/build.md +++ b/src/docs/avocado-linux/tools/avocado-cli/commands/runtime/build.md @@ -10,7 +10,6 @@ Options: -C, --config Path to avocado.yaml configuration file [default: avocado.yaml] -v, --verbose Enable verbose output -f, --force Force the operation to proceed, bypassing warnings or confirmation prompts - -r, --runtime Runtime name (alias for positional NAME) -t, --target Target architecture --container-arg Additional arguments to pass to the container runtime --dnf-arg Additional arguments to pass to DNF commands @@ -19,4 +18,4 @@ Options: --sdk-arch SDK container architecture for cross-arch emulation via Docker buildx/QEMU (aarch64 or x86-64) -h, --help Print help -``` +``` \ No newline at end of file diff --git a/src/docs/avocado-linux/tools/avocado-cli/commands/runtime/clean.md b/src/docs/avocado-linux/tools/avocado-cli/commands/runtime/clean.md index 0f2c0e5c..b790ad64 100644 --- a/src/docs/avocado-linux/tools/avocado-cli/commands/runtime/clean.md +++ b/src/docs/avocado-linux/tools/avocado-cli/commands/runtime/clean.md @@ -9,7 +9,6 @@ Arguments: Options: -C, --config Path to avocado.yaml configuration file [default: avocado.yaml] -v, --verbose Enable verbose output - -r, --runtime Runtime name (alias for positional NAME) -t, --target Target architecture --container-arg Additional arguments to pass to the container runtime --dnf-arg Additional arguments to pass to DNF commands @@ -18,4 +17,4 @@ Options: --sdk-arch SDK container architecture for cross-arch emulation via Docker buildx/QEMU (aarch64 or x86-64) -h, --help Print help -``` +``` \ No newline at end of file diff --git a/src/docs/avocado-linux/tools/avocado-cli/commands/runtime/deploy.md b/src/docs/avocado-linux/tools/avocado-cli/commands/runtime/deploy.md index a9547298..fbc8b108 100644 --- a/src/docs/avocado-linux/tools/avocado-cli/commands/runtime/deploy.md +++ b/src/docs/avocado-linux/tools/avocado-cli/commands/runtime/deploy.md @@ -1,7 +1,7 @@ ``` Deploy a runtime to a device -Usage: avocado runtime deploy [OPTIONS] [NAME] --device +Usage: avocado runtime deploy [OPTIONS] --device [NAME] Arguments: [NAME] Runtime name @@ -9,9 +9,8 @@ Arguments: Options: -C, --config Path to avocado.yaml configuration file [default: avocado.yaml] -v, --verbose Enable verbose output - -r, --runtime Runtime name (alias for positional NAME) -t, --target Target architecture - -d, --device Device IP address or hostname to deploy to + -d, --device Device to deploy to as [user@]host[:port] (e.g. root@192.168.1.100:2222) --container-arg Additional arguments to pass to the container runtime --dnf-arg Additional arguments to pass to DNF commands --runs-on Run command on remote host using local volume via NFS (format: user@host) @@ -19,4 +18,4 @@ Options: --sdk-arch SDK container architecture for cross-arch emulation via Docker buildx/QEMU (aarch64 or x86-64) -h, --help Print help -``` +``` \ No newline at end of file diff --git a/src/docs/avocado-linux/tools/avocado-cli/commands/runtime/deps.md b/src/docs/avocado-linux/tools/avocado-cli/commands/runtime/deps.md index 3f7f01fe..0e477185 100644 --- a/src/docs/avocado-linux/tools/avocado-cli/commands/runtime/deps.md +++ b/src/docs/avocado-linux/tools/avocado-cli/commands/runtime/deps.md @@ -8,11 +8,10 @@ Arguments: Options: -C, --config Path to avocado.yaml configuration file [default: avocado.yaml] - -r, --runtime Runtime name (alias for positional NAME) -t, --target Target architecture --runs-on Run command on remote host using local volume via NFS (format: user@host) --nfs-port NFS port for remote execution (auto-selects from 12050-12099 if not specified) --sdk-arch SDK container architecture for cross-arch emulation via Docker buildx/QEMU (aarch64 or x86-64) -h, --help Print help -``` +``` \ No newline at end of file diff --git a/src/docs/avocado-linux/tools/avocado-cli/commands/runtime/dnf.md b/src/docs/avocado-linux/tools/avocado-cli/commands/runtime/dnf.md index 6241b8bb..1e7b6668 100644 --- a/src/docs/avocado-linux/tools/avocado-cli/commands/runtime/dnf.md +++ b/src/docs/avocado-linux/tools/avocado-cli/commands/runtime/dnf.md @@ -18,4 +18,4 @@ Options: --sdk-arch SDK container architecture for cross-arch emulation via Docker buildx/QEMU (aarch64 or x86-64) -h, --help Print help -``` +``` \ No newline at end of file diff --git a/src/docs/avocado-linux/tools/avocado-cli/commands/runtime/install.md b/src/docs/avocado-linux/tools/avocado-cli/commands/runtime/install.md index 89943502..d8711806 100644 --- a/src/docs/avocado-linux/tools/avocado-cli/commands/runtime/install.md +++ b/src/docs/avocado-linux/tools/avocado-cli/commands/runtime/install.md @@ -10,7 +10,6 @@ Options: -C, --config Path to avocado.yaml configuration file [default: avocado.yaml] -v, --verbose Enable verbose output -f, --force Force the operation to proceed, bypassing warnings or confirmation prompts - -r, --runtime Runtime name (alias for positional NAME) -t, --target Target architecture --container-arg Additional arguments to pass to the container runtime --dnf-arg Additional arguments to pass to DNF commands @@ -19,4 +18,4 @@ Options: --sdk-arch SDK container architecture for cross-arch emulation via Docker buildx/QEMU (aarch64 or x86-64) -h, --help Print help -``` +``` \ No newline at end of file diff --git a/src/docs/avocado-linux/tools/avocado-cli/commands/runtime/list.md b/src/docs/avocado-linux/tools/avocado-cli/commands/runtime/list.md index 67c87811..4bb4cafb 100644 --- a/src/docs/avocado-linux/tools/avocado-cli/commands/runtime/list.md +++ b/src/docs/avocado-linux/tools/avocado-cli/commands/runtime/list.md @@ -11,4 +11,4 @@ Options: --sdk-arch SDK container architecture for cross-arch emulation via Docker buildx/QEMU (aarch64 or x86-64) -h, --help Print help -``` +``` \ No newline at end of file diff --git a/src/docs/avocado-linux/tools/avocado-cli/commands/runtime/provision.md b/src/docs/avocado-linux/tools/avocado-cli/commands/runtime/provision.md index 316f945f..9b986f5b 100644 --- a/src/docs/avocado-linux/tools/avocado-cli/commands/runtime/provision.md +++ b/src/docs/avocado-linux/tools/avocado-cli/commands/runtime/provision.md @@ -10,7 +10,6 @@ Options: -C, --config Path to avocado.yaml configuration file [default: avocado.yaml] -v, --verbose Enable verbose output -f, --force Force the operation to proceed, bypassing warnings or confirmation prompts - -r, --runtime Runtime name (alias for positional NAME) -t, --target Target architecture --profile Provision profile to use --env Environment variables to pass to the provision process @@ -22,4 +21,4 @@ Options: --sdk-arch SDK container architecture for cross-arch emulation via Docker buildx/QEMU (aarch64 or x86-64) -h, --help Print help -``` +``` \ No newline at end of file diff --git a/src/docs/avocado-linux/tools/avocado-cli/commands/runtime/sign.md b/src/docs/avocado-linux/tools/avocado-cli/commands/runtime/sign.md index 8ea44190..4bbb634b 100644 --- a/src/docs/avocado-linux/tools/avocado-cli/commands/runtime/sign.md +++ b/src/docs/avocado-linux/tools/avocado-cli/commands/runtime/sign.md @@ -9,7 +9,6 @@ Arguments: Options: -C, --config Path to avocado.yaml configuration file [default: avocado.yaml] -v, --verbose Enable verbose output - -r, --runtime Runtime name (alias for positional NAME) -t, --target Target architecture --container-arg Additional arguments to pass to the container runtime --dnf-arg Additional arguments to pass to DNF commands @@ -18,4 +17,4 @@ Options: --sdk-arch SDK container architecture for cross-arch emulation via Docker buildx/QEMU (aarch64 or x86-64) -h, --help Print help -``` +``` \ No newline at end of file diff --git a/src/docs/avocado-linux/tools/avocado-cli/commands/sdk/clean.md b/src/docs/avocado-linux/tools/avocado-cli/commands/sdk/clean.md index 5939886c..2b10d0c0 100644 --- a/src/docs/avocado-linux/tools/avocado-cli/commands/sdk/clean.md +++ b/src/docs/avocado-linux/tools/avocado-cli/commands/sdk/clean.md @@ -17,4 +17,4 @@ Options: --sdk-arch SDK container architecture for cross-arch emulation via Docker buildx/QEMU (aarch64 or x86-64) -h, --help Print help -``` +``` \ No newline at end of file diff --git a/src/docs/avocado-linux/tools/avocado-cli/commands/sdk/compile.md b/src/docs/avocado-linux/tools/avocado-cli/commands/sdk/compile.md index 4f7a2168..2bfbe940 100644 --- a/src/docs/avocado-linux/tools/avocado-cli/commands/sdk/compile.md +++ b/src/docs/avocado-linux/tools/avocado-cli/commands/sdk/compile.md @@ -17,4 +17,4 @@ Options: --sdk-arch SDK container architecture for cross-arch emulation via Docker buildx/QEMU (aarch64 or x86-64) -h, --help Print help -``` +``` \ No newline at end of file diff --git a/src/docs/avocado-linux/tools/avocado-cli/commands/sdk/deps.md b/src/docs/avocado-linux/tools/avocado-cli/commands/sdk/deps.md index 96efde7d..d2dc0bb2 100644 --- a/src/docs/avocado-linux/tools/avocado-cli/commands/sdk/deps.md +++ b/src/docs/avocado-linux/tools/avocado-cli/commands/sdk/deps.md @@ -13,4 +13,4 @@ Options: --sdk-arch SDK container architecture for cross-arch emulation via Docker buildx/QEMU (aarch64 or x86-64) -h, --help Print help -``` +``` \ No newline at end of file diff --git a/src/docs/avocado-linux/tools/avocado-cli/commands/sdk/dnf.md b/src/docs/avocado-linux/tools/avocado-cli/commands/sdk/dnf.md index 4586956d..62222b96 100644 --- a/src/docs/avocado-linux/tools/avocado-cli/commands/sdk/dnf.md +++ b/src/docs/avocado-linux/tools/avocado-cli/commands/sdk/dnf.md @@ -17,4 +17,4 @@ Options: --sdk-arch SDK container architecture for cross-arch emulation via Docker buildx/QEMU (aarch64 or x86-64) -h, --help Print help -``` +``` \ No newline at end of file diff --git a/src/docs/avocado-linux/tools/avocado-cli/commands/sdk/install.md b/src/docs/avocado-linux/tools/avocado-cli/commands/sdk/install.md index bb7329d9..646969f1 100644 --- a/src/docs/avocado-linux/tools/avocado-cli/commands/sdk/install.md +++ b/src/docs/avocado-linux/tools/avocado-cli/commands/sdk/install.md @@ -15,4 +15,4 @@ Options: --sdk-arch SDK container architecture for cross-arch emulation via Docker buildx/QEMU (aarch64 or x86-64) -h, --help Print help -``` +``` \ No newline at end of file diff --git a/src/docs/avocado-linux/tools/avocado-cli/commands/sdk/package.md b/src/docs/avocado-linux/tools/avocado-cli/commands/sdk/package.md index 3603adb7..cc786d47 100644 --- a/src/docs/avocado-linux/tools/avocado-cli/commands/sdk/package.md +++ b/src/docs/avocado-linux/tools/avocado-cli/commands/sdk/package.md @@ -4,141 +4,18 @@ Package a compiled SDK section into an RPM Usage: avocado sdk package [OPTIONS]
Arguments: -
Compile section to package (must have a 'package' block in sdk.compile.
) +
Compile section to package (must have a 'package' block in config) Options: -C, --config Path to avocado.yaml configuration file [default: avocado.yaml] -v, --verbose Enable verbose output -t, --target Target architecture - --out Output directory on host for the built RPM(s). If not specified, RPMs stay in the SDK container + --out Output directory on host for the built RPM(s) --container-arg Additional arguments to pass to the container runtime --dnf-arg Additional arguments to pass to DNF commands + --runs-on Run command on remote host using local volume via NFS (format: user@host) + --nfs-port NFS port for remote execution (auto-selects from 12050-12099 if not specified) --sdk-arch SDK container architecture for cross-arch emulation via Docker buildx/QEMU (aarch64 or x86-64) -h, --help Print help -``` - -## Overview - -`avocado sdk package` packages the output of a compiled SDK section into one or more architecture-specific RPM files. The compile section must have a `package` block in your `avocado.yaml`. - -## Configuration - -Add a `package` block to any `sdk.compile` section: - -```yaml -sdk: - compile: - my-lib: - compile: compile.sh - clean: clean.sh - packages: - openssl-dev: '*' - package: - name: my-lib # defaults to section name - version: '1.2.3' # required, semver - release: '1' # defaults to '1' - install: pkg-install.sh # required, script that stages files to $DESTDIR - summary: 'My shared library' - description: 'A cross-compiled shared library.' - license: MIT - vendor: Acme Corp - url: https://example.com/my-lib - requires: - - openssl >= 3.0 -``` - -### `package` block fields - -| Field | Required | Description | -| ------------- | -------- | ------------------------------------------------------------------------------------ | -| `version` | Yes | RPM version in semver format (e.g., `1.2.3`) | -| `install` | Yes | Path (relative to `src_dir`) to a script that stages files to `$DESTDIR` | -| `name` | No | RPM package name; defaults to the compile section name | -| `release` | No | RPM release string; defaults to `1` | -| `summary` | No | One-line RPM summary; auto-generated from name if omitted | -| `description` | No | Multi-line RPM description; auto-generated from name if omitted | -| `license` | No | License identifier (e.g., `MIT`, `Apache-2.0`); defaults to `Unspecified` | -| `vendor` | No | RPM vendor field; defaults to `Unspecified` | -| `url` | No | Upstream URL for the packaged software | -| `requires` | No | List of RPM dependency strings (e.g., `openssl >= 3.0`) | -| `files` | No | Glob patterns for files to include in the main package (all staged files if omitted) | -| `split` | No | Map of sub-package names to sub-package configs (see below) | - -### Sub-package splitting - -Use `split` to create multiple RPMs from a single install — for example, separating runtime libraries from development headers: - -```yaml -sdk: - compile: - my-lib: - compile: compile.sh - packages: - openssl-dev: '*' - package: - version: '2.0.0' - install: pkg-install.sh - # Main package gets everything not claimed by split packages - split: - my-lib-dev: - summary: 'Development headers for my-lib' - description: 'Headers and static libraries for building against my-lib.' - requires: - - my-lib = 2.0.0 - files: - - usr/include/** - - usr/lib/*.a - - usr/lib/*.la - my-lib-doc: - summary: 'Documentation for my-lib' - files: - - usr/share/doc/** - - usr/share/man/** -``` - -Sub-package fields: - -| Field | Description | -| ------------- | ----------------------------------------------------------------------------- | -| `summary` | One-line summary for the sub-package | -| `description` | Multi-line description | -| `requires` | RPM dependencies for the sub-package | -| `files` | Glob patterns for files included in this sub-package (relative to `$DESTDIR`) | - -Files not matched by any `split.*.files` pattern are included in the main package. - -### Install script - -The install script is responsible for staging files to `$DESTDIR`. Avocado sets `$DESTDIR` before running the script: - -```bash -#!/usr/bin/env bash -set -e - -# Files must be installed relative to $DESTDIR -install -D -m 755 my-lib/target/release/libmy.so "$DESTDIR/usr/lib/libmy.so.2.0.0" -ln -sf libmy.so.2.0.0 "$DESTDIR/usr/lib/libmy.so.2" -ln -sf libmy.so.2 "$DESTDIR/usr/lib/libmy.so" - -install -D -m 644 my-lib/include/my.h "$DESTDIR/usr/include/my.h" -``` - -## Usage - -```bash -# Package the section (RPM stays in SDK container) -avocado sdk package my-lib - -# Package and copy RPM(s) to ./dist/ -avocado sdk package my-lib --out ./dist/ - -# Package for a specific target -avocado sdk package my-lib --target qemux86-64 --out ./dist/ -``` - -## Notes - -- Run `avocado sdk compile my-lib` (or `avocado build`) before packaging to ensure the compile output is up to date. -- The RPM architecture is derived from the target (e.g., `aarch64`, `x86_64`). Override with `package.arch` if needed. -- When `--out` is specified, all generated RPMs (main + split packages) are copied to that directory. +``` \ No newline at end of file diff --git a/src/docs/avocado-linux/tools/avocado-cli/commands/sdk/run.md b/src/docs/avocado-linux/tools/avocado-cli/commands/sdk/run.md index a15604da..96347b13 100644 --- a/src/docs/avocado-linux/tools/avocado-cli/commands/sdk/run.md +++ b/src/docs/avocado-linux/tools/avocado-cli/commands/sdk/run.md @@ -25,4 +25,4 @@ Options: --sdk-arch SDK container architecture for cross-arch emulation via Docker buildx/QEMU (aarch64 or x86-64) -h, --help Print help -``` +``` \ No newline at end of file diff --git a/src/docs/avocado-linux/tools/avocado-cli/commands/sign.md b/src/docs/avocado-linux/tools/avocado-cli/commands/sign.md index dcc71b27..c99dc363 100644 --- a/src/docs/avocado-linux/tools/avocado-cli/commands/sign.md +++ b/src/docs/avocado-linux/tools/avocado-cli/commands/sign.md @@ -1,12 +1,14 @@ ``` Sign runtime images (shortcut for 'runtime sign') -Usage: avocado sign [OPTIONS] +Usage: avocado sign [OPTIONS] [NAME] + +Arguments: + [NAME] Runtime name to sign (if not provided, signs all runtimes with signing config) Options: -C, --config Path to avocado.yaml configuration file [default: avocado.yaml] -v, --verbose Enable verbose output - -r, --runtime Runtime name to sign (if not provided, signs all runtimes with signing config) -t, --target Target architecture --container-arg Additional arguments to pass to the container runtime --dnf-arg Additional arguments to pass to DNF commands @@ -15,4 +17,4 @@ Options: --sdk-arch SDK container architecture for cross-arch emulation via Docker buildx/QEMU (aarch64 or x86-64) -h, --help Print help -``` +``` \ No newline at end of file diff --git a/src/docs/avocado-linux/tools/avocado-cli/commands/signing-keys/create.md b/src/docs/avocado-linux/tools/avocado-cli/commands/signing-keys/create.md index 1f08d044..6b0309d5 100644 --- a/src/docs/avocado-linux/tools/avocado-cli/commands/signing-keys/create.md +++ b/src/docs/avocado-linux/tools/avocado-cli/commands/signing-keys/create.md @@ -18,4 +18,4 @@ Options: --sdk-arch SDK container architecture for cross-arch emulation via Docker buildx/QEMU (aarch64 or x86-64) -h, --help Print help -``` +``` \ No newline at end of file diff --git a/src/docs/avocado-linux/tools/avocado-cli/commands/signing-keys/list.md b/src/docs/avocado-linux/tools/avocado-cli/commands/signing-keys/list.md index caa1c436..a3d85303 100644 --- a/src/docs/avocado-linux/tools/avocado-cli/commands/signing-keys/list.md +++ b/src/docs/avocado-linux/tools/avocado-cli/commands/signing-keys/list.md @@ -9,4 +9,4 @@ Options: --sdk-arch SDK container architecture for cross-arch emulation via Docker buildx/QEMU (aarch64 or x86-64) -h, --help Print help -``` +``` \ No newline at end of file diff --git a/src/docs/avocado-linux/tools/avocado-cli/commands/signing-keys/remove.md b/src/docs/avocado-linux/tools/avocado-cli/commands/signing-keys/remove.md index 0c85b7ae..c6ff42ef 100644 --- a/src/docs/avocado-linux/tools/avocado-cli/commands/signing-keys/remove.md +++ b/src/docs/avocado-linux/tools/avocado-cli/commands/signing-keys/remove.md @@ -13,4 +13,4 @@ Options: --sdk-arch SDK container architecture for cross-arch emulation via Docker buildx/QEMU (aarch64 or x86-64) -h, --help Print help -``` +``` \ No newline at end of file diff --git a/src/docs/avocado-linux/tools/avocado-cli/commands/uninstall.md b/src/docs/avocado-linux/tools/avocado-cli/commands/uninstall.md index a0e5e9fe..f8188792 100644 --- a/src/docs/avocado-linux/tools/avocado-cli/commands/uninstall.md +++ b/src/docs/avocado-linux/tools/avocado-cli/commands/uninstall.md @@ -4,15 +4,15 @@ Remove packages from an extension, runtime, or SDK and update avocado.yaml Usage: avocado uninstall [OPTIONS] ... Arguments: - ... Packages to remove + ... Packages to remove Options: - -C, --config Path to avocado.yaml configuration file [default: avocado.yaml] - -v, --verbose Enable verbose output - -f, --force Force the operation to proceed, bypassing warnings or confirmation prompts -e, --extension Extension to remove packages from -r, --runtime Runtime to remove packages from --sdk Remove packages from the SDK + -C, --config Path to avocado.yaml configuration file [default: avocado.yaml] + -v, --verbose Enable verbose output + -f, --force Force the operation to proceed, bypassing warnings or confirmation prompts -t, --target Target architecture --container-arg Additional arguments to pass to the container runtime --dnf-arg Additional arguments to pass to DNF commands @@ -21,4 +21,4 @@ Options: --sdk-arch SDK container architecture for cross-arch emulation via Docker buildx/QEMU (aarch64 or x86-64) -h, --help Print help -``` +``` \ No newline at end of file diff --git a/src/docs/avocado-linux/tools/avocado-cli/commands/unlock.md b/src/docs/avocado-linux/tools/avocado-cli/commands/unlock.md index cc709f8f..3e3ec566 100644 --- a/src/docs/avocado-linux/tools/avocado-cli/commands/unlock.md +++ b/src/docs/avocado-linux/tools/avocado-cli/commands/unlock.md @@ -15,4 +15,4 @@ Options: --sdk-arch SDK container architecture for cross-arch emulation via Docker buildx/QEMU (aarch64 or x86-64) -h, --help Print help -``` +``` \ No newline at end of file diff --git a/src/docs/avocado-linux/tools/avocado-cli/commands/upgrade.md b/src/docs/avocado-linux/tools/avocado-cli/commands/upgrade.md index 54537612..fb8bea80 100644 --- a/src/docs/avocado-linux/tools/avocado-cli/commands/upgrade.md +++ b/src/docs/avocado-linux/tools/avocado-cli/commands/upgrade.md @@ -10,4 +10,4 @@ Options: --sdk-arch SDK container architecture for cross-arch emulation via Docker buildx/QEMU (aarch64 or x86-64) -h, --help Print help -``` +``` \ No newline at end of file From 6300d4a5be837abeab2501306b14b4d400098844 Mon Sep 17 00:00:00 2001 From: Justin Schneck Date: Fri, 13 Mar 2026 19:17:45 -0400 Subject: [PATCH 8/8] fix: format all docs with prettier to pass CI lint check --- .../avocado-linux/references/extensions.md | 20 +-- .../tools/avocado-cli/commands/build.md | 2 +- .../tools/avocado-cli/commands/clean.md | 2 +- .../commands/connect/auth/login.md | 2 +- .../commands/connect/auth/logout.md | 2 +- .../commands/connect/auth/status.md | 2 +- .../commands/connect/claim-tokens/create.md | 2 +- .../commands/connect/claim-tokens/delete.md | 2 +- .../commands/connect/claim-tokens/list.md | 2 +- .../commands/connect/cohorts/create.md | 2 +- .../commands/connect/cohorts/delete.md | 2 +- .../commands/connect/cohorts/list.md | 2 +- .../commands/connect/devices/create.md | 2 +- .../commands/connect/devices/delete.md | 2 +- .../commands/connect/devices/list.md | 2 +- .../avocado-cli/commands/connect/init.md | 2 +- .../commands/connect/keys/approve.md | 2 +- .../avocado-cli/commands/connect/keys/list.md | 2 +- .../commands/connect/keys/register.md | 2 +- .../commands/connect/keys/retire.md | 2 +- .../avocado-cli/commands/connect/orgs/list.md | 2 +- .../commands/connect/projects/create.md | 2 +- .../commands/connect/projects/delete.md | 2 +- .../commands/connect/projects/list.md | 2 +- .../commands/connect/server-key.md | 2 +- .../commands/connect/trust/promote-root.md | 2 +- .../connect/trust/rotate-server-key.md | 2 +- .../commands/connect/trust/status.md | 2 +- .../avocado-cli/commands/connect/upload.md | 2 +- .../tools/avocado-cli/commands/deploy.md | 2 +- .../tools/avocado-cli/commands/ext/build.md | 2 +- .../avocado-cli/commands/ext/checkout.md | 2 +- .../tools/avocado-cli/commands/ext/clean.md | 2 +- .../tools/avocado-cli/commands/ext/deps.md | 2 +- .../tools/avocado-cli/commands/ext/dnf.md | 2 +- .../tools/avocado-cli/commands/ext/fetch.md | 2 +- .../tools/avocado-cli/commands/ext/image.md | 2 +- .../tools/avocado-cli/commands/ext/install.md | 2 +- .../tools/avocado-cli/commands/ext/list.md | 2 +- .../tools/avocado-cli/commands/ext/package.md | 2 +- .../tools/avocado-cli/commands/fetch.md | 2 +- .../tools/avocado-cli/commands/hitl/server.md | 2 +- .../tools/avocado-cli/commands/init.md | 2 +- .../avocado-cli/commands/initramfs/clean.md | 2 +- .../avocado-cli/commands/initramfs/image.md | 2 +- .../avocado-cli/commands/initramfs/install.md | 2 +- .../tools/avocado-cli/commands/install.md | 4 +- .../tools/avocado-cli/commands/provision.md | 2 +- .../tools/avocado-cli/commands/prune.md | 2 +- .../avocado-cli/commands/rootfs/clean.md | 2 +- .../avocado-cli/commands/rootfs/image.md | 2 +- .../avocado-cli/commands/rootfs/install.md | 2 +- .../avocado-cli/commands/runtime/build.md | 2 +- .../avocado-cli/commands/runtime/clean.md | 2 +- .../avocado-cli/commands/runtime/deploy.md | 2 +- .../avocado-cli/commands/runtime/deps.md | 2 +- .../tools/avocado-cli/commands/runtime/dnf.md | 2 +- .../avocado-cli/commands/runtime/install.md | 2 +- .../avocado-cli/commands/runtime/list.md | 2 +- .../avocado-cli/commands/runtime/provision.md | 2 +- .../avocado-cli/commands/runtime/sign.md | 2 +- .../tools/avocado-cli/commands/sdk/clean.md | 2 +- .../tools/avocado-cli/commands/sdk/compile.md | 2 +- .../tools/avocado-cli/commands/sdk/deps.md | 2 +- .../tools/avocado-cli/commands/sdk/dnf.md | 2 +- .../tools/avocado-cli/commands/sdk/install.md | 2 +- .../tools/avocado-cli/commands/sdk/package.md | 2 +- .../tools/avocado-cli/commands/sdk/run.md | 2 +- .../tools/avocado-cli/commands/sign.md | 2 +- .../commands/signing-keys/create.md | 2 +- .../avocado-cli/commands/signing-keys/list.md | 2 +- .../commands/signing-keys/remove.md | 2 +- .../tools/avocado-cli/commands/uninstall.md | 2 +- .../tools/avocado-cli/commands/unlock.md | 2 +- .../tools/avocado-cli/commands/upgrade.md | 2 +- .../tools/avocadoctl/commands/disable.md | 10 +- .../tools/avocadoctl/commands/enable.md | 8 +- .../tools/avocadoctl/commands/ext/unmerge.md | 4 +- .../tools/avocadoctl/commands/hitl/mount.md | 10 +- .../tools/avocadoctl/commands/hitl/unmount.md | 4 +- .../avocadoctl/commands/runtime/activate.md | 6 +- .../tools/avocadoctl/commands/runtime/add.md | 6 +- .../avocadoctl/commands/runtime/inspect.md | 6 +- .../avocadoctl/commands/runtime/remove.md | 6 +- .../tools/avocadoctl/commands/serve.md | 4 +- .../tools/avocadoctl/commands/status.md | 12 +- .../tools/avocadoctl/commands/unmerge.md | 4 +- .../tools/avocadoctl/configuration.md | 48 +++---- .../avocadoctl/os-bundles/bundle-format.md | 80 +++++------ .../tools/avocadoctl/overview.md | 12 +- .../runtime-management/manifest-spec.md | 42 +++--- .../varlink-api/org-avocado-extensions.md | 126 +++++++++--------- .../varlink-api/org-avocado-hitl.md | 26 ++-- .../varlink-api/org-avocado-root-authority.md | 30 ++--- .../varlink-api/org-avocado-runtimes.md | 122 ++++++++--------- .../tools/avocadoctl/varlink-api/overview.md | 12 +- 96 files changed, 374 insertions(+), 374 deletions(-) diff --git a/src/docs/avocado-linux/references/extensions.md b/src/docs/avocado-linux/references/extensions.md index ca232bac..7c48ef43 100644 --- a/src/docs/avocado-linux/references/extensions.md +++ b/src/docs/avocado-linux/references/extensions.md @@ -781,13 +781,13 @@ You can add additional packages to customize the base system and configure the i ```yaml rootfs: - filesystem: erofs.lz4 # default + filesystem: erofs.lz4 # default packages: avocado-pkg-rootfs: '*' my-custom-base-package: '*' initramfs: - filesystem: cpio.zst # default + filesystem: cpio.zst # default packages: avocado-pkg-initramfs: '*' ``` @@ -811,19 +811,19 @@ The `filesystem` property controls the image format and compression algorithm us **Rootfs formats:** -| Value | Description | -| ----------- | ---------------------------------------------------------------- | +| Value | Description | +| ----------- | ------------------------------------------------------------------------------ | | `erofs.lz4` | EROFS with LZ4 compression (default). Fast decompression, good for boot speed. | -| `erofs.zst` | EROFS with Zstandard compression. Better compression ratio. | +| `erofs.zst` | EROFS with Zstandard compression. Better compression ratio. | **Initramfs formats:** -| Value | Description | -| ---------- | ---------------------------------------------------------------- | +| Value | Description | +| ---------- | ------------------------------------------------------------------------------- | | `cpio.zst` | CPIO archive with Zstandard compression (default). Requires `CONFIG_RD_ZSTD=y`. | -| `cpio.lz4` | CPIO archive with LZ4 compression. Requires `CONFIG_RD_LZ4=y`. | -| `cpio.gz` | CPIO archive with gzip compression. Widest kernel support. | -| `cpio` | Uncompressed CPIO archive. No kernel decompression config required. | +| `cpio.lz4` | CPIO archive with LZ4 compression. Requires `CONFIG_RD_LZ4=y`. | +| `cpio.gz` | CPIO archive with gzip compression. Widest kernel support. | +| `cpio` | Uncompressed CPIO archive. No kernel decompression config required. | :::tip Compressed formats require kernel decompression support built in. For example, `erofs.zst` requires `CONFIG_EROFS_FS_ZIP_ZSTD=y` and `cpio.zst` requires `CONFIG_RD_ZSTD=y`. BSP extensions can set the filesystem format per-platform to match the kernel's decompression capabilities. See the [custom kernel guide](../guides/custom-kernel) for kernel configuration details. diff --git a/src/docs/avocado-linux/tools/avocado-cli/commands/build.md b/src/docs/avocado-linux/tools/avocado-cli/commands/build.md index 241e85e0..f7e346aa 100644 --- a/src/docs/avocado-linux/tools/avocado-cli/commands/build.md +++ b/src/docs/avocado-linux/tools/avocado-cli/commands/build.md @@ -16,4 +16,4 @@ Options: --sdk-arch SDK container architecture for cross-arch emulation via Docker buildx/QEMU (aarch64 or x86-64) -h, --help Print help -``` \ No newline at end of file +``` diff --git a/src/docs/avocado-linux/tools/avocado-cli/commands/clean.md b/src/docs/avocado-linux/tools/avocado-cli/commands/clean.md index 2c0c11cd..e3d3985e 100644 --- a/src/docs/avocado-linux/tools/avocado-cli/commands/clean.md +++ b/src/docs/avocado-linux/tools/avocado-cli/commands/clean.md @@ -32,4 +32,4 @@ Options: -h, --help Print help -``` \ No newline at end of file +``` diff --git a/src/docs/avocado-linux/tools/avocado-cli/commands/connect/auth/login.md b/src/docs/avocado-linux/tools/avocado-cli/commands/connect/auth/login.md index 7bf882a8..124cc0b1 100644 --- a/src/docs/avocado-linux/tools/avocado-cli/commands/connect/auth/login.md +++ b/src/docs/avocado-linux/tools/avocado-cli/commands/connect/auth/login.md @@ -12,4 +12,4 @@ Options: --sdk-arch SDK container architecture for cross-arch emulation via Docker buildx/QEMU (aarch64 or x86-64) -h, --help Print help -``` \ No newline at end of file +``` diff --git a/src/docs/avocado-linux/tools/avocado-cli/commands/connect/auth/logout.md b/src/docs/avocado-linux/tools/avocado-cli/commands/connect/auth/logout.md index a8401cdc..2cbbfa10 100644 --- a/src/docs/avocado-linux/tools/avocado-cli/commands/connect/auth/logout.md +++ b/src/docs/avocado-linux/tools/avocado-cli/commands/connect/auth/logout.md @@ -10,4 +10,4 @@ Options: --sdk-arch SDK container architecture for cross-arch emulation via Docker buildx/QEMU (aarch64 or x86-64) -h, --help Print help -``` \ No newline at end of file +``` diff --git a/src/docs/avocado-linux/tools/avocado-cli/commands/connect/auth/status.md b/src/docs/avocado-linux/tools/avocado-cli/commands/connect/auth/status.md index 0e66d80e..1707bae5 100644 --- a/src/docs/avocado-linux/tools/avocado-cli/commands/connect/auth/status.md +++ b/src/docs/avocado-linux/tools/avocado-cli/commands/connect/auth/status.md @@ -10,4 +10,4 @@ Options: --sdk-arch SDK container architecture for cross-arch emulation via Docker buildx/QEMU (aarch64 or x86-64) -h, --help Print help -``` \ No newline at end of file +``` diff --git a/src/docs/avocado-linux/tools/avocado-cli/commands/connect/claim-tokens/create.md b/src/docs/avocado-linux/tools/avocado-cli/commands/connect/claim-tokens/create.md index 06460e49..871c8fb1 100644 --- a/src/docs/avocado-linux/tools/avocado-cli/commands/connect/claim-tokens/create.md +++ b/src/docs/avocado-linux/tools/avocado-cli/commands/connect/claim-tokens/create.md @@ -16,4 +16,4 @@ Options: --sdk-arch SDK container architecture for cross-arch emulation via Docker buildx/QEMU (aarch64 or x86-64) -h, --help Print help -``` \ No newline at end of file +``` diff --git a/src/docs/avocado-linux/tools/avocado-cli/commands/connect/claim-tokens/delete.md b/src/docs/avocado-linux/tools/avocado-cli/commands/connect/claim-tokens/delete.md index 7d1204b4..934da144 100644 --- a/src/docs/avocado-linux/tools/avocado-cli/commands/connect/claim-tokens/delete.md +++ b/src/docs/avocado-linux/tools/avocado-cli/commands/connect/claim-tokens/delete.md @@ -14,4 +14,4 @@ Options: --sdk-arch SDK container architecture for cross-arch emulation via Docker buildx/QEMU (aarch64 or x86-64) -h, --help Print help -``` \ No newline at end of file +``` diff --git a/src/docs/avocado-linux/tools/avocado-cli/commands/connect/claim-tokens/list.md b/src/docs/avocado-linux/tools/avocado-cli/commands/connect/claim-tokens/list.md index 6926406d..df0e7d87 100644 --- a/src/docs/avocado-linux/tools/avocado-cli/commands/connect/claim-tokens/list.md +++ b/src/docs/avocado-linux/tools/avocado-cli/commands/connect/claim-tokens/list.md @@ -12,4 +12,4 @@ Options: --sdk-arch SDK container architecture for cross-arch emulation via Docker buildx/QEMU (aarch64 or x86-64) -h, --help Print help -``` \ No newline at end of file +``` diff --git a/src/docs/avocado-linux/tools/avocado-cli/commands/connect/cohorts/create.md b/src/docs/avocado-linux/tools/avocado-cli/commands/connect/cohorts/create.md index c8243a58..ccef626a 100644 --- a/src/docs/avocado-linux/tools/avocado-cli/commands/connect/cohorts/create.md +++ b/src/docs/avocado-linux/tools/avocado-cli/commands/connect/cohorts/create.md @@ -15,4 +15,4 @@ Options: --sdk-arch SDK container architecture for cross-arch emulation via Docker buildx/QEMU (aarch64 or x86-64) -h, --help Print help -``` \ No newline at end of file +``` diff --git a/src/docs/avocado-linux/tools/avocado-cli/commands/connect/cohorts/delete.md b/src/docs/avocado-linux/tools/avocado-cli/commands/connect/cohorts/delete.md index 35ff461c..58554868 100644 --- a/src/docs/avocado-linux/tools/avocado-cli/commands/connect/cohorts/delete.md +++ b/src/docs/avocado-linux/tools/avocado-cli/commands/connect/cohorts/delete.md @@ -15,4 +15,4 @@ Options: --sdk-arch SDK container architecture for cross-arch emulation via Docker buildx/QEMU (aarch64 or x86-64) -h, --help Print help -``` \ No newline at end of file +``` diff --git a/src/docs/avocado-linux/tools/avocado-cli/commands/connect/cohorts/list.md b/src/docs/avocado-linux/tools/avocado-cli/commands/connect/cohorts/list.md index 153bb01d..cf8207cf 100644 --- a/src/docs/avocado-linux/tools/avocado-cli/commands/connect/cohorts/list.md +++ b/src/docs/avocado-linux/tools/avocado-cli/commands/connect/cohorts/list.md @@ -13,4 +13,4 @@ Options: --sdk-arch SDK container architecture for cross-arch emulation via Docker buildx/QEMU (aarch64 or x86-64) -h, --help Print help -``` \ No newline at end of file +``` diff --git a/src/docs/avocado-linux/tools/avocado-cli/commands/connect/devices/create.md b/src/docs/avocado-linux/tools/avocado-cli/commands/connect/devices/create.md index 3abf2572..77cfc626 100644 --- a/src/docs/avocado-linux/tools/avocado-cli/commands/connect/devices/create.md +++ b/src/docs/avocado-linux/tools/avocado-cli/commands/connect/devices/create.md @@ -14,4 +14,4 @@ Options: --sdk-arch SDK container architecture for cross-arch emulation via Docker buildx/QEMU (aarch64 or x86-64) -h, --help Print help -``` \ No newline at end of file +``` diff --git a/src/docs/avocado-linux/tools/avocado-cli/commands/connect/devices/delete.md b/src/docs/avocado-linux/tools/avocado-cli/commands/connect/devices/delete.md index 52027cf6..b6024d4a 100644 --- a/src/docs/avocado-linux/tools/avocado-cli/commands/connect/devices/delete.md +++ b/src/docs/avocado-linux/tools/avocado-cli/commands/connect/devices/delete.md @@ -14,4 +14,4 @@ Options: --sdk-arch SDK container architecture for cross-arch emulation via Docker buildx/QEMU (aarch64 or x86-64) -h, --help Print help -``` \ No newline at end of file +``` diff --git a/src/docs/avocado-linux/tools/avocado-cli/commands/connect/devices/list.md b/src/docs/avocado-linux/tools/avocado-cli/commands/connect/devices/list.md index 15c2f78d..8662c494 100644 --- a/src/docs/avocado-linux/tools/avocado-cli/commands/connect/devices/list.md +++ b/src/docs/avocado-linux/tools/avocado-cli/commands/connect/devices/list.md @@ -12,4 +12,4 @@ Options: --sdk-arch SDK container architecture for cross-arch emulation via Docker buildx/QEMU (aarch64 or x86-64) -h, --help Print help -``` \ No newline at end of file +``` diff --git a/src/docs/avocado-linux/tools/avocado-cli/commands/connect/init.md b/src/docs/avocado-linux/tools/avocado-cli/commands/connect/init.md index ca80877a..6d7f28d5 100644 --- a/src/docs/avocado-linux/tools/avocado-cli/commands/connect/init.md +++ b/src/docs/avocado-linux/tools/avocado-cli/commands/connect/init.md @@ -13,4 +13,4 @@ Options: --sdk-arch SDK container architecture for cross-arch emulation via Docker buildx/QEMU (aarch64 or x86-64) -h, --help Print help -``` \ No newline at end of file +``` diff --git a/src/docs/avocado-linux/tools/avocado-cli/commands/connect/keys/approve.md b/src/docs/avocado-linux/tools/avocado-cli/commands/connect/keys/approve.md index a1f13859..9376a9ed 100644 --- a/src/docs/avocado-linux/tools/avocado-cli/commands/connect/keys/approve.md +++ b/src/docs/avocado-linux/tools/avocado-cli/commands/connect/keys/approve.md @@ -15,4 +15,4 @@ Options: --sdk-arch SDK container architecture for cross-arch emulation via Docker buildx/QEMU (aarch64 or x86-64) -h, --help Print help -``` \ No newline at end of file +``` diff --git a/src/docs/avocado-linux/tools/avocado-cli/commands/connect/keys/list.md b/src/docs/avocado-linux/tools/avocado-cli/commands/connect/keys/list.md index c9b8df5d..b474bcb3 100644 --- a/src/docs/avocado-linux/tools/avocado-cli/commands/connect/keys/list.md +++ b/src/docs/avocado-linux/tools/avocado-cli/commands/connect/keys/list.md @@ -13,4 +13,4 @@ Options: --sdk-arch SDK container architecture for cross-arch emulation via Docker buildx/QEMU (aarch64 or x86-64) -h, --help Print help -``` \ No newline at end of file +``` diff --git a/src/docs/avocado-linux/tools/avocado-cli/commands/connect/keys/register.md b/src/docs/avocado-linux/tools/avocado-cli/commands/connect/keys/register.md index 6e57bfb5..cf32dd57 100644 --- a/src/docs/avocado-linux/tools/avocado-cli/commands/connect/keys/register.md +++ b/src/docs/avocado-linux/tools/avocado-cli/commands/connect/keys/register.md @@ -14,4 +14,4 @@ Options: --sdk-arch SDK container architecture for cross-arch emulation via Docker buildx/QEMU (aarch64 or x86-64) -h, --help Print help -``` \ No newline at end of file +``` diff --git a/src/docs/avocado-linux/tools/avocado-cli/commands/connect/keys/retire.md b/src/docs/avocado-linux/tools/avocado-cli/commands/connect/keys/retire.md index aa0570b9..bb51a3d3 100644 --- a/src/docs/avocado-linux/tools/avocado-cli/commands/connect/keys/retire.md +++ b/src/docs/avocado-linux/tools/avocado-cli/commands/connect/keys/retire.md @@ -15,4 +15,4 @@ Options: --sdk-arch SDK container architecture for cross-arch emulation via Docker buildx/QEMU (aarch64 or x86-64) -h, --help Print help -``` \ No newline at end of file +``` diff --git a/src/docs/avocado-linux/tools/avocado-cli/commands/connect/orgs/list.md b/src/docs/avocado-linux/tools/avocado-cli/commands/connect/orgs/list.md index 0916b1a5..c2b0ba5d 100644 --- a/src/docs/avocado-linux/tools/avocado-cli/commands/connect/orgs/list.md +++ b/src/docs/avocado-linux/tools/avocado-cli/commands/connect/orgs/list.md @@ -10,4 +10,4 @@ Options: --sdk-arch SDK container architecture for cross-arch emulation via Docker buildx/QEMU (aarch64 or x86-64) -h, --help Print help -``` \ No newline at end of file +``` diff --git a/src/docs/avocado-linux/tools/avocado-cli/commands/connect/projects/create.md b/src/docs/avocado-linux/tools/avocado-cli/commands/connect/projects/create.md index 9c53b563..86402d20 100644 --- a/src/docs/avocado-linux/tools/avocado-cli/commands/connect/projects/create.md +++ b/src/docs/avocado-linux/tools/avocado-cli/commands/connect/projects/create.md @@ -14,4 +14,4 @@ Options: --sdk-arch SDK container architecture for cross-arch emulation via Docker buildx/QEMU (aarch64 or x86-64) -h, --help Print help -``` \ No newline at end of file +``` diff --git a/src/docs/avocado-linux/tools/avocado-cli/commands/connect/projects/delete.md b/src/docs/avocado-linux/tools/avocado-cli/commands/connect/projects/delete.md index 05e0cd17..59dbb60b 100644 --- a/src/docs/avocado-linux/tools/avocado-cli/commands/connect/projects/delete.md +++ b/src/docs/avocado-linux/tools/avocado-cli/commands/connect/projects/delete.md @@ -14,4 +14,4 @@ Options: --sdk-arch SDK container architecture for cross-arch emulation via Docker buildx/QEMU (aarch64 or x86-64) -h, --help Print help -``` \ No newline at end of file +``` diff --git a/src/docs/avocado-linux/tools/avocado-cli/commands/connect/projects/list.md b/src/docs/avocado-linux/tools/avocado-cli/commands/connect/projects/list.md index e846923c..18249ec4 100644 --- a/src/docs/avocado-linux/tools/avocado-cli/commands/connect/projects/list.md +++ b/src/docs/avocado-linux/tools/avocado-cli/commands/connect/projects/list.md @@ -12,4 +12,4 @@ Options: --sdk-arch SDK container architecture for cross-arch emulation via Docker buildx/QEMU (aarch64 or x86-64) -h, --help Print help -``` \ No newline at end of file +``` diff --git a/src/docs/avocado-linux/tools/avocado-cli/commands/connect/server-key.md b/src/docs/avocado-linux/tools/avocado-cli/commands/connect/server-key.md index 9d5ca792..e9ae59df 100644 --- a/src/docs/avocado-linux/tools/avocado-cli/commands/connect/server-key.md +++ b/src/docs/avocado-linux/tools/avocado-cli/commands/connect/server-key.md @@ -12,4 +12,4 @@ Options: --sdk-arch SDK container architecture for cross-arch emulation via Docker buildx/QEMU (aarch64 or x86-64) -h, --help Print help -``` \ No newline at end of file +``` diff --git a/src/docs/avocado-linux/tools/avocado-cli/commands/connect/trust/promote-root.md b/src/docs/avocado-linux/tools/avocado-cli/commands/connect/trust/promote-root.md index 9c76a0f9..894e4c4e 100644 --- a/src/docs/avocado-linux/tools/avocado-cli/commands/connect/trust/promote-root.md +++ b/src/docs/avocado-linux/tools/avocado-cli/commands/connect/trust/promote-root.md @@ -13,4 +13,4 @@ Options: --sdk-arch SDK container architecture for cross-arch emulation via Docker buildx/QEMU (aarch64 or x86-64) -h, --help Print help -``` \ No newline at end of file +``` diff --git a/src/docs/avocado-linux/tools/avocado-cli/commands/connect/trust/rotate-server-key.md b/src/docs/avocado-linux/tools/avocado-cli/commands/connect/trust/rotate-server-key.md index a0de8ca0..83e9aed9 100644 --- a/src/docs/avocado-linux/tools/avocado-cli/commands/connect/trust/rotate-server-key.md +++ b/src/docs/avocado-linux/tools/avocado-cli/commands/connect/trust/rotate-server-key.md @@ -13,4 +13,4 @@ Options: --sdk-arch SDK container architecture for cross-arch emulation via Docker buildx/QEMU (aarch64 or x86-64) -h, --help Print help -``` \ No newline at end of file +``` diff --git a/src/docs/avocado-linux/tools/avocado-cli/commands/connect/trust/status.md b/src/docs/avocado-linux/tools/avocado-cli/commands/connect/trust/status.md index 387da86c..36c39881 100644 --- a/src/docs/avocado-linux/tools/avocado-cli/commands/connect/trust/status.md +++ b/src/docs/avocado-linux/tools/avocado-cli/commands/connect/trust/status.md @@ -12,4 +12,4 @@ Options: --sdk-arch SDK container architecture for cross-arch emulation via Docker buildx/QEMU (aarch64 or x86-64) -h, --help Print help -``` \ No newline at end of file +``` diff --git a/src/docs/avocado-linux/tools/avocado-cli/commands/connect/upload.md b/src/docs/avocado-linux/tools/avocado-cli/commands/connect/upload.md index 216eba18..0f9873f1 100644 --- a/src/docs/avocado-linux/tools/avocado-cli/commands/connect/upload.md +++ b/src/docs/avocado-linux/tools/avocado-cli/commands/connect/upload.md @@ -20,4 +20,4 @@ Options: --sdk-arch SDK container architecture for cross-arch emulation via Docker buildx/QEMU (aarch64 or x86-64) -h, --help Print help -``` \ No newline at end of file +``` diff --git a/src/docs/avocado-linux/tools/avocado-cli/commands/deploy.md b/src/docs/avocado-linux/tools/avocado-cli/commands/deploy.md index 2a1dc9b6..61787d8d 100644 --- a/src/docs/avocado-linux/tools/avocado-cli/commands/deploy.md +++ b/src/docs/avocado-linux/tools/avocado-cli/commands/deploy.md @@ -18,4 +18,4 @@ Options: --sdk-arch SDK container architecture for cross-arch emulation via Docker buildx/QEMU (aarch64 or x86-64) -h, --help Print help -``` \ No newline at end of file +``` diff --git a/src/docs/avocado-linux/tools/avocado-cli/commands/ext/build.md b/src/docs/avocado-linux/tools/avocado-cli/commands/ext/build.md index 997393d5..f8b7ce11 100644 --- a/src/docs/avocado-linux/tools/avocado-cli/commands/ext/build.md +++ b/src/docs/avocado-linux/tools/avocado-cli/commands/ext/build.md @@ -17,4 +17,4 @@ Options: --sdk-arch SDK container architecture for cross-arch emulation via Docker buildx/QEMU (aarch64 or x86-64) -h, --help Print help -``` \ No newline at end of file +``` diff --git a/src/docs/avocado-linux/tools/avocado-cli/commands/ext/checkout.md b/src/docs/avocado-linux/tools/avocado-cli/commands/ext/checkout.md index a36185b8..b985aabd 100644 --- a/src/docs/avocado-linux/tools/avocado-cli/commands/ext/checkout.md +++ b/src/docs/avocado-linux/tools/avocado-cli/commands/ext/checkout.md @@ -28,4 +28,4 @@ Options: -h, --help Print help -``` \ No newline at end of file +``` diff --git a/src/docs/avocado-linux/tools/avocado-cli/commands/ext/clean.md b/src/docs/avocado-linux/tools/avocado-cli/commands/ext/clean.md index a4362cdf..85e2fd7f 100644 --- a/src/docs/avocado-linux/tools/avocado-cli/commands/ext/clean.md +++ b/src/docs/avocado-linux/tools/avocado-cli/commands/ext/clean.md @@ -17,4 +17,4 @@ Options: --sdk-arch SDK container architecture for cross-arch emulation via Docker buildx/QEMU (aarch64 or x86-64) -h, --help Print help -``` \ No newline at end of file +``` diff --git a/src/docs/avocado-linux/tools/avocado-cli/commands/ext/deps.md b/src/docs/avocado-linux/tools/avocado-cli/commands/ext/deps.md index 00c32bc2..be439fe6 100644 --- a/src/docs/avocado-linux/tools/avocado-cli/commands/ext/deps.md +++ b/src/docs/avocado-linux/tools/avocado-cli/commands/ext/deps.md @@ -14,4 +14,4 @@ Options: --sdk-arch SDK container architecture for cross-arch emulation via Docker buildx/QEMU (aarch64 or x86-64) -h, --help Print help -``` \ No newline at end of file +``` diff --git a/src/docs/avocado-linux/tools/avocado-cli/commands/ext/dnf.md b/src/docs/avocado-linux/tools/avocado-cli/commands/ext/dnf.md index a9d48228..ce456b8e 100644 --- a/src/docs/avocado-linux/tools/avocado-cli/commands/ext/dnf.md +++ b/src/docs/avocado-linux/tools/avocado-cli/commands/ext/dnf.md @@ -18,4 +18,4 @@ Options: --sdk-arch SDK container architecture for cross-arch emulation via Docker buildx/QEMU (aarch64 or x86-64) -h, --help Print help -``` \ No newline at end of file +``` diff --git a/src/docs/avocado-linux/tools/avocado-cli/commands/ext/fetch.md b/src/docs/avocado-linux/tools/avocado-cli/commands/ext/fetch.md index 33447bda..ee03472b 100644 --- a/src/docs/avocado-linux/tools/avocado-cli/commands/ext/fetch.md +++ b/src/docs/avocado-linux/tools/avocado-cli/commands/ext/fetch.md @@ -17,4 +17,4 @@ Options: --sdk-arch SDK container architecture for cross-arch emulation via Docker buildx/QEMU (aarch64 or x86-64) -h, --help Print help -``` \ No newline at end of file +``` diff --git a/src/docs/avocado-linux/tools/avocado-cli/commands/ext/image.md b/src/docs/avocado-linux/tools/avocado-cli/commands/ext/image.md index 3c24c068..74b8889f 100644 --- a/src/docs/avocado-linux/tools/avocado-cli/commands/ext/image.md +++ b/src/docs/avocado-linux/tools/avocado-cli/commands/ext/image.md @@ -18,4 +18,4 @@ Options: --sdk-arch SDK container architecture for cross-arch emulation via Docker buildx/QEMU (aarch64 or x86-64) -h, --help Print help -``` \ No newline at end of file +``` diff --git a/src/docs/avocado-linux/tools/avocado-cli/commands/ext/install.md b/src/docs/avocado-linux/tools/avocado-cli/commands/ext/install.md index 3164a21d..0ef38730 100644 --- a/src/docs/avocado-linux/tools/avocado-cli/commands/ext/install.md +++ b/src/docs/avocado-linux/tools/avocado-cli/commands/ext/install.md @@ -18,4 +18,4 @@ Options: --sdk-arch SDK container architecture for cross-arch emulation via Docker buildx/QEMU (aarch64 or x86-64) -h, --help Print help -``` \ No newline at end of file +``` diff --git a/src/docs/avocado-linux/tools/avocado-cli/commands/ext/list.md b/src/docs/avocado-linux/tools/avocado-cli/commands/ext/list.md index fb6c3d47..4598fa68 100644 --- a/src/docs/avocado-linux/tools/avocado-cli/commands/ext/list.md +++ b/src/docs/avocado-linux/tools/avocado-cli/commands/ext/list.md @@ -11,4 +11,4 @@ Options: --sdk-arch SDK container architecture for cross-arch emulation via Docker buildx/QEMU (aarch64 or x86-64) -h, --help Print help -``` \ No newline at end of file +``` diff --git a/src/docs/avocado-linux/tools/avocado-cli/commands/ext/package.md b/src/docs/avocado-linux/tools/avocado-cli/commands/ext/package.md index c4997fa3..5dad89cf 100644 --- a/src/docs/avocado-linux/tools/avocado-cli/commands/ext/package.md +++ b/src/docs/avocado-linux/tools/avocado-cli/commands/ext/package.md @@ -18,4 +18,4 @@ Options: --sdk-arch SDK container architecture for cross-arch emulation via Docker buildx/QEMU (aarch64 or x86-64) -h, --help Print help -``` \ No newline at end of file +``` diff --git a/src/docs/avocado-linux/tools/avocado-cli/commands/fetch.md b/src/docs/avocado-linux/tools/avocado-cli/commands/fetch.md index 6140c618..4bf73b3c 100644 --- a/src/docs/avocado-linux/tools/avocado-cli/commands/fetch.md +++ b/src/docs/avocado-linux/tools/avocado-cli/commands/fetch.md @@ -16,4 +16,4 @@ Options: --sdk-arch SDK container architecture for cross-arch emulation via Docker buildx/QEMU (aarch64 or x86-64) -h, --help Print help -``` \ No newline at end of file +``` diff --git a/src/docs/avocado-linux/tools/avocado-cli/commands/hitl/server.md b/src/docs/avocado-linux/tools/avocado-cli/commands/hitl/server.md index 5f071976..5c8af9b9 100644 --- a/src/docs/avocado-linux/tools/avocado-cli/commands/hitl/server.md +++ b/src/docs/avocado-linux/tools/avocado-cli/commands/hitl/server.md @@ -17,4 +17,4 @@ Options: --sdk-arch SDK container architecture for cross-arch emulation via Docker buildx/QEMU (aarch64 or x86-64) -h, --help Print help -``` \ No newline at end of file +``` diff --git a/src/docs/avocado-linux/tools/avocado-cli/commands/init.md b/src/docs/avocado-linux/tools/avocado-cli/commands/init.md index c78623ab..17a6b98a 100644 --- a/src/docs/avocado-linux/tools/avocado-cli/commands/init.md +++ b/src/docs/avocado-linux/tools/avocado-cli/commands/init.md @@ -26,4 +26,4 @@ Options: -h, --help Print help -``` \ No newline at end of file +``` diff --git a/src/docs/avocado-linux/tools/avocado-cli/commands/initramfs/clean.md b/src/docs/avocado-linux/tools/avocado-cli/commands/initramfs/clean.md index fa4acbcc..8e62afdf 100644 --- a/src/docs/avocado-linux/tools/avocado-cli/commands/initramfs/clean.md +++ b/src/docs/avocado-linux/tools/avocado-cli/commands/initramfs/clean.md @@ -14,4 +14,4 @@ Options: --sdk-arch SDK container architecture for cross-arch emulation via Docker buildx/QEMU (aarch64 or x86-64) -h, --help Print help -``` \ No newline at end of file +``` diff --git a/src/docs/avocado-linux/tools/avocado-cli/commands/initramfs/image.md b/src/docs/avocado-linux/tools/avocado-cli/commands/initramfs/image.md index ffb693a0..e09c568f 100644 --- a/src/docs/avocado-linux/tools/avocado-cli/commands/initramfs/image.md +++ b/src/docs/avocado-linux/tools/avocado-cli/commands/initramfs/image.md @@ -15,4 +15,4 @@ Options: --sdk-arch SDK container architecture for cross-arch emulation via Docker buildx/QEMU (aarch64 or x86-64) -h, --help Print help -``` \ No newline at end of file +``` diff --git a/src/docs/avocado-linux/tools/avocado-cli/commands/initramfs/install.md b/src/docs/avocado-linux/tools/avocado-cli/commands/initramfs/install.md index 9e9ab080..7fbc8188 100644 --- a/src/docs/avocado-linux/tools/avocado-cli/commands/initramfs/install.md +++ b/src/docs/avocado-linux/tools/avocado-cli/commands/initramfs/install.md @@ -15,4 +15,4 @@ Options: --sdk-arch SDK container architecture for cross-arch emulation via Docker buildx/QEMU (aarch64 or x86-64) -h, --help Print help -``` \ No newline at end of file +``` diff --git a/src/docs/avocado-linux/tools/avocado-cli/commands/install.md b/src/docs/avocado-linux/tools/avocado-cli/commands/install.md index ed78a92b..c14df8be 100644 --- a/src/docs/avocado-linux/tools/avocado-cli/commands/install.md +++ b/src/docs/avocado-linux/tools/avocado-cli/commands/install.md @@ -15,7 +15,7 @@ Options: -C, --config Path to avocado.yaml configuration file - + [default: avocado.yaml] -v, --verbose @@ -54,4 +54,4 @@ Options: -h, --help Print help (see a summary with '-h') -``` \ No newline at end of file +``` diff --git a/src/docs/avocado-linux/tools/avocado-cli/commands/provision.md b/src/docs/avocado-linux/tools/avocado-cli/commands/provision.md index eb2ca354..bd3cc8a4 100644 --- a/src/docs/avocado-linux/tools/avocado-cli/commands/provision.md +++ b/src/docs/avocado-linux/tools/avocado-cli/commands/provision.md @@ -21,4 +21,4 @@ Options: --sdk-arch SDK container architecture for cross-arch emulation via Docker buildx/QEMU (aarch64 or x86-64) -h, --help Print help -``` \ No newline at end of file +``` diff --git a/src/docs/avocado-linux/tools/avocado-cli/commands/prune.md b/src/docs/avocado-linux/tools/avocado-cli/commands/prune.md index d2b8ce72..b08ba2db 100644 --- a/src/docs/avocado-linux/tools/avocado-cli/commands/prune.md +++ b/src/docs/avocado-linux/tools/avocado-cli/commands/prune.md @@ -19,4 +19,4 @@ Options: -h, --help Print help -``` \ No newline at end of file +``` diff --git a/src/docs/avocado-linux/tools/avocado-cli/commands/rootfs/clean.md b/src/docs/avocado-linux/tools/avocado-cli/commands/rootfs/clean.md index f8c9e6b5..8567148d 100644 --- a/src/docs/avocado-linux/tools/avocado-cli/commands/rootfs/clean.md +++ b/src/docs/avocado-linux/tools/avocado-cli/commands/rootfs/clean.md @@ -14,4 +14,4 @@ Options: --sdk-arch SDK container architecture for cross-arch emulation via Docker buildx/QEMU (aarch64 or x86-64) -h, --help Print help -``` \ No newline at end of file +``` diff --git a/src/docs/avocado-linux/tools/avocado-cli/commands/rootfs/image.md b/src/docs/avocado-linux/tools/avocado-cli/commands/rootfs/image.md index de936db1..565ed525 100644 --- a/src/docs/avocado-linux/tools/avocado-cli/commands/rootfs/image.md +++ b/src/docs/avocado-linux/tools/avocado-cli/commands/rootfs/image.md @@ -15,4 +15,4 @@ Options: --sdk-arch SDK container architecture for cross-arch emulation via Docker buildx/QEMU (aarch64 or x86-64) -h, --help Print help -``` \ No newline at end of file +``` diff --git a/src/docs/avocado-linux/tools/avocado-cli/commands/rootfs/install.md b/src/docs/avocado-linux/tools/avocado-cli/commands/rootfs/install.md index 687f24d8..5d77cb47 100644 --- a/src/docs/avocado-linux/tools/avocado-cli/commands/rootfs/install.md +++ b/src/docs/avocado-linux/tools/avocado-cli/commands/rootfs/install.md @@ -15,4 +15,4 @@ Options: --sdk-arch SDK container architecture for cross-arch emulation via Docker buildx/QEMU (aarch64 or x86-64) -h, --help Print help -``` \ No newline at end of file +``` diff --git a/src/docs/avocado-linux/tools/avocado-cli/commands/runtime/build.md b/src/docs/avocado-linux/tools/avocado-cli/commands/runtime/build.md index e1e5f7ed..c5b0a896 100644 --- a/src/docs/avocado-linux/tools/avocado-cli/commands/runtime/build.md +++ b/src/docs/avocado-linux/tools/avocado-cli/commands/runtime/build.md @@ -18,4 +18,4 @@ Options: --sdk-arch SDK container architecture for cross-arch emulation via Docker buildx/QEMU (aarch64 or x86-64) -h, --help Print help -``` \ No newline at end of file +``` diff --git a/src/docs/avocado-linux/tools/avocado-cli/commands/runtime/clean.md b/src/docs/avocado-linux/tools/avocado-cli/commands/runtime/clean.md index b790ad64..fe52402d 100644 --- a/src/docs/avocado-linux/tools/avocado-cli/commands/runtime/clean.md +++ b/src/docs/avocado-linux/tools/avocado-cli/commands/runtime/clean.md @@ -17,4 +17,4 @@ Options: --sdk-arch SDK container architecture for cross-arch emulation via Docker buildx/QEMU (aarch64 or x86-64) -h, --help Print help -``` \ No newline at end of file +``` diff --git a/src/docs/avocado-linux/tools/avocado-cli/commands/runtime/deploy.md b/src/docs/avocado-linux/tools/avocado-cli/commands/runtime/deploy.md index fbc8b108..c803140a 100644 --- a/src/docs/avocado-linux/tools/avocado-cli/commands/runtime/deploy.md +++ b/src/docs/avocado-linux/tools/avocado-cli/commands/runtime/deploy.md @@ -18,4 +18,4 @@ Options: --sdk-arch SDK container architecture for cross-arch emulation via Docker buildx/QEMU (aarch64 or x86-64) -h, --help Print help -``` \ No newline at end of file +``` diff --git a/src/docs/avocado-linux/tools/avocado-cli/commands/runtime/deps.md b/src/docs/avocado-linux/tools/avocado-cli/commands/runtime/deps.md index 0e477185..2393405a 100644 --- a/src/docs/avocado-linux/tools/avocado-cli/commands/runtime/deps.md +++ b/src/docs/avocado-linux/tools/avocado-cli/commands/runtime/deps.md @@ -14,4 +14,4 @@ Options: --sdk-arch SDK container architecture for cross-arch emulation via Docker buildx/QEMU (aarch64 or x86-64) -h, --help Print help -``` \ No newline at end of file +``` diff --git a/src/docs/avocado-linux/tools/avocado-cli/commands/runtime/dnf.md b/src/docs/avocado-linux/tools/avocado-cli/commands/runtime/dnf.md index 1e7b6668..6241b8bb 100644 --- a/src/docs/avocado-linux/tools/avocado-cli/commands/runtime/dnf.md +++ b/src/docs/avocado-linux/tools/avocado-cli/commands/runtime/dnf.md @@ -18,4 +18,4 @@ Options: --sdk-arch SDK container architecture for cross-arch emulation via Docker buildx/QEMU (aarch64 or x86-64) -h, --help Print help -``` \ No newline at end of file +``` diff --git a/src/docs/avocado-linux/tools/avocado-cli/commands/runtime/install.md b/src/docs/avocado-linux/tools/avocado-cli/commands/runtime/install.md index d8711806..01072984 100644 --- a/src/docs/avocado-linux/tools/avocado-cli/commands/runtime/install.md +++ b/src/docs/avocado-linux/tools/avocado-cli/commands/runtime/install.md @@ -18,4 +18,4 @@ Options: --sdk-arch SDK container architecture for cross-arch emulation via Docker buildx/QEMU (aarch64 or x86-64) -h, --help Print help -``` \ No newline at end of file +``` diff --git a/src/docs/avocado-linux/tools/avocado-cli/commands/runtime/list.md b/src/docs/avocado-linux/tools/avocado-cli/commands/runtime/list.md index 4bb4cafb..67c87811 100644 --- a/src/docs/avocado-linux/tools/avocado-cli/commands/runtime/list.md +++ b/src/docs/avocado-linux/tools/avocado-cli/commands/runtime/list.md @@ -11,4 +11,4 @@ Options: --sdk-arch SDK container architecture for cross-arch emulation via Docker buildx/QEMU (aarch64 or x86-64) -h, --help Print help -``` \ No newline at end of file +``` diff --git a/src/docs/avocado-linux/tools/avocado-cli/commands/runtime/provision.md b/src/docs/avocado-linux/tools/avocado-cli/commands/runtime/provision.md index 9b986f5b..c3dd3d3d 100644 --- a/src/docs/avocado-linux/tools/avocado-cli/commands/runtime/provision.md +++ b/src/docs/avocado-linux/tools/avocado-cli/commands/runtime/provision.md @@ -21,4 +21,4 @@ Options: --sdk-arch SDK container architecture for cross-arch emulation via Docker buildx/QEMU (aarch64 or x86-64) -h, --help Print help -``` \ No newline at end of file +``` diff --git a/src/docs/avocado-linux/tools/avocado-cli/commands/runtime/sign.md b/src/docs/avocado-linux/tools/avocado-cli/commands/runtime/sign.md index 4bbb634b..c5029d32 100644 --- a/src/docs/avocado-linux/tools/avocado-cli/commands/runtime/sign.md +++ b/src/docs/avocado-linux/tools/avocado-cli/commands/runtime/sign.md @@ -17,4 +17,4 @@ Options: --sdk-arch SDK container architecture for cross-arch emulation via Docker buildx/QEMU (aarch64 or x86-64) -h, --help Print help -``` \ No newline at end of file +``` diff --git a/src/docs/avocado-linux/tools/avocado-cli/commands/sdk/clean.md b/src/docs/avocado-linux/tools/avocado-cli/commands/sdk/clean.md index 2b10d0c0..5939886c 100644 --- a/src/docs/avocado-linux/tools/avocado-cli/commands/sdk/clean.md +++ b/src/docs/avocado-linux/tools/avocado-cli/commands/sdk/clean.md @@ -17,4 +17,4 @@ Options: --sdk-arch SDK container architecture for cross-arch emulation via Docker buildx/QEMU (aarch64 or x86-64) -h, --help Print help -``` \ No newline at end of file +``` diff --git a/src/docs/avocado-linux/tools/avocado-cli/commands/sdk/compile.md b/src/docs/avocado-linux/tools/avocado-cli/commands/sdk/compile.md index 2bfbe940..4f7a2168 100644 --- a/src/docs/avocado-linux/tools/avocado-cli/commands/sdk/compile.md +++ b/src/docs/avocado-linux/tools/avocado-cli/commands/sdk/compile.md @@ -17,4 +17,4 @@ Options: --sdk-arch SDK container architecture for cross-arch emulation via Docker buildx/QEMU (aarch64 or x86-64) -h, --help Print help -``` \ No newline at end of file +``` diff --git a/src/docs/avocado-linux/tools/avocado-cli/commands/sdk/deps.md b/src/docs/avocado-linux/tools/avocado-cli/commands/sdk/deps.md index d2dc0bb2..96efde7d 100644 --- a/src/docs/avocado-linux/tools/avocado-cli/commands/sdk/deps.md +++ b/src/docs/avocado-linux/tools/avocado-cli/commands/sdk/deps.md @@ -13,4 +13,4 @@ Options: --sdk-arch SDK container architecture for cross-arch emulation via Docker buildx/QEMU (aarch64 or x86-64) -h, --help Print help -``` \ No newline at end of file +``` diff --git a/src/docs/avocado-linux/tools/avocado-cli/commands/sdk/dnf.md b/src/docs/avocado-linux/tools/avocado-cli/commands/sdk/dnf.md index 62222b96..4586956d 100644 --- a/src/docs/avocado-linux/tools/avocado-cli/commands/sdk/dnf.md +++ b/src/docs/avocado-linux/tools/avocado-cli/commands/sdk/dnf.md @@ -17,4 +17,4 @@ Options: --sdk-arch SDK container architecture for cross-arch emulation via Docker buildx/QEMU (aarch64 or x86-64) -h, --help Print help -``` \ No newline at end of file +``` diff --git a/src/docs/avocado-linux/tools/avocado-cli/commands/sdk/install.md b/src/docs/avocado-linux/tools/avocado-cli/commands/sdk/install.md index 646969f1..bb7329d9 100644 --- a/src/docs/avocado-linux/tools/avocado-cli/commands/sdk/install.md +++ b/src/docs/avocado-linux/tools/avocado-cli/commands/sdk/install.md @@ -15,4 +15,4 @@ Options: --sdk-arch SDK container architecture for cross-arch emulation via Docker buildx/QEMU (aarch64 or x86-64) -h, --help Print help -``` \ No newline at end of file +``` diff --git a/src/docs/avocado-linux/tools/avocado-cli/commands/sdk/package.md b/src/docs/avocado-linux/tools/avocado-cli/commands/sdk/package.md index cc786d47..27790d24 100644 --- a/src/docs/avocado-linux/tools/avocado-cli/commands/sdk/package.md +++ b/src/docs/avocado-linux/tools/avocado-cli/commands/sdk/package.md @@ -18,4 +18,4 @@ Options: --sdk-arch SDK container architecture for cross-arch emulation via Docker buildx/QEMU (aarch64 or x86-64) -h, --help Print help -``` \ No newline at end of file +``` diff --git a/src/docs/avocado-linux/tools/avocado-cli/commands/sdk/run.md b/src/docs/avocado-linux/tools/avocado-cli/commands/sdk/run.md index 96347b13..a15604da 100644 --- a/src/docs/avocado-linux/tools/avocado-cli/commands/sdk/run.md +++ b/src/docs/avocado-linux/tools/avocado-cli/commands/sdk/run.md @@ -25,4 +25,4 @@ Options: --sdk-arch SDK container architecture for cross-arch emulation via Docker buildx/QEMU (aarch64 or x86-64) -h, --help Print help -``` \ No newline at end of file +``` diff --git a/src/docs/avocado-linux/tools/avocado-cli/commands/sign.md b/src/docs/avocado-linux/tools/avocado-cli/commands/sign.md index c99dc363..8b151826 100644 --- a/src/docs/avocado-linux/tools/avocado-cli/commands/sign.md +++ b/src/docs/avocado-linux/tools/avocado-cli/commands/sign.md @@ -17,4 +17,4 @@ Options: --sdk-arch SDK container architecture for cross-arch emulation via Docker buildx/QEMU (aarch64 or x86-64) -h, --help Print help -``` \ No newline at end of file +``` diff --git a/src/docs/avocado-linux/tools/avocado-cli/commands/signing-keys/create.md b/src/docs/avocado-linux/tools/avocado-cli/commands/signing-keys/create.md index 6b0309d5..1f08d044 100644 --- a/src/docs/avocado-linux/tools/avocado-cli/commands/signing-keys/create.md +++ b/src/docs/avocado-linux/tools/avocado-cli/commands/signing-keys/create.md @@ -18,4 +18,4 @@ Options: --sdk-arch SDK container architecture for cross-arch emulation via Docker buildx/QEMU (aarch64 or x86-64) -h, --help Print help -``` \ No newline at end of file +``` diff --git a/src/docs/avocado-linux/tools/avocado-cli/commands/signing-keys/list.md b/src/docs/avocado-linux/tools/avocado-cli/commands/signing-keys/list.md index a3d85303..caa1c436 100644 --- a/src/docs/avocado-linux/tools/avocado-cli/commands/signing-keys/list.md +++ b/src/docs/avocado-linux/tools/avocado-cli/commands/signing-keys/list.md @@ -9,4 +9,4 @@ Options: --sdk-arch SDK container architecture for cross-arch emulation via Docker buildx/QEMU (aarch64 or x86-64) -h, --help Print help -``` \ No newline at end of file +``` diff --git a/src/docs/avocado-linux/tools/avocado-cli/commands/signing-keys/remove.md b/src/docs/avocado-linux/tools/avocado-cli/commands/signing-keys/remove.md index c6ff42ef..0c85b7ae 100644 --- a/src/docs/avocado-linux/tools/avocado-cli/commands/signing-keys/remove.md +++ b/src/docs/avocado-linux/tools/avocado-cli/commands/signing-keys/remove.md @@ -13,4 +13,4 @@ Options: --sdk-arch SDK container architecture for cross-arch emulation via Docker buildx/QEMU (aarch64 or x86-64) -h, --help Print help -``` \ No newline at end of file +``` diff --git a/src/docs/avocado-linux/tools/avocado-cli/commands/uninstall.md b/src/docs/avocado-linux/tools/avocado-cli/commands/uninstall.md index f8188792..d29b705f 100644 --- a/src/docs/avocado-linux/tools/avocado-cli/commands/uninstall.md +++ b/src/docs/avocado-linux/tools/avocado-cli/commands/uninstall.md @@ -21,4 +21,4 @@ Options: --sdk-arch SDK container architecture for cross-arch emulation via Docker buildx/QEMU (aarch64 or x86-64) -h, --help Print help -``` \ No newline at end of file +``` diff --git a/src/docs/avocado-linux/tools/avocado-cli/commands/unlock.md b/src/docs/avocado-linux/tools/avocado-cli/commands/unlock.md index 3e3ec566..cc709f8f 100644 --- a/src/docs/avocado-linux/tools/avocado-cli/commands/unlock.md +++ b/src/docs/avocado-linux/tools/avocado-cli/commands/unlock.md @@ -15,4 +15,4 @@ Options: --sdk-arch SDK container architecture for cross-arch emulation via Docker buildx/QEMU (aarch64 or x86-64) -h, --help Print help -``` \ No newline at end of file +``` diff --git a/src/docs/avocado-linux/tools/avocado-cli/commands/upgrade.md b/src/docs/avocado-linux/tools/avocado-cli/commands/upgrade.md index fb8bea80..54537612 100644 --- a/src/docs/avocado-linux/tools/avocado-cli/commands/upgrade.md +++ b/src/docs/avocado-linux/tools/avocado-cli/commands/upgrade.md @@ -10,4 +10,4 @@ Options: --sdk-arch SDK container architecture for cross-arch emulation via Docker buildx/QEMU (aarch64 or x86-64) -h, --help Print help -``` \ No newline at end of file +``` diff --git a/src/docs/avocado-linux/tools/avocadoctl/commands/disable.md b/src/docs/avocado-linux/tools/avocadoctl/commands/disable.md index 3be3c435..af624de1 100644 --- a/src/docs/avocado-linux/tools/avocadoctl/commands/disable.md +++ b/src/docs/avocado-linux/tools/avocadoctl/commands/disable.md @@ -11,15 +11,15 @@ avocadoctl disable [OPTIONS] [EXTENSION]... ### Options -| Option | Description | -|---|---| +| Option | Description | +| ------------------------ | ----------------------------------------------------------- | | `--os-release ` | OS release version. Defaults to the current system version. | -| `--all` | Disable all extensions | +| `--all` | Disable all extensions | ### Arguments -| Argument | Description | -|---|---| +| Argument | Description | +| -------------- | ------------------------------------------------------------------------ | | `EXTENSION...` | One or more extension names to disable (required unless `--all` is used) | ### Examples diff --git a/src/docs/avocado-linux/tools/avocadoctl/commands/enable.md b/src/docs/avocado-linux/tools/avocadoctl/commands/enable.md index 9fdfb11d..6d7190f1 100644 --- a/src/docs/avocado-linux/tools/avocadoctl/commands/enable.md +++ b/src/docs/avocado-linux/tools/avocadoctl/commands/enable.md @@ -11,14 +11,14 @@ avocadoctl enable [OPTIONS] ... ### Options -| Option | Description | -|---|---| +| Option | Description | +| ------------------------ | ----------------------------------------------------------- | | `--os-release ` | OS release version. Defaults to the current system version. | ### Arguments -| Argument | Description | -|---|---| +| Argument | Description | +| -------------- | ------------------------------------------------ | | `EXTENSION...` | One or more extension names to enable (required) | ### Examples diff --git a/src/docs/avocado-linux/tools/avocadoctl/commands/ext/unmerge.md b/src/docs/avocado-linux/tools/avocadoctl/commands/ext/unmerge.md index a2cb5414..fe61dbb2 100644 --- a/src/docs/avocado-linux/tools/avocadoctl/commands/ext/unmerge.md +++ b/src/docs/avocado-linux/tools/avocadoctl/commands/ext/unmerge.md @@ -11,8 +11,8 @@ avocadoctl ext unmerge [OPTIONS] ### Options -| Option | Description | -|---|---| +| Option | Description | +| ----------- | ------------------------------------------------------- | | `--unmount` | Also unmount all persistent loops for `.raw` extensions | ### Examples diff --git a/src/docs/avocado-linux/tools/avocadoctl/commands/hitl/mount.md b/src/docs/avocado-linux/tools/avocadoctl/commands/hitl/mount.md index 6a39241e..a0c1070e 100644 --- a/src/docs/avocado-linux/tools/avocadoctl/commands/hitl/mount.md +++ b/src/docs/avocado-linux/tools/avocadoctl/commands/hitl/mount.md @@ -11,15 +11,15 @@ avocadoctl hitl mount [OPTIONS] -s ... ### Options -| Option | Description | -|---|---| +| Option | Description | +| ------------------------------- | -------------------------------- | | `-s`, `--server-ip ` | NFS server IP address (required) | -| `-e`, `--server-port ` | NFS server port | +| `-e`, `--server-port ` | NFS server port | ### Arguments -| Argument | Description | -|---|---| +| Argument | Description | +| -------------- | ------------------------------------ | | `EXTENSION...` | One or more extension names to mount | ### Examples diff --git a/src/docs/avocado-linux/tools/avocadoctl/commands/hitl/unmount.md b/src/docs/avocado-linux/tools/avocadoctl/commands/hitl/unmount.md index 4207bfa9..e4816906 100644 --- a/src/docs/avocado-linux/tools/avocadoctl/commands/hitl/unmount.md +++ b/src/docs/avocado-linux/tools/avocadoctl/commands/hitl/unmount.md @@ -11,8 +11,8 @@ avocadoctl hitl unmount [OPTIONS] ... ### Arguments -| Argument | Description | -|---|---| +| Argument | Description | +| -------------- | -------------------------------------- | | `EXTENSION...` | One or more extension names to unmount | ### Examples diff --git a/src/docs/avocado-linux/tools/avocadoctl/commands/runtime/activate.md b/src/docs/avocado-linux/tools/avocadoctl/commands/runtime/activate.md index a3e6f0e3..f869a1e1 100644 --- a/src/docs/avocado-linux/tools/avocadoctl/commands/runtime/activate.md +++ b/src/docs/avocado-linux/tools/avocadoctl/commands/runtime/activate.md @@ -19,9 +19,9 @@ avocadoctl runtime activate [OPTIONS] ### Arguments -| Argument | Description | -|---|---| -| `ID` | Runtime ID or unambiguous prefix | +| Argument | Description | +| -------- | -------------------------------- | +| `ID` | Runtime ID or unambiguous prefix | ### Examples diff --git a/src/docs/avocado-linux/tools/avocadoctl/commands/runtime/add.md b/src/docs/avocado-linux/tools/avocadoctl/commands/runtime/add.md index ff08581d..a834858b 100644 --- a/src/docs/avocado-linux/tools/avocadoctl/commands/runtime/add.md +++ b/src/docs/avocado-linux/tools/avocadoctl/commands/runtime/add.md @@ -16,9 +16,9 @@ avocadoctl runtime add [OPTIONS] (--url | --manifest ) ### Options -| Option | Description | -|---|---| -| `--url ` | TUF repository URL | +| Option | Description | +| ------------------- | ---------------------------------- | +| `--url ` | TUF repository URL | | `--manifest ` | Path to local `manifest.json` file | ### Examples diff --git a/src/docs/avocado-linux/tools/avocadoctl/commands/runtime/inspect.md b/src/docs/avocado-linux/tools/avocadoctl/commands/runtime/inspect.md index f07983c9..2567b133 100644 --- a/src/docs/avocado-linux/tools/avocadoctl/commands/runtime/inspect.md +++ b/src/docs/avocado-linux/tools/avocadoctl/commands/runtime/inspect.md @@ -11,9 +11,9 @@ avocadoctl runtime inspect [OPTIONS] [ID] ### Arguments -| Argument | Description | -|---|---| -| `ID` | Runtime ID or unambiguous prefix. Inspects the active runtime if omitted. | +| Argument | Description | +| -------- | ------------------------------------------------------------------------- | +| `ID` | Runtime ID or unambiguous prefix. Inspects the active runtime if omitted. | ### Examples diff --git a/src/docs/avocado-linux/tools/avocadoctl/commands/runtime/remove.md b/src/docs/avocado-linux/tools/avocadoctl/commands/runtime/remove.md index d70fbb41..3534fecb 100644 --- a/src/docs/avocado-linux/tools/avocadoctl/commands/runtime/remove.md +++ b/src/docs/avocado-linux/tools/avocadoctl/commands/runtime/remove.md @@ -11,9 +11,9 @@ avocadoctl runtime remove [OPTIONS] ### Arguments -| Argument | Description | -|---|---| -| `ID` | Runtime ID or unambiguous prefix | +| Argument | Description | +| -------- | -------------------------------- | +| `ID` | Runtime ID or unambiguous prefix | ### Examples diff --git a/src/docs/avocado-linux/tools/avocadoctl/commands/serve.md b/src/docs/avocado-linux/tools/avocadoctl/commands/serve.md index 9d89b651..2eaf6066 100644 --- a/src/docs/avocado-linux/tools/avocadoctl/commands/serve.md +++ b/src/docs/avocado-linux/tools/avocadoctl/commands/serve.md @@ -11,8 +11,8 @@ avocadoctl serve [OPTIONS] ### Options -| Option | Description | -|---|---| +| Option | Description | +| --------------------- | ------------------------------------------------------------ | | `--address
` | Listen address. Default: `unix:/run/avocado/avocadoctl.sock` | ### Examples diff --git a/src/docs/avocado-linux/tools/avocadoctl/commands/status.md b/src/docs/avocado-linux/tools/avocadoctl/commands/status.md index 6fcd3229..052c1313 100644 --- a/src/docs/avocado-linux/tools/avocadoctl/commands/status.md +++ b/src/docs/avocado-linux/tools/avocadoctl/commands/status.md @@ -11,12 +11,12 @@ avocadoctl status [OPTIONS] ### Global Options -| Option | Description | -|---|---| -| `-c`, `--config ` | Path to configuration file | -| `-v`, `--verbose` | Enable verbose output | -| `-o`, `--output ` | Output format | -| `--socket
` | Varlink socket address | +| Option | Description | +| ------------------------- | -------------------------- | +| `-c`, `--config ` | Path to configuration file | +| `-v`, `--verbose` | Enable verbose output | +| `-o`, `--output ` | Output format | +| `--socket
` | Varlink socket address | ### Examples diff --git a/src/docs/avocado-linux/tools/avocadoctl/commands/unmerge.md b/src/docs/avocado-linux/tools/avocadoctl/commands/unmerge.md index d4c06be4..c9c5476b 100644 --- a/src/docs/avocado-linux/tools/avocadoctl/commands/unmerge.md +++ b/src/docs/avocado-linux/tools/avocadoctl/commands/unmerge.md @@ -11,8 +11,8 @@ avocadoctl unmerge [OPTIONS] ### Options -| Option | Description | -|---|---| +| Option | Description | +| ----------- | ------------------------------------------------------- | | `--unmount` | Also unmount all persistent loops for `.raw` extensions | ### Examples diff --git a/src/docs/avocado-linux/tools/avocadoctl/configuration.md b/src/docs/avocado-linux/tools/avocadoctl/configuration.md index 73e0d09d..03c85ccb 100644 --- a/src/docs/avocado-linux/tools/avocadoctl/configuration.md +++ b/src/docs/avocado-linux/tools/avocadoctl/configuration.md @@ -26,51 +26,51 @@ stream_os_to_partition = false The `[avocado.ext]` section controls how extensions are stored and merged. -| Key | Type | Default | Description | -|-----|------|---------|-------------| -| `dir` | string | `/var/lib/avocado/images` | Directory where extension images are stored | -| `sysext_mutable` | string | `ephemeral` | Mutability mode for system extensions (sysext) overlaying `/usr` and `/opt` | -| `confext_mutable` | string | `ephemeral` | Mutability mode for configuration extensions (confext) overlaying `/etc` | -| `mutable` | string | - | **Deprecated.** Legacy option that applies to both sysext and confext. Use the specific options above instead. | +| Key | Type | Default | Description | +| ----------------- | ------ | ------------------------- | -------------------------------------------------------------------------------------------------------------- | +| `dir` | string | `/var/lib/avocado/images` | Directory where extension images are stored | +| `sysext_mutable` | string | `ephemeral` | Mutability mode for system extensions (sysext) overlaying `/usr` and `/opt` | +| `confext_mutable` | string | `ephemeral` | Mutability mode for configuration extensions (confext) overlaying `/etc` | +| `mutable` | string | - | **Deprecated.** Legacy option that applies to both sysext and confext. Use the specific options above instead. | ### Mutability Modes These values control how systemd-sysext and systemd-confext handle writes to the overlaid directories. -| Value | Description | -|-------|-------------| -| `no` | Overlaid directories are read-only | -| `auto` | Let systemd decide based on the underlying filesystem | -| `yes` | Overlaid directories are writable (persistent) | -| `import` | Import the upper directory contents into the base on unmerge | -| `ephemeral` | Overlaid directories are writable but changes are discarded on unmerge | -| `ephemeral-import` | Like `ephemeral`, but imports upper contents on unmerge | +| Value | Description | +| ------------------ | ---------------------------------------------------------------------- | +| `no` | Overlaid directories are read-only | +| `auto` | Let systemd decide based on the underlying filesystem | +| `yes` | Overlaid directories are writable (persistent) | +| `import` | Import the upper directory contents into the base on unmerge | +| `ephemeral` | Overlaid directories are writable but changes are discarded on unmerge | +| `ephemeral-import` | Like `ephemeral`, but imports upper contents on unmerge | ## General Settings The `[avocado]` section controls base paths and daemon communication. -| Key | Type | Default | Description | -|-----|------|---------|-------------| -| `runtimes_dir` | string | `/var/lib/avocado` | Base directory for runtimes, images, and the active symlink | -| `socket` | string | `unix:/run/avocado/avocadoctl.sock` | Varlink daemon socket address | +| Key | Type | Default | Description | +| -------------- | ------ | ----------------------------------- | ----------------------------------------------------------- | +| `runtimes_dir` | string | `/var/lib/avocado` | Base directory for runtimes, images, and the active symlink | +| `socket` | string | `unix:/run/avocado/avocadoctl.sock` | Varlink daemon socket address | ## Update Settings The `[avocado.update]` section controls OS update behavior. -| Key | Type | Default | Description | -|-----|------|---------|-------------| +| Key | Type | Default | Description | +| ------------------------ | ---- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `stream_os_to_partition` | bool | `false` | Stream OS bundle artifacts directly from HTTP to partitions without staging to disk. Reduces disk I/O and temporary storage but disables resumable downloads for the OS bundle. | ## Environment Variable Overrides Environment variables take precedence over config file values. -| Variable | Overrides | Description | -|----------|-----------|-------------| -| `AVOCADO_BASE_DIR` | `avocado.runtimes_dir` | Override the base directory for all avocado data | -| `AVOCADO_EXTENSIONS_PATH` | `avocado.ext.dir` | Override the extensions image directory | +| Variable | Overrides | Description | +| ------------------------- | ---------------------- | ------------------------------------------------ | +| `AVOCADO_BASE_DIR` | `avocado.runtimes_dir` | Override the base directory for all avocado data | +| `AVOCADO_EXTENSIONS_PATH` | `avocado.ext.dir` | Override the extensions image directory | ## Precedence Order diff --git a/src/docs/avocado-linux/tools/avocadoctl/os-bundles/bundle-format.md b/src/docs/avocado-linux/tools/avocadoctl/os-bundles/bundle-format.md index d8d0cd4d..1e4854a6 100644 --- a/src/docs/avocado-linux/tools/avocadoctl/os-bundles/bundle-format.md +++ b/src/docs/avocado-linux/tools/avocadoctl/os-bundles/bundle-format.md @@ -61,17 +61,17 @@ The `bundle.json` file inside an `.aos` archive describes how to apply the OS up ## Top-Level Fields -| Field | Type | Required | Description | -|-------|------|----------|-------------| -| `format_version` | integer | Yes | Bundle format version. | -| `platform` | string | Yes | Target hardware platform identifier. | -| `architecture` | string | Yes | Target CPU architecture (e.g., `aarch64`, `x86-64`). | -| `os_build_id` | string | Yes | Identifier for this rootfs build version. | -| `initramfs_build_id` | string | No | Identifier for this initramfs build version. | -| `update` | object | No | Update configuration. Omit if the bundle is metadata-only. | -| `verify` | object | No | Post-update verification for the rootfs. | -| `verify_initramfs` | object | No | Post-update verification for the initramfs. | -| `layout` | object | No | Partition layout for MBR-based targets. | +| Field | Type | Required | Description | +| -------------------- | ------- | -------- | ---------------------------------------------------------- | +| `format_version` | integer | Yes | Bundle format version. | +| `platform` | string | Yes | Target hardware platform identifier. | +| `architecture` | string | Yes | Target CPU architecture (e.g., `aarch64`, `x86-64`). | +| `os_build_id` | string | Yes | Identifier for this rootfs build version. | +| `initramfs_build_id` | string | No | Identifier for this initramfs build version. | +| `update` | object | No | Update configuration. Omit if the bundle is metadata-only. | +| `verify` | object | No | Post-update verification for the rootfs. | +| `verify_initramfs` | object | No | Post-update verification for the initramfs. | +| `layout` | object | No | Partition layout for MBR-based targets. | ## Slot Detection Strategies @@ -88,8 +88,8 @@ Reads a U-Boot environment variable to determine the active slot. } ``` -| Field | Description | -|-------|-------------| +| Field | Description | +| ----- | ------------------------------------------------------------------------------------------ | | `var` | U-Boot environment variable name containing the active slot identifier (e.g., "a" or "b"). | ### command @@ -103,8 +103,8 @@ Runs a shell command whose stdout output is the active slot identifier. } ``` -| Field | Description | -|-------|-------------| +| Field | Description | +| --------- | ----------------------------------------------------------------------------------------------------- | | `command` | Array of command and arguments to execute. The command's stdout is trimmed and used as the slot name. | ### sdboot-efi @@ -121,22 +121,22 @@ Uses systemd-boot EFI partition mappings. Maps slot names to EFI partition devic } ``` -| Field | Description | -|-------|-------------| +| Field | Description | +| ------------ | ------------------------------------------------ | | `partitions` | Map of slot names to EFI partition device paths. | ## Artifacts Each entry in `update.artifacts` describes a file to write to a partition. -| Field | Type | Required | Description | -|-------|------|----------|-------------| -| `name` | string | Yes | Artifact name (e.g., "rootfs", "initramfs"). | -| `file` | string | Yes | Filename within the `.aos` archive. | -| `sha256` | string | Yes | Expected SHA-256 hash of the artifact file. | -| `size` | integer | No | File size in bytes. | -| `slot_targets` | object | Yes | Map of slot names to target partitions. | -| `slot_targets.{slot}.partition` | string | Yes | Partition identifier (PARTLABEL for GPT, name for MBR layout). | +| Field | Type | Required | Description | +| ------------------------------- | ------- | -------- | -------------------------------------------------------------- | +| `name` | string | Yes | Artifact name (e.g., "rootfs", "initramfs"). | +| `file` | string | Yes | Filename within the `.aos` archive. | +| `sha256` | string | Yes | Expected SHA-256 hash of the artifact file. | +| `size` | integer | No | File size in bytes. | +| `slot_targets` | object | Yes | Map of slot names to target partitions. | +| `slot_targets.{slot}.partition` | string | Yes | Partition identifier (PARTLABEL for GPT, name for MBR layout). | ## Activation Actions @@ -195,24 +195,24 @@ The optional `update.rollback` array has the same format as `activate`. These ac The `verify` and `verify_initramfs` objects define how to confirm the OS update was successful after reboot. -| Field | Type | Description | -|-------|------|-------------| -| `type` | string | Verification type (e.g., `os-release`). | -| `field` | string | Field name to check in `/etc/os-release`. | +| Field | Type | Description | +| ---------- | ------ | ----------------------------------------------------------------------- | +| `type` | string | Verification type (e.g., `os-release`). | +| `field` | string | Field name to check in `/etc/os-release`. | | `expected` | string | Expected value. Update is considered successful when the field matches. | ## Partition Layout (MBR) The optional `layout` object is used on MBR-based systems where partitions are identified by offset rather than label. -| Field | Type | Description | -|-------|------|-------------| -| `device` | string | Block device path (e.g., `/dev/mmcblk0`). | -| `block_size` | integer | Optional block size in bytes. | -| `partitions` | array | List of partition definitions. | -| `partitions[].name` | string | Partition name for referencing in `slot_targets`. | -| `partitions[].offset` | number | Partition start offset. | -| `partitions[].offset_unit` | string | Unit for offset (e.g., `MiB`, `sectors`). | -| `partitions[].size` | number | Partition size. | -| `partitions[].size_unit` | string | Unit for size (e.g., `MiB`, `GiB`). | -| `partitions[].expand` | string | Optional expand strategy. | +| Field | Type | Description | +| -------------------------- | ------- | ------------------------------------------------- | +| `device` | string | Block device path (e.g., `/dev/mmcblk0`). | +| `block_size` | integer | Optional block size in bytes. | +| `partitions` | array | List of partition definitions. | +| `partitions[].name` | string | Partition name for referencing in `slot_targets`. | +| `partitions[].offset` | number | Partition start offset. | +| `partitions[].offset_unit` | string | Unit for offset (e.g., `MiB`, `sectors`). | +| `partitions[].size` | number | Partition size. | +| `partitions[].size_unit` | string | Unit for size (e.g., `MiB`, `GiB`). | +| `partitions[].expand` | string | Optional expand strategy. | diff --git a/src/docs/avocado-linux/tools/avocadoctl/overview.md b/src/docs/avocado-linux/tools/avocadoctl/overview.md index 5220b2b7..52c976ba 100644 --- a/src/docs/avocado-linux/tools/avocadoctl/overview.md +++ b/src/docs/avocado-linux/tools/avocadoctl/overview.md @@ -55,9 +55,9 @@ avocadoctl operates in a client-daemon model. The daemon listens on a Unix socke ## Global Flags -| Flag | Description | -|------|-------------| -| `-c, --config ` | Path to custom config file (default: `/etc/avocado/avocadoctl.conf`) | -| `-v, --verbose` | Enable verbose output | -| `-o, --output ` | Output format: `table` (default) or `json` | -| `--socket
` | Varlink daemon socket address (overrides config) | +| Flag | Description | +| ----------------------- | -------------------------------------------------------------------- | +| `-c, --config ` | Path to custom config file (default: `/etc/avocado/avocadoctl.conf`) | +| `-v, --verbose` | Enable verbose output | +| `-o, --output ` | Output format: `table` (default) or `json` | +| `--socket
` | Varlink daemon socket address (overrides config) | diff --git a/src/docs/avocado-linux/tools/avocadoctl/runtime-management/manifest-spec.md b/src/docs/avocado-linux/tools/avocadoctl/runtime-management/manifest-spec.md index 6c646f09..b7770b6a 100644 --- a/src/docs/avocado-linux/tools/avocadoctl/runtime-management/manifest-spec.md +++ b/src/docs/avocado-linux/tools/avocadoctl/runtime-management/manifest-spec.md @@ -61,23 +61,23 @@ The runtime manifest is a JSON file that describes a complete runtime configurat ## Field Reference -| Field | Type | Required | Description | -|-------|------|----------|-------------| -| `manifest_version` | integer | Yes | Schema version. `1` for extensions-only manifests, `2` adds `initramfs_build_id` support. | -| `id` | string | Yes | Unique identifier for this runtime, typically a UUID. Used as the directory name under `runtimes/`. | -| `built_at` | string | Yes | ISO-8601 timestamp of when the runtime was built. | -| `runtime` | object | Yes | Runtime identity. | -| `runtime.name` | string | Yes | Human-readable runtime name (e.g., "production", "dev"). | -| `runtime.version` | string | Yes | Semantic version of the runtime. | -| `extensions` | array | Yes | List of extension images included in this runtime. May be empty. | -| `extensions[].name` | string | Yes | Extension name. | -| `extensions[].version` | string | Yes | Extension version. | -| `extensions[].image_id` | string | No | UUIDv5 content-addressable image identifier. When present, the image file is `{image_id}.raw`. | -| `os_bundle` | object | No | Optional OS bundle reference for rootfs/initramfs updates. | -| `os_bundle.image_id` | string | Yes* | UUIDv5 identifier for the OS bundle image file. *Required if `os_bundle` is present. | -| `os_bundle.sha256` | string | Yes* | SHA-256 hash of the OS bundle `.raw` file for integrity verification. | -| `os_bundle.os_build_id` | string | No | Identifies the rootfs version. Compared against the running system's `AVOCADO_OS_BUILD_ID` to detect OS changes. | -| `os_bundle.initramfs_build_id` | string | No | Identifies the initramfs version. Requires `manifest_version` >= 2. | +| Field | Type | Required | Description | +| ------------------------------ | ------- | -------- | ---------------------------------------------------------------------------------------------------------------- | +| `manifest_version` | integer | Yes | Schema version. `1` for extensions-only manifests, `2` adds `initramfs_build_id` support. | +| `id` | string | Yes | Unique identifier for this runtime, typically a UUID. Used as the directory name under `runtimes/`. | +| `built_at` | string | Yes | ISO-8601 timestamp of when the runtime was built. | +| `runtime` | object | Yes | Runtime identity. | +| `runtime.name` | string | Yes | Human-readable runtime name (e.g., "production", "dev"). | +| `runtime.version` | string | Yes | Semantic version of the runtime. | +| `extensions` | array | Yes | List of extension images included in this runtime. May be empty. | +| `extensions[].name` | string | Yes | Extension name. | +| `extensions[].version` | string | Yes | Extension version. | +| `extensions[].image_id` | string | No | UUIDv5 content-addressable image identifier. When present, the image file is `{image_id}.raw`. | +| `os_bundle` | object | No | Optional OS bundle reference for rootfs/initramfs updates. | +| `os_bundle.image_id` | string | Yes\* | UUIDv5 identifier for the OS bundle image file. \*Required if `os_bundle` is present. | +| `os_bundle.sha256` | string | Yes\* | SHA-256 hash of the OS bundle `.raw` file for integrity verification. | +| `os_bundle.os_build_id` | string | No | Identifies the rootfs version. Compared against the running system's `AVOCADO_OS_BUILD_ID` to detect OS changes. | +| `os_bundle.initramfs_build_id` | string | No | Identifies the initramfs version. Requires `manifest_version` >= 2. | ## Image ID Scheme @@ -99,7 +99,7 @@ When `image_id` is absent (legacy): ## Manifest Version History -| Version | Changes | -|---------|---------| -| 1 | Initial format with extensions and optional `os_bundle` (supports `os_build_id`). | -| 2 | Adds `initramfs_build_id` to `os_bundle` for independent initramfs version tracking. | +| Version | Changes | +| ------- | ------------------------------------------------------------------------------------ | +| 1 | Initial format with extensions and optional `os_bundle` (supports `os_build_id`). | +| 2 | Adds `initramfs_build_id` to `os_bundle` for independent initramfs version tracking. | diff --git a/src/docs/avocado-linux/tools/avocadoctl/varlink-api/org-avocado-extensions.md b/src/docs/avocado-linux/tools/avocadoctl/varlink-api/org-avocado-extensions.md index 32b507e5..3792b9cb 100644 --- a/src/docs/avocado-linux/tools/avocadoctl/varlink-api/org-avocado-extensions.md +++ b/src/docs/avocado-linux/tools/avocadoctl/varlink-api/org-avocado-extensions.md @@ -70,28 +70,28 @@ error CommandFailed (command: string, message: string) Represents an extension image or directory available on the filesystem. -| Field | Type | Description | -|-------|------|-------------| -| `name` | `string` | Extension name (derived from the image filename) | -| `version` | `?string` | Extension version, if embedded in the image metadata | -| `path` | `string` | Absolute path to the extension image or directory | -| `isSysext` | `bool` | `true` if this is a system extension (overlays `/usr`) | -| `isConfext` | `bool` | `true` if this is a configuration extension (overlays `/etc`) | -| `isDirectory` | `bool` | `true` if the extension is a plain directory rather than an image file | +| Field | Type | Description | +| ------------- | --------- | ---------------------------------------------------------------------- | +| `name` | `string` | Extension name (derived from the image filename) | +| `version` | `?string` | Extension version, if embedded in the image metadata | +| `path` | `string` | Absolute path to the extension image or directory | +| `isSysext` | `bool` | `true` if this is a system extension (overlays `/usr`) | +| `isConfext` | `bool` | `true` if this is a configuration extension (overlays `/etc`) | +| `isDirectory` | `bool` | `true` if the extension is a plain directory rather than an image file | ### ExtensionStatus Represents the current status of an extension, including whether it is merged into the running system. -| Field | Type | Description | -|-------|------|-------------| -| `name` | `string` | Extension name | -| `version` | `?string` | Extension version | -| `isSysext` | `bool` | `true` if this is a system extension | -| `isConfext` | `bool` | `true` if this is a configuration extension | -| `isMerged` | `bool` | `true` if the extension is currently merged into the root filesystem | -| `origin` | `?string` | Origin identifier (e.g., the TUF target name) | -| `imageId` | `?string` | Image digest or build identifier | +| Field | Type | Description | +| ----------- | --------- | -------------------------------------------------------------------- | +| `name` | `string` | Extension name | +| `version` | `?string` | Extension version | +| `isSysext` | `bool` | `true` if this is a system extension | +| `isConfext` | `bool` | `true` if this is a configuration extension | +| `isMerged` | `bool` | `true` if the extension is currently merged into the root filesystem | +| `origin` | `?string` | Origin identifier (e.g., the TUF target name) | +| `imageId` | `?string` | Image digest or build identifier | ## Methods @@ -105,8 +105,8 @@ List all available extensions in the extensions directory. **Returns:** -| Field | Type | Description | -|-------|------|-------------| +| Field | Type | Description | +| ------------ | ------------- | ------------------------------------ | | `extensions` | `[]Extension` | Array of available extension objects | **C Example:** @@ -156,10 +156,10 @@ Merge all enabled extensions into the running system using `systemd-sysext` and **Returns (streaming):** -| Field | Type | Description | -|-------|------|-------------| +| Field | Type | Description | +| --------- | -------- | -------------------------------------------- | | `message` | `string` | Progress message describing the current step | -| `done` | `bool` | `true` on the final reply | +| `done` | `bool` | `true` on the final reply | **Streaming:** Yes. Call with `VARLINK_CALL_MORE` to receive progress updates. @@ -206,16 +206,16 @@ Unmerge extensions from the running system. **Parameters:** -| Field | Type | Description | -|-------|------|-------------| +| Field | Type | Description | +| --------- | ------- | ------------------------------------------------------------------ | | `unmount` | `?bool` | If `true`, also unmount the extension images. Defaults to `false`. | **Returns (streaming):** -| Field | Type | Description | -|-------|------|-------------| +| Field | Type | Description | +| --------- | -------- | -------------------------------------------- | | `message` | `string` | Progress message describing the current step | -| `done` | `bool` | `true` on the final reply | +| `done` | `bool` | `true` on the final reply | **Streaming:** Yes. Call with `VARLINK_CALL_MORE` to receive progress updates. @@ -265,10 +265,10 @@ Unmerge and then re-merge all enabled extensions. This is equivalent to calling **Returns (streaming):** -| Field | Type | Description | -|-------|------|-------------| +| Field | Type | Description | +| --------- | -------- | -------------------------------------------- | | `message` | `string` | Progress message describing the current step | -| `done` | `bool` | `true` on the final reply | +| `done` | `bool` | `true` on the final reply | **Streaming:** Yes. Call with `VARLINK_CALL_MORE` to receive progress updates. @@ -315,17 +315,17 @@ Enable one or more extensions for a specific OS release version. Enabling an ext **Parameters:** -| Field | Type | Description | -|-------|------|-------------| -| `extensions` | `[]string` | List of extension names to enable | -| `osRelease` | `?string` | Target OS release version. If omitted, the current OS release is used. | +| Field | Type | Description | +| ------------ | ---------- | ---------------------------------------------------------------------- | +| `extensions` | `[]string` | List of extension names to enable | +| `osRelease` | `?string` | Target OS release version. If omitted, the current OS release is used. | **Returns:** -| Field | Type | Description | -|-------|------|-------------| -| `enabled` | `int` | Number of extensions successfully enabled | -| `failed` | `int` | Number of extensions that failed to enable | +| Field | Type | Description | +| --------- | ----- | ------------------------------------------ | +| `enabled` | `int` | Number of extensions successfully enabled | +| `failed` | `int` | Number of extensions that failed to enable | **C Example:** @@ -371,18 +371,18 @@ Disable extensions for a specific OS release version. Disabled extensions will n **Parameters:** -| Field | Type | Description | -|-------|------|-------------| -| `extensions` | `?[]string` | List of extension names to disable. Omit if using `all`. | -| `all` | `?bool` | If `true`, disable all extensions. | -| `osRelease` | `?string` | Target OS release version. If omitted, the current OS release is used. | +| Field | Type | Description | +| ------------ | ----------- | ---------------------------------------------------------------------- | +| `extensions` | `?[]string` | List of extension names to disable. Omit if using `all`. | +| `all` | `?bool` | If `true`, disable all extensions. | +| `osRelease` | `?string` | Target OS release version. If omitted, the current OS release is used. | **Returns:** -| Field | Type | Description | -|-------|------|-------------| -| `disabled` | `int` | Number of extensions successfully disabled | -| `failed` | `int` | Number of extensions that failed to disable | +| Field | Type | Description | +| ---------- | ----- | ------------------------------------------- | +| `disabled` | `int` | Number of extensions successfully disabled | +| `failed` | `int` | Number of extensions that failed to disable | **C Example:** @@ -420,8 +420,8 @@ Show the current merge status of all extensions. **Returns:** -| Field | Type | Description | -|-------|------|-------------| +| Field | Type | Description | +| ------------ | ------------------- | --------------------------------- | | `extensions` | `[]ExtensionStatus` | Array of extension status objects | **C Example:** @@ -465,9 +465,9 @@ varlink_object_unref(parameters); Returned when a referenced extension name does not exist in the extensions directory. -| Parameter | Type | Description | -|-----------|------|-------------| -| `name` | `string` | The extension name that was not found | +| Parameter | Type | Description | +| --------- | -------- | ------------------------------------- | +| `name` | `string` | The extension name that was not found | **Trigger:** Passing an unknown extension name to `Enable` or `Disable`. @@ -475,9 +475,9 @@ Returned when a referenced extension name does not exist in the extensions direc Returned when the merge operation fails. -| Parameter | Type | Description | -|-----------|------|-------------| -| `reason` | `string` | Human-readable description of the failure | +| Parameter | Type | Description | +| --------- | -------- | ----------------------------------------- | +| `reason` | `string` | Human-readable description of the failure | **Trigger:** `systemd-sysext merge` or `systemd-confext merge` exits with a non-zero status, or an internal error occurs during the merge process. @@ -485,9 +485,9 @@ Returned when the merge operation fails. Returned when the unmerge operation fails. -| Parameter | Type | Description | -|-----------|------|-------------| -| `reason` | `string` | Human-readable description of the failure | +| Parameter | Type | Description | +| --------- | -------- | ----------------------------------------- | +| `reason` | `string` | Human-readable description of the failure | **Trigger:** `systemd-sysext unmerge` or `systemd-confext unmerge` exits with a non-zero status. @@ -495,8 +495,8 @@ Returned when the unmerge operation fails. Returned when the extension configuration is invalid. -| Parameter | Type | Description | -|-----------|------|-------------| +| Parameter | Type | Description | +| --------- | -------- | ---------------------------------------- | | `message` | `string` | Description of the configuration problem | **Trigger:** Malformed extension metadata, missing required fields, or incompatible OS release versions. @@ -505,9 +505,9 @@ Returned when the extension configuration is invalid. Returned when an external command executed during extension management fails. -| Parameter | Type | Description | -|-----------|------|-------------| -| `command` | `string` | The command that failed | +| Parameter | Type | Description | +| --------- | -------- | ----------------------------------------- | +| `command` | `string` | The command that failed | | `message` | `string` | The command's error output or exit status | **Trigger:** Any subprocess invoked during merge, unmerge, enable, or disable operations exits with a non-zero status. diff --git a/src/docs/avocado-linux/tools/avocadoctl/varlink-api/org-avocado-hitl.md b/src/docs/avocado-linux/tools/avocadoctl/varlink-api/org-avocado-hitl.md index 65588da2..5b6ebdce 100644 --- a/src/docs/avocado-linux/tools/avocadoctl/varlink-api/org-avocado-hitl.md +++ b/src/docs/avocado-linux/tools/avocadoctl/varlink-api/org-avocado-hitl.md @@ -34,11 +34,11 @@ Mount one or more extension directories from an NFS server. The server must expo **Parameters:** -| Field | Type | Description | -|-------|------|-------------| -| `serverIp` | `string` | IP address of the NFS server | -| `serverPort` | `?string` | NFS server port. Defaults to the standard NFS port if omitted. | -| `extensions` | `[]string` | List of extension names to mount from the server | +| Field | Type | Description | +| ------------ | ---------- | -------------------------------------------------------------- | +| `serverIp` | `string` | IP address of the NFS server | +| `serverPort` | `?string` | NFS server port. Defaults to the standard NFS port if omitted. | +| `extensions` | `[]string` | List of extension names to mount from the server | **Returns:** Empty on success. @@ -89,8 +89,8 @@ Unmount previously mounted NFS extensions. **Parameters:** -| Field | Type | Description | -|-------|------|-------------| +| Field | Type | Description | +| ------------ | ---------- | ---------------------------------- | | `extensions` | `[]string` | List of extension names to unmount | **Returns:** Empty on success. @@ -139,10 +139,10 @@ varlink_object_unref(parameters); Returned when an NFS mount operation fails for a specific extension. -| Parameter | Type | Description | -|-----------|------|-------------| +| Parameter | Type | Description | +| ----------- | -------- | --------------------------------------- | | `extension` | `string` | The extension name that failed to mount | -| `reason` | `string` | Human-readable failure description | +| `reason` | `string` | Human-readable failure description | **Trigger:** NFS server unreachable, export not found, permission denied, or filesystem error during mount. @@ -150,9 +150,9 @@ Returned when an NFS mount operation fails for a specific extension. Returned when an NFS unmount operation fails for a specific extension. -| Parameter | Type | Description | -|-----------|------|-------------| +| Parameter | Type | Description | +| ----------- | -------- | ----------------------------------------- | | `extension` | `string` | The extension name that failed to unmount | -| `reason` | `string` | Human-readable failure description | +| `reason` | `string` | Human-readable failure description | **Trigger:** Extension not currently mounted, busy filesystem preventing unmount, or filesystem error during unmount. diff --git a/src/docs/avocado-linux/tools/avocadoctl/varlink-api/org-avocado-root-authority.md b/src/docs/avocado-linux/tools/avocadoctl/varlink-api/org-avocado-root-authority.md index c109e3c8..706f88fc 100644 --- a/src/docs/avocado-linux/tools/avocadoctl/varlink-api/org-avocado-root-authority.md +++ b/src/docs/avocado-linux/tools/avocadoctl/varlink-api/org-avocado-root-authority.md @@ -41,21 +41,21 @@ error ParseFailed (reason: string) A single signing key trusted by this device. -| Field | Type | Description | -|-------|------|-------------| -| `keyId` | `string` | Hex-encoded key identifier (SHA-256 of the canonical key representation) | -| `keyType` | `string` | Key algorithm (e.g., `ed25519`, `ecdsa-sha2-nistp256`, `rsa`) | -| `roles` | `[]string` | TUF roles this key is authorized for (e.g., `root`, `targets`, `snapshot`, `timestamp`) | +| Field | Type | Description | +| --------- | ---------- | --------------------------------------------------------------------------------------- | +| `keyId` | `string` | Hex-encoded key identifier (SHA-256 of the canonical key representation) | +| `keyType` | `string` | Key algorithm (e.g., `ed25519`, `ecdsa-sha2-nistp256`, `rsa`) | +| `roles` | `[]string` | TUF roles this key is authorized for (e.g., `root`, `targets`, `snapshot`, `timestamp`) | ### RootAuthorityInfo The parsed contents of the TUF root metadata. -| Field | Type | Description | -|-------|------|-------------| -| `version` | `int` | Root metadata version number. Increments on each root key rotation. | -| `expires` | `string` | ISO 8601 expiration timestamp of the root metadata | -| `keys` | `[]TrustedKey` | All trusted signing keys declared in the root metadata | +| Field | Type | Description | +| --------- | -------------- | ------------------------------------------------------------------- | +| `version` | `int` | Root metadata version number. Increments on each root key rotation. | +| `expires` | `string` | ISO 8601 expiration timestamp of the root metadata | +| `keys` | `[]TrustedKey` | All trusted signing keys declared in the root metadata | ## Methods @@ -69,8 +69,8 @@ Return the device's current trust anchor information. If no `root.json` has been **Returns:** -| Field | Type | Description | -|-------|------|-------------| +| Field | Type | Description | +| ----------- | -------------------- | -------------------------------------------------------------- | | `authority` | `?RootAuthorityInfo` | Trust anchor information, or `null` if no root metadata exists | **C Example:** @@ -163,8 +163,8 @@ Returned when no `root.json` file exists at `/var/lib/avocado/metadata/root.json Returned when `root.json` exists but cannot be parsed. -| Parameter | Type | Description | -|-----------|------|-------------| -| `reason` | `string` | Description of the parse error | +| Parameter | Type | Description | +| --------- | -------- | ------------------------------ | +| `reason` | `string` | Description of the parse error | **Trigger:** Corrupt or malformed `root.json`, unsupported metadata version, or missing required fields in the root metadata file. diff --git a/src/docs/avocado-linux/tools/avocadoctl/varlink-api/org-avocado-runtimes.md b/src/docs/avocado-linux/tools/avocadoctl/varlink-api/org-avocado-runtimes.md index 07f7ff92..44badd4e 100644 --- a/src/docs/avocado-linux/tools/avocadoctl/varlink-api/org-avocado-runtimes.md +++ b/src/docs/avocado-linux/tools/avocadoctl/varlink-api/org-avocado-runtimes.md @@ -70,35 +70,35 @@ error UpdateFailed (reason: string) Basic identity of a runtime. -| Field | Type | Description | -|-------|------|-------------| -| `name` | `string` | Runtime name | +| Field | Type | Description | +| --------- | -------- | ---------------------- | +| `name` | `string` | Runtime name | | `version` | `string` | Runtime version string | ### ManifestExtension An extension declared in the runtime manifest. -| Field | Type | Description | -|-------|------|-------------| -| `name` | `string` | Extension name | -| `version` | `string` | Extension version string | +| Field | Type | Description | +| --------- | --------- | ------------------------------------------------------------- | +| `name` | `string` | Extension name | +| `version` | `string` | Extension version string | | `imageId` | `?string` | Image digest used to verify the downloaded extension artifact | ### Runtime Full description of a runtime, including its manifest metadata, constituent extensions, and activation state. -| Field | Type | Description | -|-------|------|-------------| -| `id` | `string` | Unique runtime identifier (hex digest) | -| `manifestVersion` | `int` | Manifest schema version | -| `builtAt` | `string` | ISO 8601 timestamp of when the runtime was built | -| `runtime` | `RuntimeInfo` | Runtime name and version | -| `extensions` | `[]ManifestExtension` | Extensions included in this runtime | -| `active` | `bool` | `true` if this is the currently active runtime | -| `osBuildId` | `?string` | OS image build identifier. A change in this value triggers an OS update on activation. | -| `initramfsBuildId` | `?string` | Initramfs build identifier | +| Field | Type | Description | +| ------------------ | --------------------- | -------------------------------------------------------------------------------------- | +| `id` | `string` | Unique runtime identifier (hex digest) | +| `manifestVersion` | `int` | Manifest schema version | +| `builtAt` | `string` | ISO 8601 timestamp of when the runtime was built | +| `runtime` | `RuntimeInfo` | Runtime name and version | +| `extensions` | `[]ManifestExtension` | Extensions included in this runtime | +| `active` | `bool` | `true` if this is the currently active runtime | +| `osBuildId` | `?string` | OS image build identifier. A change in this value triggers an OS update on activation. | +| `initramfsBuildId` | `?string` | Initramfs build identifier | ## Methods @@ -112,8 +112,8 @@ List all available runtimes, both staged and active. **Returns:** -| Field | Type | Description | -|-------|------|-------------| +| Field | Type | Description | +| ---------- | ----------- | --------------------------- | | `runtimes` | `[]Runtime` | Array of all known runtimes | **C Example:** @@ -165,18 +165,18 @@ Stage a new runtime by downloading its manifest and artifacts from a TUF reposit **Parameters:** -| Field | Type | Description | -|-------|------|-------------| -| `url` | `string` | TUF repository URL | -| `authToken` | `?string` | Optional bearer token for authenticated endpoints | +| Field | Type | Description | +| -------------- | --------- | ------------------------------------------------------------------------------------------------------------ | +| `url` | `string` | TUF repository URL | +| `authToken` | `?string` | Optional bearer token for authenticated endpoints | | `artifactsUrl` | `?string` | Optional separate URL for artifact downloads. If omitted, artifacts are fetched from the TUF repository URL. | **Returns (streaming):** -| Field | Type | Description | -|-------|------|-------------| -| `message` | `string` | Progress message | -| `done` | `bool` | `true` on the final reply | +| Field | Type | Description | +| --------- | ---------- | ---------------------------------------------------------- | +| `message` | `string` | Progress message | +| `done` | `bool` | `true` on the final reply | | `runtime` | `?Runtime` | The staged runtime object, present only in the final reply | **Streaming:** Yes. Call with `VARLINK_CALL_MORE` to receive download and verification progress. @@ -242,16 +242,16 @@ Stage a new runtime from a local manifest file. The manifest references artifact **Parameters:** -| Field | Type | Description | -|-------|------|-------------| +| Field | Type | Description | +| -------------- | -------- | ---------------------------------------- | | `manifestPath` | `string` | Absolute path to the local manifest file | **Returns (streaming):** -| Field | Type | Description | -|-------|------|-------------| -| `message` | `string` | Progress message | -| `done` | `bool` | `true` on the final reply | +| Field | Type | Description | +| --------- | ---------- | ---------------------------------------------------------- | +| `message` | `string` | Progress message | +| `done` | `bool` | `true` on the final reply | | `runtime` | `?Runtime` | The staged runtime object, present only in the final reply | **Streaming:** Yes. Call with `VARLINK_CALL_MORE` to receive progress updates. @@ -309,9 +309,9 @@ Remove a staged runtime by its ID or an unambiguous ID prefix. **Parameters:** -| Field | Type | Description | -|-------|------|-------------| -| `id` | `string` | Runtime ID or unique prefix | +| Field | Type | Description | +| ----- | -------- | --------------------------- | +| `id` | `string` | Runtime ID or unique prefix | **Returns:** Empty on success. @@ -362,17 +362,17 @@ Activate a staged runtime. If the runtime's `osBuildId` differs from the current **Parameters:** -| Field | Type | Description | -|-------|------|-------------| -| `id` | `string` | Runtime ID or unique prefix | +| Field | Type | Description | +| ----- | -------- | --------------------------- | +| `id` | `string` | Runtime ID or unique prefix | **Returns (streaming):** -| Field | Type | Description | -|-------|------|-------------| -| `message` | `string` | Progress message (e.g., writing OS image, enabling extensions) | -| `done` | `bool` | `true` on the final reply | -| `runtime` | `?Runtime` | The activated runtime object, present only in the final reply | +| Field | Type | Description | +| --------- | ---------- | -------------------------------------------------------------- | +| `message` | `string` | Progress message (e.g., writing OS image, enabling extensions) | +| `done` | `bool` | `true` on the final reply | +| `runtime` | `?Runtime` | The activated runtime object, present only in the final reply | **Streaming:** Yes. Call with `VARLINK_CALL_MORE` to receive progress updates. This is especially useful during OS updates, which may take significant time. @@ -440,14 +440,14 @@ Inspect the details of a specific runtime. If `id` is omitted, the currently act **Parameters:** -| Field | Type | Description | -|-------|------|-------------| -| `id` | `?string` | Runtime ID or unique prefix. Omit to inspect the active runtime. | +| Field | Type | Description | +| ----- | --------- | ---------------------------------------------------------------- | +| `id` | `?string` | Runtime ID or unique prefix. Omit to inspect the active runtime. | **Returns:** -| Field | Type | Description | -|-------|------|-------------| +| Field | Type | Description | +| --------- | --------- | ----------------------- | | `runtime` | `Runtime` | The full runtime object | **C Example:** @@ -519,9 +519,9 @@ varlink_object_unref(parameters); Returned when the specified runtime ID does not match any known runtime. -| Parameter | Type | Description | -|-----------|------|-------------| -| `id` | `string` | The ID that was not found | +| Parameter | Type | Description | +| --------- | -------- | ------------------------- | +| `id` | `string` | The ID that was not found | **Trigger:** Passing an unknown ID to `Remove`, `Activate`, or `Inspect`. @@ -529,9 +529,9 @@ Returned when the specified runtime ID does not match any known runtime. Returned when the specified ID prefix matches more than one runtime. The response includes the list of matching candidate IDs so the caller can present them to the user or retry with a longer prefix. -| Parameter | Type | Description | -|-----------|------|-------------| -| `id` | `string` | The ambiguous prefix | +| Parameter | Type | Description | +| ------------ | ---------- | --------------------------------- | +| `id` | `string` | The ambiguous prefix | | `candidates` | `[]string` | Full IDs of all matching runtimes | **Trigger:** Passing a short ID prefix to `Remove`, `Activate`, or `Inspect` that matches multiple runtimes. @@ -548,9 +548,9 @@ Returned when attempting to remove the currently active runtime. The active runt Returned when staging a new runtime fails during download, verification, or installation. -| Parameter | Type | Description | -|-----------|------|-------------| -| `reason` | `string` | Human-readable failure description | +| Parameter | Type | Description | +| --------- | -------- | ---------------------------------- | +| `reason` | `string` | Human-readable failure description | **Trigger:** TUF metadata verification failure, artifact download error, disk space exhaustion, or corrupt manifest in `AddFromUrl` or `AddFromManifest`. @@ -558,8 +558,8 @@ Returned when staging a new runtime fails during download, verification, or inst Returned when the OS update triggered by `Activate` fails. -| Parameter | Type | Description | -|-----------|------|-------------| -| `reason` | `string` | Human-readable failure description | +| Parameter | Type | Description | +| --------- | -------- | ---------------------------------- | +| `reason` | `string` | Human-readable failure description | **Trigger:** OS image write failure, bootloader configuration error, or extension enable/merge failure during `Activate`. diff --git a/src/docs/avocado-linux/tools/avocadoctl/varlink-api/overview.md b/src/docs/avocado-linux/tools/avocadoctl/varlink-api/overview.md index 0643d4fc..8493cb57 100644 --- a/src/docs/avocado-linux/tools/avocadoctl/varlink-api/overview.md +++ b/src/docs/avocado-linux/tools/avocadoctl/varlink-api/overview.md @@ -168,9 +168,9 @@ if (varlink_reply_is_error(reply, &error_name)) { ## Available Interfaces -| Interface | Description | -|-----------|-------------| -| [org.avocado.Extensions](./org-avocado-extensions) | Extension management (merge, unmerge, enable, disable) | -| [org.avocado.Runtimes](./org-avocado-runtimes) | Runtime lifecycle (add, activate, remove, inspect) | -| [org.avocado.Hitl](./org-avocado-hitl) | Hardware-in-the-loop NFS testing | -| [org.avocado.RootAuthority](./org-avocado-root-authority) | TUF trust anchor information | +| Interface | Description | +| --------------------------------------------------------- | ------------------------------------------------------ | +| [org.avocado.Extensions](./org-avocado-extensions) | Extension management (merge, unmerge, enable, disable) | +| [org.avocado.Runtimes](./org-avocado-runtimes) | Runtime lifecycle (add, activate, remove, inspect) | +| [org.avocado.Hitl](./org-avocado-hitl) | Hardware-in-the-loop NFS testing | +| [org.avocado.RootAuthority](./org-avocado-root-authority) | TUF trust anchor information |