CLI v1.13.0

23 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.
  • object-capability Inspect and use object capabilities.
  • 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. CTRL+] to exit.
  • list List zone information.
  • vcpu-list Display information about a zone’s vCPUs and their pinning.
  • 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.
  • export Export a zone’s full state to a snapshot file.
  • import Import a zone from a snapshot file.
  • fork Fork a running zone into a new memory-shared child zone.
  • exec Execute a command inside the zone.
  • port-forward Forward local TCP connections to a port inside a 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.
  • advertise-service Advertise a service in a zone.
  • unadvertise-service Unadvertise a service in a zone.
  • kernel-events Manage kernel events from zones.

attach

Attach to the zone console. CTRL+] to exit.

 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, tree, json, json-pretty, jsonl, yaml, key-value, simple, quiet].
  • -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).

vcpu-list

Display information about a zone’s vCPUs and their pinning.

 protect zone vcpu-list [OPTIONS] [ZONE]

Arguments:

  • <ZONE> Zone to list vCPUs for, either the name or the uuid.

Options:

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

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].
  • --cpus-hard-affinity <CPUS_HARD_AFFINITY> vCPUs to host CPUs hard affinity.
  • --cpus-soft-affinity <CPUS_SOFT_AFFINITY> vCPUs to host CPUs soft affinity.
  • --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 MiB.
  • --attach-scratch-disk <ATTACH_SCRATCH_DISK> Attach a host disk as a scratch disk.
  • -D, --device <DEVICE> Devices to request for the zone.
  • -k, --kernel <KERNEL> OCI kernel image for zone to use [deprecated: prefer –kernel-variant].
  • --kernel-variant <KERNEL_VARIANT> Named kernel variant to use. Takes precedence over –kernel if both are given. Use protect-ctl image list-kernel-variants to see available kernels.
  • -I, --initrd <INITRD> OCI initrd image for zone to use.
  • --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.
  • --vm-image <VM_IMAGE> Boot the zone from this VM disk image (filename under the daemon’s vm-image directory). Mutually exclusive with the container payload flags (–kernel, –initrd, –addon, –create-scratch-disk, –attach-scratch-disk).
  • --vm-image-format <VM_IMAGE_FORMAT> Disk image format for –vm-image; required when –vm-image is set [possible values: raw, qcow2].
  • --timeout <TIMEOUT> Seconds to wait for the zone to be ready before giving up; 0 waits indefinitely. Only used with –wait/–attach [default value: 60].
  • -a, --attach Attach to the zone after zone starts, implies –wait.
  • -W, --wait Wait for the zone to be ready, implied by –attach.
  • -S, --with-spire Run a SPIRE agent in the zone.
  • --pki-adapter Run the certificate adapter from the daemon’s [pki.adapter] config in the zone.

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 [OPTIONS] <ZONE>

Arguments:

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

Options:

  • -W, --wait Wait for the zone to be suspended.

resume

Resume a suspended zone.

 protect zone resume [OPTIONS] <ZONE>

Arguments:

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

Options:

  • -W, --wait Wait for the zone to be ready.

export

Exports a zone’s vcpus, memory, hypervisor configuration, device topology, spec and workloads into a single snapshot file that protect zone import turns back into a running zone. The zone is suspended for the whole export so the snapshot is one consistent instant, then resumed unless –leave-suspended is given; a zone that was already suspended is exported as it is and left suspended. A zone whose workloads mount host paths, or which has passthrough devices, is refused: neither would work in the imported zone. The contents of the zone’s writable disks are always embedded; read-only images are referenced by path. –file is where the snapshot goes and –output is how this command reports what it did. With the snapshot itself on stdout (--file -) the report goes to stderr, so it cannot end up inside the snapshot; -o quiet suppresses it, and the progress indicator with it.

 protect zone export [OPTIONS] --file <FILE> <ZONE>

Arguments:

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

Options:

  • -f, --file <FILE> File to write the snapshot to; - writes to stdout.
  • -o, --output <OUTPUT> Output format [default value: simple] [possible values: table, tree, json, json-pretty, jsonl, yaml, key-value, simple, quiet].
  • -S, --leave-suspended Leave the zone suspended after the export instead of resuming it.
  • -c, --compress Compress the snapshot.

import

Rebuilds a zone from a file produced by protect zone export, resuming the guest exactly where it was exported. The imported zone gets a fresh id and, on the default network backend, a fresh address, so a snapshot can be imported alongside the zone it came from. –count imports the same snapshot more than once, giving that many independent zones from one export. Each copy is a separate upload of the file, so it cannot be combined with reading the snapshot from stdin. Left to itself, an import keeps the exported zone’s name when it is free and otherwise takes the next free 2, 3 suffix, as does every further copy. –name overrides the exported name and is used as given, with copies after the first named <name>2, <name>3 and so on, skipping any name already taken. The import is refused, with every reason, if this host cannot continue the guest: a different CPU vendor or missing CPU features, a clock it would have to emulate, an older hypervisor, a different zone agent protocol, or read-only images the snapshot references that are missing or changed here. –smart-fork changes how –count makes the copies after the first: it uploads the snapshot once, imports one zone from it, suspends that zone, forks the rest from the one instant, and resumes it. The copies share the first one’s memory, so they cost a fraction of the time and disk – and because there is only one upload, –smart-fork works with a snapshot on stdin and with –zone-id. It needs the fork feature enabled as well as snapshot. The default output is one zone id per line, which is what a script reads to find out what it just made. The other formats name and describe the zones instead, which costs a listing to find out; -o quiet prints nothing.

 protect zone import [OPTIONS] --file <FILE>

Options:

  • -f, --file <FILE> Snapshot file to import, or ‘-’ to read from stdin.
  • -n, --name <NAME> Name for the imported zone; overrides the snapshot’s.
  • --zone-id <ZONE_ID> Import under this zone id instead of a freshly allocated one.
  • -c, --count <COUNT> Number of copies to import from the snapshot; the file is uploaded once per copy unless –smart-fork is given [default value: 1].
  • --smart-fork With –count, import one zone and fork the rest from it, uploading the snapshot only once.
  • -W, --wait Wait for the imported zone to be ready.
  • -o, --output <OUTPUT> Output format [default value: simple] [possible values: table, tree, json, json-pretty, jsonl, yaml, key-value, simple, quiet].

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.
  • -c, --count <COUNT> Number of forks to create; each child name is suffixed with its index [default value: 1].
  • -W, --wait Wait for each forked zone to be ready.

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.

port-forward

Forward local TCP connections to a port inside a zone.

 protect zone port-forward [OPTIONS] <ZONE> <PORTS>

Arguments:

  • <ZONE> Zone to forward to, either the name or the uuid.
  • <PORTS> Ports to forward, as [BIND_ADDRESS:]LOCAL_PORT:REMOTE_PORT.

Options:

  • --remote-address <REMOTE_ADDRESS> Address to dial inside the zone [default value: 127.0.0.1].

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: table, tree, json, json-pretty, jsonl, yaml, key-value, simple, quiet].

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: table, tree, json, json-pretty, jsonl, yaml, key-value, simple, quiet].

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].
  • --cpus-hard-affinity <CPUS_HARD_AFFINITY> vCPUs to host CPUs hard affinity.
  • --cpus-soft-affinity <CPUS_SOFT_AFFINITY> vCPUs to host CPUs soft affinity.
  • --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.

advertise-service

Advertise a service in a zone.

 protect zone advertise-service --service <SERVICE> <ZONE>

Arguments:

  • <ZONE> Zone with the service, either the name or the uuid.

Options:

  • --service <SERVICE> Service Name.

unadvertise-service

Unadvertise a service in a zone.

 protect zone unadvertise-service --service <SERVICE> <ZONE>

Arguments:

  • <ZONE> Zone with the service, either the name or the uuid.

Options:

  • --service <SERVICE> Service Name.

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][:cache=cached|none]).
  • -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.
  • --ocap-consume <OCAP_CONSUME> Object capability to consume as NAME[=PROVIDER] (repeatable). NAME may be a capability type implemented by several providers; PROVIDER pins one implementation instead of taking the highest-priority one, e.g. ‘dev.edera/bar=dev.edera/foo’.
  • --ocap-publish <OCAP_PUBLISH> Object capability to publish as NAME[=COMMAND ARGS] (repeatable). The command is split with shell word rules, so quote arguments containing spaces, e.g. ‘dev.edera/x/fetch=/bin/holder fetch 1’.
  • --ocap-implements <OCAP_IMPLEMENTS> Capability types a published capability satisfies, as NAME=TYPE[,TYPE] (repeatable). NAME must match an –ocap-publish, e.g. ‘dev.edera/foo=dev.edera/bar’.
  • --enable-spire-access Mount the SPIRE agent’s Workload API socket into the workload at /shared/zone/sockets/agent.sock, read-only, for workloads that can fetch their own SVID with a SPIFFE client. Requires a zone launched with –with-spire.
  • --enable-identity Have the zone agent fetch this workload’s SVID and write it into the workload at /run/spire/identity, read-only, as svid.<n>.pem, svid.<n>.key and bundle.<trust-domain>.pem, for workloads with no SPIFFE client. Requires a zone launched with –with-spire.
  • --require-signature Give this workload a SPIFFE identity only when its image has a verified signature from an identity the daemon’s [spire.sigstore] config allows. The daemon refuses the launch unless that config names allowed identities. With –enable-identity, the registered entry also requires edera:image-signature:verified.
  • --squash-uid <SQUASH_UID> KVM only: squash this workload’s writable host mounts into its zone’s own host identity (also changes the owner of each mount’s host path), so guest writes never land as a real host account. A number pins the exact host UID, ‘auto’ opts in with one allocated from the zone’s credential pool. Setting either this or –squash-gid opts in; independent of it otherwise.
  • --squash-gid <SQUASH_GID> KVM only: same as –squash-uid, for the host gid. Setting either this or –squash-uid opts in; independent of it otherwise.
  • --ocap-priority <OCAP_PRIORITY> Preference weight for a published capability, as NAME=N (repeatable). Higher wins among providers of the same capability; NAME must match an –ocap-publish.

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.

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, tree, json, json-pretty, jsonl, yaml, key-value, simple, quiet].
  • -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: table, tree, json, json-pretty, jsonl, yaml, key-value, simple, quiet].

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.
  • prune Remove cached images whose linked blob is gone.
  • list List cached images.
  • list-kernel-variants List the named kernel variants the daemon can resolve.

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].

prune

Remove cached images whose linked blob is gone.

 protect image prune

list

List cached images.

 protect image list [OPTIONS]

Options:

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

list-kernel-variants

List the named kernel variants configured under [zone.kernel-variants] in daemon.toml. These names are the values accepted by zone launch --kernel-variant and the dev.edera/kernel-variant pod annotation.

 protect image list-kernel-variants [OPTIONS]

Options:

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

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, tree, json, json-pretty, jsonl, yaml, key-value, simple, quiet].

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, tree, json, json-pretty, jsonl, yaml, key-value, simple, quiet].

host

Manage the host of Edera Protect.

 protect host <COMMAND>

Subcommands:

  • cpu-topology Display information about the host CPU topology.
  • resources Get aggregate memory, CPU, and topology resources of the host.
  • 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.
  • hv-zone-details Display per-domain memory and resource usage from the hypervisor.
  • spire-start Launch a SPIRE server zone (the daemon runs the server using its [spire] config).

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, tree, json, json-pretty, jsonl, yaml, key-value, simple, quiet].

resources

Get aggregate memory, CPU, and topology resources of the host.

 protect host resources [OPTIONS]

Options:

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

status

Get information about the host.

 protect host status [OPTIONS]

Options:

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

control-snoop

Snoop on the Control API.

 protect host control-snoop [OPTIONS]

Options:

  • -o, --output <OUTPUT> Output format [default value: simple] [possible values: table, tree, json, json-pretty, jsonl, yaml, key-value, simple, quiet].
  • --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: table, tree, json, json-pretty, jsonl, yaml, key-value, simple, quiet].

hv-console

Display hypervisor console output.

 protect host hv-console

hv-debug-info

Read hypervisor debug information.

 protect host hv-debug-info

hv-zone-details

Display per-domain memory and resource usage from the hypervisor.

 protect host hv-zone-details [OPTIONS]

Options:

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

spire-start

Launch a SPIRE server zone (the daemon runs the server using its [spire] config).

 protect host spire-start [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].
  • --cpus-hard-affinity <CPUS_HARD_AFFINITY> vCPUs to host CPUs hard affinity.
  • --cpus-soft-affinity <CPUS_SOFT_AFFINITY> vCPUs to host CPUs soft affinity.
  • --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 MiB.
  • --attach-scratch-disk <ATTACH_SCRATCH_DISK> Attach a host disk as a scratch disk.
  • -D, --device <DEVICE> Devices to request for the zone.
  • -k, --kernel <KERNEL> OCI kernel image for zone to use [deprecated: prefer –kernel-variant].
  • --kernel-variant <KERNEL_VARIANT> Named kernel variant to use. Takes precedence over –kernel if both are given. Use protect-ctl image list-kernel-variants to see available kernels.
  • -I, --initrd <INITRD> OCI initrd image for zone to use.
  • --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.
  • --vm-image <VM_IMAGE> Boot the zone from this VM disk image (filename under the daemon’s vm-image directory). Mutually exclusive with the container payload flags (–kernel, –initrd, –addon, –create-scratch-disk, –attach-scratch-disk).
  • --vm-image-format <VM_IMAGE_FORMAT> Disk image format for –vm-image; required when –vm-image is set [possible values: raw, qcow2].
  • --timeout <TIMEOUT> Seconds to wait for the zone to be ready before giving up; 0 waits indefinitely. Only used with –wait/–attach [default value: 60].
  • -W, --wait Wait for the zone to be ready before returning.

object-capability

Inspect and use object capabilities. Also available as protect ocap.

 protect object-capability <COMMAND>

Subcommands:

  • list List published object capabilities.
  • dial Run a session against a published object capability.

list

List published object capabilities.

 protect object-capability list [OPTIONS]

Options:

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

dial

Run a session against a published object capability.

 protect object-capability dial [OPTIONS] <NAME> [ARGS]...

Arguments:

  • <NAME> Capability requested, e.g. dev.edera/bar. May be a capability type implemented by several providers.
  • <ARGS> Program and arguments to run.

Options:

  • --provider <PROVIDER> Pin the implementation published under this name instead of taking the highest-priority provider, e.g. dev.edera/foo.
  • -t, --tty Allocate an interactive tty.
  • -e, --env <ENV> Environment variables (KEY=VALUE).

completion

Output shell completion code for the specified shell.

 protect completion <SHELL>

Arguments:

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