Skip to content

ctl.en.md

Latest commit

 

History

History
138 lines (93 loc) · 3.39 KB

ctl.en.md

File metadata and controls

138 lines (93 loc) · 3.39 KB
Raw

revm ctl

revm ctl controls the control plane of an existing session. It never starts a new VM and never executes guest commands.

Supported control operations:

  • --list-port: list current gvproxy port mappings.
  • --port-export: expose a guest TCP port on the host.
  • --port-unexport: remove a host port exposure.
  • --export-rootfs: export the rootfs from the session directory to a host tar.zst file.
  • --import-rootfs: import a host tar.zst file as the rootfs for the session selected by --id.

Use revm attach to connect to the guest or execute commands.

Usage

revm ctl --id <session-id> --list-port
revm ctl --id <session-id> --port-export <spec>
revm ctl --id <session-id> --port-unexport <spec>
revm ctl --id <session-id> --export-rootfs <path.tar.zst>
revm ctl --id <session-id> --import-rootfs <path.tar.zst>

Port operations require --id to reference a running session. Rootfs import and export operate directly on the session directory; --id is the target rootfs session ID.

Export Rootfs

Export the rootfs from the session directory to a tar.zst file:

revm ctl --id web --export-rootfs ./rootfs.tar.zst

The archive is rooted at the rootfs contents and does not add an extra rootfs/ directory. The output path cannot be inside that session rootfs directory.

Import Rootfs

Import a tar.zst file as the rootfs for the session selected by --id:

revm ctl --id web --import-rootfs ./rootfs.tar.zst

Import first extracts into a temporary directory under the session directory, then replaces:

~/.cache/revm/<session-id>/rootfs

Because of that, --id is the imported rootfs ID. Import replaces any existing rootfs; do not import while a VM is using that rootfs.

List Ports

List every current port mapping:

revm ctl --id web --list-port

The output includes revm's internal SSH forward, container port publishing, and manually exposed ports:

PROTOCOL  HOST            GUEST
tcp       127.0.0.1:6123  192.168.127.2:22
tcp       127.0.0.1:8080  192.168.127.2:8000

Expose Ports

Expose a guest port:

revm ctl --id web --port-export 127.0.0.1:8080:8000
curl http://127.0.0.1:8080

Remove the exposure:

revm ctl --id web --port-unexport 127.0.0.1:8080

Update multiple ports at once:

revm ctl --id web \
  --port-export 127.0.0.1:8080:8000 \
  --port-export 127.0.0.1:8443:8443

Port formats:

--port-export [tcp:]<host-port>:<guest-port>
--port-export [tcp:]<host-ip>:<host-port>:<guest-port>
--port-unexport [tcp:]<host-port>
--port-unexport [tcp:]<host-ip>:<host-port>

When host IP is omitted, 127.0.0.1 is used. Only TCP and IPv4 are currently supported.

How It Works

revm ctl first reads VM metadata from the session management API:

~/.cache/revm/<session-id>/socks/vmctl.sock

Port updates read the gvproxy control endpoint from the management API, then call the gvproxy forwarder API:

/services/forwarder/expose
/services/forwarder/unexpose

Because of that, port updates require gvisor networking. tsi networking does not support --port-export or --port-unexport.

Invalid Usage

This fails because no control operation is selected:

revm ctl --id dev

This fails because ctl does not execute guest commands:

revm ctl --id dev -- sh

Use this instead:

revm attach --id dev -- sh