CLI v1.10.0

13 min read

Using the CLI

Control the Edera Protect daemon.

 protect [OPTIONS] <COMMAND>

Subcommands:

  • zone Manage the zones on Edera Protect.
  • workload Manage the workloads on Edera Protect.
  • image Manage the images on Edera Protect.
  • network Manage the network on Edera Protect.
  • device Manage the devices on Edera Protect.
  • host Manage the host of Edera Protect.
  • completion Output shell completion code for the specified shell.

Options:

  • -c, --connection <CONNECTION> The connection URL to the Edera Protect daemon [default value: unix:///var/lib/edera/protect/daemon.socket].
  • --user-agent <USER_AGENT> User agent to connect to the daemon as [default value: edera-protect-ctl/0.0.1].

zone

Manage the zones on Edera Protect.

 protect zone <COMMAND>

Subcommands:

  • attach Attach to the zone console.
  • list List zone information.
  • resolve Resolve a zone name to matching zone ids.
  • launch Launch a new zone.
  • destroy Destroy a zone.
  • suspend Suspend a running zone.
  • resume Resume a suspended zone.
  • fork Fork a running zone into a new memory-shared child zone.
  • exec Execute a command inside the zone.
  • forget Forget destroyed zones (clear their tombstones).
  • logs View the logs of a zone.
  • metrics Read metrics from the zone.
  • top Dashboard for running zones.
  • watch Watch for zone changes.
  • update-resources Update the available resources to a zone.
  • configure-network Configure the network of an external network backend zone.
  • kernel-events Manage kernel events from zones.

attach

Attach to the zone console.

 protect zone attach <ZONE>

Arguments:

  • <ZONE> Zone to attach to, either the name or the uuid.

list

List zone information.

 protect zone list [OPTIONS] [ZONE]

Arguments:

  • <ZONE> Limit to a single zone, either the name or the uuid.

Options:

  • -o, --output <OUTPUT> Output format [default value: table] [possible values: table, json, json-pretty, jsonl, yaml, key-value, simple].
  • -l, --selector <SELECTOR> A selector for filtering the result set. Currently only supports ‘=’ and the ‘status.state’ field. Supported states include ‘creating’, ‘created’, ‘ready’, ‘destroying’, ‘destroyed’, ‘failed’, ‘suspending’, ‘suspended’, ‘resuming’ and ‘forking’, with or without the ‘zone_state_’ prefix. (e.g. --selector status.state=failed or --selector status.state=ZONE_STATE_FAILED).

resolve

Resolve a zone name to matching zone ids.

 protect zone resolve [OPTIONS] <NAME>

Arguments:

  • <NAME> The zone name to resolve.

Options:

  • -f, --first If there are multiple matching zones, only print the first zone id.

launch

Launch a new zone.

 protect zone launch [OPTIONS]

Options:

  • --pull-overwrite-cache Overwrite image cache on pull.
  • --pull-update Update image on pull.
  • -n, --name <NAME> Name of the zone.
  • --min-cpus <MIN_CPUS> Minimum vCPUs available for the zone [default value: 4].
  • -C, --max-cpus <MAX_CPUS> Maximum vCPUs available for the zone [default value: 4].
  • -c, --target-cpus <TARGET_CPUS> Target vCPUs for the zone to use [default value: 1].
  • --min-memory <MIN_MEMORY> Minimum memory available to the zone, in megabytes [default value: 0].
  • -M, --max-memory <MAX_MEMORY> Maximum memory available to the zone, in megabytes [default value: 1024].
  • -m, --target-memory <TARGET_MEMORY> Target memory for the zone to use, in megabytes [default value: 1024].
  • --create-scratch-disk <CREATE_SCRATCH_DISK> Create a scratch disk of size, in megabytes.
  • --attach-scratch-disk <ATTACH_SCRATCH_DISK> Attach a host disk as a scratch disk.
  • -D, --device <DEVICE> Devices to request for the zone.
  • -a, --attach Attach to the zone after zone starts, implies –wait.
  • -W, --wait Wait for the zone to be ready, implied by –attach.
  • -k, --kernel <KERNEL> OCI kernel image for zone to use.
  • -I, --initrd <INITRD> OCI initrd image for zone to use.
  • -w, --working-directory <WORKING_DIRECTORY> Working directory.
  • --kernel-verbose Enable verbose logging on the kernel.
  • --kernel-cmdline <KERNEL_CMDLINE> Additional kernel cmdline options.
  • --kernel-module <KERNEL_MODULE> Additional kernel modules to load.
  • --kernel-module-parameter <KERNEL_MODULE_PARAMETER> Additional kernel module parameters to add.
  • --kernel-cmdline-append <KERNEL_CMDLINE_APPEND> Additional kernel cmdline options (raw).
  • --assume-network-reservation <ASSUME_NETWORK_RESERVATION> Assume an already allocated network reservation.
  • --retain-network-reservation Retain network reservation after zone destruction.
  • -R, --resource-adjustment-policy <RESOURCE_ADJUSTMENT_POLICY> Resource adjustment policy [possible values: static, dynamic].
  • -V, --virt-backend <VIRT_BACKEND> Virtualization backend [possible values: auto, pv, pvh].
  • -N, --network-backend <NETWORK_BACKEND> Network backend [possible values: default, none, external, passthrough].
  • --numa-nodes <NUMA_NODES> Requested vNUMA node count; 0 (default) lets the daemon pick based on vCPU count and host topology [default value: 0].
  • --numa-strategy <NUMA_STRATEGY> Strategy for selecting additional NUMA nodes beyond the seed [default value: compact] [possible values: compact, scatter].
  • -A, --addon <ADDON> Addons for the zone.
  • --sysctl <SYSCTL> sysctl parameters to set on the zone.
  • --control-api-access <CONTROL_API_ACCESS> Enables access to the Control API from inside a zone [possible values: deny, allow].

destroy

Destroy a zone.

 protect zone destroy [OPTIONS] [ZONE_IDENTIFIER]

Arguments:

  • <ZONE_IDENTIFIER> Zone to destroy, either the name or the uuid. Optional when --selector is specified.

Options:

  • -W, --wait Wait for the destruction of the zone to complete.
  • -A, --all Destroy all zones matching the input.
  • -l, --selector <SELECTOR> A selector for filtering the result set. Currently only supports ‘=’ and the ‘status.state’ field. Supported states include ‘creating’, ‘created’, ‘ready’, ‘destroying’, ‘destroyed’, ‘failed’, ‘suspending’, ‘suspended’, ‘resuming’ and ‘forking’, with or without the ‘zone_state_’ prefix. (e.g. --selector status.state=failed or --selector status.state=ZONE_STATE_FAILED).

suspend

Suspend a running zone.

 protect zone suspend <ZONE>

Arguments:

  • <ZONE> Zone to suspend, either the name or the uuid.

resume

Resume a suspended zone.

 protect zone resume <ZONE>

Arguments:

  • <ZONE> Zone to resume, either the name or the uuid.

fork

Fork a running zone into a new memory-shared child zone.

 protect zone fork [OPTIONS] <ZONE>

Arguments:

  • <ZONE> Zone to fork, either the name or the uuid.

Options:

  • -n, --name <NAME> Name for the forked child zone.

exec

Execute a command inside the zone.

 protect zone exec [OPTIONS] <ZONE> [COMMAND]...

Arguments:

  • <ZONE> Zone to exec inside, either the name or the uuid.
  • <COMMAND> Command to run inside the zone.

Options:

  • -e, --env <ENV> Environment variables.
  • -w, --working-directory <WORKING_DIRECTORY> Working directory.
  • -t, --tty Allocate tty.
  • --privileged Execute command with elevated privileges.

forget

Clears the tombstone record for destroyed zones. Tombstones are the in-memory record retained after a zone is destroyed so post-mortem tooling (protect zone logs, debug reports) can still inspect them. They expire automatically after the daemon’s linger window; this command evicts them sooner – most importantly so a new zone can reuse a destroyed zone’s name without ambiguity. Forgetting a tombstone is low-risk: the live zone is already gone, so the only consequence of being wrong is losing post-mortem visibility into the destroyed zone. That’s why a bare protect zone forget (no arguments) forgets every tombstone – it’s the most common operation (“tidy up”) and has no failure mode worth gating behind a flag.

 protect zone forget [OPTIONS] [ZONE]

Arguments:

  • <ZONE> Optional zone name or uuid. If omitted, every tombstone is forgotten. If a name matches multiple tombstones, --all is required to disambiguate.

Options:

  • -A, --all When <ZONE> is a name matching multiple tombstones, forget all of them rather than refusing.

logs

View the logs of a zone.

 protect zone logs [OPTIONS] <ZONE>

Arguments:

  • <ZONE> Zone to show logs for, either the name or the uuid.

Options:

  • -f, --follow Follow output from the zone.

metrics

Read metrics from the zone.

 protect zone metrics [OPTIONS] <ZONE>

Arguments:

  • <ZONE> Zone to read metrics for, either the name or the uuid.

Options:

  • -o, --output <OUTPUT> Output format [default value: tree] [possible values: tree, json, json-pretty, yaml, key-value].

top

Dashboard for running zones.

 protect zone top

watch

Watch for zone changes.

 protect zone watch [OPTIONS]

Options:

  • -o, --output <OUTPUT> Output format [default value: simple] [possible values: simple, json, key-value].

update-resources

Update the available resources to a zone.

 protect zone update-resources [OPTIONS] <ZONE>

Arguments:

  • <ZONE> Zone to update resources of, either the name or the uuid.

Options:

  • --min-cpus <MIN_CPUS> Minimum vCPUs available to the zone (0 means previous value) [default value: 0].
  • -C, --max-cpus <MAX_CPUS> Maximum vCPUs available to the zone (0 means previous value) [default value: 0].
  • -c, --target-cpus <TARGET_CPUS> Target vCPUs for the zone to use (0 means previous value) [default value: 0].
  • --min-memory <MIN_MEMORY> Minimum memory available to the zone, in megabytes (0 means previous value) [default value: 0].
  • -M, --max-memory <MAX_MEMORY> Maximum memory available to the zone, in megabytes (0 means previous value) [default value: 0].
  • -m, --target-memory <TARGET_MEMORY> Target memory for the zone to use, in megabytes (0 means previous value) [default value: 0].
  • -p, --adjustment-policy <ADJUSTMENT_POLICY> Adjustment policy [possible values: static, dynamic].

configure-network

Configure the network of an external network backend zone.

 protect zone configure-network [OPTIONS] <ZONE>

Arguments:

  • <ZONE> Zone to update resources of, either the name or the uuid.

Options:

  • --zone-interface <ZONE_INTERFACE> Zone Network Interface.
  • --zone-ipv4 <ZONE_IPV4> Zone IPv4 Network.
  • --zone-ipv6 <ZONE_IPV6> Zone IPv6 Network.
  • --gateway-ipv4 <GATEWAY_IPV4> Zone Gateway IPv4 Network.
  • --gateway-ipv6 <GATEWAY_IPV6> Zone Gateway IPv6 Network.
  • --zone-mac <ZONE_MAC> Zone MAC Address.
  • --mtu <MTU> Zone MTU.

kernel-events

Manage kernel events from zones.

 protect zone kernel-events <COMMAND>

Subcommands:

  • stream Stream kernel events from a zone.
  • list-syscalls List all available syscalls.

kernel-events stream

Stream kernel events from a zone.

 protect zone kernel-events stream [OPTIONS] <ZONE>

Arguments:

  • <ZONE> Zone to show logs for, either the name or the uuid.

Options:

  • -e, --enabled-events <ENABLED_EVENTS> Zone event types (syscall ids, etc) to enable notifications for.

kernel-events list-syscalls

List all available syscalls.

 protect zone kernel-events list-syscalls

workload

Manage the workloads on Edera Protect.

 protect workload <COMMAND>

Subcommands:

  • launch Launch a new workload.
  • exec Execute a command inside the workload.
  • attach Attach to a workload console.
  • resolve Resolve a workload name to matching workload ids.
  • start Start a workload.
  • stop Stop a workload.
  • destroy Destroy a workload.
  • list List workload information.
  • watch Watch for workload changes.

launch

Launch a new workload.

 protect workload launch [OPTIONS] --zone <ZONE> <OCI> [COMMAND]...

Arguments:

  • <OCI> Container image for zone to use.
  • <COMMAND> Command to run the workload.

Options:

  • --image-format <IMAGE_FORMAT> Image format [default value: squashfs] [possible values: squashfs].
  • --pull-overwrite-cache Overwrite image cache on pull.
  • --pull-update Update image on pull.
  • -n, --name <NAME> Name of the workload.
  • -W, --wait Wait for the workload to be started.
  • -t, --tty Allocate tty for the workload.
  • -a, --attach Attach to workload console.
  • --disable-all-namespaces Disable all process namespaces.
  • --disable-namespace <DISABLE_NAMESPACE> Process namespaces to disable [possible values: mount, uts, ipc, user, pid, net, cgroup, time].
  • --strict-user-namespace Enable strictness of user namespaces on the workload.
  • --read-only-rootfs Enable read-only rootfs.
  • --no-new-privs Prevent workload from requesting new privileges after launch.
  • -e, --env <ENV> Environment variables set in the workload.
  • -m, --mounts <MOUNTS> Mount host directories into the workload (in the form src=<HOSTDIR>:dst=<WORKLOAD_PATH>[:ro=true]).
  • -b, --block-device <BLOCK_DEVICE> Mount host block device into the workload (in the form src=<HOSTDEV>:dst=<WORKLOAD_PATH>[:ro=true]).
  • --cap-add <CAP_ADD> Capabilities to add.
  • --cap-ambient-add <CAP_AMBIENT_ADD> Ambient capabilities to add.
  • --cap-drop <CAP_DROP> Capabilities to drop.
  • --privileged Run workload with elevated privileges.
  • -w, --working-directory <WORKING_DIRECTORY> Working directory.
  • --user <USER> User name or id.
  • --group <GROUP> Group name or id.
  • -z, --zone <ZONE> Zone to launch on, can be a name or id.
  • --mount-scratch-disk <MOUNT_SCRATCH_DISK> Mount zone scratch disk on a certain directory.
  • --hostname <HOSTNAME> Hostname inside the workload.
  • --pci-device <PCI_DEVICE> PCI devices to attach to the workload.

exec

Execute a command inside the workload.

 protect workload exec [OPTIONS] <WORKLOAD> [COMMAND]...

Arguments:

  • <WORKLOAD> Workload to exec inside, either the name or the uuid.
  • <COMMAND> Command to run inside the zone.

Options:

  • -e, --env <ENV> Environment variables.
  • -w, --working-directory <WORKING_DIRECTORY> Working directory.
  • -t, --tty Allocate tty.
  • --user <USER> User name or id.
  • --group <GROUP> Group name or id.
  • --privileged Execute with elevated privileges.

attach

Attach to a workload console.

 protect workload attach <WORKLOAD>

Arguments:

  • <WORKLOAD> Workload to attach to, either the name or the uuid.

resolve

Resolve a workload name to matching workload ids.

 protect workload resolve [OPTIONS] <NAME>

Arguments:

  • <NAME> The workload name to resolve.

Options:

  • -f, --first If there are multiple matching workloads, only print the first workload id.

start

Start a workload.

 protect workload start <WORKLOAD>

Arguments:

  • <WORKLOAD> Workload to start, either the name or the uuid.

stop

Stop a workload.

 protect workload stop <WORKLOAD> [TIMEOUT]

Arguments:

  • <WORKLOAD> Workload to stop, either the name or the uuid.
  • <TIMEOUT> How long to wait for the workload to stop (in seconds) before forcibly killing it, default 0.

destroy

Destroy a workload.

 protect workload destroy [OPTIONS] [WORKLOAD_IDENTIFIER]

Arguments:

  • <WORKLOAD_IDENTIFIER> Workload to destroy, either the name or the uuid. Optional when --selector is specified.

Options:

  • -W, --wait Wait for the destruction of the workload to complete.
  • -a, --all Destroy all workloads matching the input.
  • -l, --selector <SELECTOR> A selector for filtering the result set. Currently only supports ‘=’ and the ‘status.state’ field. Supported states include ‘creating’, ‘created’, ‘running’, ‘completed’, ‘destroying’, ‘destroyed’ and ‘failed’, with or without the ‘workload_state_’ prefix. (e.g. --selector status.state=failed or --selector status.state=WORKLOAD_STATE_FAILED).

list

List workload information.

 protect workload list [OPTIONS] [WORKLOAD]

Arguments:

  • <WORKLOAD> Limit to a single workload, either the name or the uuid.

Options:

  • -o, --output <OUTPUT> Output format [default value: table] [possible values: table, json, json-pretty, jsonl, yaml, key-value, simple].
  • -l, --selector <SELECTOR> A selector for filtering the result set. Currently only supports ‘=’ and the ‘status.state’ field. Supported states include ‘creating’, ‘created’, ‘running’, ‘completed’, ‘destroying’, ‘destroyed’ and ‘failed’, with or without the ‘workload_state_’ prefix. (e.g. --selector status.state=failed or --selector status.state=WORKLOAD_STATE_FAILED).

watch

Watch for workload changes.

 protect workload watch [OPTIONS]

Options:

  • -o, --output <OUTPUT> Output format [default value: simple] [possible values: simple, json, key-value].

image

Manage the images on Edera Protect.

 protect image <COMMAND>

Subcommands:

  • pull Pull an image into the cache.
  • import Import an image into the cache.
  • remove Remove an image from the cache.
  • list List cached images.

pull

Pull an image into the cache.

 protect image pull [OPTIONS] <IMAGE>

Arguments:

  • <IMAGE> Image name.

Options:

  • -s, --image-format <IMAGE_FORMAT> Image format [default value: squashfs] [possible values: squashfs, tar, directory].
  • -n, --no-update Don’t update from registry.
  • -o, --overwrite-cache Overwrite image cache.
  • -U, --username <USERNAME> Auth username.
  • -P, --password <PASSWORD> Auth password.
  • -T, --registry-token <REGISTRY_TOKEN> Auth registry token.
  • --identity-token <IDENTITY_TOKEN> Auth identity token.

import

Import an image into the cache.

 protect image import [OPTIONS] --digest <DIGEST> --image <IMAGE>

Options:

  • -d, --digest <DIGEST> Image digest.
  • -n, --image <IMAGE> Image name.
  • -s, --image-format <IMAGE_FORMAT> Image format [default value: squashfs] [possible values: squashfs, tar, directory].
  • -o, --overwrite-cache Overwrite image cache.
  • -i <INPUT_FILE> Input image tar [default value: /dev/stdin].

remove

Remove an image from the cache.

 protect image remove [OPTIONS] <DIGEST>

Arguments:

  • <DIGEST> Image digest.

Options:

  • -s, --image-format <IMAGE_FORMAT> Image format [default value: all] [possible values: all, squashfs, tar, directory].

list

List cached images.

 protect image list [OPTIONS]

Options:

  • -o, --output <OUTPUT> Output format [default value: table] [possible values: table, json, json-pretty, jsonl, yaml, key-value, simple].

network

Manage the network on Edera Protect.

 protect network <COMMAND>

Subcommands:

  • reservation Manage network reservations.

reservation

Manage network reservations.

 protect network reservation <COMMAND>

Subcommands:

  • create Create network reservation.
  • destroy Destroy network reservation.
  • list List network reservation information.

reservation create

Create network reservation.

 protect network reservation create

reservation destroy

Destroy network reservation.

 protect network reservation destroy <RESERVATION>

Arguments:

  • <RESERVATION> Reservation to destroy.

reservation list

List network reservation information.

 protect network reservation list [OPTIONS]

Options:

  • -o, --output <OUTPUT> Output format [default value: table] [possible values: table, json, json-pretty, jsonl, yaml, key-value, simple].

device

Manage the devices on Edera Protect.

 protect device <COMMAND>

Subcommands:

  • list List device information.

list

List device information.

 protect device list [OPTIONS]

Options:

  • -o, --output <OUTPUT> Output format [default value: table] [possible values: table, json, json-pretty, jsonl, yaml, key-value, simple].

host

Manage the host of Edera Protect.

 protect host <COMMAND>

Subcommands:

  • cpu-topology Display information about the host CPU topology.
  • status Get information about the host.
  • control-snoop Snoop on the Control API.
  • idm-snoop Snoop on the IDM bus.
  • hv-console Display hypervisor console output.
  • hv-debug-info Read hypervisor debug information.

cpu-topology

Display information about the host CPU topology.

 protect host cpu-topology [OPTIONS]

Options:

  • -o, --output <OUTPUT> Output format [default value: table] [possible values: table, json, json-pretty, jsonl, yaml, key-value].

status

Get information about the host.

 protect host status [OPTIONS]

Options:

  • -o, --output <OUTPUT> Output format [default value: simple] [possible values: simple, json, json-pretty, yaml, key-value].

control-snoop

Snoop on the Control API.

 protect host control-snoop [OPTIONS]

Options:

  • -o, --output <OUTPUT> Output format [default value: simple] [possible values: simple, jsonl, key-value].
  • --filter-internals Filters out user agents matching edera-protect-*, excluding the CLI.

idm-snoop

Snoop on the IDM bus.

 protect host idm-snoop [OPTIONS]

Options:

  • -o, --output <OUTPUT> Output format [default value: simple] [possible values: simple, jsonl, key-value].

hv-console

Display hypervisor console output.

 protect host hv-console

hv-debug-info

Read hypervisor debug information.

 protect host hv-debug-info

completion

Output shell completion code for the specified shell.

 protect completion <SHELL>

Arguments:

  • <SHELL> [possible values: bash, elvish, fish, powershell, zsh].
Last updated on