Goal
Provide a safe, trackless way for operators and developers to test new AosEdge network topologies, node configurations, or system images without impacting the running production aos-unit daemon or leaving orphaned state files on the host.
Command Specification
aos-unitctl debug --config <path_to_yaml> --images <path_to_images_dir>
Implementation Details & Architecture
- Transient Execution: The command must bypass
systemctl start and exclusively use systemd-run --system to spawn a purely transient unit in RAM.
- Unit Naming: Dynamically name the debug unit (e.g.,
--unit="aos-unit-debug-$$") using the CLI process PID to allow multiple isolated debug sessions in separate terminals without naming collisions.
- Foreground Attachment: Utilize systemd's
--pty and --wait flags so the daemon's stdout/stderr streams directly to the operator's terminal in real-time.
- Zero-Trace Cleanup: Must use the
--collect flag. When the operator terminates the session via SIGINT (Ctrl+C), systemd must completely garbage-collect the unit from memory, leaving no residual service files.
- Path Safety: The CLI must wrap the user-provided
<path_to_yaml> and <path_to_images_dir> with realpath to ensure absolute paths are passed into the systemd environment.
Acceptance Criteria
- Privilege Enforcement: The command must verify it is running with sufficient privileges (root/sudo) to execute
systemd-run --system and exit with a clear error if not.
- Pre-flight Validation: The command must automatically run the YAML parser and CIDR validation logic before invoking
systemd-run, failing fast if the configuration is mathematically invalid.
- Environment Injection: The absolute paths must be correctly injected into the transient unit's environment (via
--setenv=AOS_CONFIG_PATH=...) so the runner script consumes them seamlessly.
- Clean Teardown: Terminating the CLI process must successfully tear down the transient QEMU nodes, the randomly generated debug bridge, and the isolated
dnsmasq instance without manual cleanup.
Goal
Provide a safe, trackless way for operators and developers to test new AosEdge network topologies, node configurations, or system images without impacting the running production
aos-unitdaemon or leaving orphaned state files on the host.Command Specification
Implementation Details & Architecture
systemctl startand exclusively usesystemd-run --systemto spawn a purely transient unit in RAM.--unit="aos-unit-debug-$$") using the CLI process PID to allow multiple isolated debug sessions in separate terminals without naming collisions.--ptyand--waitflags so the daemon's stdout/stderr streams directly to the operator's terminal in real-time.--collectflag. When the operator terminates the session viaSIGINT(Ctrl+C), systemd must completely garbage-collect the unit from memory, leaving no residual service files.<path_to_yaml>and<path_to_images_dir>withrealpathto ensure absolute paths are passed into the systemd environment.Acceptance Criteria
systemd-run --systemand exit with a clear error if not.systemd-run, failing fast if the configuration is mathematically invalid.--setenv=AOS_CONFIG_PATH=...) so the runner script consumes them seamlessly.dnsmasqinstance without manual cleanup.