Document nspawn 3.2.0

content/en/docs/building.md

@@ -20,9 +20,11 @@ as: the tag moves to the new build, so a script that builds and runs its image
 builds it again. A machine that has the name (one that ran, starts or runs), or
 an image of another reference, keeps it, and the build goes beside it with the
 same reference, into the image an earlier build of the tag put there or else
-under a free name (`app-2`), which a note says; `run`, `create`, compose and the
-Docker API find it by the reference, the image before the machine. An mkosi
-build given `--name` is refused instead when a machine or an image of another
+under a free name (`app-2`), which a note and the build's last line say. The
+name stays with the record that has it: `run` and `create` take the build by the
+name the build gave or by the reference (`app:latest`), and compose and the
+Docker API find it by the reference, the image before the machine. An
+mkosi build given `--name` is refused instead when a machine or an image of another
 reference has that name. `--force` replaces whatever has the name, a machine
 that ran included, and refuses one that runs. `-f` names the Dockerfile, so
 `--force` has no short form.

content/en/docs/images.md

@@ -28,18 +28,22 @@ An image reference has the form `[registry/]repository[:tag|@digest]`:
 - A digest is a sha256 one; sha384 and sha512 digests are refused, in a
   Dockerfile's `FROM` too.
 
-`run` and `create` look for a local image of a name without a registry under
-the configured registry first, then as Docker Hub's (`app` as
+`run` and `create` take a local image by its local name, and look for one of a
+reference, a name without a registry under the configured registry first, then
+as Docker Hub's (`app` as
 `docker.io/library/app`, the name of an image compose pulled from Docker Hub),
 and pull from the configured registry only when neither is there. Given by
 reference, the source is the most recently pulled image of that reference that
 never ran as a machine.
 
-The **local name** of an image, the one `start`, `stop`, `exec` and friends
-use, is derived from the reference (`fedora:44` becomes `fedora-44`) unless
-`--name` says otherwise. It has to be a valid machine name, which is a host
-name: letters, digits, `.` and `-`, at most 64 characters, with no part between
-dots empty or starting or ending with `-`.
+The **local name** of an image is derived from the reference (`fedora:44`
+becomes `fedora-44`) unless `--name` says otherwise. It has to be a valid
+machine name, which is a host name: letters, digits, `.` and `-`, at most 64
+characters, with no part between dots empty or starting or ending with `-`.
+Every command takes an image by its local name or its reference alike
+(`nspawn images rm fedora:44` and `nspawn images rm fedora-44` remove the same
+image), and a reference never names a machine made from the image; the
+[reference](/docs/reference/#names) has the rule.
 
 ## The hub
 
@@ -302,7 +306,7 @@ create (`old-arch` above, with `-` in the nspawn columns). `ORIGIN` is `pull`,
 `build` or `create`.
 
 ```shell
-sudo nspawn images rm NAME...
+sudo nspawn images rm NAME|REFERENCE...
 ```
 
 `images rm` refuses to remove the image of a running machine, or of one its

content/en/docs/machines.md

@@ -90,8 +90,10 @@ variables and the volumes of the last run:
 - `--gpus` and `--device VENDOR/CLASS=NAME` hand it devices of the host's CDI
   specs; see [GPUs and CDI devices](#gpus-and-cdi-devices).
 
-Machines are started by name. A reference (`fedora:44`, `docker.io/x`) is
-refused with a hint to `pull` it or to `create` a machine from a local image.
+`start` takes a machine or an image by its name, or an image by its reference
+(see [Names](/docs/reference/#names)), which then runs as a machine itself; a
+reference of no image here (`fedora:44`, `docker.io/x`) is refused with a hint
+to `pull` it or to `create` a machine from a local image.
 Images that were not installed by nspawn, for example something created with
 `machinectl import-tar`, can be started too: they get the stock template's veth
 networking, and nspawn starts systemd-networkd on the host when the host has no
@@ -101,15 +103,19 @@ are refused for them.
 ## run
 
 ```shell
-sudo nspawn run [-d] [--rm] [-i] [-t] [OPTIONS] REFERENCE [COMMAND [ARGUMENT...]]
+sudo nspawn run [-d] [--rm] [-i] [-t] [OPTIONS] IMAGE [COMMAND [ARGUMENT...]]
 ```
 
 `run` makes a machine from an image and starts it: `pull`,
 or `create` from a local image with the same reference, then `start`, with the
-options of both. A name without a registry is looked for here under the
-configured registry, then as Docker Hub's (`app` as `docker.io/library/app`,
-the name of an image compose pulled from Docker Hub), and only then pulled from
-the configured registry.
+options of both. The image is looked for here as every command looks for one
+(see [Names](/docs/reference/#names)): a local image's name, or a reference
+under the configured registry, then as Docker Hub's (`app` as
+`docker.io/library/app`, the name of an image compose pulled from Docker Hub),
+and only then pulled from the configured registry. Where an image has the name
+the machine would get (`nspawn build -t app:1 .`, then `nspawn run app:1`), the
+machine goes beside it under the first free `NAME-N` (`app-1-2`), which a note
+says, and the image stays for the next run.
 What follows the image replaces an app's command; one that
 starts with a dash comes after `--`. Without `-d` it stays with the machine:
 

content/en/docs/reference.md

@@ -3,7 +3,7 @@ title: Command reference
 linkTitle: Reference
 weight: 10
 description: >-
-  Every command and option of nspawn 3.1.0.
+  Every command and option of nspawn 3.2.0.
 ---
 
 `nspawn --help` and `nspawn COMMAND --help` list the options; this page
@@ -22,6 +22,36 @@ whether the caller may take the action: the listings (`images ls`, `ps`,
 `org.nspawn.manage`. Both are for administrators by default, and root is never
 asked.
 
+## Names
+
+Every command that takes a machine or an image reads its name one way. A
+machine and an image pulled or built here are both records with a name of their
+own. A text that can be a machine's name (letters, digits, `.` and `-`) is a
+name: the record of that name or nothing, so that `rm -f app` run again never
+takes an image of `app:latest` for the machine that went. Any other text is the
+reference of an image, under the configured registry first and then as a Docker
+Hub name (`nginx:1.27` is `docker.io/library/nginx:1.27` when no image of the
+configured registry's is here), and names the image pulled or built for it, the
+last one made of several: `busybox:1.37`, `docker.io/library/busybox:1.37` and
+`busybox-1.37`, the name it was pulled under, are one image to `run`, `create`,
+`push`, `rm`, `images rm`, `inspect`, `images inspect`, `start`, `exec`,
+`logs`, `network connect` and the rest. The commands that take an image,
+`run`, `create`, `push`, `images rm` and `images inspect`, read a name nothing
+here has as a reference too: `nspawn run busybox` and `nspawn images rm
+busybox` take the image of `busybox:latest`, whatever its name. The MACHINE of
+`cp`'s MACHINE:PATH is a name.
+
+A reference never names a machine made from the image, which has a name of its
+own: `rm nginx:latest` removes the image and leaves the machines made from it,
+and `stop nginx:latest` stops none. Where the image is only read (`inspect`,
+`images inspect`, `push`), a machine made from it holds it too and is taken
+when no image of it is left. A text that names nothing here is refused by the
+command (a reference in full under `--registry`, when it is given): a reference
+of no image here is `no local image of REFERENCE` to
+`images rm`, `images inspect`, `push` and `run --pull never`, and `no machine or
+image of REFERENCE` to the commands that take a machine (`rm`, `inspect`,
+`stop`, `exec`, `logs` and the rest; `start` adds how to pull it).
+
 ## Global options
 
 These are accepted by every command and can also come from the environment;
@@ -225,8 +255,8 @@ 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
+stored for it. `IMAGE` is a local image's name or its reference (see
+[Names](#names)), the one 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`.
 
@@ -256,10 +286,9 @@ nspawn images inspect [-f FORMAT] NAME|REFERENCE...
 
 Prints the records of images as a JSON array, the keys of
 [inspect](#inspect) without the ones it adds for a machine (state, start
-time, leader, health, published ports, exit code). A record's name is that
-record; anything else is a reference, and the image it means is the one the
-service resolves it to, as `run` and `create` do: `busybox:1.37` is the
-configured registry's `busybox:1.37` when there is one here,
+time, leader, health, published ports, exit code). Each name is read as every
+command reads one (see [Names](#names)): `busybox:1.37` is the configured
+registry's `busybox:1.37` when there is one here,
 `docker.io/library/busybox:1.37` otherwise; an image goes before a machine made
 from it, and a machine is shown when it alone holds the image. One that is not
 here is said as `no local image of NAME` after the others are printed, and the
@@ -282,24 +311,28 @@ repeatable; `-f` skips the question.
 ### images rm
 
 ```text
-nspawn images rm NAME...
+nspawn images rm NAME|REFERENCE...
 ```
 
-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
+Removes local images and the layers and blobs nobody uses any more, each by its
+name or its reference (see [Names](#names)): a reference removes the image of
+it and never a machine made from it, and one of no image here is refused with
+`no local image of REFERENCE`. 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](#rm) without `--force`.
 
 ## rm
 
 ```text
-nspawn rm [-f] NAME...
+nspawn rm [-f] NAME|REFERENCE...
 ```
 
 Removes machines: 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
+boot link a restart policy made, and the layers and blobs nobody else uses. An
+image goes by its reference too, never a machine made from it (see
+[Names](#names)). Every name is tried; one that cannot be removed, or that
+nothing is behind (`no machine or image named NAME`, `no machine or image of
+REFERENCE`), is reported at the end. Named volumes are
 kept, and each one kept is mentioned.
 
 A machine that others depend on (`--depends-on`) or take their network from
@@ -336,7 +369,7 @@ each machine, its whole record included. `machines list` is an alias of
 ## inspect
 
 ```text
-nspawn inspect [-f FORMAT] NAME...
+nspawn inspect [-f FORMAT] NAME|REFERENCE...
 ```
 
 Prints everything nspawn knows about machines or images, running or not, as a
@@ -481,15 +514,18 @@ A path inside the machine, the target of `-v` or `--secret`, a `--tmpfs` or a
 ```text
 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...]]
+           IMAGE [COMMAND [ARGUMENT...]]
 ```
 
 Makes a machine from an image and starts it: `pull` (or
 `create` from a local image with the same reference) followed by `start`, whose
-options are remembered as after `start`. A name without a registry is looked
-for here under the configured registry, then as Docker Hub's
-(`docker.io/library/NAME`), and pulled from the configured registry only when
-neither is there. What `pull` or `create` report goes to
+options are remembered as after `start`. The image is looked for here as every
+command looks for one (see [Names](#names)): a record's name (an image's, or a
+machine's, which gives the image it was made from, its layers and not what
+changed inside it, as `create` takes it), or a reference under the configured
+registry, then as Docker Hub's (`docker.io/library/NAME`), pulled from the
+configured registry only when neither is there. A pull of a record's name asks
+for the reference that record goes by. What `pull` or `create` report goes to
 standard error, so that standard output carries the program's output alone.
 
 Without `-d`, `run` stays attached. The machine's output
@@ -505,13 +541,13 @@ image shows its console until it powers off, and Ctrl-C powers it off.
 
 | Option | Meaning |
 | --- | --- |
-| `REFERENCE` | `[registry/]repository[:tag\|@digest]`, for example `nginx:1.27`. |
+| `IMAGE` | A local image's name, or a reference, `[registry/]repository[:tag\|@digest]`, for example `nginx:1.27`. |
 | `COMMAND [ARGUMENT...]` | App images: replace the image's cmd and follow its entrypoint; everything after the reference that is not an option of `run`, or everything after `--`, which a command that starts with a dash needs. |
 | `-d`, `--detach` | Start the machine in the background and return; `nspawn logs -f NAME` follows its output. |
 | `--rm` | Remove the machine once it ends, with or without `-d`; named volumes stay. An image the run had to pull is kept under the image's local name when that name is free, and without `--name` the machine gets a name of its own (`alpine-3-1f0c9a2e`). Refused with a restart policy. A run that fails to start leaves nothing behind. |
 | `-i`, `--interactive` | App images: give the program this standard input. Not with `-d`. |
 | `-t`, `--tty` | App images: give the program a terminal; Ctrl-C and resizes reach it through the terminal. Closing the terminal stops the machine. With `-i` on a booted image: wait for it to boot, open a root shell, and power it off when the shell ends, with the shell's exit code. Not with `-d`. |
-| `-n`, `--name NAME` | Name of the machine. Default: derived from the reference, for example `nginx-1.27`. A name that is taken is refused, with a pointer to `start`. |
+| `-n`, `--name NAME` | Name of the machine. Default: derived from the image's name or reference, for example `nginx-1.27`; where an image has that name, the one run makes the machine from (`nspawn build -t app:1 .`, then `nspawn run app:1`) or another, the machine goes beside it under the first free `NAME-N` (`app-1-2`), which a note says, and the image stays for the next run, whatever `--force`, `--pull` and `--mode` say; `stop`, `logs` and `rm` then take the machine as `NAME-N`. A machine that has the name, or an image that has a name given here, is refused unless `--force`, with a pointer to `start` for a machine. |
 | `--pull missing\|always\|never` | When to ask the registry. `missing`, the default: a local image with the same reference is made into the machine, as `create` does, and the registry is asked only when there is none. `always`: every time, for the image the tag names now. `never`: a local image or nothing. |
 | `--backend auto\|overlay\|flat\|mstack` | How to assemble the machine, as for `pull`. |
 | `--mode auto\|boot\|app` | As for `pull`; a mode other than `auto` always pulls. |
@@ -1077,11 +1113,11 @@ them, TAB completes names, asked from the service as it goes:
 
 | After | TAB offers |
 | --- | --- |
-| `stop`, `exec`, `kill`, `pause`, `unpause`, `top`, `shell`, `stats`, `port` | the running machines |
+| `stop`, `exec`, `kill`, `pause`, `unpause`, `top`, `shell`, `stats`, `port`, `logs -f` | the running machines |
 | `start` | the images that do not run |
 | `rm`, `inspect`, `generate`, `logs`, `restart`, `update`, `wait`, `auto-update`, `images rm`, `--depends-on`, the machine of `network connect` and `network disconnect` | every machine and image |
 | `create`, `push` | the local images |
-| `run` | the references of the local images |
+| `run` | the local images, by their names and their references |
 | `--network` | the networks, and `host`, `none` and `veth` |
 | `network rm`, `network inspect`, `network connect`, `network disconnect` | the networks |
 | `volume rm` | the volumes |

hugo.yaml

@@ -53,7 +53,7 @@ params:
   privacy_policy: /about/#privacy
 
   # Version of nspawn the documentation describes.
-  version: 3.1.0
+  version: 3.2.0
   archived_version: false
 
   # In-page links to open issues and suggest changes.