vmlab container

vmlab container controls one lab container at a time: its lifecycle, a command or a shell inside it, its console log and its IP address. A lab container runs as a micro-VM, so the power subcommands are the same requests vmlab vm makes under the other noun.

vmlab container <COMMAND>

Every subcommand takes a container reference of the form [lab/]container. A bare name is resolved against the lab in the current directory, and the lab daemon is started if none is running. The qualified form addresses a lab that is already running from any directory and never starts one.

vmlab container start

vmlab container start <CONTAINER>

Starts one container without running the lab's up plan. The image is pulled first if it is still pending, with progress on the terminal, then the host binaries are checked and the micro-VM boots. When the container declares volumes the bundled SMB server is started so they can mount. A container that is already running is left alone. Nothing is printed on success.

The container is built from the lab file as it is on disk now: if vmlab.wcl has changed since the lab daemon loaded it, the daemon is replaced first, and the verb refuses while another machine in the lab still runs. See Editing the lab file between runs.

vmlab container stop

vmlab container stop [OPTIONS] <CONTAINER>

Stops one container through its ladder. The first rung asks the container's init over the control channel to signal the entrypoint and power off once it exits, waiting the image's stop grace (default 10 seconds) plus 15 seconds. The second rung is a shutdown through the guest agent, and the last a hard kill. --force kills at once. Only the named container stops; its dependents keep running. Nothing is printed on success.

vmlab container restart

vmlab container restart <CONTAINER>

Stops the container gracefully, waits up to 60 seconds for it to settle, and boots it again. Its scratch overlay is kept, so files written since the last destroy survive. Nothing is printed on success.

Like vmlab vm restart, it refuses after an edit to vmlab.wcl, since a new daemon cannot take over a running container; vmlab down and vmlab up apply the edit.

vmlab container destroy

vmlab container destroy <CONTAINER>

Force-stops the container and deletes its scratch overlay, runtime directory and snapshots. Named volumes are lab-scoped and survive until vmlab destroy. The container stays declared, so a later vmlab up <container> re-creates it from the image. Prints container "<name>" destroyed.

vmlab container exec

vmlab container exec [OPTIONS] <CONTAINER> [-- <CMD>...]

Runs one command inside the container through the guest agent, the container spelling of vmlab exec. The command's stdout and stderr are mirrored to this process's stdout and stderr once it finishes, and its exit code becomes this verb's exit code. Without a command the verb refuses with `nothing to execute — usage: vmlab container exec <container> -- <cmd> [args...]`.

Who the command runs as follows the ladder in Logins: --user first, then the container's default login {}, then the agent identity, root. A container has no PAM, so a declared login is entered by setuid, the container identity floor. A login that cannot be resolved fails naming both the account and the machine.

vmlab container logs

vmlab container logs [OPTIONS] <CONTAINER>

Prints the tail of the container's console log, which carries the micro-VM's kernel messages and the entrypoint's stdout and stderr. With --follow the tail is printed and then the daemon polls the log every half second and streams what was appended, until you press Ctrl-C or the container stops. An empty log prints nothing. The log is read from the host, so it works while the container is stopped and needs no agent.

vmlab container ip

vmlab container ip <CONTAINER>

Prints the first IPv4 address the guest agent reports on one of the container's NICs. The container must be running with its agent answering.

vmlab container shell

vmlab container shell [OPTIONS] <CONTAINER>

Opens an interactive terminal inside the container over the agent's virtio-serial channel, so it works with no guest network. Every attach opens a fresh session at your terminal's current size, and resizes follow the local window. The local terminal goes raw; Ctrl-] detaches, as in telnet. The banner connected to "<name>" — escape character is ^] is printed on connect. Identity is resolved the same way as for exec.

Examples

Run a health probe inside the mixed-lab web container:

vmlab container exec web -- wget -qO- http://localhost/

Watch the entrypoint start up:

vmlab container logs -f -n 20 web

Open a shell as the dev login on the dev-container example's container:

vmlab container shell dev-container/dev01 --user dev

Exit status

Exit status is 0 on success. exec exits with the guest command's own exit code when it is non-zero. Exit 4 (not_found) means the lab declares no container by that name, for stop, exec, logs, ip and shell. Exit 6 (unsupported) is what logs answers on a machine with no console log. start, restart and destroy exit 1 (failed) on an unknown name and on any boot, stop or disk failure; every subcommand exits 1 on a container that is not running, an agent that does not answer, a login that cannot be resolved, or a lab that cannot be reached. Exit 5 (conflict) means the supervisor tracks a lab with this name from another directory. A usage error, including --password without --user, exits 2.