Command reference

nspawn --help and nspawn COMMAND --help print the same information. Errors are printed as error: ... on standard error and the exit status is 1; exec and an attached run exit with the status of the program they ran.

Every command but daemon, completions and the unit hooks is a call to the service on the system bus, which asks polkit whether the caller may take the action: the listings (images ls, ps, machines ls, inspect, top, stats, events, network ls, network inspect, volume ls, secret ls, secret inspect) ask for org.nspawn.inspect; everything else, search and hub included, asks for org.nspawn.manage. Both are for administrators by default, and root is never asked.

Global options

These are accepted by every command and can also come from the environment:

login and logout take the registry as their argument, so there --registry has to come before the subcommand: nspawn --registry hub.example login -u me. -V, --version belongs to nspawn itself, not to the subcommands.

hub

Query the hub (an OCI registry).

hub ls

nspawn hub ls [FILTER] [--no-tags]

Lists the repositories of the registry with their tags. FILTER keeps the repositories whose name contains that text; --no-tags skips the tag query of every repository, which is faster on big registries. hub list is an alias.

hub tags

nspawn hub tags REPOSITORY

Prints the tags of one repository, one per line.

search

nspawn search TERM [--source hub|dockerhub] [-n LIMIT]

Finds images on the hub and on Docker Hub, like docker search, and prints every hit with its source and the reference pull takes.

login

nspawn login [REGISTRY] [-u USERNAME] [--password-stdin]

Checks credentials against a registry, like docker login, and keeps them in /etc/nspawn/auth.json for pull, push, search and hub.

logout

nspawn logout [REGISTRY]

Forgets the credentials stored for a registry (the hub by default).

pull

nspawn pull REFERENCE [-n NAME] [--backend BACKEND] [--mode MODE] [-f] [--no-verify]

Downloads an image from the hub or another registry, checking its signature first where the registry has a policy (the hub’s is built in; see Signed images), and makes it available to systemd-machined. On a terminal a bar shows how far each blob got, with its size, speed and time left; in a pipe or a log only the lines are written.

create

nspawn create SOURCE NAME [--backend BACKEND] [--network NETWORK]... [--network-alias [NETWORK=]NAME]...
              [-p [IP:]HOST:CONTAINER[/udp]]... [--entrypoint PROGRAM] [-e VAR[=VALUE]]...
              [-v SOURCE:TARGET[:ro]]... [-l KEY=VALUE]... [--restart POLICY] [-m SIZE] [--memory-swap SIZE]
              [--cpus N] [--pids-limit N] [HEALTHCHECK OPTIONS] [OTHER OPTIONS] [--interface IFACE]... [--secret SECRET]...
              [-f] [--no-verify] [-- ARGUMENTS...]

Makes another machine from a local image, like docker create, without touching the registry; a reference that is not local is pulled first, under the image’s own name, as run does. The layers are shared with the source.

build

nspawn build [DIRECTORY] -t TAG [-n NAME] [-d DISTRIBUTION] [-r RELEASE]
             [--profile PROFILE]... [--backend BACKEND] [--mode MODE] [-f]
             [--keep-output] [-- MKOSI_ARGS...]

Builds an image with mkosi and makes it available locally, ready to push. Needs mkosi.

push

nspawn push IMAGE [--to REFERENCE]

Uploads a local image to the hub or another registry, with the credentials stored for it. IMAGE is a local image name, or the reference it was pulled from or built as. --to pushes it under a different reference than the one recorded for the image. The destination needs a tag, not a digest. On a terminal a bar shows how far each blob got, as with pull.

images

Manage local images.

images ls

nspawn images ls [--json]

Lists the local images known to systemd-machined: name, type, and for the ones nspawn installed the backend, origin (pull, build or create), source reference, size and whether the image is read-only. --json prints the list as the service returns it. images list is an alias.

images rm

nspawn images rm NAME...

Removes local images and the layers and blobs nobody uses any more. Refuses the image of a running machine, or of one its restart policy is bringing back, and a name nothing is behind. Named volumes are kept. A pulled image is a machine too, so this is the same as rm without --force.

rm

nspawn rm [-f] NAME...

Removes machines, like docker rm: the record, the tree, the unit files, the boot link a restart policy made, and the layers and blobs nobody else uses. Every name is tried; one that cannot be removed, or that nothing is behind (no machine or image named NAME), is reported at the end. Named volumes are kept, and each one kept is mentioned.

ps, machines ls

nspawn ps [-a] [--json]
nspawn machines ls [-a] [--json]

Lists the running machines, like docker ps: name, image, mode, command, state, uptime, leader PID, network and OS. A machine whose restart policy is bringing it back shows as restarting, even without -a. -a, --all also lists the nspawn machines that are not running: stopped, or starting and closing while their unit comes up or goes down. --json prints what the service returns for each machine, its whole record included. machines list is an alias of machines ls.

inspect

nspawn inspect NAME...

Prints everything nspawn knows about machines or images, running or not, as a JSON array with one object per name, like docker inspect: the record (image reference, digest, backend, mode, networks, addresses, aliases, ports, volumes, environment, command, labels, restart policy, limits, healthcheck, secrets, the other flags, and who signed the image and when, as the pull verified it: signed_by, signed_at), for a running machine its state, start time, leader PID, OS and health, and for a stopped one the exit code of its last run. The keys are those of the D-Bus interface.

start

nspawn start NAME [--network NETWORK]... [--network-alias [NETWORK=]NAME]... [-p [IP:]HOST:CONTAINER[/udp]]...
             [--entrypoint PROGRAM] [-e VAR[=VALUE]]... [-v SOURCE:TARGET[:ro]]... [-l KEY=VALUE]...
             [--restart POLICY] [-m SIZE] [--memory-swap SIZE] [--cpus N] [--pids-limit N]
             [--health-cmd COMMAND] [--health-interval D] [--health-timeout D] [--health-retries N]
             [--health-start-period D] [--health-start-interval D] [--no-healthcheck]
             [--hostname NAME] [-u USER[:GROUP]] [-w DIR] [--cap-add CAP]... [--cap-drop CAP]... [--privileged]
             [--read-only] [--tmpfs PATH[:OPTIONS]]... [--shm-size SIZE]
             [--device HOST[:CONTAINER[:PERMISSIONS]]]... [--dns ADDRESS]... [--dns-search DOMAIN]...
             [--add-host HOST:IP]... [--ulimit NAME=SOFT[:HARD]]... [--oom-score-adj N]
             [--stop-signal SIGNAL] [--stop-timeout SECONDS] [--timezone MODE] [--log-driver DRIVER] [--init] [--sysctl KEY=VALUE]...
             [--interface IFACE]... [--secret NAME[:TARGET[:MODE[:UID:GID]]]]... [--image-command] [--no-wait]
             [-- ARGUMENTS...]

Boots an image as a machine. Every option is remembered for the next start.

A path inside the machine, the target of -v or --secret, a --tmpfs or a --device path, must be plain: a . or .. component is refused.

run

nspawn run [-d] [--rm] [-i] [-t] [-n NAME] [--pull missing|always|never]
           [--backend BACKEND] [--mode MODE] [-f] [--no-verify] [OPTIONS OF start] [--no-wait]
           REFERENCE [COMMAND [ARGUMENT...]]

Makes a machine from an image and starts it, like docker run: pull (or create from a local image with the same reference) followed by start, whose options are remembered as after start. What pull or create report goes to standard error, so that standard output carries the program’s output alone.

Without -d, run stays attached, as docker run does. The machine’s output follows until the machine ends, a line at a time, stdout and stderr together: it is read from nspawn’s journal, so nspawn logs NAME shows it later too, and the machine goes on should run be interrupted. With --log-driver none it comes straight from the program instead, and nothing is kept. run exits with the program’s exit code, or 128 plus the signal it died of (130 after Ctrl-C, 137 after kill). Ctrl-C, SIGTERM, SIGHUP and SIGQUIT are passed on to the program; a third Ctrl-C within a second leaves the machine running and returns. A booted image shows its console until it powers off, and Ctrl-C powers it off.

stop

nspawn stop NAME... [-f] [-t TIMEOUT] [--no-wait]

Powers off running machines, one after the other: the machine’s stop signal (--stop-signal, else the image’s) to the program of an app, a poweroff request to a booted machine. Stopping a machine that already ended only cleans up after it, and a paused one is thawed first. A machine with a restart policy stays stopped, and one that was waiting to be restarted is stopped too. An unless-stopped machine is also taken off the boot list until the next start; an always one stays enabled and starts again at the next boot (rm takes that away). Every name is tried; one that could not be stopped is reported at the end.

restart

nspawn restart NAME... [-t TIMEOUT]

Stops and starts machines, like docker restart: a stop followed by a start with everything the machine remembers, and prints each name once it runs again. A machine that is not running is started. Every name is tried; one that could not be restarted is reported at the end.

kill

nspawn kill [-s SIGNAL] NAME...

Sends a signal to running machines, like docker kill, and prints each name once it is sent. SIGKILL, the default, stops the machine for good, as stop --force does. Any other signal goes to the program of an app or the init of a booted machine, and the machine lives on unless the signal ends it, in which case its restart policy applies; the machine’s own stop signal (an app’s, or SIGRTMIN+3 and SIGRTMIN+4 for a booted machine’s init) ends it for good, as docker does.

pause, unpause

nspawn pause NAME...
nspawn unpause NAME...

pause freezes every process of running machines through the cgroup freezer of their units, like docker pause, and unpause thaws them; each name is printed once done. ps and inspect show a frozen machine as paused, and stop and kill thaw it first.

update

nspawn update NAME... [--restart POLICY] [-m SIZE] [--memory-swap SIZE] [--cpus N] [--pids-limit N]
              [--health-cmd COMMAND] [--health-interval D] [--health-timeout D] [--health-retries N]
              [--health-start-period D] [--health-start-interval D] [--no-healthcheck]

Changes the restart policy, the limits and the healthcheck of machines, like docker update, and prints each name once changed. A running machine gets the new limits and healthcheck at once (its probes start afresh) and the policy for its next ending; a stopped one at its next start. The options are those of start; at least one is needed.

exec

nspawn exec MACHINE [-u USER] [-e VAR[=VALUE]]... [-w DIR] [-T] [-t] [-i] [-d] COMMAND...

Runs a command inside a running machine of either kind, attached to the terminal when standard input and output are one, in the machine’s namespaces, with the image’s environment and the machine’s -e variables. The program is found on the machine’s PATH and runs with the machine’s capabilities and resource limits, like its own processes, except CAP_SYS_BOOT in an app that shares the host’s user namespace (unless --privileged), since the command does not carry the seccomp filter that keeps kexec out of the machine; right after a start it waits, a few seconds at most, until systemd-nspawn has finished confining the machine. Exits with the command’s status.

shell

nspawn shell MACHINE [-u USER]

Opens an interactive shell inside a running machine as USER (default root): machined’s login session for booted machines, /bin/sh in the machine’s namespaces for app machines.

top

nspawn top MACHINE

Lists the processes of a running machine, like docker top: PID as the host sees it, USER as the machine sees it, TIME of CPU and COMMAND, read from the machine’s cgroup and PID namespace.

cp

nspawn cp MACHINE:PATH DESTINATION
nspawn cp SOURCE MACHINE:PATH

Copies files and directories between the host and a machine, like docker cp. The machine may be running, or stopped if it is an overlay or flat machine; a stopped mstack machine has no tree on the host until it runs.

• An existing directory as the destination receives the source under its own name; anything else is the name of the copy, whose parent must exist. A destination ending in / must be a directory.
• DIR/. as the source copies the contents of DIR instead of DIR itself.
• What goes into a machine belongs to its root, whatever user namespace the machine runs in; what comes out belongs to the user who ran cp. Modes and modification times are kept.
• Paths inside the machine are resolved inside it: a link there, absolute or not, never leads to the host. Links are copied as links; devices, sockets and fifos are left out, and so are the kernel’s file systems mounted inside a running machine (/proc, /sys and the like).
• A relative path after MACHINE: starts at the machine’s root. A local path with a colon is written ./a:b.

logs

nspawn logs MACHINE... [-f] [-n N] [--since WHEN] [--until WHEN] [-t] [--all] [--inside]

Shows what machines printed, like docker logs. With several machines every line carries its machine’s name (web | ...), the way docker compose shows them. The lines come from nspawn’s journal namespace (--log-driver local, the default) and from the system’s journal, which holds what a machine wrote before 1.8.0 or with --log-driver journal. A machine started with --log-driver none keeps nothing, and logs says so (a booted one’s own journal is still there with --inside).

stats

nspawn stats [NAME...] [--no-stream] [--json]

Shows what running machines use, like docker stats: CPU (100% is one CPU busy), memory in use against the limit (the host’s memory without one), network and disk traffic, and processes, read from the cgroup of each machine’s unit, which holds the whole machine. Without names it shows every running machine. The table is drawn again every second on a terminal.

events

nspawn events [--since WHEN] [--until WHEN] [-f KEY=VALUE]... [--json]

Reports what happens to machines, networks, volumes and secrets, like docker events: for machines start, die (with its exit code), stop, restart, oom and fail, which systemd logs for every machine however it was started, health_status (with the new status) and what nspawn does, pull, build, create, push, kill, update and remove; for networks, volumes and secrets create and remove. It reads the journal, so past events can be read back.

network

The default network (bridge) and the ones made with network create.

network up

nspawn network up

Brings up every network’s bridge with its NAT rules and firewall exceptions, and brings the published ports in line with the machines that run. start does it for its machine’s network too; this is useful at boot and for troubleshooting.

network ls

nspawn network ls [--json]

Lists the networks, the default one first: name, bridge interface, subnet, whether it is internal, and the machines whose records name it. --json prints them as the service returns them. network list is an alias.

network create

nspawn network create NAME [--subnet CIDR] [--internal] [-l KEY=VALUE]...

Makes a network of its own, like docker network create: a bridge nsbr-NAME (hashed when the name is long) with its NAT and firewall rules, brought up at once. Machines of one network reach each other by name, and nothing of another network, the default one included, reaches them; ports they publish are reachable from everywhere through the host, as from the LAN.

network inspect

nspawn network inspect NAME...

Prints networks as a JSON array, like docker network inspect: name, interface, subnet, gateway, whether it is internal, its labels, and its machines with their addresses, aliases, ports and whether they run. bridge is the default network.

network rm

nspawn network rm NAME...

Removes networks no machine uses, with their bridges and rules. A network a machine’s record names is refused, with the machines that use it; the default network cannot be removed. network remove is an alias.

network prune

nspawn network prune [-f]

Removes every network no machine uses, after asking on standard input unless -f is given.

volume

Named volumes, the directories -v NAME:/path makes under /var/lib/nspawn/volumes. Removing a machine keeps them.

volume ls

nspawn volume ls [--json]

Lists the named volumes with the machines whose records mount them, when each was made and its path. --json prints the list as the service returns it. volume list is an alias.

volume create

nspawn volume create NAME

Makes a volume ahead of its first use (start makes it otherwise): a directory owned by root, mode 0755. One that exists already is fine. Names have letters, digits, _, . and -, not starting with a dot.

volume rm

nspawn volume rm NAME...

Removes volumes no machine uses. A volume a machine still names is refused until that machine is started with other volumes (or -v none) or removed.

volume prune

nspawn volume prune [-f]

Removes every volume no machine uses once a yes comes on standard input, as docker does: from a script, whose input ends without one, nothing is removed. -f removes them without asking.

secret

Secrets, like docker’s without a swarm: kept encrypted on the host with systemd-creds, handed to machines as files by --secret on start, run and create.

secret ls

nspawn secret ls [--json]

Lists the secrets: name, when it was made, the size of its plaintext, its labels and the machines that take it; never the content. --json prints the list as the service returns it. secret list is an alias.

secret create

nspawn secret create NAME [--file FILE] [-l KEY=VALUE]...

Keeps a secret read from standard input, or from --file, encrypted for this host: bound to its TPM2 where there is one, to its credential key otherwise, under /var/lib/nspawn/secrets. A name that exists already is refused.

secret inspect

nspawn secret inspect NAME...

Prints what nspawn keeps about secrets as a JSON array: name, creation time, size, labels and the machines that take them; never the content.

secret rm

nspawn secret rm NAME...

Removes secrets no machine takes. One a machine’s record names is refused, with the machines that take it, until they are started with other secrets (or --secret none) or removed. Every name is tried; one that cannot be removed is reported at the end. secret remove is an alias.

daemon

nspawn daemon [--install] [--idle-exit SECONDS]

Serves org.nspawn on the system bus. The bus starts it on demand, so this is not a command to type; --install is.

completions

nspawn completions bash|elvish|fish|powershell|zsh

Writes the completions for that shell on standard output. Commands and flags come from the same definition the command line itself is built from; besides them, TAB completes names, asked from the service as it goes:

The service hands those names to any user without asking polkit, so this works under sudo and without a password; secrets are not completed. The flags come once the word starts with - (- brings the short forms, -- the long ones), or where there is no name to offer. The packages install the completions, so this is for a binary you built yourself:

nspawn completions bash > ~/.local/share/bash-completion/completions/nspawn

man nspawn is the same reference as this page, generated the same way.

Unit hooks

nspawn network prepare NAME, nspawn network publish NAME and nspawn network release NAME are what the drop-in of systemd-nspawn@NAME.service runs as ExecStartPre, ExecStartPost and ExecStopPost, and nspawn health-run NAME is what nspawn-health-NAME.service runs to probe a machine’s healthcheck. They are not meant to be typed and are hidden from --help.