Enum Command

pub(crate) enum Command {
    Complete(Complete),
    Completions(Completions),
    Shell {
        shell: String,
        args: Vec<String>,
    },
    Run {
        command: String,
        args: Vec<String>,
    },
    Inspect {
        recursive: bool,
        limit: Option<usize>,
        json: bool,
        poll: bool,
        period: f64,
        count: Option<usize>,
        path: Option<String>,
        update: Option<String>,
        timeout: u64,
    },
    Update {
        path: String,
        value: String,
    },
    Start {
        env: Vec<EnvString>,
        unset: Vec<String>,
        args: Vec<String>,
    },
    Kmsg {
        follow: bool,
        reconnect: bool,
        verbose: bool,
    },
    File {
        follow: bool,
        file_path: String,
    },
    Gdbserver {
        pid: Option<i32>,
        multi: bool,
    },
    Gdbstub {
        port: u32,
    },
    Crash {
        crash_type: CrashType,
        pid: Option<i32>,
        name: Option<String>,
    },
    CoreDump {
        verbose: bool,
        pid: Option<i32>,
        name: Option<String>,
        dst: Option<PathBuf>,
    },
    Restart,
    PerfTrace {
        output: Option<PathBuf>,
    },
    VsockTcpRelay {
        vsock_port: u32,
        tcp_port: u16,
        allow_remote: bool,
        reconnect: bool,
    },
    Pause,
    Resume,
    DumpSavedState {
        output: Option<PathBuf>,
    },
    PacketCapture {
        output: PathBuf,
        seconds: Duration,
        snaplen: u16,
    },
}

Variants

Complete(Complete)

Completions(Completions)

Shell

Starts an interactive terminal in VTL2.

Fields

shell: String

The shell process to start.

args: Vec<String>

The arguments to pass to the shell process.

Run

Runs a process in VTL2.

Fields

command: String

The command to run.

args: Vec<String>

Arguments to pass to the command.

Inspect

Inspects the Underhill state.

Fields

recursive: bool

Recursively enumerate child nodes.

limit: Option<usize>

Limit the recursive inspection depth.

json: bool

Output in JSON format.

poll: bool

Poll periodically.

period: f64

The poll period in seconds.

count: Option<usize>

The count of polls

path: Option<String>

The path to inspect.

update: Option<String>

Update the path with a new value.

timeout: u64

Timeout to wait for the inspection. 0 means no timeout.

Update

Updates an inspectable value.

Fields

path: String

The path.

value: String

The new value.

Start

Starts the VM if it’s waiting for the signal to start.

Underhill must have been started with –wait-for-start or OPENHCL_WAIT_FOR_START set.

Fields

env: Vec<EnvString>

Environment variables to set, in the form X=Y

unset: Vec<String>

Environment variables to clear

args: Vec<String>

Extra command line arguments to append.

Kmsg

Writes the contents of the kernel message buffer, /dev/kmsg.

Fields

follow: bool

Keep waiting for and writing new data as its logged.

reconnect: bool

Reconnect (retrying indefinitely) whenever the connection is lost.

verbose: bool

Write verbose information about the connection state.

File

Writes the contents of the file.

Fields

follow: bool

Keep waiting for and writing new data as its logged.

file_path: String

Gdbserver

Starts GDB server on stdio.

Use this with gdb’s target command:

target remote |ohcldiag-dev.exe gdbserver my-vm

Or for multi-process debugging:

target extended-remote |ohcldiag-dev.exe gdbserver --multi my-vm

Fields

pid: Option<i32>

The pid to attach to. Defaults to Underhill’s.

multi: bool

Use multi-process debugging, for use with gdb’s extended-remote.

Gdbstub

Starts the GDB stub for debugging the guest on stdio.

Use this with gdb’s target command:

target remote |ohcldiag-dev.exe gdbstub my-vm

Fields

port: u32

The vsock prot to connect to.

Crash

Crashes the VM.

Must specify the VM name, as well as the crash type.

Fields

crash_type: CrashType

Type of crash.

Current crash types supported: “panic”

pid: Option<i32>

PID of underhill process to crash

name: Option<String>

Name of underhill process to crash

CoreDump

Streams the ELF core dump file of a process to the host.

Streams the core dump file of a process to the host where the file is saved as dst.

Fields

verbose: bool

Enable verbose output.

pid: Option<i32>

PID of process to dump

name: Option<String>

Name of underhill process to dump

dst: Option<PathBuf>

Destination file path. If omitted, the data is written to the standard output unless it is a terminal. In that case, an error is returned.

Restart

Restarts the Underhill worker process, keeping VTL0 running.

PerfTrace

Get the current contents of the performance trace buffer, for use with https://ui.perfetto.dev.

Fields

output: Option<PathBuf>

The output file. Defaults to stdout.

VsockTcpRelay

Sets up a relay between a virtual socket and a TCP client on the host.

Fields

vsock_port: u32

tcp_port: u16

allow_remote: bool

reconnect: bool

Reconnect (retrying indefinitely) whenever either side of the connection is lost.

NOTE: Today, this does not handle the case where the vsock side is not ready to connect. That will cause the relay to terminate.

Pause

Pause the VM (including all devices)

Resume

Resume the VM

DumpSavedState

Dumps the VM’s VTL2 state without servicing or tearing down Underhill.

Fields

output: Option<PathBuf>

The output file. Defaults to stdout.

PacketCapture

Starts a network packet capture trace.

Fields

output: PathBuf

Destination file path. nic index is appended to the file name.

seconds: Duration

Number of seconds for which to capture packets.

snaplen: u16

Length of the packet to capture.

Trait Implementations

impl FromArgMatches for Command

fn from_arg_matches(__clap_arg_matches: &ArgMatches) -> Result<Self, Error>

Instantiate Self from [ArgMatches], parsing the arguments as needed.

fn from_arg_matches_mut( __clap_arg_matches: &mut ArgMatches, ) -> Result<Self, Error>

Instantiate Self from [ArgMatches], parsing the arguments as needed.

fn update_from_arg_matches( &mut self, __clap_arg_matches: &ArgMatches, ) -> Result<(), Error>

Assign values from ArgMatches to self.

fn update_from_arg_matches_mut<'b>( &mut self, __clap_arg_matches: &mut ArgMatches, ) -> Result<(), Error>

Assign values from ArgMatches to self.

impl Subcommand for Command

fn augment_subcommands<'b>(__clap_app: Command) -> Command

Append to [Command] so it can instantiate Self via [FromArgMatches::from_arg_matches_mut]

fn augment_subcommands_for_update<'b>(__clap_app: Command) -> Command

Append to [Command] so it can instantiate self via [FromArgMatches::update_from_arg_matches_mut]

fn has_subcommand(__clap_name: &str) -> bool

Test whether Self can parse a specific subcommand