Skip to content

Add debug command to aos-unitctl CLI for isolated side-instance testing #7

Description

@klogg

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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions