Skip to content

Add provision --dry-run and host mount export - #390

Open
jetm wants to merge 15 commits into
mainfrom
avocado-flash-engine-guards/avocado-provision-parity
Open

jetm wants to merge 15 commits into
mainfrom
avocado-flash-engine-guards/avocado-provision-parity

Conversation

@jetm

@jetm jetm commented Nov 12, 2026 •

Copy link
Copy Markdown
Contributor

Problem

Profiles that guard against writing a mounted disk need the host's mount table, and operators need a dry run that runs every guard and writes nothing. avocado provision provided neither.

Solution

Bind a read-only copy of the host mount table into the provision container, export AVOCADO_PROVISION_HOST_MOUNTS, and add --dry-run, refused for a profile whose stone manifest does not declare config.dry_run: true.

Key changes

  • src/utils/host_mounts.rs: private 0600 copy of /proc/self/mounts with symlink sources rewritten, bound read-only at a fixed path; left unset on Docker Desktop, with --runs-on and under VM routing.
  • --dry-run on provision and runtime provision exports AVOCADO_PROVISION_DRY_RUN=1 after any --env, and skips the host-side SD burn.
  • The dry-run gate refuses an undeclared profile, a custom stone manifest, and a manifest it cannot read, before the provisioning container starts.
  • Docs: the i.MX93 guide uses avocado provision; the new variables are documented.

Reviewer notes

  • cargo test for host_mounts, provision and profiles passes, with fmt and clippy clean. Nothing ran against a real container.
  • Known and not fixed here: a dry run still writes the provision stamp and copies state back; the mount table is snapshotted before the container starts, so a card inserted later is not in it; \040-escaped sources are not decoded.
  • Feedback wanted: whether AVOCADO_PROVISION_PROFILE from --env winning over --profile is the order you want, and the gate's fail-closed cases.

Dependency

This depends on the avocado-flash change in avocado-linux/meta-avocado#632 (provision safe-disk guards and the stone launcher), which is stacked on meta-avocado#591. The guards in that PR read the host mount table this PR exports, so merge order is #632 with #591, then this stack.

jetm added 7 commits November 11, 2026 19:21
--force runs the provision container with interactive: false, so the
script has no TTY. A script that wants the operator to confirm an
erasing flash before it starts cannot tell a --force run (operator
already confirmed) from a piped or unattended run (nobody confirmed):
both look like "no terminal".

Export AVOCADO_PROVISION_FORCE on every provision run, "1" with --force
and "0" without, next to the other AVOCADO_PROVISION_* variables. It is
inserted after the --env merge so a value passed with --env cannot claim
a confirmation that did not happen. The insert lives in a small helper
so the value for both flag states is unit-tested; the env map is
otherwise assembled inline in execute().

Scripts that do not read the variable are unaffected. A script that does
read it should treat "0" with no terminal as unconfirmed and refuse to
run the destructive step, so such a script now refuses a piped run
without --force.

Signed-off-by: Javier Tia <javier@peridio.com>
The i.MX93 hardware guide still tells users to write cards with the
avocado-flash script, while the provision flow now covers the same
ground through the CLI. Users following the old guide bypass the
guards that the provision path enforces, and they have no documented
way to preview a destructive write, pick the upgrade task to keep /var
intact, or understand why the mounted-device check only warns when run
from the SDK container.

Point the guide at avocado provision and describe the pieces a user
needs to make it work: dry-run support, the privileged container
requirement for USB profiles, and the host mount table binding that
lets the mounted-device check see host mounts. Document the
corresponding AVOCADO_PROVISION_DRY_RUN, AVOCADO_PROVISION_HOST_MOUNTS
and AVOCADO_PROVISION_FWUP_TASK variables in the provisioning
references so script authors know they exist and which profiles honour
them. Note that some of these features depend on a CLI release that
carries the matching change, so readers are not surprised by older
versions.

Signed-off-by: Javier Tia <javier@peridio.com>
The provisioning scripts refuse to write to a disk that is currently
mounted. Inside the provision container, /proc/self/mounts shows only
the container's own mounts, so a card that the host has mounted looks
free. A user could therefore overwrite a mounted disk without any
warning from the safety check.

Take a private, owner-only copy of the host mount table and bind it
read-only into the container, then point the provisioning library at it
through an environment variable. Symlink sources such as by-uuid paths
are rewritten to kernel device names, since the container's /dev
differs and cannot resolve them. The copy is held for the duration of
the run and removed when it ends.

Only export the table for a local run against a native Docker daemon,
as that is the only case where the container shares a kernel with the
disk being written. Docker Desktop, the avocado-vm and --runs-on all
execute the container elsewhere, so the local table would describe the
wrong host. Always clear any value supplied through --env so a caller
cannot redirect the check at a file of their choosing, or leave it set
when no table was bound.

Signed-off-by: Javier Tia <javier@peridio.com>
Currently there is no way to exercise a provision script without
touching the target. Users who want to validate a runtime or script
change must either write a real device or hand-edit the script, and on
Docker Desktop the host-side SD card burn runs unconditionally after
the container finishes. That makes it easy to overwrite a removable
disk when only a rehearsal was intended.

Add a --dry-run option to both `avocado provision` and `avocado
runtime provision`. The flag exports AVOCADO_PROVISION_DRY_RUN=1 to the
provision script so it can skip its destructive steps, and it also
suppresses the host-side burn that the CLI performs itself. The
variable is set after user-supplied --env values so that a stray
--env AVOCADO_PROVISION_DRY_RUN=0 cannot turn a dry run into a real
write. Without the flag nothing is exported, leaving any user value
untouched.

The option is rejected together with --list, since listing does not
provision anything and the combination has no meaning, consistent with
how the other provisioning options are handled.

Signed-off-by: Javier Tia <javier@peridio.com>
Currently --dry-run is passed to the provision script through the
AVOCADO_PROVISION_DRY_RUN environment variable, but nothing verifies
that the chosen profile's script actually honors it. A script that
ignores the variable runs normally and writes to the target device,
so a user who asked for a safe preview can end up flashing hardware.

Read the stone manifest before any container, ssh probe or stamp check
is started, and require the selected profile to declare
`config.dry_run: true`. Only a literal boolean true counts, so absent,
false, null and non-bool values are all refused. When no profile is
given, resolve the manifest's default provision profile, since that is
the one that would be run. If the manifest cannot be read, refuse as
well, because support cannot be verified and failing closed is safer
than risking a write.

Place the check in the shared runtime provision path so that both
`avocado provision` and `avocado runtime provision` are covered by a
single gate. The manifest is read with the same read-only one-shot
container that `provision --list` already uses, so no new mechanism is
introduced. The validation logic is kept pure over the manifest text so
it can be tested without docker.

Signed-off-by: Javier Tia <javier@peridio.com>
The --dry-run gate checked support using only the --profile flag. The
provisioning script, however, reads AVOCADO_PROVISION_PROFILE from the
effective environment, so that variable takes precedence at run time.
The gate could therefore approve one profile while the script ran
another, defeating the purpose of the guard.

The gate also only reads the SDK's default stone manifest. When a
runtime sets a custom manifest, through its `stone_manifest` config or
an AVOCADO_STONE_MANIFEST variable, the gate verified a different file
than the one the run would use and could give a false assurance.

Add a container-free preflight step ahead of the manifest read. It
resolves the profile the same way the script does, with the environment
winning over the flag and an empty value counting as unset. It also
refuses outright when a custom manifest is in play, since support
cannot be verified there. Refusing is safer than guessing, and the user
can still run without --dry-run or use the default manifest. Keeping
the logic separate from the container work lets it be unit tested
without starting anything.

Signed-off-by: Javier Tia <javier@peridio.com>
A dry run of runtime provisioning still copied the container's state file over the host's, wrote the provision stamp, and reported "Successfully provisioned". This left the host claiming the runtime was provisioned when nothing had been written, so later stamp-based checks would skip real provisioning.

Separately, the mount table in /proc/self/mounts encodes spaces, tabs, newlines and backslashes in the device field as octal escapes. Resolving a by-label symlink such as "My\040Card" failed because the escaped text was passed to the filesystem verbatim, and a resolved name containing such characters would have split into several fields in the rewritten table.

Gate the state copy, the stamp and the success message on the dry-run flag, and report that a dry run wrote nothing. Decode the escapes before resolving a source and re-encode the resolved name, so each device stays a single field and an unresolvable source keeps its original text. Unrecognised escapes are left as written to avoid corrupting entries that are not valid escapes.

Signed-off-by: Javier Tia <javier@peridio.com>
Comment thread src/commands/profiles.rs Resolved
Comment thread src/commands/runtime/provision.rs Resolved
Comment thread src/commands/profiles.rs Resolved
Comment thread docs/container-dev/hardware-imx93.md Resolved
Comment thread src/commands/profiles.rs Resolved
jetm added 7 commits November 13, 2026 14:28
A leftover `"""` sat in the middle of the ensure_dry_run_supported doc
comment and rendered into rustdoc as literal text.

Signed-off-by: Javier Tia <javier@peridio.com>
… loads

The --dry-run gate read the SDK's stone-<target>.json, but the provision
hook runs `stone provision` with no -m flag. Stone loads the first
manifest.json across its -i dirs: AVOCADO_STONE_INCLUDE_PATHS first,
then the runtime's stone dir that `stone create` staged at build time.
Profile scripts resolve the same way. So the gate could approve a file
the run never reads. After an SDK upgrade without a rebuild, the new SDK
manifest declares dry_run while the staged pre-upgrade script ignores
AVOCADO_PROVISION_DRY_RUN and writes the card. A project include path
can supply its own manifest or script the gate never saw.

Read the staged manifest.json instead. It is the file stone loads when
no include paths are set, and it already reflects a custom
stone_manifest, so the custom-manifest refusal goes away. It also drops
the sdk/* glob, which picked the first SDK architecture rather than the
one in use. With include paths set, from the runtime or extension config
or from the env, a dir the CLI does not inspect comes first in the
search, so refuse instead of guessing. The path is passed to the shell
as $1 so a runtime name never becomes script text.

Signed-off-by: Javier Tia <javier@peridio.com>
The dry_run_preflight doc said AVOCADO_PROVISION_PROFILE from the env
wins over --profile. Both provision entry points build their env through
build_env_vars in main.rs. That function writes --profile into the map
after parsing --env, so the two always agree when --profile is given.
The test that fed the preflight a differing env value and flag covered a
state the CLI cannot produce, and it documented the wrong rule.

State the real precedence and drop that test. The env value still
decides the profile when no --profile is given, and the remaining
preflight_env_only_is_the_profile_checked test covers that.

Signed-off-by: Javier Tia <javier@peridio.com>
Container args are appended after the generated -e flags in every run
path, so docker applies a later -e last. An -e for
AVOCADO_PROVISION_PROFILE, AVOCADO_PROVISION_DRY_RUN or
AVOCADO_PROVISION_HOST_MOUNTS in sdk.container_args, a provision
profile's container_args or --container-arg replaced the value the CLI
set. That could run a different profile from the one the dry-run gate
checked, turn a dry run back into a write, or point the script at a
mount table the CLI never bound. The existing --env override tests only
looked at the env map, before container args are applied.

Strip those keys from the merged container args before the run, as
take_git_config_args already does for GIT_CONFIG_PARAMETERS, reusing its
docker_env_flag parser so every -e and --env spelling is caught,
including a bare key that would pass the host's value. The strip happens
once in provision rather than in build_container_command, because the
remote run paths read container_args without going through it. Args with
no match are returned byte for byte, so quoting the remote paths depend
on is left alone.

Signed-off-by: Javier Tia <javier@peridio.com>
The provision docs said --dry-run and AVOCADO_PROVISION_HOST_MOUNTS were
"added by this change" and "need a release that carries it". Once merged,
that wording describes a pull request rather than the CLI, and it does
not tell a reader which version has the feature. The imx93 page also
said the mounted-device check only warns on a host. That stops being
true once the CLI binds the table in on native Linux.

Drop the revision wording and limit the warn-only case to where
host_mounts_export_applies leaves the table out: Docker Desktop, the
avocado-vm and --runs-on. Also name the new stone-include-paths refusal
next to the existing dry_run declaration rule, so a refused dry run is
explained where readers look for it.

Signed-off-by: Javier Tia <javier@peridio.com>
This branch sits on provision-force-env, which still carries the
duplicated attribute that main already fixed. clippy rejects it, so the
pre-push hook blocks every push of this branch.

The same one-line deletion main took, so the change drops out when this
stack is rebased onto main.

Signed-off-by: Javier Tia <javier@peridio.com>
cargo audit reports a spin loop in quinn-udp 0.5.14 after a truncated
datagram, and the pre-push hook refuses the push on it. The lockfile
inherited from the base branch still pins 0.5.14.

A lockfile-only bump to 0.5.16, the patched release inside the same
semver range, so no manifest or code change is needed.

Signed-off-by: Javier Tia <javier@peridio.com>
@jetm
jetm requested a review from lee-reinhardt November 13, 2026 21:05
@jetm
jetm dismissed lee-reinhardt’s stale review November 14, 2026 03:02

Every review thread on this pull request is resolved and the fixes are on the current head. This change request points at an older commit, so I am dismissing it to unblock the merge. I have asked for a fresh review; please re-request changes if anything is still open.

Base automatically changed from provision-force-env to main November 14, 2026 17:36
…parity

main gained the AVOCADO_PROVISION_FORCE export while this branch was
carrying the same change plus the dry-run, host-mounts and fwup-task
exports. Conflicts in provision.rs and the two provision-signing docs
were resolved by keeping this branch's side, which is a superset of what
main added.

Signed-off-by: Javier Tia <javier@peridio.com>
@jetm

jetm commented Nov 15, 2026

Copy link
Copy Markdown
Contributor Author

@lee-reinhardt your change request (review 5884547733) on #390 was dismissed and every review thread on it is resolved. Checks on the head 9319407: 11 passed, 0 pending, none failing. Could you take another look and re-review?

&target_arch,
&self.config.config_path,
)?;
let profile = crate::commands::profiles::dry_run_preflight(

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

blocker: The dry-run gate checks only self.config.env_vars and configured Stone include paths, but the provisioning run also receives the merged container arguments. For example, -e AVOCADO_STONE_INCLUDE_PATHS=/opt/src/custom-stone survives sanitization and reaches the SDK hook, which searches that directory before the staged Stone directory. The gate can therefore approve the staged declaration while an unchecked project manifest or script runs. An --env-file can likewise supply include paths or, when no profile was explicitly exported, an unchecked profile. Before checking the staged manifest, reject --dry-run when merged container arguments supply Stone include paths or an env file the gate does not validate.

Comment thread src/utils/container.rs
let mut kept = Vec::with_capacity(tokens.len());
let mut i = 0;
while i < tokens.len() {
if let Some((used, operand)) = docker_env_flag(&tokens, i) {

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

blocker: docker_env_flag() does not recognize clustered short flags, so this sanitizer leaves -ie AVOCADO_PROVISION_DRY_RUN=0 untouched. Verified with Docker create/inspect: when appended after the generated -e AVOCADO_PROVISION_DRY_RUN=1, the resulting container environment contains AVOCADO_PROVISION_DRY_RUN=0. A requested dry run can therefore execute a real write; the same spelling can replace the checked profile or host-mount-table variable. Recognize clustered short environment flags, remove protected assignments while preserving the other flags in the cluster, and add a regression test for the final effective environment.

Comment thread src/commands/profiles.rs
let sdk_image = config.get_sdk_image().ok_or_else(|| {
anyhow::anyhow!("--dry-run cannot be verified, stone manifest could not be read: avocado.yaml has no `sdk.image` set")
})?;
let project_dir = Path::new(config_path)

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

error: This selects .avocado-state beside config_path, while SdkContainer selects the provisioning volume from the working directory. Running from the project root with -C configs/avocado.yaml --dry-run therefore reports the SDK missing when its state is correctly stored at the root; if both directories have state files, the gate can inspect a different volume from the one provision uses. Load the same working-directory volume state used by provisioning, and cover a nested config path in a regression test.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants