diff --git a/content/en/docs/images.md b/content/en/docs/images.md index c6b8662..d6fa81a 100644 --- a/content/en/docs/images.md +++ b/content/en/docs/images.md @@ -178,10 +178,14 @@ the registry, never the policy. sudo nspawn pull REFERENCE [--name NAME] [--backend BACKEND] [--mode MODE] [--force] [--no-verify] ``` -`pull` resolves the reference to the manifest for the host's platform (image -indexes are followed) and checks the image's signatures where its registry has a -policy (the hub's is built in; see [Signed images](#signed-images)) before -anything is downloaded. It then downloads every layer and the config blob that +`pull` resolves the reference to the manifest for the host's platform and checks +the image's signatures where its registry has a policy (the hub's is built in; +see [Signed images](#signed-images)) before anything is downloaded. Of an image +index it takes the entry of the best platform the host runs: amd64 then 386, +arm64 from the CPU's variant down to v8 and then 32-bit arm, arm from the CPU's +variant down to v5. Without one, it tries the entries that name no platform, in +the index's order, and takes the first whose config gives a platform the host +runs. It then downloads every layer and the config blob that is not already in the store, three at a time, each checked against its sha256 digest while it streams: a blob is written next to its final name and renamed only once verified, so an interrupted download never passes for @@ -256,7 +260,7 @@ pulled again; [Machines](/docs/machines/) explains how it changes `start`, `exec ## More machines from one image ```shell -sudo nspawn create SOURCE NAME [--backend BACKEND] [--network NETWORK]... [-p [IP:]HOST:CONTAINER[/udp]]... +sudo nspawn create SOURCE NAME [--backend BACKEND] [--network NETWORK]... [-p [IP:][HOST:]CONTAINER[/udp]]... [--entrypoint PROGRAM] [-e VAR[=VALUE]]... [-v SOURCE:TARGET[:ro]]... [-l KEY=VALUE]... [--restart POLICY] [-m SIZE] [--cpus N] [--pids-limit N] [OPTIONS OF start] [-f] [-- ARGUMENTS...] ``` diff --git a/content/en/docs/networking.md b/content/en/docs/networking.md index a212a13..cd9af8d 100644 --- a/content/en/docs/networking.md +++ b/content/en/docs/networking.md @@ -221,7 +221,7 @@ sudo nspawn network inspect front sudo nspawn start web -p 8080:80 -p 5353:53/udp -p 127.0.0.1:9090:9090 -p 8000-8010:8000-8010 ``` -On IPv4 each `-p [IP:]HOST:CONTAINER[/udp]` becomes a DNAT entry in the `ip +On IPv4 each `-p [IP:][HOST:]CONTAINER[/udp]` becomes a DNAT entry in the `ip nspawn` table. Without an address the port is reachable from other hosts, from the host's own addresses and from `127.0.0.1` (through `route_localnet`); with one, `127.0.0.1:9090:9090` say, on @@ -234,10 +234,19 @@ address or on that one, or one a service of the host already listens on, is refused before the machine starts, and a refused port is not remembered. On a machine with several networks the port leads to its primary address. -The list is remembered for the machine: `nspawn start web` next time publishes -the same ports, and `-p none` forgets them all. Ports need a bridge network -(not an internal one); a machine on the host's network listens on the host's -ports directly. +Without a host port, `-p 80` or `-p :80`, or with 0, the port gets a free one of +the host, and `nspawn port web` shows which: the kernel hands one out, passing +over the ports other running machines publish and those a service of the host +holds. A host range with one port of the machine, `-p 8000-8010:80`, gets the +first free port of the range, and `-p 80-82` a free host port for each port. +`create` picks them, or the `start` that gave them. The long form, +`published=8080,target=80,protocol=udp,host_ip=127.0.0.1`, has the same fields, +`target` the only one required. + +The list is remembered for the machine, the host ports it got included: +`nspawn start web` next time publishes the same ports, and `-p none` forgets +them all. Ports need a bridge network (not an internal one); a machine on the +host's network listens on the host's ports directly. ### IPv6 diff --git a/content/en/docs/reference.md b/content/en/docs/reference.md index 2ef123d..ac97c11 100644 --- a/content/en/docs/reference.md +++ b/content/en/docs/reference.md @@ -3,7 +3,7 @@ title: Command reference linkTitle: Reference weight: 10 description: >- - Every command and option of nspawn 2.3.1. + Every command and option of nspawn 2.4.0. --- `nspawn --help` and `nspawn COMMAND --help` list the options; this page @@ -125,7 +125,7 @@ size, speed and time left; in a pipe or a log only the lines are written. ```text nspawn create SOURCE NAME [--backend BACKEND] [--network NETWORK]... [--network-alias [NETWORK=]NAME]... - [-p [IP:]HOST:CONTAINER[/udp]]... [--entrypoint PROGRAM] [-e VAR[=VALUE]]... + [-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]... [--depends-on NAME[:CONDITION][:optional]]... [--env-file FILE]... [--label-file FILE]... @@ -143,7 +143,7 @@ the image's own name, as `run` does. The layers are shared with the source. | `--backend BACKEND` | How to assemble it. Default: like the source. | | `--network NETWORK` | Networks of the new machine, as for [start](#start). Default: the source's kind; a network made with `network create` is not inherited, as ports and labels are not. | | `--network-alias [NETWORK=]NAME` | Other names of the machine on its networks, as for [start](#start). | -| `-p`, `--publish [IP:]HOST:CONTAINER[/udp]` | Ports to publish on the host, like `start -p`. Not inherited from the source. | +| `-p`, `--publish [IP:][HOST:]CONTAINER[/udp]` | Ports to publish on the host, like `start -p`. Not inherited from the source. | | `--entrypoint PROGRAM` | Replace the image's entrypoint and drop its cmd, so only the arguments given follow it; an empty string runs the arguments alone. An app left with nothing to run is refused with `no command specified`. App images only. | | `-e`, `--env VAR[=VALUE]` | Environment for the program, `VAR=value` or `VAR` copied from the calling shell. App images only. | | `-v`, `--volume SOURCE:TARGET[:ro]` | Mount a host directory or a named volume; `z`, `Z`, a propagation, `nocopy` and `cached` are taken and do nothing. | @@ -362,7 +362,7 @@ comes along. See ## start ```text -nspawn start NAME [--network NETWORK]... [--network-alias [NETWORK=]NAME]... [-p [IP:]HOST:CONTAINER[/udp]]... +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 DURATION] [--health-timeout DURATION] [--health-retries N] @@ -384,7 +384,7 @@ Boots an image as a machine. Every option is remembered for the next start. | --- | --- | | `--network NETWORK` | Network of the machine: `bridge`, the default network (the default); the name of a network made with [network create](#network-create); `veth`, a veth pair configured by systemd-networkd on the host (booted images only); `host`, the host's own network; `none`, no interface but `lo`; or `container:NAME`, the network namespace of that running machine (app images only; see [container:NAME](/docs/networking/#containername)). Repeatable for several bridge networks, the first one primary: its address is where published ports lead and its gateway the default route, unless it is internal, in which case the first network that is not has the route. `veth`, `host`, `none` and `container:NAME` go alone. | | `--network-alias [NETWORK=]NAME` | Another name for the machine on its primary network, or on `NETWORK`: every member of that network resolves it. Repeatable; `none` forgets them. | -| `-p`, `--publish [IP:]HOST:CONTAINER[/udp]` | Publish a port on the host: on every IPv4 and IPv6 address of the host, or on `IP` alone (`127.0.0.1:8080:80`, `[::1]:8080:80`); `0.0.0.0` is every IPv4 address, `[::]` every IPv6 one. `8000-8010:8000-8010` publishes a range, one mapping per port. Repeatable; `none` forgets them all. | +| `-p`, `--publish [IP:][HOST:]CONTAINER[/udp]` | Publish a port on the host: on every IPv4 and IPv6 address of the host, or on `IP` alone (`127.0.0.1:8080:80`, `[::1]:8080:80`); `0.0.0.0` is every IPv4 address, `[::]` every IPv6 one. No host port (`80`, `:80`) or 0 takes a free one of the host, kept by the machine; a host range with one port of the machine (`8000-8010:80`) the first free one in it. `8000-8010:8000-8010` publishes a range, one mapping per port. Also `published=HOST,target=CONTAINER[,protocol=udp][,host_ip=IP]`, `target` the only one required. Repeatable; `none` forgets them all. | | `--ip [NETWORK=]IP` | A fixed IPv4 address on the primary network, or on `NETWORK`: one made with [network create](#network-create), inside its subnet and nobody else's there. Repeatable, once per network. | | `--entrypoint PROGRAM` | Replace the image's entrypoint and drop its cmd, so only the arguments given follow it; an empty string runs the arguments alone. An app left with nothing to run is refused with `no command specified`. App images only. | | `-e`, `--env VAR[=VALUE]` | Environment for the program, `VAR=value` or `VAR` copied from the calling shell. Repeatable; `none` forgets them. App images only. | @@ -417,8 +417,8 @@ Boots an image as a machine. Every option is remembered for the next start. | `--device HOST[:CONTAINER[:rwm]]` | A device node of the host for the machine (`/dev/ttyUSB0:/dev/ttyUSB0:rw`), or a directory whose nodes are allowed one by one (`/dev/dri`), or a CDI name (`nvidia.com/gpu=all`) for the devices of the host's specs. Repeatable; `none` forgets them. | | `--gpus REQUEST` | GPUs of the host's CDI specs: `all`, a count, or `'"device=0,1"'`, for the NVIDIA spec's devices (the AMD one when only that is there); `driver=` says which. See [GPUs and CDI devices](/docs/machines/#gpus-and-cdi-devices). Repeatable; `none` forgets them. | | `--dns IP` | DNS server for the machine, instead of the host's. Repeatable; `none` forgets them. | -| `--dns-search DOMAIN` | DNS search domain, in an app's `resolv.conf` and a booted machine's `.network` file. Repeatable; `none` forgets them. | -| `--add-host HOST:IP` | A line for the machine's `/etc/hosts`, `HOST:IP` or `HOST=IP` (the second for an IPv6 address); `host-gateway` is the host's address on the machine's network. Repeatable; `none` forgets them. | +| `--dns-search DOMAIN` | DNS search domain, in an app's `resolv.conf` and a booted machine's `.network` file; 254 characters at most, with a letter among its labels. A trailing dot is dropped and `.` stands for none. Repeatable; `none` forgets them. | +| `--add-host HOST:IP` | A line for the machine's `/etc/hosts`, `HOST:IP` or `HOST=IP` (the second for an IPv6 address), the IP in brackets or not; the name is anything without colons or whitespace. `host-gateway` is the host's address on the machine's network. Repeatable; `none` forgets them. | | `--ulimit NAME=SOFT[:HARD]` | A resource limit of the program (`nofile=1024:4096`, `core=unlimited`). Repeatable; `none` forgets them. | | `--oom-score-adj N` | OOM score adjustment of the machine, -1000 to 1000. | | `--stop-signal SIGNAL` | Signal `stop` sends the program, instead of the image's (`SIGTERM`). | diff --git a/hugo.yaml b/hugo.yaml index 7a8c5b8..3475721 100644 --- a/hugo.yaml +++ b/hugo.yaml @@ -53,7 +53,7 @@ params: privacy_policy: /about/#privacy # Version of nspawn the documentation describes. - version: 2.3.1 + version: 2.4.0 archived_version: false # In-page links to open issues and suggest changes.