Document 1.8.0

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.

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.
 

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:
 

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 |
 | --- | --- |

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.