From 79dd162a55824ed660ea1e53ccb7f46431fd2292 Mon Sep 17 00:00:00 2001 From: Eduard Tolosa Date: Mon, 28 Sep 2026 19:16:01 -0500 Subject: [PATCH] Document nspawn 1.8.0: --log-driver, output in nspawn's own journal --- content/en/docs/configuration.md | 2 +- content/en/docs/faq.md | 2 +- content/en/docs/machines.md | 30 ++++++++++++++++++++++++------ content/en/docs/reference.md | 14 ++++++++++---- hugo.yaml | 2 +- 5 files changed, 37 insertions(+), 13 deletions(-) diff --git a/content/en/docs/configuration.md b/content/en/docs/configuration.md index c269bbb..c8382ab 100644 --- a/content/en/docs/configuration.md +++ b/content/en/docs/configuration.md @@ -137,7 +137,7 @@ it is created or started; every one of them is remembered until it is changed: - `--hostname`, `-u`, `-w`, `--cap-add`, `--cap-drop`, `--privileged`, `--read-only`, `--tmpfs`, `--shm-size`, `--device`, `--dns`, `--dns-search`, `--add-host`, `--ulimit`, `--oom-score-adj`, `--stop-signal`, - `--stop-timeout`, `--timezone`, `--init`, `--sysctl` and `--secret` on `start`, `run` and + `--stop-timeout`, `--timezone`, `--log-driver`, `--init`, `--sysctl` and `--secret` on `start`, `run` and `create`, applied at the next start. A list takes `none` to forget it, a value an empty string or `0`, and `--privileged=false` and `--read-only=false` take those back. diff --git a/content/en/docs/faq.md b/content/en/docs/faq.md index 54eced4..9bbf1a7 100644 --- a/content/en/docs/faq.md +++ b/content/en/docs/faq.md @@ -26,7 +26,7 @@ images on the hub contain systemd as well; images without an init system run as No. The commands and flags look alike on purpose (`-p`, `-e`, `-v`, `--entrypoint`, `create`, `exec`, `logs`), but the machines are systemd-nspawn containers managed by systemd: they are `systemd-nspawn@NAME.service` units, -appear in `machinectl list`, log to the journal and boot a full init when the +appear in `machinectl list`, log to journald and boot a full init when the image has one. nspawn's own service holds none of them open, there is no compose file and no orchestration. diff --git a/content/en/docs/machines.md b/content/en/docs/machines.md index 305a57c..ff2b99a 100644 --- a/content/en/docs/machines.md +++ b/content/en/docs/machines.md @@ -16,7 +16,8 @@ without a password. The examples here use `sudo`. Every machine nspawn starts is the systemd unit `systemd-nspawn@NAME.service`, registered with systemd-machined under its name. `machinectl list`, `machinectl status NAME`, `systemctl status systemd-nspawn@NAME` and -`journalctl -u systemd-nspawn@NAME` all work on it; nspawn adds the +`journalctl -u systemd-nspawn@NAME` (with `--namespace=nspawn` for what the +machine prints, see [logs](#logs)) all work on it; nspawn adds the docker-like commands on top. The unit also carries a drop-in, `nspawn-hooks.conf`, that calls nspawn around @@ -75,7 +76,8 @@ variables and the volumes of the last run: `--read-only`, `--tmpfs`, `--shm-size`, `--device`, `--dns`, `--dns-search`, `--add-host`, `--ulimit`, `--oom-score-adj`, `--stop-signal`, `--stop-timeout`, `--init` and `--sysctl` are the other flags of - `docker run`, and `--timezone` says how systemd-nspawn sets + `docker run`, `--log-driver` where the program's output goes, and + `--timezone` how systemd-nspawn sets `/etc/localtime`; see [The other flags of docker run](#the-other-flags-of-docker-run). - `--secret` hands it a secret as a file; see [Secrets](#secrets). @@ -98,8 +100,9 @@ options of both. What follows the image replaces an app's command, as with docker. Without `-d` it stays with the machine: - The machine's output follows until it ends, stdout and stderr together, a - line at a time. It is read from the journal, so `nspawn logs NAME` shows it - later, and the machine goes on should `run` be interrupted. + line at a time. It is read from nspawn's journal, so `nspawn logs NAME` shows + it later, and the machine goes on should `run` be interrupted. With + `--log-driver none` it comes straight from the program 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 go to the program; a third Ctrl-C within a second leaves the machine running and @@ -400,6 +403,18 @@ its unit: a zone set inside with `timedatectl` does not survive a restart; `off` leaves the machine's own, and `copy`, `bind`, `symlink` and `delete` are its other modes. An app also takes `-e TZ=`. +- `--log-driver DRIVER`: where the program's output goes. `local`, the + default, sends it to journald's `nspawn` namespace, a journal of nspawn's + own apart from the system's, so that a program that writes a lot never + floods the host's logs; `logs` and an attached `run` read it, and + `journalctl --namespace=nspawn` shows every machine's. It holds 1 GiB at + most, shared by all machines, the oldest lines going first + (`/usr/lib/systemd/journald@nspawn.conf`, which + `/etc/systemd/journald@nspawn.conf` overrides). `journal` keeps the output + in the system's journal, and `none` drops it: `logs` then refuses the + machine, an attached `run` of an app still shows the output straight from + the program, and a booted machine, whose console goes nowhere, runs with + `-d`. - `--init`: accepted for docker's sake; nspawn's stub init reaps orphans anyway. App images only. - `--sysctl KEY=VALUE`: `net.*` keys, set in the network namespace nspawn @@ -539,8 +554,11 @@ named volumes are nspawn's own and always work. sudo nspawn logs MACHINE... [-f] [-n N] [--since WHEN] [--until WHEN] [-t] [--all] [--inside] ``` -systemd-nspawn sends what the machine writes to its console to the journal of -`systemd-nspawn@MACHINE.service`, and `logs` reads it with `journalctl`. By +What the machine writes to its console goes, by default, to journald's +`nspawn` namespace under `systemd-nspawn@MACHINE.service`, apart from the +system's journal (see `--log-driver` above), and `logs` reads it with +`journalctl`, together with the system's journal, where systemd's lines and +what a machine wrote before 1.8.0 or with `--log-driver journal` are. By default only the machine's own output is shown, from every run of the unit, earlier ones included: diff --git a/content/en/docs/reference.md b/content/en/docs/reference.md index 8931a9d..99f8526 100644 --- a/content/en/docs/reference.md +++ b/content/en/docs/reference.md @@ -267,7 +267,7 @@ nspawn start NAME [--network NETWORK]... [--network-alias [NETWORK=]NAME]... [-p [--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] [--init] [--sysctl KEY=VALUE]... + [--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...] ``` @@ -313,6 +313,7 @@ Boots an image as a machine. Every option is remembered for the next start. | `--stop-signal SIGNAL` | Signal `stop` sends the program, instead of the image's (`SIGTERM`). | | `--stop-timeout SECONDS` | Seconds `stop` waits after the signal before SIGKILL, unless `-t` says otherwise. Default: 10. | | `--timezone MODE` | How systemd-nspawn sets the machine's `/etc/localtime` at each start, its `Timezone=`: `auto` (the default, the host's zone), `off` (left alone, so a zone set inside stays), `copy`, `bind`, `symlink` or `delete`. `auto` forgets the setting. | +| `--log-driver DRIVER` | Where the program's output goes, like `docker --log-driver`: `local` (the default: journald's `nspawn` namespace, a journal of nspawn's own apart from the system's, capped at 1 GiB, which `logs` and an attached `run` read), `journal` (the system's journal) or `none` (dropped; `logs` refuses the machine, an attached `run` of an app still shows the output straight from the program, and a booted machine runs with `-d`). | | `--init` | Accepted for docker's sake: nspawn's stub init reaps orphans anyway. App images only. | | `--sysctl KEY=VALUE` | A `net.*` sysctl for an app machine's network namespace. Repeatable; `none` forgets them. | | `--interface IFACE` | A network interface of the host, moved into the machine while it runs and given back when it stops: an ethernet one, or a wifi adapter with its whole phy (`iw` on the host for an app on the bridge, systemd 256 for a booted machine); the name is kept inside. Not with `--network host` or `container:NAME`; one machine at a time. See [Physical interfaces](/docs/networking/#physical-interfaces). Repeatable; `none` forgets them. | @@ -339,8 +340,9 @@ 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 the journal, so `nspawn logs NAME` shows it later too, and the -machine goes on should `run` be interrupted. `run` exits with the program's +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 @@ -523,7 +525,11 @@ nspawn logs MACHINE... [-f] [-n N] [--since WHEN] [--until WHEN] [-t] [--all] [- Shows what machines printed, like `docker logs`. With several machines every line carries its machine's name (`web | ...`), the way docker compose shows -them. +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`). | Option | Meaning | | --- | --- | diff --git a/hugo.yaml b/hugo.yaml index 69500f1..1a9dc15 100644 --- a/hugo.yaml +++ b/hugo.yaml @@ -53,7 +53,7 @@ params: privacy_policy: /about/#privacy # Version of nspawn the documentation describes. - version: 1.7.2 + version: 1.8.0 archived_version: false # In-page links to open issues and suggest changes.