diff --git a/.github/workflows/k3s-ca.yml b/.github/workflows/k3s-ca.yml
new file mode 100644
index 0000000..381bf76
--- /dev/null
+++ b/.github/workflows/k3s-ca.yml
@@ -0,0 +1,64 @@
+name: k3s-ca
+
+# The k3s custom-CA library (pkg/templates/scripts/tn-k3s-ca.sh) and its harness.
+# Unit tests run on every change; the docker matrix against real rancher/k3s
+# releases is started by hand (it needs privileged containers and several minutes).
+
+on:
+  pull_request:
+    paths:
+      - 'pkg/templates/**'
+      - 'test/k3s-ca/**'
+      - '.github/workflows/k3s-ca.yml'
+  workflow_dispatch:
+    inputs:
+      suites:
+        description: 'run.sh --suite value'
+        default: 'fresh,remediation'
+      versions:
+        description: 'k3s versions (space separated)'
+        default: 'v1.34.11 v1.36.5'
+
+permissions:
+  contents: read
+
+jobs:
+  unit:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-go@v5
+        with:
+          go-version: '1.25'
+          cache: true
+      - name: shellcheck
+        run: |
+          shellcheck -s sh -S warning pkg/templates/scripts/tn-k3s-ca.sh
+      - name: go test
+        run: go test ./pkg/templates/... ./test/k3s-ca/...
+
+  docker-matrix:
+    if: github.event_name == 'workflow_dispatch'
+    runs-on: ubuntu-latest
+    timeout-minutes: 60
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-go@v5
+        with:
+          go-version: '1.25'
+          cache: true
+      - name: run the harness
+        env:
+          TN_K3S_CA_LIB: ${{ github.workspace }}/pkg/templates/scripts/tn-k3s-ca.sh
+          SUITES: ${{ inputs.suites }}
+          VERSIONS: ${{ inputs.versions }}
+        run: |
+          test/k3s-ca/run.sh --suite "$SUITES" --versions "$VERSIONS" --gens bs-o111 -j 3 --out "$RUNNER_TEMP/k3sca"
+      - name: logs
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: k3sca-results
+          path: |
+            ${{ runner.temp }}/k3sca/results.tsv
+            ${{ runner.temp }}/k3sca/logs
diff --git a/README.md b/README.md
index 9b6082c..ee197da 100644
--- a/README.md
+++ b/README.md
@@ -88,6 +88,22 @@ Securely connect to your edge devices via Teknoir's proxy infrastructure.
   tnctl socks-proxy [device] 1080
   ```
 
+### 4. Bootstrap a device
+
+```bash
+tnctl bootstrap my-device                      # writes bootstrap_{agent,server,docker_server}_my-device.sh
+tnctl bootstrap my-device --k3s-version v1.34.11+k3s1   # install another k3s release
+```
+
+The scripts install a **pinned k3s release** (`v1.36.5+k3s1` by default, the `stable` channel when this
+was written and the release the CA tests run against) instead of whatever the `stable` channel happens
+to be on the day the script runs. `--k3s-version` takes an exact release, or `stable` / `latest` for the
+installer's own channels; at run time `INSTALL_K3S_VERSION=... sh bootstrap_server_my-device.sh` wins.
+An agent must run the version of its server: generate both scripts with the same `--k3s-version`.
+k3s cannot be downgraded, so do not pin below what a device already runs. The server script also
+repairs the k3s CA of devices that were bootstrapped with an older script, see
+[`docs/commands/bootstrap.md`](docs/commands/bootstrap.md) and [`docs/troubleshooting.md`](docs/troubleshooting.md).
+
 ## Global Flags
 
 These flags are available to all subcommands:
diff --git a/cmd/bootstrap.go b/cmd/bootstrap.go
index bf1e3da..87c6ddb 100644
--- a/cmd/bootstrap.go
+++ b/cmd/bootstrap.go
@@ -20,6 +20,10 @@ var bootstrapCmd = &cobra.Command{
 	Use:   "bootstrap [device-name]",
 	Short: "Generate bootstrap scripts for a device",
 	RunE: func(cmd *cobra.Command, args []string) error {
+		k3sVersion, _ := cmd.Flags().GetString("k3s-version")
+		if err := templates.ValidateK3SVersion(k3sVersion); err != nil {
+			return err
+		}
 		cfg, err := config.Load()
 		if err != nil {
 			return err
@@ -101,18 +105,27 @@ var bootstrapCmd = &cobra.Command{
 		}
 
 		dockerSecret, _ := cmd.Flags().GetString("docker-secret")
+		k3sUpgrade, _ := cmd.Flags().GetBool("k3s-upgrade")
+		force, _ := cmd.Flags().GetBool("force")
+		if force && !k3sUpgrade {
+			return fmt.Errorf("--force only applies together with --k3s-upgrade")
+		}
 
 		data := templates.TemplateData{
-			Domain:       domain,
-			Namespace:    namespace,
-			DeviceID:     deviceName,
-			RSAPrivate:   rsaPrivate,
-			RSAPublic:    rsaPublic,
-			Username:     username,
-			Password:     password,
-			PublicSSHKey: publicSSHKey,
-			K3SToken:     k3sToken,
-			DockerSecret: dockerSecret,
+			Domain:             domain,
+			Namespace:          namespace,
+			DeviceID:           deviceName,
+			RSAPrivate:         rsaPrivate,
+			RSAPublic:          rsaPublic,
+			Username:           username,
+			Password:           password,
+			PublicSSHKey:       publicSSHKey,
+			K3SToken:           k3sToken,
+			DockerSecret:       dockerSecret,
+			K3SVersion:         k3sVersion,
+			K3SVersionExplicit: cmd.Flags().Changed("k3s-version"),
+			K3SUpgrade:         k3sUpgrade,
+			K3SForce:           force,
 		}
 
 		generate := func(tmpl *template.Template, filename string) error {
@@ -162,6 +175,12 @@ func generateK3SToken() (string, error) {
 
 func init() {
 	bootstrapCmd.Flags().Bool("skip-upload", false, "Skip uploading the generated scripts")
+	bootstrapCmd.Flags().String("k3s-version", templates.DefaultK3SVersion,
+		"k3s release the scripts install (INSTALL_K3S_VERSION): an exact release like v1.36.5+k3s1, or stable / latest for the installer's channels. Server and agent scripts use the same value")
+	bootstrapCmd.Flags().Bool("k3s-upgrade", false,
+		"let the scripts replace an installed k3s with --k3s-version (TN_K3S_UPGRADE=true is the default in the scripts). Without it a re-run keeps the installed k3s; a downgrade is always refused")
+	bootstrapCmd.Flags().Bool("force", false,
+		"with --k3s-upgrade: allow an upgrade over more than one minor version (TN_K3S_FORCE=true is the default in the scripts)")
 	bootstrapCmd.Flags().String("docker-secret", "", "The contents of the .dockerconfigjson")
 	rootCmd.AddCommand(bootstrapCmd)
 }
diff --git a/cmd/bootstrap_test.go b/cmd/bootstrap_test.go
new file mode 100644
index 0000000..4292023
--- /dev/null
+++ b/cmd/bootstrap_test.go
@@ -0,0 +1,30 @@
+package cmd
+
+import (
+	"testing"
+
+	"teknoir/cli/pkg/templates"
+)
+
+func TestBootstrapK3SVersionFlag(t *testing.T) {
+	f := bootstrapCmd.Flags().Lookup("k3s-version")
+	if f == nil {
+		t.Fatal("no --k3s-version flag")
+	}
+	if f.DefValue != templates.DefaultK3SVersion {
+		t.Errorf("default %q", f.DefValue)
+	}
+}
+
+func TestBootstrapK3SUpgradeFlags(t *testing.T) {
+	for _, name := range []string{"k3s-upgrade", "force"} {
+		f := bootstrapCmd.Flags().Lookup(name)
+		if f == nil {
+			t.Fatalf("no --%s flag", name)
+		}
+		// a re-run keeps the installed k3s unless the operator asks otherwise
+		if f.DefValue != "false" {
+			t.Errorf("--%s defaults to %q", name, f.DefValue)
+		}
+	}
+}
diff --git a/docs/commands/bootstrap.md b/docs/commands/bootstrap.md
index 03dcebc..3a18c2b 100644
--- a/docs/commands/bootstrap.md
+++ b/docs/commands/bootstrap.md
@@ -15,6 +15,9 @@ The device may be given as an argument, via the `--device` global flag, or selec
 | Flag | Default | Description |
 | --- | --- | --- |
 | `--skip-upload` | `false` | Skip uploading the generated scripts. |
+| `--k3s-version` | `v1.36.5+k3s1` | k3s release the server script installs: an exact release (`v1.36.5+k3s1`), or `stable` / `latest` for the installer's channels. The agent script installs the release of its server instead; a release given here explicitly is installed only if it is not newer than the server's. |
+| `--k3s-upgrade` | `false` | Let the scripts replace an installed k3s with `--k3s-version` (sets `TN_K3S_UPGRADE=true` as the script's default). Without it a re-run **keeps** the installed k3s. See [Re-running a script](#re-running-a-script-the-installed-k3s-is-kept). |
+| `--force` | `false` | Only with `--k3s-upgrade`: allow an upgrade over more than one minor version (`TN_K3S_FORCE=true`). A downgrade is never allowed. |
 | `--docker-secret` | `""` | Contents of the `.dockerconfigjson` to embed. |
 
 Plus all [global flags](index.md#global-flags).
@@ -33,6 +36,152 @@ The scripts are rendered from templates and populated with the device's decoded
 (RSA keypair, username/password, public SSH key), the domain/namespace, the device ID, a freshly
 generated K3S token, and the optional Docker secret.
 
+## The k3s version
+
+The server and agent scripts install a **pinned** k3s release: `INSTALL_K3S_VERSION` is set from
+`--k3s-version`, default `v1.36.5+k3s1` (the `stable` channel of
+<https://update.k3s.io/v1-release/channels> when this was written, and the release that the CA tests in
+`test/k3s-ca` prove with the re-issued root). Without a pin the installer takes whatever `stable` is on
+the day the script runs, and that moved the fleet onto a k3s that refused the device CA once already.
+
+| `--k3s-version` | What the script does |
+| --- | --- |
+| *(default)* or `v1.36.5+k3s1` | `INSTALL_K3S_VERSION=v1.36.5+k3s1` |
+| any other `vX.Y.Z+k3sN` | that release |
+| `stable` | nothing: the old behaviour, the installer picks the `stable` channel |
+| `latest` | `INSTALL_K3S_CHANNEL=latest` |
+
+- At run time, `INSTALL_K3S_VERSION=v1.xx.y+k3sN sh bootstrap_server_<device>.sh` overrides the pin.
+- The pin is the release for a **new server**. A device that already has k3s keeps what it has, see
+  below.
+- **An agent follows its server.** A kubelet must never be newer than the apiserver it joins, so the
+  agent script does not install the pin. It reads the release of the server and installs exactly that
+  one. k3s does **not** answer `/version` to an anonymous caller (its apiserver runs with
+  `anonymous-auth=false`: HTTP 401 on every release, checked with v1.30, v1.34 and v1.36), and the join
+  token only opens the supervisor endpoints, so the **server script publishes the release it runs**
+  as `<data dir>/server/static/teknoir/k3s-version` after its installer has run. k3s serves
+  `server/static` without authentication, so an agent reads
+  `https://<K3S_URL>/static/teknoir/k3s-version` (and, for a server that does allow it, `/version`).
+  A release that you asked for (`--k3s-version`, or `INSTALL_K3S_VERSION` when running the script) is
+  installed if it is not newer than the server's (older gets a warning) and **refused** if it is,
+  unless `TN_K3S_FORCE=true`. A channel (`stable`, `latest`) cannot be compared: the server's release
+  is installed instead. If the release of the server cannot be read, the script **stops** and says
+  why, unless a release was asked for (it is then installed as asked, with a warning) or
+  `TN_K3S_FORCE=true`: the server is down or not reachable (tried three times), or it was
+  bootstrapped by a script from before this change and publishes nothing. **For such a server, run
+  its bootstrap script again**: that keeps k3s as it is and publishes the release. An out-of-band
+  upgrade of k3s leaves the file at the older release, which is the safe direction. An OS image build
+  (`OS_BUILD`) cannot reach a server and installs the pin.
+- Raise the default in `pkg/templates/bootstrap_templates.go` (`DefaultK3SVersion`) together with the
+  harness runs in `test/k3s-ca` for the new release.
+
+## Re-running a script: the installed k3s is kept
+
+A bootstrap script is meant to be run again (to repair the CA, refresh the manifests, ...). It must not
+upgrade k3s as a side effect, so the pin only applies to a device **without** k3s. Before it runs the
+installer, the server and agent scripts read `k3s --version` and decide:
+
+| State of the device | What the script does |
+| --- | --- |
+| k3s is not installed | Installs the pin (`INSTALL_K3S_VERSION`); an **agent** installs the release of its server, see above |
+| a k3s binary or `server/db` exists, but `k3s --version` gives no release | **Refuses** to install anything (the installer would replace k3s without any of the checks below); `TN_K3S_FORCE=true` goes on as if k3s were not installed |
+| k3s is installed, any pin | **Keeps the installed release**: it passes that exact release to the installer (which then only rewrites the unit and the symlinks) and says that the pin was not applied |
+| k3s is installed, `--k3s-upgrade` (or `TN_K3S_UPGRADE=true`) | Upgrades to the pin (an agent: to the release of its server), with these checks: a pin **below** the installed release is **refused** (k3s cannot go back, the datastore has been migrated; this also holds with `--force`), and so is a pin more than **one minor version** above (`v1.34` to `v1.36`: upgrade to `v1.35.x` first) unless `--force` (`TN_K3S_FORCE=true`), which turns the refusal into a warning |
+| installed, upgrade requested, but the pin is a channel (`stable`, `latest`) | Upgrades, with a warning: the installer picks the release, so downgrade and minor jump cannot be checked. Pin an exact release to get the checks |
+
+Upgrade servers before their agents, and one minor version at a time. The environment of the
+script overrides what `tnctl bootstrap` baked in (`TN_K3S_UPGRADE=false sh bootstrap_*.sh`).
+
+**Order in the server script**: (0) the arguments of the installer (`INSTALL_K3S_EXEC`, including a
+value you gave: the cgroup step reads it), the data dir and its check against `config.yaml`, (1) this
+release decision and the cgroup flag below, (2) the CA repair, (3) the k3s installer. A refusal in (0)
+or (1) happens before anything is changed ("Nothing was changed"). The CA is still repaired before the installer, so an upgrade never meets a root that the
+new k3s would reject. Should a later step ever refuse after the CA step has changed the device (the CA
+rotated, files replaced, k3s restarted), the message lists exactly that, instead of "Nothing was
+changed".
+
+## cgroup v1 devices
+
+Kubernetes 1.35 and later make the kubelet **refuse to start on a cgroup v1 host**
+(`failCgroupV1` defaults to true) and k3s does not change that. Devices on Jetson L4T r32/r35,
+Ubuntu 18.04 or 20.04 are cgroup v1 (or hybrid). Both scripts therefore check
+`stat -fc %T /sys/fs/cgroup`: anything but `cgroup2fs` is v1 or hybrid. On such a host, when the k3s
+that will run is **v1.31 or later** (the kept installed release, or the pin, or the release of the
+server, or a channel; the kubelet knows the flag since 1.31, and an older one would not start with an
+unknown argument), the script writes
+
+```yaml
+# /etc/rancher/k3s/config.yaml.d/99-teknoir-cgroupv1.yaml
+kubelet-arg+:
+  - "fail-cgroupv1=false"
+```
+
+and warns that cgroup v1 is deprecated. The flag only matters from v1.35, but it is set from v1.31 so
+that a later upgrade (also one made by hand, outside the scripts) does not stop the kubelet. The file
+is written atomically (temporary file, then `mv`). `kubelet-arg+` **appends** to the `kubelet-arg` of
+`config.yaml` and the other drop-ins, so the arguments of the device owner are kept; the file is
+rewritten only when it differs, so a re-run changes nothing. A `fail-cgroupv1` that the device sets
+itself in a file that k3s reads (`config.yaml` or another `config.yaml.d/*.yaml` or `*.yml`) is respected
+and our file is removed. Only an uncommented line that sets `fail-cgroupv1=false` counts: a comment, or
+`fail-cgroupv1=true`, does not, and our file is written as usual (setting `true` on a cgroup v1 host on
+purpose is not supported).
+A flag only in `INSTALL_K3S_EXEC` reaches the unit when the installer has run, so our file stays (or is
+written) until then: the same value twice is harmless, and the command line wins. For an installed k3s
+older than v1.31 that is being upgraded, the flag is written after the installer (`tn_inst_finish`), as the
+old kubelet cannot take it. The installer starts the new release as soon as it has rewritten the unit, and
+v1.35 or later does not start on cgroup v1 without the flag, so when the release is a channel (`stable`,
+`latest`) or an exact v1.35 or later, `--kubelet-arg=fail-cgroupv1=false` is also appended to
+`INSTALL_K3S_EXEC` (once): the new unit has it from its first start, and the old kubelet never reads it.
+An exact v1.31 to v1.34 does not need it. On cgroup v2 the file is removed. An OS image build (`OS_BUILD=true`) runs on another machine than the
+device and cannot tell: the flag is set there, it is harmless on cgroup v2. `TN_K3S_CGROUPV1=true|false`
+forces the answer. The way out is cgroup v2 (kernel command line `systemd.unified_cgroup_hierarchy=1`,
+or a newer OS release); then delete the file.
+
+The flag is written **before** the CA step, which may restart k3s: a k3s that a cgroup v1 host made
+exit (an old script upgraded it to v1.35 or later) restarts itself every few seconds and reads the
+flag then, so it is up for `rotate-ca` and the re-run ends with a working k3s. `rotate-ca` is tried
+again for about a minute while the unit is starting.
+
+The server script no longer replaces an existing `/etc/rancher/k3s/config.yaml` on a re-run: it adds
+`disable`, `node-name` and (for a non-default data dir) `data-dir` when they are missing.
+
+## The k3s CA
+
+The server scripts (`bootstrap_server_<device>.sh`) use the device certificate (`rsa_public.pem`)
+and key from the device's settings as the **root of the cluster CA** and issue the intermediate and
+leaf CAs below it. k3s v1.34.12, v1.35.9, v1.36.5, v1.37.1 and later only accept a root with the
+`keyCertSign` key usage, so the script **re-issues the root from the same key and subject** with
+`keyCertSign` and CA:TRUE (valid 20 years; the device files are not modified). The code is
+[`pkg/templates/scripts/tn-k3s-ca.sh`](https://github.com/teknoir/cli/blob/main/pkg/templates/scripts/tn-k3s-ca.sh),
+embedded in the script and usable stand-alone (`sh tn-k3s-ca.sh check|remediate`).
+
+Re-running a server script is safe:
+
+| State of the device | What the script does with the CA |
+| --- | --- |
+| k3s never started | Creates the PKI (keeps a valid one) |
+| k3s started, root is fine | Leaves it alone |
+| k3s started, root has no `keyCertSign` (bootstrapped by an older script) | Repairs it first with `k3s certificate rotate-ca` and restarts k3s, so the k3s installer that follows cannot brick the device. `TN_K3S_CA_AUTO_REMEDIATE=false` stops with advice instead; a failed repair stops the script |
+| k3s runs, but from another data dir than the one found (no `server/token` there) | Stops before anything is changed: generating a CA in the wrong directory would not touch the CA that k3s uses. Pass `DATA_DIR=` |
+| k3s too old for `rotate-ca` (before v1.24.12, v1.25.8, v1.26.3) | Stops before anything is changed, with advice to upgrade k3s one minor version at a time to a release that has `rotate-ca` but is older than v1.34.12 |
+
+The data dir is the one k3s uses on the device, resolved the way k3s does: `--data-dir`/`-d` in the
+`ExecStart` of the `k3s.service` unit, the last `data-dir` in `/etc/rancher/k3s/config.yaml.d/*.yaml`,
+`data-dir` in `/etc/rancher/k3s/config.yaml`, `K3S_DATA_DIR` of the unit, then
+`/var/lib/rancher/k3s`. Set `DATA_DIR` to override it. The server script writes the same data dir to
+`config.yaml` when it is not the default, so the installer's unit keeps using it, and puts the Teknoir
+manifests there. If the data dir found (from the `ExecStart`, `K3S_DATA_DIR` or `DATA_DIR`) differs from
+the `data-dir` of `config.yaml` or `config.yaml.d`, the script **stops** before anything is changed: the
+installer writes a unit without `--data-dir`, after which k3s would start from the `config.yaml`
+directory, with a new CA, and leave the cluster behind. Make them agree and run the script again.
+
+`k3s certificate rotate-ca` and the restart wait for a slow device: a stop, start or restart of k3s may
+take `TN_K3S_SERVICE_TIMEOUT` seconds (default **600**), and after a timeout the unit is watched for
+`TN_K3S_READY_GRACE` (120) more seconds before the restart is called failed.
+
+See [Troubleshooting](../troubleshooting.md#bootstrapping-k3s) for devices that hang or were
+bricked by a k3s upgrade. The agent script has no CA step (an agent has no CA of its own); it follows the k3s release of its server, see above.
+
 ## Requirements
 
 A domain and namespace must be set, and you must be authenticated.
diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md
index ffce9c6..d747f70 100644
--- a/docs/troubleshooting.md
+++ b/docs/troubleshooting.md
@@ -53,6 +53,193 @@ including resolved URLs and the exact `ssh` invocation used.
     - Re-run with `--debug` to see the full `ssh` command and any `ncat`/proxy errors.
     - Verify network access to `deadend-<namespace>.<domain>:2222`.
 
+## Bootstrapping & k3s
+
+??? failure "k3s never becomes Ready: `Failed to validate connection to cluster ... CA cert validation failed ... x509: certificate signed by unknown authority`"
+    k3s v1.34.12, v1.35.9, v1.36.5, v1.37.1 and later (k3s-io/k3s#14699, a CVE fix) drop every
+    certificate without the `keyCertSign` key usage from the CA bundle. The device certificate of
+    the platform (`/etc/teknoir/rsa_public.pem`) is the **root** of the cluster CA, and the
+    certificates generated before this was fixed never had `keyCertSign`. The get.k3s.io `stable`
+    channel has been v1.36.5 since 2026-10-01, so a new device bootstrapped with an old script, or an
+    old device whose k3s was upgraded, hits this.
+
+    The bootstrap scripts generated by a `tnctl` with this fix re-issue the root from the **same key
+    and subject** with `keyCertSign` (valid 20 years); the device files in `/etc/teknoir` are never
+    changed, and everything signed below the old root stays valid. Check that your `tnctl` has it:
+    `grep -c tn_k3s_ca_setup bootstrap_server_<device>.sh` prints a number above 0.
+
+    Find out where the device is with the CA tool (`tn-k3s-ca.sh`, run as root on the device; it is
+    [`pkg/templates/scripts/tn-k3s-ca.sh`](https://github.com/teknoir/cli/blob/main/pkg/templates/scripts/tn-k3s-ca.sh)
+    in this repository and is embedded in every generated `bootstrap_server_*.sh`):
+
+    ```bash
+    sh tn-k3s-ca.sh check     # exit 0 = ok, 2 = needs rotation, 3 = needs regeneration, 4 = foreign CA or no server data found
+    ```
+
+    Without `--data-dir`, the tool finds the k3s data dir the way k3s does (`--data-dir`/`-d` in the
+    `ExecStart` of `k3s.service`, then the last `data-dir` in `/etc/rancher/k3s/config.yaml.d/*.yaml`,
+    then `data-dir` in `/etc/rancher/k3s/config.yaml`, then `K3S_DATA_DIR` of the unit, then
+    `/var/lib/rancher/k3s`) and tells which one it used (`data dir ... (source)` on stderr). If a k3s
+    **server unit exists but the data dir it found has no `server/tls/server-ca.crt`**, `check` is never
+    "ok": it exits 4 (`no-server-data`) and names the directory it looked in. Either k3s has not
+    started on this device yet, or its data dir is somewhere the tool cannot see; pass `--data-dir DIR`.
+
+    | Situation | How to tell | What to do |
+    | --- | --- | --- |
+    | **Fresh bootstrap that hangs**: k3s was never Ready on this device | `check` says `needs-regeneration`; `<data dir>/server/token` (`/var/lib/rancher/k3s/server/token`) does not exist | Run the fixed `bootstrap_server_*.sh` again, or `sh tn-k3s-ca.sh remediate`. Nothing was ever stored in the cluster, so there is nothing to rotate: k3s is stopped while `server/tls` is replaced (the old dir is moved aside, the result is validated, and the old dir is put back if anything fails), the old files are saved as `server/tls-backup-tn-*.tar`, and k3s is started again. `rotate-ca` cannot be used here, it needs the token a started server writes |
+    | **Bricked by an upgrade**: the device worked, then k3s was upgraded and does not start | `check` says `needs-rotation`; k3s logs the error above | `sh tn-k3s-ca.sh remediate`. k3s must be running (a k3s that loops on the error is fine, it listens). The tool stages the new CA files, runs `k3s certificate rotate-ca` against the running server, copies the files and restarts k3s. Workloads and the datastore are kept. Details below |
+    | **Still works, not upgraded yet** | `check` says `needs-rotation`; `k3s --version` shows v1.34.11, v1.35.8, v1.36.4 or v1.37.0 or older | Do it now: `sh tn-k3s-ca.sh remediate`, or run the fixed bootstrap script again (it repairs the CA before it touches k3s; `TN_K3S_CA_AUTO_REMEDIATE=false` makes it stop with advice instead) |
+    | **`foreign`** | `check` says `foreign` | The root is not the Teknoir device CA (no matching key in `server/tls/root-ca.key` or `/etc/teknoir/rsa_private.pem`). The tool does not touch it |
+
+    `remediate` runs in phases, which you can also run one at a time (`--phase`): `prepare`
+    (offline: checks, backs up `server/tls`, stages `server/.tn-ca-rotate-<time>/` with a `ROTATE_CMD`),
+    `rotate` (runs `ROTATE_CMD` against the running server), `finalize` (copies the files, only after
+    the rotation succeeded), `all` (default, plus a k3s restart). It is safe to run again: when the
+    root is fine it does nothing.
+
+    `rotate-ca` makes k3s verify the new CA bundle against the old one. An old root that has expired,
+    or that has a key usage without `keyCertSign` (the certificates the device-controller made), cannot
+    vouch for anything any more, so for those the tool verifies the new bundle itself with openssl and
+    adds `--force` to `rotate-ca` (it says so when it stages the rotation). A root without any key usage
+    (the Backstage certificates) is rotated without `--force`.
+
+    Also with `--force`: an old root that is not yet valid, has no `basicConstraints` or `CA:FALSE`, and,
+    generally, any old root against which openssl cannot verify the old chain while the new chain
+    verifies. The reason is printed when the rotation is staged.
+
+    A k3s older than v1.24.12 / v1.25.8 / v1.26.3 has no `certificate rotate-ca`. The tool stops
+    before it changes anything and says so: that k3s still accepts the current root (the `keyCertSign`
+    check only came with v1.34.12 and later), so upgrade it one minor version at a time to a release
+    with `rotate-ca` that is older than v1.34.12 (v1.27 to v1.34.11), then run `remediate`, then go on.
+
+    **When the CA was changed but a later step failed** (`remediate` exits 5; the bootstrap script stops
+    with "the k3s CA of this device WAS changed"): `rotate-ca` succeeded, so the datastore of k3s holds
+    the new CA. If copying the files failed, fix the cause and run `sh tn-k3s-ca.sh remediate --phase
+    finalize`; if the restart failed, look at `systemctl status k3s` / `journalctl -u k3s` and restart
+    it. Running `remediate` again finalizes a completed rotation instead of rotating twice.
+
+    **Rollback limits.** The tool saves `server/tls` as `server/tls-backup-tn-<time>.tar` (the newest 3
+    are kept; they hold keys, mode 600). A rotation also writes the new CA into the datastore of k3s,
+    which the tool does not back up: after a successful `rotate-ca`, restoring the tar alone does not go
+    back (files and datastore would disagree). A real rollback needs a copy of `server/db` taken before
+    with k3s stopped. Before `rotate-ca` has succeeded nothing on disk is changed. A leftover staging dir
+    `server/.tn-ca-rotate-*` (it holds copies of the keys) is removed by the next `remediate` or
+    bootstrap run once the CA is fine.
+
+    If `rotate-ca` fails, nothing was changed on disk. Use the fallback: put the last release before
+    the fix of **the same minor** in place, remediate, and upgrade again.
+
+    | Your minor | Last release without the check |
+    | --- | --- |
+    | v1.34 | v1.34.11 |
+    | v1.35 | v1.35.8 |
+    | v1.36 | v1.36.4 |
+    | v1.37 | v1.37.0 |
+
+    ```bash
+    systemctl stop k3s
+    # k3s-arm64 / k3s-armhf on ARM devices; replace the version with the row for your minor
+    curl -fL -o /usr/local/bin/k3s 'https://github.com/k3s-io/k3s/releases/download/v1.36.4%2Bk3s1/k3s'
+    chmod 755 /usr/local/bin/k3s
+    systemctl start k3s
+    sh tn-k3s-ca.sh remediate
+    ```
+
+    Then upgrade k3s as usual.
+
+    Devices with several k3s servers (embedded etcd) were not part of the tests; remediate the
+    servers one by one and read the [k3s documentation](https://docs.k3s.io/cli/certificate) for
+    `rotate-ca` first. Agent nodes need nothing: they have no CA of their own and pick up the new
+    root from the server.
+
+??? question "Which k3s version do the bootstrap scripts install?"
+    A pinned one, `v1.36.5+k3s1` by default (`tnctl bootstrap --k3s-version` changes it, `stable`
+    restores "whatever the installer's stable channel is today", and `INSTALL_K3S_VERSION=... sh
+    bootstrap_*.sh` overrides it when the script runs) on a device **without** k3s. A device that
+    already runs k3s **keeps its version** when the script is run again; upgrading takes
+    `tnctl bootstrap --k3s-upgrade` (or `TN_K3S_UPGRADE=true`). A new **agent** installs the version of
+    its **server** (read from `https://<server>:6443/static/teknoir/k3s-version`, which the server script publishes; `/version` is only tried second, k3s does not answer it anonymously), never a newer one. See
+    [`tnctl bootstrap`](commands/bootstrap.md#the-k3s-version).
+
+??? failure "The agent script stops with `cannot read the k3s release of the server`"
+    The agent asks its server for its k3s release before it installs anything, because a kubelet must
+    not be newer than the apiserver. k3s does not answer `/version` anonymously (401), so the server
+    script publishes the release it runs at `https://<server>:6443/static/teknoir/k3s-version`. The
+    message tells which of two things is wrong. **The server is down, `K3S_URL` is wrong or the device
+    cannot reach it**: fix that and run the script again. **The server answered but publishes nothing**
+    (`curl -k https://<server>:6443/static/teknoir/k3s-version` gives 404): it was bootstrapped by an
+    older script; run its bootstrap script again (it keeps k3s as it is and publishes the release). Or
+    say which release the server runs: `INSTALL_K3S_VERSION=v1.xx.y+k3sN` (`tnctl bootstrap
+    --k3s-version`), or `TN_K3S_FORCE=true` to install the script's default anyway.
+
+    **This is a change for a fleet.** Servers bootstrapped by older scripts publish no release, so a
+    **new** agent (a node that has no k3s yet) stops until the server's script has been run again, or
+    until `INSTALL_K3S_VERSION` says what the server runs. Running the server's script again is the
+    right fix anyway: it publishes the release and, on a server that still has the old root CA
+    (the device certificate without `keyCertSign`), it also repairs it first (`k3s certificate
+    rotate-ca`, then a restart of k3s), which a k3s upgrade to v1.34.12 / v1.35.9 / v1.36.5 / v1.37.1 or
+    later would otherwise turn into a device that no longer starts. Agents that already run k3s are not
+    affected: a re-run keeps the installed k3s and does not ask the server.
+
+??? failure "The agent script stops with `refusing to install k3s ... on this agent`"
+    You asked for a release that is newer than the server's. Drop `--k3s-version` /
+    `INSTALL_K3S_VERSION` (the agent then gets the server's release), upgrade the server first, or set
+    `TN_K3S_FORCE=true`.
+
+??? failure "The script stops with `its k3s version cannot be read`"
+    A k3s binary or `server/db` exists, but `k3s --version` gives no release (a broken or half-copied
+    binary, a data dir without the binary). The script does not install over it blind. Look at
+    `k3s --version`, repair or remove k3s on purpose, or set `TN_K3S_FORCE=true`.
+
+??? failure "The server script stops with `... sets data-dir: ...`"
+    k3s runs from one data dir (`ExecStart --data-dir`, `K3S_DATA_DIR` or `DATA_DIR`), but `config.yaml`
+    or `config.yaml.d` names another. The k3s installer would write a unit without `--data-dir`, and k3s
+    would then start from the config directory. Make them agree (usually: set `data-dir:` in
+    `/etc/rancher/k3s/config.yaml` to where the cluster is) and run the script again. Nothing was
+    changed.
+
+??? failure "The script says `k3s ... is kept; the requested ... is NOT installed`"
+    Intended: the device already has k3s and a re-run does not upgrade it. To upgrade, run the
+    script with `TN_K3S_UPGRADE=true` (or generate it with `tnctl bootstrap --k3s-upgrade`), one minor
+    version at a time and servers before agents.
+
+??? failure "The script stops with `refusing to downgrade k3s` or `more than one minor version`"
+    Both stop before the k3s installer runs, and before the CA step, so nothing is changed (should
+    the message ever list changes made earlier in the run, those are exactly the ones that happened). **Downgrade**: the pin is older than the installed
+    release, and k3s cannot go back (its datastore has been migrated); pin the installed release or a
+    newer one. **More than one minor version** (for example `v1.34.11` to `v1.36.5`): upgrade to
+    `v1.35.x` first and run the script again, or set `TN_K3S_FORCE=true` (`tnctl bootstrap --k3s-upgrade
+    --force`) if you have a backup of `/var/lib/rancher/k3s/server/db` and accept the risk. See
+    [Re-running a script](commands/bootstrap.md#re-running-a-script-the-installed-k3s-is-kept).
+
+??? failure "k3s does not start on a Jetson / Ubuntu 18.04 / 20.04: `kubelet is configured to not run on a host using cgroup v1`"
+    Kubernetes 1.35 and later (k3s v1.35+) refuse cgroup v1 by default. Scripts from a `tnctl` with
+    this fix set the kubelet argument `fail-cgroupv1=false` (for k3s v1.31 and later) for you in
+    `/etc/rancher/k3s/config.yaml.d/99-teknoir-cgroupv1.yaml` (check with `stat -fc %T /sys/fs/cgroup`:
+    `tmpfs` means cgroup v1 or hybrid, `cgroup2fs` means v2). To fix a device by hand, create that file
+    with the content shown in [`tnctl bootstrap`](commands/bootstrap.md#cgroup-v1-devices) and
+    `systemctl restart k3s`. cgroup v1 is deprecated upstream: the lasting fix is cgroup v2 (kernel
+    command line `systemd.unified_cgroup_hierarchy=1`, or a newer OS release).
+
+??? failure "The script stops with `k3s ... is active and ready, but the data dir ... was never initialised`"
+    The data dir the script found (it tells where it came from) has no `server/token`, but the k3s unit
+    is running: k3s uses another data dir (a `--config` file, a drop-in the tool does not read). A CA
+    generated in the wrong directory would not change the CA that k3s uses, so nothing was changed.
+    Find the real directory (`systemctl cat k3s`, `ps aux | grep k3s`) and run the script again with
+    `DATA_DIR=/that/dir`.
+
+??? failure "Remediation ends with `the restart of k3s did not finish within 600s`"
+    The CA **was** changed (the message says so and what to look at), but `systemctl restart k3s`
+    did not return, and the unit was not active a further 120 s later either: the k3s unit waits for
+    ever for a k3s that cannot start. The wait is capped (`TN_K3S_SERVICE_TIMEOUT`, seconds, default
+    600; then `TN_K3S_READY_GRACE`, default 120, for the unit to become active). Look at `journalctl -u k3s -n 50`, fix the cause, and
+    restart k3s yourself. Do not restore the backup tar.
+
+??? failure "Bootstrap fails with `string too long maxsize=64`"
+    The generated CA certificates carry the device ID and the domain in their common name, which is
+    limited to 64 characters. Fixed: the name is cut to 64 characters in scripts from a `tnctl` with
+    the CA fix. Regenerate the script.
+
 ## Configuration
 
 ??? question "Where is my config?"
diff --git a/pkg/templates/agent.sh.tmpl b/pkg/templates/agent.sh.tmpl
index 18a9bcc..65db83a 100644
--- a/pkg/templates/agent.sh.tmpl
+++ b/pkg/templates/agent.sh.tmpl
@@ -7,9 +7,23 @@
 #   K3S_URL=https://<IP or mDNS name>:6443 (default: generated at master node creation time)
 #   K3S_TOKEN="32 char string" (default: generated at master node creation time)
 #   CREATE_USER=false (default: ask, create a user for the device without asking)
+#   INSTALL_K3S_VERSION=v1.xx.y+k3sN (default: the release of the SERVER, read from https://<K3S_URL>/static/teknoir/k3s-version: an
+#                          agent never installs a k3s newer than its server. A release you ask for (here, or
+#                          tnctl bootstrap --k3s-version) is installed if it is not newer than the server's, and
+#                          refused if it is. If the server cannot be reached the script stops, unless the
+#                          release was asked for or TN_K3S_FORCE=true)
+#   TN_K3S_UPGRADE=true (default: false; a re-run KEEPS the installed k3s version. true lets the pin replace
+#                          it: never a downgrade, never more than one minor version. Upgrade the server first)
+#   TN_K3S_FORCE=true (default: false; allows an upgrade over more than one minor version, an agent that is
+#                          newer than its server, and an install when the release of the server is unknown)
+#   TN_K3S_CGROUPV1=true|false (default: detected; on cgroup v1 with k3s >= v1.31 the kubelet gets
+#                          fail-cgroupv1=false, see /etc/rancher/k3s/config.yaml.d/99-teknoir-cgroupv1.yaml)
 
 {{template "variables.sh.tmpl" .}}
 
+# The k3s release policy (a re-run keeps the installed k3s) and the cgroup v1 kubelet flag.
+{{template "tn-k3s-install.sh" .}}
+
 {{template "keys.sh.tmpl" .}}
 
 $SUDO cp ${CONFIG_PATH}/rsa_public.pem /usr/local/share/ca-certificates/${_DEVICE_ID}-${_DOMAIN}.crt
@@ -51,8 +65,16 @@ if [ "${USE_DOCKER}" = true ]; then
     export INSTALL_K3S_EXEC="${INSTALL_K3S_EXEC} --docker"
 fi
 
+{{template "k3s_version.sh.tmpl" .}}
+# A new agent gets the k3s release of its server; a re-run keeps the installed k3s (unless
+# TN_K3S_UPGRADE=true) and sets fail-cgroupv1=false on cgroup v1 hosts, which Kubernetes >= 1.35 would refuse
+# (the flag goes in from k3s v1.31, where the kubelet learned it). INSTALL_K3S_EXEC is final above, before
+# tn_inst_prepare reads it.
+tn_inst_prepare agent
 export INSTALL_K3S_SYMLINK=force
 $SUDO ./k3s_installer.sh
+# The kubelet flag that had to wait for the installer (an installed k3s older than v1.31 that was upgraded)
+tn_inst_finish
 
 info "K3s agent node joined successfully!"
 
diff --git a/pkg/templates/bootstrap_templates.go b/pkg/templates/bootstrap_templates.go
index 19d9a80..6a5e35c 100644
--- a/pkg/templates/bootstrap_templates.go
+++ b/pkg/templates/bootstrap_templates.go
@@ -2,9 +2,30 @@ package templates
 
 import (
 	"embed"
+	"fmt"
+	"regexp"
 	"text/template"
 )
 
+// DefaultK3SVersion is the k3s release the bootstrap scripts install unless told otherwise
+// (`tnctl bootstrap --k3s-version`, or INSTALL_K3S_VERSION when the script runs). It is the stable
+// channel (https://update.k3s.io/v1-release/channels) at the time of writing, and the release the
+// CA harness in test/k3s-ca proves with the re-issued root. Server and agent scripts use the same
+// value, so a cluster is not installed with two versions by accident.
+const DefaultK3SVersion = "v1.36.5+k3s1"
+
+var k3sVersionRE = regexp.MustCompile(`^v[0-9]+\.[0-9]+\.[0-9]+\+k3s[0-9]+$`)
+
+// ValidateK3SVersion accepts an exact release (v1.36.5+k3s1), or the channels "stable" (the
+// installer's own default: whatever stable is when the script runs) and "latest". The value ends up
+// in a shell script, so nothing else is let through.
+func ValidateK3SVersion(v string) error {
+	if v == "" || v == "stable" || v == "latest" || k3sVersionRE.MatchString(v) {
+		return nil
+	}
+	return fmt.Errorf("invalid k3s version %q: want an exact release like %s, or stable or latest", v, DefaultK3SVersion)
+}
+
 type TemplateData struct {
 	Domain       string
 	Namespace    string
@@ -16,6 +37,42 @@ type TemplateData struct {
 	PublicSSHKey string
 	K3SToken     string
 	DockerSecret string
+	// K3SVersion is the k3s release to install: an exact release, "stable" or "latest".
+	// Empty means DefaultK3SVersion.
+	K3SVersion string
+	// K3SVersionExplicit is true when K3SVersion was asked for (`tnctl bootstrap --k3s-version`), not
+	// taken from the default. An agent script follows the k3s release of its server, except for a
+	// release that was asked for.
+	K3SVersionExplicit bool
+	// K3SUpgrade makes the generated scripts replace an installed k3s with K3SVersion
+	// (TN_K3S_UPGRADE=true is the default in the script). Without it a re-run keeps the installed version.
+	K3SUpgrade bool
+	// K3SForce allows that upgrade to skip minor versions (TN_K3S_FORCE=true is the default in the script).
+	K3SForce bool
+}
+
+func (d TemplateData) k3sVersion() string {
+	if d.K3SVersion == "" {
+		return DefaultK3SVersion
+	}
+	return d.K3SVersion
+}
+
+// K3SPin is the value for INSTALL_K3S_VERSION, or "" when the installer is to pick (stable, latest).
+func (d TemplateData) K3SPin() string {
+	if v := d.k3sVersion(); v != "stable" && v != "latest" {
+		return v
+	}
+	return ""
+}
+
+// K3SChannel is the value for INSTALL_K3S_CHANNEL: "latest", or "" (the installer's default,
+// stable, and the pinned releases).
+func (d TemplateData) K3SChannel() string {
+	if d.k3sVersion() == "latest" {
+		return "latest"
+	}
+	return ""
 }
 
 //go:embed agent.sh.tmpl
@@ -30,6 +87,21 @@ var DockerServerTemplateStr string
 //go:embed partials/*.tmpl
 var partialsFS embed.FS
 
+// TnK3sCAScript is the k3s CA library (setup, check, remediate). It is embedded in the server
+// bootstrap script as the template "tn-k3s-ca.sh" and is also usable stand-alone.
+//
+//go:embed scripts/tn-k3s-ca.sh
+var TnK3sCAScript string
+
+// TnK3sInstallScript is the k3s release policy and cgroup v1 handling (tn_inst_prepare), embedded
+// in the server and the agent bootstrap script as the template "tn-k3s-install.sh".
+//
+//go:embed scripts/tn-k3s-install.sh
+var TnK3sInstallScript string
+
+//go:embed scripts/*.sh
+var scriptsFS embed.FS
+
 var (
 	AgentTemplate        *template.Template
 	ServerTemplate       *template.Template
@@ -39,9 +111,11 @@ var (
 func init() {
 	AgentTemplate = template.Must(template.New("agent").Parse(AgentTemplateStr))
 	template.Must(AgentTemplate.ParseFS(partialsFS, "partials/*.tmpl"))
+	template.Must(AgentTemplate.ParseFS(scriptsFS, "scripts/tn-k3s-install.sh"))
 
 	ServerTemplate = template.Must(template.New("server").Parse(ServerTemplateStr))
 	template.Must(ServerTemplate.ParseFS(partialsFS, "partials/*.tmpl"))
+	template.Must(ServerTemplate.ParseFS(scriptsFS, "scripts/*.sh"))
 
 	DockerServerTemplate = template.Must(template.New("docker_server").Parse(DockerServerTemplateStr))
 	template.Must(DockerServerTemplate.ParseFS(partialsFS, "partials/*.tmpl"))
diff --git a/pkg/templates/k3sca_final_test.go b/pkg/templates/k3sca_final_test.go
new file mode 100644
index 0000000..3043cc4
--- /dev/null
+++ b/pkg/templates/k3sca_final_test.go
@@ -0,0 +1,436 @@
+package templates
+
+import (
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+	"time"
+)
+
+// Tests of the findings of the final review: an activating unit, the unknown data dir, the checked
+// rebuild of the bundles, leftover work dirs, and a restart that cannot hang.
+
+// fakeSystemctl puts a systemctl first in PATH. `is-active` prints state (and exits 3 unless it is
+// "active"), stop/start change the state, restart sleeps for sleep seconds. Every call is logged.
+func fakeSystemctl(t *testing.T, state string, restartSleep int) (log string) {
+	t.Helper()
+	dir := t.TempDir()
+	log = filepath.Join(dir, "systemctl.log")
+	st := filepath.Join(dir, "state")
+	write(t, st, state+"\n")
+	script := `#!/bin/sh
+echo "$*" >> '` + log + `'
+case "$1" in
+  is-active) s=$(/bin/cat '` + st + `'); echo "$s"; [ "$s" = active ] ;;
+  stop) echo inactive > '` + st + `' ;;
+  start) echo active > '` + st + `' ;;
+  restart) sleep ` + itoa(restartSleep) + ` ;;
+  cat) exit 0 ;;
+esac
+`
+	write(t, filepath.Join(dir, "systemctl"), script)
+	if err := os.Chmod(filepath.Join(dir, "systemctl"), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	t.Setenv("PATH", dir+":"+os.Getenv("PATH"))
+	return log
+}
+
+func itoa(n int) string {
+	if n == 0 {
+		return "0"
+	}
+	s := ""
+	for ; n > 0; n /= 10 {
+		s = string(rune('0'+n%10)) + s
+	}
+	return s
+}
+
+func readLog(path string) string { b, _ := os.ReadFile(path); return string(b) }
+
+// ---------------------------------------------------------------- activating
+
+func TestAnActivatingUnitIsStoppedBeforeTheRegeneration(t *testing.T) {
+	for _, state := range []string{"activating", "reloading"} {
+		t.Run(state, func(t *testing.T) {
+			p := newPKI(t)
+			p.legacyCert()
+			orig, _ := os.ReadFile(filepath.Join(p.cfg, "rsa_public.pem"))
+			p.legacyPKI(false) // hung first start
+			write(t, p.unit, unitText())
+			log := fakeSystemctl(t, state, 0)
+			out := p.mustSh("tn_k3s_ca_setup")
+			if !strings.Contains(out, "Stopping k3s") {
+				t.Errorf("an %s unit was not stopped:\n%s", state, out)
+			}
+			if got := readLog(log); !strings.Contains(got, "stop k3s.service") || !strings.Contains(got, "start k3s.service") {
+				t.Errorf("systemctl calls:\n%s", got)
+			}
+			p.assertGoodPKI(orig)
+		})
+	}
+	// an inactive or failed unit is not stopped (and so not started either)
+	for _, state := range []string{"inactive", "failed"} {
+		p := newPKI(t)
+		p.legacyCert()
+		p.legacyPKI(false)
+		write(t, p.unit, unitText())
+		log := fakeSystemctl(t, state, 0)
+		out := p.mustSh("tn_k3s_ca_setup")
+		if strings.Contains(out, "Stopping k3s") || strings.Contains(readLog(log), "stop") {
+			t.Errorf("a %s unit was stopped:\n%s\n%s", state, out, readLog(log))
+		}
+	}
+}
+
+// ---------------------------------------------------------------- unknown data dir
+
+func TestReadyK3sWithAnUninitialisedDataDirStopsTheSetup(t *testing.T) {
+	// k3s is up and ready, but the data dir we resolved was never initialised: k3s runs somewhere else
+	p := newPKI(t)
+	p.legacyCert()
+	write(t, p.unit, unitText())
+	log := fakeSystemctl(t, "active", 0)
+	out, err := p.sh("tn_k3s_ca_setup")
+	if exitCode(err) != 1 {
+		t.Fatalf("rc=%d\n%s", exitCode(err), out)
+	}
+	for _, want := range []string{"active and ready", "never initialised", "another data dir", "DATA_DIR=", "The CA and k3s were not changed"} {
+		if !strings.Contains(out, want) {
+			t.Errorf("message lacks %q:\n%s", want, out)
+		}
+	}
+	if _, err := os.Stat(p.tls("root-ca.pem")); err == nil {
+		t.Error("a CA was generated in the wrong data dir")
+	}
+	if strings.Contains(readLog(log), "stop") {
+		t.Error("k3s was stopped")
+	}
+
+	// the same with a (useless) PKI already in that dir: setup and remediate both refuse
+	q := newPKI(t)
+	q.legacyCert()
+	q.legacyPKI(false)
+	write(t, q.unit, unitText())
+	fakeSystemctl(t, "active", 0)
+	before := sum(t, q.tls("root-ca.pem"))
+	if out, err := q.sh("tn_k3s_ca_setup"); exitCode(err) != 1 || !strings.Contains(out, "another data dir") {
+		t.Errorf("setup: rc=%d\n%s", exitCode(err), out)
+	}
+	out, err = q.sh("tn_ca_remediate prepare")
+	if exitCode(err) != 4 || !strings.Contains(out, "another data dir") {
+		t.Errorf("remediate: rc=%d\n%s", exitCode(err), out)
+	}
+	if sum(t, q.tls("root-ca.pem")) != before {
+		t.Error("server/tls was changed")
+	}
+	if m, _ := filepath.Glob(filepath.Join(q.data, "server", "tls-backup-tn-*")); len(m) != 0 {
+		t.Errorf("a backup was made: %v", m)
+	}
+}
+
+func TestTheDataDirGuardOnlyFiresForAReadyUnit(t *testing.T) {
+	for _, tc := range []struct {
+		name, state string
+		initialised bool
+		wantRC      int
+	}{
+		{"activating: a hung first start is the case to repair", "activating", false, 0},
+		{"inactive", "inactive", false, 0},
+		{"ready and initialised: this is the right data dir", "active", true, 0},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			p := newPKI(t)
+			p.legacyCert()
+			if tc.initialised {
+				// a device whose k3s started once with a good CA: setup leaves it alone
+				p.mustSh("tn_k3s_ca_setup")
+				write(t, filepath.Join(p.data, "server", "token"), "K10x::server:y")
+			} else {
+				p.legacyPKI(false)
+			}
+			write(t, p.unit, unitText())
+			fakeSystemctl(t, tc.state, 0)
+			out, err := p.sh("tn_k3s_ca_setup", "K3S_BIN="+fakeK3sPath(t), "TN_K3S_RESTART_CMD=true")
+			if exitCode(err) != tc.wantRC {
+				t.Errorf("rc=%d\n%s", exitCode(err), out)
+			}
+			if strings.Contains(out, "another data dir") {
+				t.Errorf("the guard fired:\n%s", out)
+			}
+		})
+	}
+	// no unit at all (a new device): not a guard case
+	p := newPKI(t)
+	p.legacyCert()
+	fakeSystemctl(t, "inactive", 0)
+	if out, err := p.sh("tn_k3s_ca_setup"); err != nil {
+		t.Errorf("new device: %v\n%s", err, out)
+	}
+}
+
+func fakeK3sPath(t *testing.T) string {
+	bin, _ := fakeK3sVersion(t, t.TempDir(), "v1.34.11+k3s1", true)
+	return bin
+}
+
+// ---------------------------------------------------------------- the rebuild of the bundles
+
+// fakeCat first in PATH: the Nth call that has newroot.pem among its arguments either fails
+// (mode fail) or does nothing and succeeds (mode skip).
+func fakeCat(t *testing.T, n int, mode string) (counter string) {
+	t.Helper()
+	dir := t.TempDir()
+	cnt := filepath.Join(dir, "count")
+	script := `#!/bin/sh
+case "$*" in
+  *newroot.pem*)
+    n=$(/bin/cat '` + cnt + `' 2>/dev/null || echo 0); n=$((n + 1)); echo $n > '` + cnt + `'
+    if [ "$n" = ` + itoa(n) + ` ]; then
+      case ` + mode + ` in fail) echo "cat: write error: No space left on device" >&2; exit 1 ;; skip) exit 0 ;; esac
+    fi ;;
+esac
+exec /bin/cat "$@"
+`
+	write(t, filepath.Join(dir, "cat"), script)
+	if err := os.Chmod(filepath.Join(dir, "cat"), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	t.Setenv("PATH", dir+":"+os.Getenv("PATH"))
+	return cnt
+}
+
+func TestPrepareChecksEveryWriteOfTheBundleRebuild(t *testing.T) {
+	for _, tc := range []struct {
+		name, mode string
+		n          int
+		want       string
+	}{
+		{"a write fails in the first bundle", "fail", 1, "cannot rebuild the CA bundles"},
+		{"a write fails in a later bundle", "fail", 4, "cannot rebuild the CA bundles"},
+		{"the last write fails", "fail", 7, "cannot rebuild the CA bundles"},
+		{"a write is silently lost (too few certificates)", "skip", 3, "holds 2 certificates, the original 3"},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			p := newPKI(t)
+			p.legacyCert()
+			p.legacyPKI(true)
+			bin, calls := fakeK3sVersion(t, t.TempDir(), "v1.34.11+k3s1", true)
+			beforeRoot, beforeServer := sum(t, p.tls("root-ca.pem")), sum(t, p.tls("server-ca.crt"))
+			counter := fakeCat(t, tc.n, tc.mode)
+			for _, script := range []string{"tn_ca_remediate prepare", "tn_ca_remediate all", "tn_k3s_ca_setup"} {
+				os.Remove(counter) // the Nth call of every run fails
+				out, err := p.sh(script, "K3S_BIN="+bin, "TN_K3S_RESTART_CMD=touch "+filepath.Join(p.dir, "restarted"))
+				if err == nil {
+					t.Fatalf("%s went on:\n%s", script, out)
+				}
+				if !strings.Contains(out, tc.want) {
+					t.Errorf("%s: lacks %q:\n%s", script, tc.want, out)
+				}
+				if script != "tn_k3s_ca_setup" && !strings.Contains(out, "were not changed") {
+					t.Errorf("%s: does not say that the CA and k3s were not changed:\n%s", script, out)
+				}
+			}
+			if sum(t, p.tls("root-ca.pem")) != beforeRoot || sum(t, p.tls("server-ca.crt")) != beforeServer {
+				t.Error("server/tls changed")
+			}
+			if m, _ := filepath.Glob(filepath.Join(p.data, "server", ".tn-ca-rotate-*")); len(m) != 0 {
+				t.Errorf("staging left behind (it holds keys): %v", m)
+			}
+			if m, _ := filepath.Glob(filepath.Join(p.data, "server", "tls-backup-tn-*.tar")); len(m) != 0 {
+				t.Errorf("a backup was made for a rotation that never started: %v", m)
+			}
+			if _, err := os.Stat(calls); err == nil {
+				t.Errorf("rotate-ca was called:\n%s", readLog(calls))
+			}
+			if _, err := os.Stat(filepath.Join(p.dir, "restarted")); err == nil {
+				t.Error("k3s was restarted")
+			}
+		})
+	}
+}
+
+func TestPrepareRefusesABundleThatDoesNotEndWithTheOldRoot(t *testing.T) {
+	p := newPKI(t)
+	p.legacyCert()
+	p.legacyPKI(true)
+	// a root-ca.crt with something after the root: the rebuilt one would not end with the new root
+	b, _ := os.ReadFile(p.tls("root-ca.crt"))
+	i, _ := os.ReadFile(p.tls("intermediate-ca.pem"))
+	if err := os.WriteFile(p.tls("root-ca.crt"), append(b, i...), 0o640); err != nil {
+		t.Fatal(err)
+	}
+	bin, calls := fakeK3sVersion(t, t.TempDir(), "v1.34.11+k3s1", true)
+	out, err := p.sh("tn_ca_remediate prepare", "K3S_BIN="+bin)
+	if err == nil || !strings.Contains(out, "is not the new root") {
+		t.Fatalf("err=%v\n%s", err, out)
+	}
+	if _, err := os.Stat(calls); err == nil {
+		t.Error("rotate-ca was called")
+	}
+	if m, _ := filepath.Glob(filepath.Join(p.data, "server", ".tn-ca-rotate-*")); len(m) != 0 {
+		t.Errorf("staging left behind: %v", m)
+	}
+}
+
+func TestPrepareStillRebuildsEveryBundleOfARealDevice(t *testing.T) {
+	// the happy path, with the strict checks on: all seven bundles end with the new root and keep their length
+	p := newPKI(t)
+	p.legacyCert()
+	orig, _ := os.ReadFile(filepath.Join(p.cfg, "rsa_public.pem"))
+	p.legacyPKI(true)
+	lens := map[string]int{}
+	for _, b := range []string{"server-ca.crt", "client-ca.crt", "request-header-ca.crt", "etcd/peer-ca.crt", "etcd/server-ca.crt", "intermediate-ca.crt", "root-ca.crt"} {
+		lens[b] = len(readCerts(t, p.tls(b)))
+	}
+	bin, _ := fakeK3sVersion(t, t.TempDir(), "v1.34.11+k3s1", true)
+	p.mustSh("tn_ca_remediate all", "K3S_BIN="+bin, "TN_K3S_RESTART_CMD=true")
+	p.assertGoodPKI(orig)
+	for b, n := range lens {
+		certs := readCerts(t, p.tls(b))
+		if len(certs) != n {
+			t.Errorf("%s: %d certificates, was %d", b, len(certs), n)
+		}
+		if certs[len(certs)-1].KeyUsage == 0 {
+			t.Errorf("%s: the last certificate has no key usage", b)
+		}
+	}
+}
+
+// ---------------------------------------------------------------- leftovers of a regeneration
+
+func TestLeftoverRegenerationDirsAreCleanedWhenTheCAIsOk(t *testing.T) {
+	p := newPKI(t)
+	p.legacyCert()
+	p.mustSh("tn_k3s_ca_setup") // never started: a valid PKI, no token yet
+	leftovers := func() []string {
+		return []string{
+			filepath.Join(p.data, "server", ".tn-tls-old.20200101T000000.4242"),
+			filepath.Join(p.data, "server", ".tn-tls-new.AbCdEf"),
+			filepath.Join(p.data, "server", ".tn-ca-rotate-20200101T000000"),
+		}
+	}
+	plant := func() {
+		for _, d := range leftovers() {
+			write(t, filepath.Join(d, "root-ca.key"), "not a key")
+		}
+	}
+	gone := func(name string) {
+		t.Helper()
+		for _, d := range leftovers() {
+			if _, err := os.Stat(d); err == nil {
+				t.Errorf("%s: %s was not removed", name, filepath.Base(d))
+			}
+		}
+	}
+	// the PKI that exists and is valid, k3s has not started yet
+	plant()
+	out := p.mustSh("tn_k3s_ca_setup")
+	gone("setup, valid PKI, not started")
+	if !strings.Contains(out, "Removed the leftover staging dir") {
+		t.Errorf("no message:\n%s", out)
+	}
+	if err := os.WriteFile(filepath.Join(p.data, "server", "token"), []byte("K10x::server:y"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	for _, script := range []string{"tn_k3s_ca_setup", "tn_ca_remediate prepare", "tn_ca_remediate all"} {
+		plant()
+		p.mustSh(script)
+		gone(script)
+	}
+	// check is read-only
+	plant()
+	p.check()
+	for _, d := range leftovers() {
+		if _, err := os.Stat(d); err != nil {
+			t.Errorf("check removed %s", d)
+		}
+	}
+	// a device that still needs its CA fixed keeps them until it is fine (they may be the only copy of
+	// an interrupted run)
+	q := newPKI(t)
+	q.legacyCert()
+	q.legacyPKI(true)
+	old := filepath.Join(q.data, "server", ".tn-tls-old.20200101T000000.4242")
+	write(t, filepath.Join(old, "root-ca.key"), "not a key")
+	badBin, _ := fakeK3s(t, t.TempDir(), false)
+	if _, err := q.sh("tn_ca_remediate all", "K3S_BIN="+badBin); err == nil {
+		t.Fatal("rotate-ca was meant to fail")
+	}
+	if _, err := os.Stat(old); err != nil {
+		t.Error("the leftover was removed while the CA was not repaired")
+	}
+}
+
+// ---------------------------------------------------------------- bounded restart
+
+func TestARestartThatHangsIsReported(t *testing.T) {
+	for _, tc := range []struct {
+		name string
+		env  func(t *testing.T) []string
+	}{
+		{"systemctl restart", func(t *testing.T) []string {
+			fakeSystemctl(t, "activating", 20)
+			return []string{"TN_K3S_READY_GRACE=1", "TN_K3S_READY_POLL=1"}
+		}},
+		{"TN_K3S_RESTART_CMD", func(t *testing.T) []string { return []string{"TN_K3S_RESTART_CMD=sleep 20"} }},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			p := newPKI(t)
+			p.legacyCert()
+			orig, _ := os.ReadFile(filepath.Join(p.cfg, "rsa_public.pem"))
+			p.legacyPKI(true)
+			write(t, p.unit, unitText())
+			bin, _ := fakeK3sVersion(t, t.TempDir(), "v1.34.11+k3s1", true)
+			env := append(tc.env(t), "K3S_BIN="+bin, "TN_K3S_SERVICE_TIMEOUT=1")
+			start := time.Now()
+			out, err := p.sh("tn_ca_remediate all", env...)
+			if d := time.Since(start); d > 12*time.Second {
+				t.Errorf("took %s: the restart is not bounded", d)
+			}
+			if exitCode(err) != 5 {
+				t.Fatalf("rc=%d\n%s", exitCode(err), out)
+			}
+			if tc.name == "systemctl restart" && !strings.Contains(out, "was not active") {
+				t.Errorf("the message does not say that the unit was watched:\n%s", out)
+			}
+			for _, want := range []string{"did not finish within 1s", "datastore of k3s holds the new CA", "could not be restarted", "Do not roll back"} {
+				if !strings.Contains(out, want) {
+					t.Errorf("message lacks %q:\n%s", want, out)
+				}
+			}
+			p.assertGoodPKI(orig) // the files were finalized before the restart
+		})
+	}
+}
+
+func TestAStartThatHangsAfterTheRegenerationIsReported(t *testing.T) {
+	p := newPKI(t)
+	p.legacyCert()
+	orig, _ := os.ReadFile(filepath.Join(p.cfg, "rsa_public.pem"))
+	p.legacyPKI(false)
+	start := time.Now()
+	out := p.mustSh("tn_ca_remediate prepare", "TN_K3S_STOP_CMD=true", "TN_K3S_START_CMD=sleep 20", "TN_K3S_SERVICE_TIMEOUT=1")
+	if d := time.Since(start); d > 12*time.Second {
+		t.Errorf("took %s: the start is not bounded", d)
+	}
+	if !strings.Contains(out, "the new CA is installed, but k3s could not be started") {
+		t.Errorf("message:\n%s", out)
+	}
+	p.assertGoodPKI(orig)
+}
+
+func TestARestartThatWorksIsNotReportedAsAFailure(t *testing.T) {
+	p := newPKI(t)
+	p.legacyCert()
+	p.legacyPKI(true)
+	write(t, p.unit, unitText())
+	log := fakeSystemctl(t, "active", 0)
+	bin, _ := fakeK3sVersion(t, t.TempDir(), "v1.34.11+k3s1", true)
+	out := p.mustSh("tn_ca_remediate all", "K3S_BIN="+bin)
+	if !strings.Contains(readLog(log), "restart k3s.service") || strings.Contains(out, "did not finish") {
+		t.Errorf("log:\n%s\nout:\n%s", readLog(log), out)
+	}
+}
diff --git a/pkg/templates/k3sca_fixes_test.go b/pkg/templates/k3sca_fixes_test.go
new file mode 100644
index 0000000..04388ae
--- /dev/null
+++ b/pkg/templates/k3sca_fixes_test.go
@@ -0,0 +1,658 @@
+package templates
+
+import (
+	"context"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"strings"
+	"testing"
+	"time"
+)
+
+// Tests of the "final fixes": data dir detection, regeneration race, --force conditions, messages,
+// backups, old k3s. They use the helpers of k3sca_test.go.
+
+// ---------------------------------------------------------------- data dir detection
+
+// unitText is a k3s.service as the k3s installer writes it, with the given ExecStart arguments.
+func unitText(args ...string) string {
+	var b strings.Builder
+	b.WriteString(`[Unit]
+Description=Lightweight Kubernetes
+[Service]
+Type=notify
+EnvironmentFile=-/etc/default/%N
+EnvironmentFile=-/etc/systemd/system/k3s.service.env
+KillMode=process
+ExecStartPre=/bin/sh -xc '! /usr/bin/systemctl is-enabled --quiet nm-cloud-setup.service 2>/dev/null'
+ExecStartPre=-/sbin/modprobe br_netfilter
+ExecStart=/usr/local/bin/k3s \
+    server \
+`)
+	for i, a := range args {
+		b.WriteString("\t'" + a + "'")
+		if i < len(args)-1 {
+			b.WriteString(" \\")
+		}
+		b.WriteString("\n")
+	}
+	return b.String()
+}
+
+func write(t *testing.T, path, content string) {
+	t.Helper()
+	if err := os.MkdirAll(filepath.Dir(path), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(path, []byte(content), 0o644); err != nil {
+		t.Fatal(err)
+	}
+}
+
+// resolve runs tn_ca_resolve_datadir without an explicit DATA_DIR and returns "dir|source"
+func (p *pki) resolve(env ...string) string {
+	p.t.Helper()
+	out := p.mustSh(`tn_ca_resolve_datadir; echo "RESOLVED:$DATA_DIR|$TN_CA_DATADIR_SRC"`, append([]string{"DATA_DIR="}, env...)...)
+	for _, l := range strings.Split(out, "\n") {
+		if strings.HasPrefix(l, "RESOLVED:") {
+			return strings.TrimPrefix(l, "RESOLVED:")
+		}
+	}
+	p.t.Fatalf("no RESOLVED line:\n%s", out)
+	return ""
+}
+
+func TestDataDirResolution(t *testing.T) {
+	t.Run("default", func(t *testing.T) {
+		p := newPKI(t)
+		if got := p.resolve(); got != "/var/lib/rancher/k3s|default" {
+			t.Errorf("got %q", got)
+		}
+	})
+	t.Run("explicit beats everything", func(t *testing.T) {
+		p := newPKI(t)
+		write(t, p.unit, unitText("--data-dir", "/from/unit"))
+		write(t, filepath.Join(p.k3sCfg, "config.yaml"), "data-dir: /from/config\n")
+		if got := p.resolve("DATA_DIR=/explicit"); got != "/explicit|--data-dir / DATA_DIR" {
+			t.Errorf("got %q", got)
+		}
+	})
+	t.Run("config.yaml", func(t *testing.T) {
+		for name, tc := range map[string]struct{ yaml, want string }{
+			"plain":            {"data-dir: /opt/k3s\n", "/opt/k3s"},
+			"no space":         {"data-dir:/opt/k3s\n", "/opt/k3s"},
+			"double quoted":    {"disable:\n  - traefik\ndata-dir: \"/opt/k 3s\" # c\nnode-name: x\n", "/opt/k 3s"},
+			"single quoted":    {"data-dir: '/opt/k3s'\n", "/opt/k3s"},
+			"comment":          {"data-dir: /opt/k3s   # where\n", "/opt/k3s"},
+			"crlf":             {"data-dir: /opt/k3s\r\nnode-name: x\r\n", "/opt/k3s"},
+			"last one wins":    {"data-dir: /first\ndata-dir: /second\n", "/second"},
+			"indented ignored": {"x:\n  data-dir: /nested\n", "/var/lib/rancher/k3s"},
+			"commented out":    {"# data-dir: /opt/k3s\n", "/var/lib/rancher/k3s"},
+			"empty":            {"data-dir:\n", "/var/lib/rancher/k3s"},
+		} {
+			t.Run(name, func(t *testing.T) {
+				p := newPKI(t)
+				write(t, filepath.Join(p.k3sCfg, "config.yaml"), tc.yaml)
+				got := p.resolve()
+				dir, src, _ := strings.Cut(got, "|")
+				if dir != tc.want {
+					t.Errorf("dir %q, want %q", dir, tc.want)
+				}
+				if tc.want != "/var/lib/rancher/k3s" && src != filepath.Join(p.k3sCfg, "config.yaml") {
+					t.Errorf("source %q", src)
+				}
+			})
+		}
+	})
+	t.Run("config.yaml.d beats config.yaml, last file in lexical order wins", func(t *testing.T) {
+		p := newPKI(t)
+		write(t, filepath.Join(p.k3sCfg, "config.yaml"), "data-dir: /from/config\n")
+		write(t, filepath.Join(p.k3sCfg, "config.yaml.d", "10-a.yaml"), "data-dir: /from/a\n")
+		write(t, filepath.Join(p.k3sCfg, "config.yaml.d", "20-b.yaml"), "data-dir: /from/b\n")
+		write(t, filepath.Join(p.k3sCfg, "config.yaml.d", "05-c.yaml"), "data-dir: /from/c\n")
+		write(t, filepath.Join(p.k3sCfg, "config.yaml.d", "30-nodir.yaml"), "node-name: x\n")
+		write(t, filepath.Join(p.k3sCfg, "config.yaml.d", "40-other.txt"), "data-dir: /ignored\n")
+		got := p.resolve()
+		if want := "/from/b|" + filepath.Join(p.k3sCfg, "config.yaml.d", "20-b.yaml"); got != want {
+			t.Errorf("got %q, want %q", got, want)
+		}
+	})
+	t.Run("config.yaml.d only", func(t *testing.T) {
+		p := newPKI(t)
+		write(t, filepath.Join(p.k3sCfg, "config.yaml.d", "a.yaml"), "data-dir: /from/a\n")
+		if got := p.resolve(); !strings.HasPrefix(got, "/from/a|") {
+			t.Errorf("got %q", got)
+		}
+	})
+	t.Run("ExecStart of the unit beats the config files", func(t *testing.T) {
+		for name, tc := range map[string]struct {
+			args []string
+			want string
+		}{
+			"--data-dir DIR":    {[]string{"--disable=traefik", "--data-dir", "/from/unit", "--token", "x"}, "/from/unit"},
+			"--data-dir=DIR":    {[]string{"--data-dir=/from/unit", "--token", "x"}, "/from/unit"},
+			"-d DIR":            {[]string{"--token", "x", "-d", "/from/unit"}, "/from/unit"},
+			"-d=DIR":            {[]string{"-d=/from/unit"}, "/from/unit"},
+			"the last one":      {[]string{"--data-dir", "/one", "--data-dir=/two"}, "/two"},
+			"none in ExecStart": {[]string{"--disable=traefik", "--token", "x"}, "/from/conf.d"},
+		} {
+			t.Run(name, func(t *testing.T) {
+				p := newPKI(t)
+				write(t, p.unit, unitText(tc.args...))
+				write(t, filepath.Join(p.k3sCfg, "config.yaml"), "data-dir: /from/config\n")
+				write(t, filepath.Join(p.k3sCfg, "config.yaml.d", "a.yaml"), "data-dir: /from/conf.d\n")
+				got := p.resolve()
+				if dir, _, _ := strings.Cut(got, "|"); dir != tc.want {
+					t.Errorf("got %q, want %q", got, tc.want)
+				}
+			})
+		}
+	})
+	t.Run("ExecStart on one line and a drop-in reset", func(t *testing.T) {
+		p := newPKI(t)
+		write(t, p.unit, "[Service]\nExecStart=/usr/local/bin/k3s server --data-dir /old\nExecStart=\nExecStart=/usr/local/bin/k3s server -d /new\n")
+		if got := p.resolve(); !strings.HasPrefix(got, "/new|ExecStart of k3s.service") {
+			t.Errorf("got %q", got)
+		}
+		write(t, p.unit, "[Service]\nExecStartPre=/bin/true --data-dir /pre\nExecStart=/usr/local/bin/k3s server --token x\n")
+		if got := p.resolve(); got != "/var/lib/rancher/k3s|default" {
+			t.Errorf("ExecStartPre must not count: %q", got)
+		}
+	})
+	t.Run("K3S_DATA_DIR of the unit", func(t *testing.T) {
+		p := newPKI(t)
+		envf := filepath.Join(p.dir, "k3s.service.env")
+		write(t, envf, "K3S_URL=x\nK3S_DATA_DIR='/from/envfile'\n")
+		write(t, p.unit, unitText("--token", "x")+"EnvironmentFile=-"+envf+"\n")
+		if got := p.resolve(); !strings.HasPrefix(got, "/from/envfile|K3S_DATA_DIR") {
+			t.Errorf("got %q", got)
+		}
+		// config.yaml (a command line flag to k3s) beats the environment
+		write(t, filepath.Join(p.k3sCfg, "config.yaml"), "data-dir: /from/config\n")
+		if got := p.resolve(); !strings.HasPrefix(got, "/from/config|") {
+			t.Errorf("got %q", got)
+		}
+		q := newPKI(t)
+		write(t, q.unit, "[Service]\nEnvironment=\"FOO=1\" \"K3S_DATA_DIR=/from/env\"\nExecStart=/usr/local/bin/k3s server\n")
+		if got := q.resolve(); !strings.HasPrefix(got, "/from/env|K3S_DATA_DIR") {
+			t.Errorf("got %q", got)
+		}
+	})
+	t.Run("no globbing, the bootstrap runs with noglob", func(t *testing.T) {
+		p := newPKI(t)
+		write(t, filepath.Join(p.k3sCfg, "config.yaml.d", "a.yaml"), "data-dir: /from/a\n")
+		// p.sh already runs with `set -o noglob`; this is the same assertion under dash -u as well
+		if got := p.resolve(); !strings.HasPrefix(got, "/from/a|") {
+			t.Errorf("got %q", got)
+		}
+	})
+}
+
+// check, remediate and setup all use the resolved dir when there is no explicit one
+func TestCheckRemediateSetupUseTheResolvedDataDir(t *testing.T) {
+	p := newPKI(t)
+	p.legacyCert()
+	orig, _ := os.ReadFile(filepath.Join(p.cfg, "rsa_public.pem"))
+	other := filepath.Join(p.dir, "opt-k3s")
+	p.data = other
+	p.legacyPKI(true)
+	write(t, filepath.Join(p.k3sCfg, "config.yaml"), "data-dir: "+other+"\n")
+
+	out, err := p.sh("tn_ca_check", "DATA_DIR=")
+	if rc := exitCode(err); rc != 2 || !strings.Contains(out, "needs-rotation") || !strings.Contains(out, "config.yaml") {
+		t.Fatalf("check rc=%d\n%s", rc, out)
+	}
+	// stand-alone, no --data-dir
+	cmd := exec.Command("sh", libPath, "check", "--config-dir", p.cfg)
+	o, err := cmd.CombinedOutput()
+	if rc := exitCode(err); rc != 2 || !strings.Contains(string(o), "needs-rotation") {
+		t.Errorf("sh tn-k3s-ca.sh check: rc=%d\n%s", rc, o)
+	}
+
+	bin, calls := fakeK3s(t, t.TempDir(), true)
+	p.mustSh("tn_ca_remediate all", "DATA_DIR=", "K3S_BIN="+bin, "TN_K3S_RESTART_CMD=true")
+	if c, _ := os.ReadFile(calls); !strings.Contains(string(c), "--data-dir "+other+" ") {
+		t.Errorf("rotate-ca was not called with the resolved data dir: %s", c)
+	}
+	p.assertGoodPKI(orig)
+
+	// setup on a never started device with the data dir in a conf.d file
+	q := newPKI(t)
+	q.legacyCert()
+	qdir := filepath.Join(q.dir, "conf-d-dir")
+	write(t, filepath.Join(q.k3sCfg, "config.yaml.d", "50-data.yaml"), "data-dir: "+qdir+"\n")
+	out = q.mustSh("tn_k3s_ca_setup", "DATA_DIR=")
+	if !strings.Contains(out, "k3s data dir: "+qdir) {
+		t.Errorf("setup did not say where it works:\n%s", out)
+	}
+	if _, err := os.Stat(filepath.Join(qdir, "server", "tls", "server-ca.crt")); err != nil {
+		t.Errorf("setup did not create the PKI in the resolved dir: %v", err)
+	}
+	if _, err := os.Stat(filepath.Join(q.data, "server")); err == nil {
+		t.Error("setup used the default data dir")
+	}
+}
+
+func exitCode(err error) int {
+	if err == nil {
+		return 0
+	}
+	if ee, ok := err.(*exec.ExitError); ok {
+		return ee.ExitCode()
+	}
+	return -1
+}
+
+// A k3s server unit exists, but no data dir with a CA was found: never ok.
+func TestCheckIsNotOkWhenAServerUnitExistsButNoServerDataFound(t *testing.T) {
+	p := newPKI(t)
+	p.legacyCert()
+	// no unit, no data: an agent or a fresh machine, ok
+	if rc, o := p.check(); rc != 0 || !strings.Contains(o, "not-a-server") {
+		t.Fatalf("no unit: rc=%d %s", rc, o)
+	}
+	// a server unit, data dir (the default or a wrong explicit one) without server/tls
+	write(t, p.unit, unitText("--data-dir", "/somewhere/else", "--token", "x"))
+	out, err := p.sh("tn_ca_check", "DATA_DIR=")
+	rc := exitCode(err)
+	if rc != 4 || !strings.Contains(out, "no-server-data") || !strings.Contains(out, "/somewhere/else") || !strings.Contains(out, "--data-dir") {
+		t.Errorf("unit with a missing data dir: rc=%d\n%s", rc, out)
+	}
+	if rc, o := p.check(); rc != 4 || !strings.Contains(o, "no-server-data") {
+		t.Errorf("explicit data dir without server/tls: rc=%d %s", rc, o)
+	}
+	// remediate cannot act on it either, and says why
+	if o, err := p.sh("tn_ca_remediate all"); exitCode(err) != 4 || !strings.Contains(o, "no-server-data") && !strings.Contains(o, "server unit") {
+		t.Errorf("remediate: rc=%d\n%s", exitCode(err), o)
+	}
+	// pointing at the real dir: ok again
+	p.mustSh("tn_k3s_ca_setup")
+	if rc, o := p.check(); rc != 0 {
+		t.Errorf("check after setup: rc=%d %s", rc, o)
+	}
+	// ... and setup itself is not blocked by a unit without a data dir (OS builds install the
+	// unit without starting it; the first bootstrap creates the PKI before the installer)
+	q := newPKI(t)
+	q.legacyCert()
+	write(t, q.unit, unitText("--token", "x"))
+	q.mustSh("tn_k3s_ca_setup")
+	if _, err := os.Stat(q.tls("server-ca.crt")); err != nil {
+		t.Errorf("setup with a unit but no data: %v", err)
+	}
+}
+
+// ---------------------------------------------------------------- regeneration race
+
+func TestRegenerationStopsK3sAndReplacesTheDirSafely(t *testing.T) {
+	p := newPKI(t)
+	p.legacyCert()
+	orig, _ := os.ReadFile(filepath.Join(p.cfg, "rsa_public.pem"))
+	p.legacyPKI(false) // hung first start
+	oldSum := sum(t, p.tls("root-ca.pem"))
+	log := filepath.Join(p.dir, "svc.log")
+	// the stop command records what server/tls looked like at that moment
+	stop := "echo stop root=$(sha256sum " + p.tls("root-ca.pem") + " | cut -d' ' -f1) >> " + log
+	start := "echo start root=$(sha256sum " + p.tls("root-ca.pem") + " | cut -d' ' -f1) >> " + log
+	p.mustSh("tn_ca_remediate prepare", "TN_K3S_STOP_CMD="+stop, "TN_K3S_START_CMD="+start)
+	b, _ := os.ReadFile(log)
+	lines := strings.Split(strings.TrimSpace(string(b)), "\n")
+	if len(lines) != 2 || lines[0] != "stop root="+oldSum || !strings.HasPrefix(lines[1], "start root=") || lines[1] == "start root="+oldSum {
+		t.Errorf("service log:\n%s", b)
+	}
+	p.assertGoodPKI(orig)
+	if m, _ := filepath.Glob(filepath.Join(p.data, "server", ".tn-tls-*")); len(m) != 0 {
+		t.Errorf("work dirs left behind: %v", m)
+	}
+
+	// `remediate all` on such a device: stop, replace, start, then the restart of the tool
+	q := newPKI(t)
+	q.legacyCert()
+	q.legacyPKI(false)
+	qlog := filepath.Join(q.dir, "svc.log")
+	q.mustSh("tn_ca_remediate all", "TN_K3S_STOP_CMD=echo stop >> "+qlog, "TN_K3S_START_CMD=echo start >> "+qlog, "TN_K3S_RESTART_CMD=echo restart >> "+qlog)
+	if b, _ := os.ReadFile(qlog); string(b) != "stop\nstart\nrestart\n" {
+		t.Errorf("service log: %q", b)
+	}
+
+	// a fresh bootstrap has no k3s: nothing is stopped or started (STOP_CMD unset, no active unit)
+	r := newPKI(t)
+	r.legacyCert()
+	out := r.mustSh("tn_k3s_ca_setup")
+	if strings.Contains(out, "Stopping k3s") {
+		t.Errorf("setup stopped k3s:\n%s", out)
+	}
+}
+
+func TestRegenerationRestoresTheOldDirOnAnyFailure(t *testing.T) {
+	t.Run("installed result does not validate", testRestoreWhenInstalledPKIFails)
+	t.Run("k3s cannot be stopped", testNothingReplacedWhenK3sCannotBeStopped)
+}
+
+// the installed result does not validate: the old dir comes back and k3s is started again
+func testRestoreWhenInstalledPKIFails(t *testing.T) {
+	p := newPKI(t)
+	p.legacyCert()
+	p.legacyPKI(false)
+	oldSum := sum(t, p.tls("root-ca.pem")) + sum(t, p.tls("server-ca.crt"))
+	log := filepath.Join(p.dir, "svc.log")
+	failingOpenssl(t, "verify", 7) // the 6 checks of the generated dir pass, those of the installed dir fail
+	out, err := p.sh("tn_ca_remediate prepare", "TN_K3S_STOP_CMD=echo stop >> "+log, "TN_K3S_START_CMD=echo start >> "+log)
+	if err == nil {
+		t.Fatalf("prepare succeeded although the installed PKI does not validate:\n%s", out)
+	}
+	if !strings.Contains(out, "does not validate") || !strings.Contains(out, "was restored") {
+		t.Errorf("messages:\n%s", out)
+	}
+	if got := sum(t, p.tls("root-ca.pem")) + sum(t, p.tls("server-ca.crt")); got != oldSum {
+		t.Error("the old server/tls was not restored")
+	}
+	if b, _ := os.ReadFile(log); string(b) != "stop\nstart\n" {
+		t.Errorf("service log: %q (k3s must be started again after a failure)", b)
+	}
+	if m, _ := filepath.Glob(filepath.Join(p.data, "server", ".tn-tls-*")); len(m) != 0 {
+		t.Errorf("work dirs left behind: %v", m)
+	}
+
+}
+
+// k3s cannot be stopped: nothing is replaced, nothing is started
+func testNothingReplacedWhenK3sCannotBeStopped(t *testing.T) {
+	q := newPKI(t)
+	q.legacyCert()
+	q.legacyPKI(false)
+	before := sum(t, q.tls("server-ca.crt"))
+	qlog := filepath.Join(q.dir, "svc.log")
+	out, err := q.sh("tn_ca_remediate prepare", "TN_K3S_STOP_CMD=false", "TN_K3S_START_CMD=echo start >> "+qlog)
+	if err == nil || !strings.Contains(out, "cannot stop k3s") {
+		t.Errorf("stop failure: err=%v\n%s", err, out)
+	}
+	if sum(t, q.tls("server-ca.crt")) != before {
+		t.Error("server/tls changed although k3s could not be stopped")
+	}
+	if _, err := os.Stat(qlog); err == nil {
+		t.Error("k3s was started although it was never stopped")
+	}
+	if m, _ := filepath.Glob(filepath.Join(q.data, "server", "tls-backup-tn-*.tar")); len(m) != 0 {
+		t.Errorf("backup made although nothing was replaced: %v", m)
+	}
+}
+
+// ---------------------------------------------------------------- --force conditions
+
+func (p *pki) stagedRotateCmd() string {
+	p.t.Helper()
+	stages, _ := filepath.Glob(filepath.Join(p.data, "server", ".tn-ca-rotate-*"))
+	if len(stages) != 1 {
+		p.t.Fatalf("staging dirs: %v", stages)
+	}
+	b, err := os.ReadFile(filepath.Join(stages[0], "ROTATE_CMD"))
+	if err != nil {
+		p.t.Fatal(err)
+	}
+	return string(b)
+}
+
+func TestRotateCmdForcesWhenTheOldRootCannotVouch(t *testing.T) {
+	noBC := filepath.Join(t.TempDir(), "no-ext.cnf")
+	write(t, noBC, "[req]\ndistinguished_name=dn\nprompt=no\n[dn]\nCN=teknoir.ai\n")
+	future := time.Now().Add(48 * time.Hour).UTC().Format("20060102150405Z")
+	for _, tc := range []struct {
+		name string
+		args []string
+		why  string
+	}{
+		{"no basicConstraints", []string{"-config", noBC}, "no basicConstraints"},
+		{"CA:FALSE", []string{"-addext", "basicConstraints=critical,CA:FALSE"}, "CA:FALSE"},
+		{"not yet valid", []string{"-not_before", future, "-not_after", "20700101000000Z"}, "cannot verify the old chain"},
+		{"pathlen 0, openssl cannot verify the old chain", []string{"-addext", "basicConstraints=critical,CA:TRUE,pathlen:0"}, "cannot verify the old chain"},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			p := newPKI(t)
+			p.legacyCertArgs(tc.args...)
+			p.legacyPKI(true)
+			out := p.mustSh("tn_ca_openssl; tn_ca_remediate prepare")
+			if !strings.Contains(out, "--force") || !strings.Contains(out, tc.why) {
+				t.Errorf("no word about --force (%q):\n%s", tc.why, out)
+			}
+			if rc := p.stagedRotateCmd(); !strings.Contains(rc, "--force && touch") {
+				t.Errorf("ROTATE_CMD: %s", rc)
+			}
+		})
+	}
+	// a good old root (CA:TRUE, no keyUsage, valid) needs no --force: covered by
+	// TestRotateCmdForcesOnlyWhenTheOldRootCannotVouch
+}
+
+// ---------------------------------------------------------------- messages and cleanup
+
+func TestRestartFailureAfterARotationSaysTheCAWasChanged(t *testing.T) {
+	p := newPKI(t)
+	p.legacyCert()
+	orig, _ := os.ReadFile(filepath.Join(p.cfg, "rsa_public.pem"))
+	p.legacyPKI(true)
+	bin, _ := fakeK3s(t, t.TempDir(), true)
+	out, err := p.sh("tn_ca_remediate all", "K3S_BIN="+bin, "TN_K3S_RESTART_CMD=false")
+	if exitCode(err) != 5 {
+		t.Fatalf("rc=%d\n%s", exitCode(err), out)
+	}
+	for _, want := range []string{"datastore of k3s holds the new CA", "systemctl restart k3s", "journalctl", "Do not roll back"} {
+		if !strings.Contains(out, want) {
+			t.Errorf("message lacks %q:\n%s", want, out)
+		}
+	}
+	if strings.Contains(out, "not changed") {
+		t.Errorf("a changed device is described as not changed:\n%s", out)
+	}
+	p.assertGoodPKI(orig) // the files were finalized before the restart
+
+	// the same through the bootstrap setup
+	q := newPKI(t)
+	q.legacyCert()
+	q.legacyPKI(true)
+	out, err = q.sh("tn_k3s_ca_setup", "K3S_BIN="+bin, "TN_K3S_RESTART_CMD=false")
+	if err == nil {
+		t.Fatal("setup continued after a failed restart")
+	}
+	if strings.Contains(out, "was not changed") || !strings.Contains(out, "WAS changed") || !strings.Contains(out, "holds the new CA") {
+		t.Errorf("setup message:\n%s", out)
+	}
+
+	// and a failed rotate-ca still says that nothing was changed
+	r := newPKI(t)
+	r.legacyCert()
+	r.legacyPKI(true)
+	badBin, _ := fakeK3s(t, t.TempDir(), false)
+	out, err = r.sh("tn_k3s_ca_setup", "K3S_BIN="+badBin, "TN_K3S_RESTART_CMD=true")
+	if err == nil || !strings.Contains(out, "was not changed beyond the saved backup") {
+		t.Errorf("failed rotation: err=%v\n%s", err, out)
+	}
+}
+
+// rotate-ca succeeded, the files were not copied: a second run finalizes, it does not stage again
+func TestRemediateFinalizesACompletedRotationInsteadOfStagingAgain(t *testing.T) {
+	p := newPKI(t)
+	p.legacyCert()
+	orig, _ := os.ReadFile(filepath.Join(p.cfg, "rsa_public.pem"))
+	p.legacyPKI(true)
+	bin, calls := fakeK3s(t, t.TempDir(), true)
+	p.mustSh("tn_ca_remediate prepare", "K3S_BIN="+bin)
+	p.mustSh("tn_ca_remediate rotate", "K3S_BIN="+bin)
+	// (finalize "failed": the files are still the old ones)
+	restarted := filepath.Join(p.dir, "restarted")
+	out := p.mustSh("tn_ca_remediate all", "K3S_BIN="+bin, "TN_K3S_RESTART_CMD=touch "+restarted)
+	if !strings.Contains(out, "finalizing it") {
+		t.Errorf("message:\n%s", out)
+	}
+	if b, _ := os.ReadFile(calls); strings.Count(string(b), "rotate-ca") != 1 {
+		t.Errorf("rotate-ca was run again:\n%s", b)
+	}
+	if _, err := os.Stat(restarted); err != nil {
+		t.Error("k3s was not restarted")
+	}
+	p.assertGoodPKI(orig)
+}
+
+func TestLeftoverRotatedStagingIsCleanedWhenTheCAIsOk(t *testing.T) {
+	p := newPKI(t)
+	p.legacyCert()
+	p.mustSh("tn_k3s_ca_setup")
+	if err := os.WriteFile(filepath.Join(p.data, "server", "token"), []byte("K10x::server:y"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	for _, tc := range []struct{ name, script string }{
+		{"remediate all", "tn_ca_remediate all"},
+		{"remediate prepare", "tn_ca_remediate prepare"},
+		{"setup", "tn_k3s_ca_setup"},
+	} {
+		stage := filepath.Join(p.data, "server", ".tn-ca-rotate-20200101T000000")
+		write(t, filepath.Join(stage, "ROTATED"), "")
+		write(t, filepath.Join(stage, "server", "tls", "root-ca.key"), "not a key")
+		out := p.mustSh(tc.script)
+		if _, err := os.Stat(stage); err == nil {
+			t.Errorf("%s: the staging dir was not removed", tc.name)
+		}
+		if !strings.Contains(out, "Removed the leftover staging dir") {
+			t.Errorf("%s: no message:\n%s", tc.name, out)
+		}
+	}
+	// a read-only check leaves it alone
+	stage := filepath.Join(p.data, "server", ".tn-ca-rotate-20200101T000000")
+	write(t, filepath.Join(stage, "ROTATED"), "")
+	p.check()
+	if _, err := os.Stat(stage); err != nil {
+		t.Error("check removed the staging dir")
+	}
+}
+
+func TestBackupsKeepTheNewestThree(t *testing.T) {
+	p := newPKI(t)
+	p.legacyCert()
+	p.legacyPKI(false)
+	for _, ts := range []string{"20200101T000000", "20200102T000000", "20200103T000000", "20200104T000000"} {
+		write(t, filepath.Join(p.data, "server", "tls-backup-tn-"+ts+".tar"), "old")
+	}
+	p.mustSh("tn_ca_remediate prepare")
+	m, _ := filepath.Glob(filepath.Join(p.data, "server", "tls-backup-tn-*.tar"))
+	if len(m) != 3 {
+		t.Fatalf("backups: %v", m)
+	}
+	for _, gone := range []string{"20200101T000000", "20200102T000000"} {
+		if _, err := os.Stat(filepath.Join(p.data, "server", "tls-backup-tn-"+gone+".tar")); err == nil {
+			t.Errorf("%s was kept", gone)
+		}
+	}
+	if _, err := os.Stat(filepath.Join(p.data, "server", "tls-backup-tn-20200104T000000.tar")); err != nil {
+		t.Error("an older one than the newest 3 survived instead")
+	}
+}
+
+func TestProgramModeOptionWithoutValue(t *testing.T) {
+	for _, args := range [][]string{
+		{"remediate", "--phase"},
+		{"check", "--data-dir"},
+		{"check", "--config-dir"},
+		{"remediate", "--phase", ""},
+	} {
+		ctx, cancel := context.WithTimeout(context.Background(), 20*time.Second)
+		cmd := exec.CommandContext(ctx, "sh", append([]string{libPath}, args...)...)
+		out, err := cmd.CombinedOutput()
+		timedOut := ctx.Err() != nil
+		cancel()
+		if timedOut {
+			t.Errorf("%v hangs", args)
+			continue
+		}
+		if exitCode(err) != 2 || !strings.Contains(string(out), "needs a value") || !strings.Contains(string(out), "usage:") {
+			t.Errorf("%v: rc=%d\n%s", args, exitCode(err), out)
+		}
+	}
+}
+
+// ---------------------------------------------------------------- k3s too old for rotate-ca
+
+func fakeK3sVersion(t *testing.T, dir, version string, ok bool) (bin, log string) {
+	t.Helper()
+	log = filepath.Join(dir, "k3s-calls")
+	bin = filepath.Join(dir, "fake-k3s")
+	rc := "0"
+	if !ok {
+		rc = "1"
+	}
+	script := "#!/bin/sh\nif [ \"$1\" = --version ]; then echo 'k3s version " + version + " (0123abcd)'; echo 'go version go1.22.1'; exit 0; fi\necho \"$*\" >> '" + log + "'\nexit " + rc + "\n"
+	if err := os.WriteFile(bin, []byte(script), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	return bin, log
+}
+
+func TestRotateCaSupportedVersions(t *testing.T) {
+	p := newPKI(t)
+	for _, tc := range []struct {
+		v    string
+		want int
+	}{
+		{"v1.23.17+k3s1", 1}, {"v1.24.11+k3s1", 1}, {"v1.24.12+k3s1", 0},
+		{"v1.25.7+k3s1", 1}, {"v1.25.8+k3s1", 0}, {"v1.26.2+k3s1", 1}, {"v1.26.3+k3s1", 0},
+		{"v1.27.0+k3s1", 0}, {"v1.34.11+k3s1", 0}, {"v1.36.5+k3s1", 0}, {"v1.19.5+k3s2", 1},
+	} {
+		bin, _ := fakeK3sVersion(t, t.TempDir(), tc.v, true)
+		_, err := p.sh("tn_ca_rotate_supported", "K3S_BIN="+bin)
+		if exitCode(err) != tc.want {
+			t.Errorf("%s: rc=%d, want %d", tc.v, exitCode(err), tc.want)
+		}
+	}
+	// a version that cannot be told (no k3s binary, odd output) does not block
+	for _, bin := range []string{"/nonexistent/k3s", "echo hello"} {
+		if out, err := p.sh("tn_ca_rotate_supported", "K3S_BIN="+bin); err != nil {
+			t.Errorf("K3S_BIN=%q blocks: %v\n%s", bin, err, out)
+		}
+	}
+	// a K3S_BIN with arguments, like the harness' "docker exec srv k3s", works
+	old, _ := fakeK3sVersion(t, t.TempDir(), "v1.20.1+k3s1", true)
+	if _, err := p.sh("tn_ca_rotate_supported", "K3S_BIN=env FAKE=1 "+old); exitCode(err) != 1 {
+		t.Errorf("K3S_BIN with arguments is not used")
+	}
+}
+
+func TestOldK3sFailsSafeBeforeAnythingIsChanged(t *testing.T) {
+	p := newPKI(t)
+	p.legacyCert()
+	p.legacyPKI(true)
+	before := sum(t, p.tls("server-ca.crt")) + sum(t, p.tls("root-ca.pem"))
+	bin, calls := fakeK3sVersion(t, t.TempDir(), "v1.24.5+k3s1", true)
+	for _, script := range []string{"tn_ca_remediate prepare", "tn_ca_remediate all", "tn_k3s_ca_setup"} {
+		out, err := p.sh(script, "K3S_BIN="+bin, "TN_K3S_RESTART_CMD=touch "+filepath.Join(p.dir, "restarted"))
+		if err == nil {
+			t.Fatalf("%s succeeded on k3s v1.24.5:\n%s", script, out)
+		}
+		for _, want := range []string{"v1.24.5", "v1.24.12", "v1.26.3", "one minor version at a time", "The CA and k3s were not changed"} {
+			if !strings.Contains(out, want) && script != "tn_k3s_ca_setup" {
+				t.Errorf("%s: advice lacks %q:\n%s", script, want, out)
+			}
+		}
+	}
+	if sum(t, p.tls("server-ca.crt"))+sum(t, p.tls("root-ca.pem")) != before {
+		t.Error("server/tls changed")
+	}
+	if m, _ := filepath.Glob(filepath.Join(p.data, "server", ".tn-ca-rotate-*")); len(m) != 0 {
+		t.Errorf("staging left behind: %v", m)
+	}
+	if m, _ := filepath.Glob(filepath.Join(p.data, "server", "tls-backup-tn-*.tar")); len(m) != 0 {
+		t.Errorf("backup made: %v", m)
+	}
+	if _, err := os.Stat(calls); err == nil {
+		t.Error("rotate-ca was called")
+	}
+	if _, err := os.Stat(filepath.Join(p.dir, "restarted")); err == nil {
+		t.Error("k3s was restarted")
+	}
+	// the phase `rotate` refuses too (a staging made by a newer k3s binary, then a downgrade)
+	good, _ := fakeK3sVersion(t, t.TempDir(), "v1.34.11+k3s1", true)
+	p.mustSh("tn_ca_remediate prepare", "K3S_BIN="+good)
+	if out, err := p.sh("tn_ca_remediate rotate", "K3S_BIN="+bin); err == nil || !strings.Contains(out, "v1.24.12") {
+		t.Errorf("rotate on an old k3s: err=%v\n%s", err, out)
+	}
+	// a k3s with rotate-ca goes on
+	p.mustSh("tn_ca_remediate all", "K3S_BIN="+good, "TN_K3S_RESTART_CMD=true")
+}
diff --git a/pkg/templates/k3sca_test.go b/pkg/templates/k3sca_test.go
new file mode 100644
index 0000000..c8f73c0
--- /dev/null
+++ b/pkg/templates/k3sca_test.go
@@ -0,0 +1,855 @@
+package templates
+
+import (
+	"bytes"
+	"crypto"
+	"crypto/sha256"
+	"crypto/x509"
+	"encoding/hex"
+	"encoding/pem"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"regexp"
+	"strconv"
+	"strings"
+	"testing"
+	"time"
+)
+
+// Offline tests of scripts/tn-k3s-ca.sh (setup, check, remediate) with the local openssl and a
+// fake k3s. The docker harness in test/k3s-ca runs the same library against real k3s releases.
+
+const libPath = "scripts/tn-k3s-ca.sh"
+
+func needTool(t *testing.T, name string) {
+	t.Helper()
+	if _, err := exec.LookPath(name); err != nil {
+		t.Skipf("%s not installed", name)
+	}
+}
+
+func TestK3sCALibraryIsPlainShell(t *testing.T) {
+	needTool(t, "sh")
+	b, err := os.ReadFile(libPath)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if bytes.Contains(b, []byte("{{")) {
+		t.Fatal("the library is embedded as a template: it must not contain '{{'")
+	}
+	if out, err := exec.Command("sh", "-n", libPath).CombinedOutput(); err != nil {
+		t.Fatalf("sh -n: %v\n%s", err, out)
+	}
+	if string(b) != TnK3sCAScript {
+		t.Error("embedded TnK3sCAScript differs from the file")
+	}
+	// the dangers of a file that is pasted into a bootstrap script
+	s := string(b)
+	for _, bad := range []string{"\ntrap ", "\n  trap ", "set +o noglob", "set -x"} {
+		if strings.Contains(s, bad) {
+			t.Errorf("library must not contain %q (it would change the caller's traps/options)", bad)
+		}
+	}
+}
+
+func TestServerTemplateUsesTheLibrary(t *testing.T) {
+	var buf bytes.Buffer
+	if err := ServerTemplate.Execute(&buf, TemplateData{Domain: "test.cloud", DeviceID: "dev-1", K3SToken: "tok"}); err != nil {
+		t.Fatal(err)
+	}
+	out := buf.String()
+	for _, want := range []string{"tn_k3s_ca_setup()", "TN_K3S_CA_NO_MAIN=1", "\ntn_k3s_ca_setup\n", "tn_ca_reissue_root()"} {
+		if !strings.Contains(out, want) {
+			t.Errorf("server script lacks %q", want)
+		}
+	}
+	// the defining bug: the device certificate must not be copied verbatim to root-ca.pem
+	re := regexp.MustCompile(`cp\s+\S*rsa_public\.pem\s+\S*root-ca\.pem`)
+	if re.MatchString(out) {
+		t.Error("server script still copies rsa_public.pem to root-ca.pem")
+	}
+	if strings.Index(out, "tn_k3s_ca_setup\n") > strings.Index(out, "k3s_installer.sh") {
+		t.Error("the CA must be set up before the k3s installer runs")
+	}
+	// the agent and docker variants do not create a CA
+	for name, tpl := range map[string]string{"agent": AgentTemplateStr, "docker": DockerServerTemplateStr} {
+		if strings.Contains(tpl, "tn-k3s-ca.sh") {
+			t.Errorf("%s template unexpectedly embeds the CA library", name)
+		}
+	}
+	if _, err := exec.LookPath("sh"); err == nil {
+		f := filepath.Join(t.TempDir(), "server.sh")
+		if err := os.WriteFile(f, buf.Bytes(), 0o600); err != nil {
+			t.Fatal(err)
+		}
+		if o, err := exec.Command("sh", "-n", f).CombinedOutput(); err != nil {
+			t.Errorf("rendered server script: sh -n: %v\n%s", err, o)
+		}
+	}
+}
+
+// ---------------------------------------------------------------- the PKI
+
+type pki struct {
+	t    *testing.T
+	dir  string // work dir
+	cfg  string // CONFIG_PATH
+	data string // DATA_DIR
+	// k3sCfg is the TN_K3S_CONFIG_DIR (/etc/rancher/k3s), unit the TN_K3S_UNIT_FILE (k3s.service);
+	// neither exists until a test writes it
+	k3sCfg string
+	unit   string
+}
+
+func newPKI(t *testing.T) *pki {
+	t.Helper()
+	needTool(t, "sh")
+	needTool(t, "openssl")
+	// every test runs with a failing `info` binary first in PATH, like a Debian/Ubuntu machine
+	// with the GNU info reader: nothing may call it
+	fake := t.TempDir()
+	if err := os.WriteFile(filepath.Join(fake, "info"), []byte("#!/bin/sh\necho GNU-INFO-WAS-CALLED \"$*\" >&2\nexit 1\n"), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	t.Setenv("PATH", fake+":"+os.Getenv("PATH"))
+	p := &pki{t: t, dir: t.TempDir()}
+	p.cfg = filepath.Join(p.dir, "etc")
+	p.data = filepath.Join(p.dir, "data")
+	// never read the real /etc/rancher/k3s or the systemd units of the machine running the tests
+	p.k3sCfg = filepath.Join(p.dir, "rancher-k3s")
+	p.unit = filepath.Join(p.dir, "k3s.service")
+	t.Setenv("TN_K3S_CONFIG_DIR", p.k3sCfg)
+	t.Setenv("TN_K3S_UNIT_FILE", p.unit)
+	for _, d := range []string{p.cfg, p.data} {
+		if err := os.MkdirAll(d, 0o755); err != nil {
+			t.Fatal(err)
+		}
+	}
+	return p
+}
+
+// legacyCert writes the pair Backstage generates (openssl req -x509, no keyUsage).
+func (p *pki) legacyCert() { p.legacyCertArgs() }
+
+// legacyCertArgs adds openssl req arguments, e.g. -addext keyUsage=... for the device-controller kind.
+func (p *pki) legacyCertArgs(extra ...string) {
+	p.t.Helper()
+	args := []string{"req", "-x509", "-nodes", "-newkey", "rsa:2048",
+		"-keyout", filepath.Join(p.cfg, "rsa_private.pem"), "-out", filepath.Join(p.cfg, "rsa_public.pem"),
+		"-days", "365", "-subj", "/C=US/ST=Texas/L=SHouston/O=Teknoir LLC/CN=teknoir.ai", "-sha256", "-batch"}
+	cmd := exec.Command("openssl", append(args, extra...)...)
+	if out, err := cmd.CombinedOutput(); err != nil {
+		p.t.Fatalf("openssl req: %v\n%s", err, out)
+	}
+}
+
+// sh runs script with the bootstrap script shell options and the library sourced.
+func (p *pki) sh(script string, env ...string) (string, error) {
+	p.t.Helper()
+	full := "set -e; set -o noglob; umask 027; " +
+		"info() { echo '[INFO] ' \"$@\"; }; warn() { echo '[WARN] ' \"$@\" >&2; }; fatal() { echo '[ERROR] ' \"$@\" >&2; exit 1; }; " +
+		". " + libPath + "; " + script
+	cmd := exec.Command("sh", "-c", full)
+	cmd.Env = append(os.Environ(), "CONFIG_PATH="+p.cfg, "DATA_DIR="+p.data, "PRODUCT=k3s", "_DEVICE_ID=dev1", "_DOMAIN=test.local")
+	cmd.Env = append(cmd.Env, env...)
+	out, err := cmd.CombinedOutput()
+	if bytes.Contains(out, []byte("PRIVATE KEY")) {
+		p.t.Errorf("a private key was printed:\n%s", out)
+	}
+	if bytes.Contains(out, []byte("GNU-INFO-WAS-CALLED")) {
+		p.t.Errorf("the info binary was called:\n%s", out)
+	}
+	return string(out), err
+}
+
+func (p *pki) mustSh(script string, env ...string) string {
+	p.t.Helper()
+	out, err := p.sh(script, env...)
+	if err != nil {
+		p.t.Fatalf("%s: %v\n%s", script, err, out)
+	}
+	return out
+}
+
+// check runs `check` and returns its exit code
+func (p *pki) check() (int, string) {
+	p.t.Helper()
+	out, err := p.sh("tn_ca_check")
+	if err == nil {
+		return 0, out
+	}
+	if ee, ok := err.(*exec.ExitError); ok {
+		return ee.ExitCode(), out
+	}
+	p.t.Fatal(err)
+	return -1, ""
+}
+
+func (p *pki) tls(name string) string { return filepath.Join(p.data, "server", "tls", name) }
+
+func readCerts(t *testing.T, path string) []*x509.Certificate {
+	t.Helper()
+	b, err := os.ReadFile(path)
+	if err != nil {
+		t.Fatal(err)
+	}
+	var certs []*x509.Certificate
+	for {
+		var blk *pem.Block
+		blk, b = pem.Decode(b)
+		if blk == nil {
+			break
+		}
+		c, err := x509.ParseCertificate(blk.Bytes)
+		if err != nil {
+			t.Fatalf("%s: %v", path, err)
+		}
+		certs = append(certs, c)
+	}
+	if len(certs) == 0 {
+		t.Fatalf("%s: no certificates", path)
+	}
+	return certs
+}
+
+func sum(t *testing.T, path string) string {
+	t.Helper()
+	b, err := os.ReadFile(path)
+	if err != nil {
+		t.Fatal(err)
+	}
+	h := sha256.Sum256(b)
+	return hex.EncodeToString(h[:])
+}
+
+// k3sPool builds the trust pool like k3s >= v1.36.5: certificates without keyCertSign are
+// dropped from a multi-certificate bundle, roots are the self-issued ones.
+func k3sPool(certs []*x509.Certificate) *x509.CertPool {
+	pool := x509.NewCertPool()
+	for _, c := range certs {
+		if c.KeyUsage&x509.KeyUsageCertSign != 0 && (len(c.AuthorityKeyId) == 0 || bytes.Equal(c.AuthorityKeyId, c.SubjectKeyId)) {
+			pool.AddCert(c)
+		}
+	}
+	return pool
+}
+
+func (p *pki) assertGoodPKI(orig []byte) {
+	t := p.t
+	t.Helper()
+	oc := readCerts(t, filepath.Join(p.cfg, "rsa_public.pem"))[0]
+	root := readCerts(t, p.tls("root-ca.pem"))[0]
+	if !root.IsCA || root.KeyUsage&x509.KeyUsageCertSign == 0 || root.KeyUsage&x509.KeyUsageCRLSign == 0 {
+		t.Errorf("root: IsCA=%v KeyUsage=%b", root.IsCA, root.KeyUsage)
+	}
+	if len(root.ExtKeyUsage) != 0 {
+		t.Error("root has extendedKeyUsage")
+	}
+	if !bytes.Equal(root.RawSubject, oc.RawSubject) || !bytes.Equal(root.RawIssuer, root.RawSubject) {
+		t.Error("root subject differs from the device certificate, or is not self-issued")
+	}
+	if len(oc.SubjectKeyId) > 0 && !bytes.Equal(root.SubjectKeyId, oc.SubjectKeyId) {
+		t.Error("root SKI differs from the device certificate")
+	}
+	if len(root.AuthorityKeyId) > 0 && !bytes.Equal(root.AuthorityKeyId, root.SubjectKeyId) {
+		t.Error("root AKI != SKI: k3s would treat it as an intermediate")
+	}
+	if !root.PublicKey.(interface{ Equal(crypto.PublicKey) bool }).Equal(oc.PublicKey) {
+		t.Error("root public key differs from the device certificate")
+	}
+	if d := time.Until(root.NotAfter); d < 7000*24*time.Hour || d > 7400*24*time.Hour {
+		t.Errorf("root valid for %v, want about 7300 days", d)
+	}
+	seen := map[string]bool{}
+	for _, e := range root.Extensions {
+		if seen[e.Id.String()] {
+			t.Errorf("duplicate extension %s", e.Id)
+		}
+		seen[e.Id.String()] = true
+	}
+	for _, b := range []string{"server-ca.crt", "client-ca.crt", "request-header-ca.crt", "etcd/peer-ca.crt", "etcd/server-ca.crt", "intermediate-ca.crt"} {
+		certs := readCerts(t, p.tls(b))
+		for i, c := range certs {
+			if c.KeyUsage&x509.KeyUsageCertSign == 0 {
+				t.Errorf("%s cert %d (%s) has no keyCertSign: k3s would prune it", b, i, c.Subject.CommonName)
+			}
+		}
+		inter := x509.NewCertPool()
+		for _, c := range certs[1 : len(certs)-1] {
+			inter.AddCert(c)
+		}
+		if _, err := certs[0].Verify(x509.VerifyOptions{Roots: k3sPool(certs), Intermediates: inter, KeyUsages: []x509.ExtKeyUsage{x509.ExtKeyUsageAny}}); err != nil {
+			t.Errorf("%s: %v", b, err)
+		}
+		if last := certs[len(certs)-1]; !bytes.Equal(last.Raw, root.Raw) && b != "root-ca.crt" {
+			t.Errorf("%s does not end in the root", b)
+		}
+	}
+	if got := sum(t, filepath.Join(p.cfg, "rsa_public.pem")); got != hashOf(orig) {
+		t.Error("rsa_public.pem was modified")
+	}
+}
+
+func hashOf(b []byte) string { h := sha256.Sum256(b); return hex.EncodeToString(h[:]) }
+
+func TestSetupCreatesAProperRoot(t *testing.T) {
+	p := newPKI(t)
+	p.legacyCert()
+	orig, _ := os.ReadFile(filepath.Join(p.cfg, "rsa_public.pem"))
+	out := p.mustSh("tn_k3s_ca_setup")
+	if !strings.Contains(out, "keyCertSign") {
+		t.Errorf("no message about the re-issued root:\n%s", out)
+	}
+	p.assertGoodPKI(orig)
+	if rc, o := p.check(); rc != 0 {
+		t.Errorf("check rc=%d: %s", rc, o)
+	}
+
+	// a second run while k3s never started keeps the PKI
+	before := sum(t, p.tls("server-ca.crt"))
+	p.mustSh("tn_k3s_ca_setup")
+	if sum(t, p.tls("server-ca.crt")) != before {
+		t.Error("second setup regenerated a valid PKI")
+	}
+
+	// a run on an initialised data dir never touches it
+	if err := os.WriteFile(filepath.Join(p.data, "server", "token"), []byte("K10x::server:y"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	p.mustSh("tn_k3s_ca_setup")
+	if sum(t, p.tls("server-ca.crt")) != before {
+		t.Error("setup changed the PKI of an initialised data dir")
+	}
+}
+
+func TestSetupLongDeviceName(t *testing.T) {
+	p := newPKI(t)
+	p.legacyCert()
+	p.mustSh("tn_k3s_ca_setup", "_DEVICE_ID=a-device-with-a-really-long-name-for-an-edge-computer", "_DOMAIN=customer-teamspace.teknoir.cloud")
+	for _, c := range readCerts(t, p.tls("request-header-ca.crt"))[:1] {
+		if n := len(c.Subject.CommonName); n == 0 || n > 64 {
+			t.Errorf("CN %q has %d characters", c.Subject.CommonName, n)
+		}
+	}
+}
+
+// the old, broken layout: the device certificate itself as the root
+func (p *pki) legacyPKI(initialised bool) {
+	p.t.Helper()
+	legacy, err := filepath.Abs("../../test/k3s-ca/legacy-ca.sh")
+	if err != nil {
+		p.t.Fatal(err)
+	}
+	tls := filepath.Join(p.data, "server", "tls")
+	if err := os.MkdirAll(tls, 0o750); err != nil {
+		p.t.Fatal(err)
+	}
+	cmd := exec.Command("sh", "-c", "set -e; set -o noglob; umask 027; . "+legacy+"; tn_legacy_ca "+tls+" "+p.cfg+"/rsa_public.pem "+p.cfg+"/rsa_private.pem dev1.test.local")
+	cmd.Env = append(os.Environ(), "PRODUCT=k3s")
+	if out, err := cmd.CombinedOutput(); err != nil {
+		p.t.Fatalf("legacy PKI: %v\n%s", err, out)
+	}
+	if initialised {
+		if err := os.WriteFile(filepath.Join(p.data, "server", "token"), []byte("K10x::server:y"), 0o600); err != nil {
+			p.t.Fatal(err)
+		}
+	}
+}
+
+func fakeK3s(t *testing.T, dir string, ok bool) (bin, log string) {
+	t.Helper()
+	log = filepath.Join(dir, "k3s-calls")
+	bin = filepath.Join(dir, "fake-k3s")
+	rc := "0"
+	if !ok {
+		rc = "1"
+	}
+	script := "#!/bin/sh\necho \"SSL_CERT_FILE=$SSL_CERT_FILE $*\" >> '" + log + "'\nexit " + rc + "\n"
+	if err := os.WriteFile(bin, []byte(script), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	return bin, log
+}
+
+func TestRemediateInitialisedLegacyDevice(t *testing.T) {
+	p := newPKI(t)
+	p.legacyCert()
+	orig, _ := os.ReadFile(filepath.Join(p.cfg, "rsa_public.pem"))
+	p.legacyPKI(true)
+	if rc, o := p.check(); rc != 2 || !strings.Contains(o, "needs-rotation") {
+		t.Fatalf("check on a legacy initialised device: rc=%d %s", rc, o)
+	}
+	oldRoot := sum(t, p.tls("root-ca.pem"))
+	if oldRoot != hashOf(orig) {
+		t.Fatal("legacy fixture does not copy the device certificate")
+	}
+
+	// prepare stages the rotation and changes nothing on disk
+	before := sum(t, p.tls("server-ca.crt"))
+	p.mustSh("tn_ca_openssl; tn_ca_remediate prepare")
+	if sum(t, p.tls("server-ca.crt")) != before || sum(t, p.tls("root-ca.pem")) != oldRoot {
+		t.Error("prepare modified server/tls")
+	}
+	stages, _ := filepath.Glob(filepath.Join(p.data, "server", ".tn-ca-rotate-*"))
+	if len(stages) != 1 {
+		t.Fatalf("staging dirs: %v", stages)
+	}
+	rotate, err := os.ReadFile(filepath.Join(stages[0], "ROTATE_CMD"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !strings.Contains(string(rotate), "certificate rotate-ca") || strings.Contains(string(rotate), "--force") || strings.Contains(string(rotate), "PRIVATE") {
+		t.Errorf("ROTATE_CMD: %s", rotate)
+	}
+	if fi, _ := os.Stat(stages[0]); fi.Mode().Perm() != 0o700 {
+		t.Errorf("staging dir mode %v", fi.Mode().Perm())
+	}
+	if _, err := filepath.Glob(filepath.Join(p.data, "server", "tls-backup-tn-*.tar")); err != nil {
+		t.Fatal(err)
+	}
+	if m, _ := filepath.Glob(filepath.Join(p.data, "server", "tls-backup-tn-*.tar")); len(m) != 1 {
+		t.Errorf("backups: %v", m)
+	}
+
+	// finalize before the rotation happened must refuse
+	if out, err := p.sh("tn_ca_openssl; tn_ca_remediate finalize"); err == nil {
+		t.Errorf("finalize without a completed rotation succeeded:\n%s", out)
+	}
+	if sum(t, p.tls("root-ca.pem")) != oldRoot {
+		t.Error("finalize without ROTATED changed the root")
+	}
+
+	// a failing rotate-ca leaves everything as it was and says what to do
+	badBin, _ := fakeK3s(t, t.TempDir(), false)
+	if out, err := p.sh("tn_ca_openssl; tn_ca_remediate rotate", "K3S_BIN="+badBin); err == nil || !strings.Contains(out, "v1.36.4") {
+		t.Errorf("failed rotate: err=%v\n%s", err, out)
+	}
+	if sum(t, p.tls("root-ca.pem")) != oldRoot {
+		t.Error("failed rotate changed the root")
+	}
+
+	// the full run with a fake k3s that "succeeds"
+	bin, calls := fakeK3s(t, t.TempDir(), true)
+	restarted := filepath.Join(p.dir, "restarted")
+	p.mustSh("tn_ca_remediate all", "K3S_BIN="+bin, "TN_K3S_RESTART_CMD=touch "+restarted)
+	if _, err := os.Stat(restarted); err != nil {
+		t.Error("k3s was not restarted")
+	}
+	c, _ := os.ReadFile(calls)
+	if !strings.Contains(string(c), "certificate rotate-ca --data-dir "+p.data+" --path ") || !strings.Contains(string(c), "SSL_CERT_FILE=") {
+		t.Errorf("k3s was called with: %s", c)
+	}
+	p.assertGoodPKI(orig)
+	if rc, o := p.check(); rc != 0 {
+		t.Errorf("check after remediate rc=%d %s", rc, o)
+	}
+	if m, _ := filepath.Glob(filepath.Join(p.data, "server", ".tn-ca-rotate-*")); len(m) != 0 {
+		t.Errorf("staging left behind: %v", m)
+	}
+
+	// idempotent: a second remediate and a setup change nothing
+	after := sum(t, p.tls("server-ca.crt")) + sum(t, p.tls("root-ca.pem")) + sum(t, p.tls("intermediate-ca.crt"))
+	p.mustSh("tn_ca_remediate all", "K3S_BIN="+bin, "TN_K3S_RESTART_CMD=false")
+	p.mustSh("tn_k3s_ca_setup", "K3S_BIN="+bin)
+	if got := sum(t, p.tls("server-ca.crt")) + sum(t, p.tls("root-ca.pem")) + sum(t, p.tls("intermediate-ca.crt")); got != after {
+		t.Error("a second remediate/setup changed the PKI")
+	}
+}
+
+// A root with a keyUsage that lacks keyCertSign (the device-controller kind) cannot vouch for the
+// chain in k3s's own check of the new CA bundle, so rotate-ca needs --force there. Only there.
+func TestRotateCmdForcesOnlyWhenTheOldRootCannotVouch(t *testing.T) {
+	p := newPKI(t)
+	p.legacyCertArgs("-addext", "keyUsage=digitalSignature,keyEncipherment")
+	p.legacyPKI(true)
+	out := p.mustSh("tn_ca_openssl; tn_ca_remediate prepare")
+	if !strings.Contains(out, "--force") {
+		t.Errorf("no word about --force:\n%s", out)
+	}
+	stages, _ := filepath.Glob(filepath.Join(p.data, "server", ".tn-ca-rotate-*"))
+	if len(stages) != 1 {
+		t.Fatalf("staging dirs: %v", stages)
+	}
+	rotate, _ := os.ReadFile(filepath.Join(stages[0], "ROTATE_CMD"))
+	if !strings.Contains(string(rotate), "--path '"+stages[0]+"/server' --force && touch") {
+		t.Errorf("ROTATE_CMD: %s", rotate)
+	}
+
+	// no keyUsage at all (Backstage kind): k3s can verify, no --force
+	q := newPKI(t)
+	q.legacyCert()
+	q.legacyPKI(true)
+	q.mustSh("tn_ca_openssl; tn_ca_remediate prepare")
+	stages, _ = filepath.Glob(filepath.Join(q.data, "server", ".tn-ca-rotate-*"))
+	rotate, _ = os.ReadFile(filepath.Join(stages[0], "ROTATE_CMD"))
+	if strings.Contains(string(rotate), "--force") {
+		t.Errorf("unexpected --force: %s", rotate)
+	}
+}
+
+func TestSetupRepairsAnInitialisedLegacyDevice(t *testing.T) {
+	p := newPKI(t)
+	p.legacyCert()
+	orig, _ := os.ReadFile(filepath.Join(p.cfg, "rsa_public.pem"))
+	p.legacyPKI(true)
+	bin, calls := fakeK3s(t, t.TempDir(), true)
+
+	// opt out: stops before anything is touched
+	before := sum(t, p.tls("root-ca.pem"))
+	if out, err := p.sh("tn_k3s_ca_setup", "TN_K3S_CA_AUTO_REMEDIATE=false", "K3S_BIN="+bin); err == nil || !strings.Contains(out, "remediate") {
+		t.Errorf("auto-remediate=false: err=%v\n%s", err, out)
+	}
+	if sum(t, p.tls("root-ca.pem")) != before {
+		t.Error("changed despite TN_K3S_CA_AUTO_REMEDIATE=false")
+	}
+
+	// default: repaired before the installer would run
+	p.mustSh("tn_k3s_ca_setup", "K3S_BIN="+bin, "TN_K3S_RESTART_CMD=true")
+	if c, _ := os.ReadFile(calls); !strings.Contains(string(c), "rotate-ca") {
+		t.Errorf("setup did not rotate: %s", c)
+	}
+	p.assertGoodPKI(orig)
+
+	// a failing rotation stops the bootstrap (no installer run that would brick the device)
+	p2 := newPKI(t)
+	p2.legacyCert()
+	p2.legacyPKI(true)
+	badBin, _ := fakeK3s(t, t.TempDir(), false)
+	if _, err := p2.sh("tn_k3s_ca_setup", "K3S_BIN="+badBin, "TN_K3S_RESTART_CMD=true"); err == nil {
+		t.Error("setup continued after a failed rotation")
+	}
+}
+
+func TestRemediateHungFreshBootstrap(t *testing.T) {
+	p := newPKI(t)
+	p.legacyCert()
+	orig, _ := os.ReadFile(filepath.Join(p.cfg, "rsa_public.pem"))
+	p.legacyPKI(false) // old script ran, post-fix k3s never finished its start: no server/token
+	if rc, o := p.check(); rc != 3 || !strings.Contains(o, "needs-regeneration") {
+		t.Fatalf("check: rc=%d %s", rc, o)
+	}
+	// no k3s is needed: there is nothing to rotate
+	out := p.mustSh("tn_ca_remediate prepare", "K3S_BIN=/nonexistent/k3s")
+	if !strings.Contains(out, "Nothing to rotate") {
+		t.Errorf("message:\n%s", out)
+	}
+	if m, _ := filepath.Glob(filepath.Join(p.data, "server", ".tn-ca-rotate-*")); len(m) != 0 {
+		t.Errorf("unexpected staging %v", m)
+	}
+	p.assertGoodPKI(orig)
+	if rc, o := p.check(); rc != 0 {
+		t.Errorf("check after: rc=%d %s", rc, o)
+	}
+	if m, _ := filepath.Glob(filepath.Join(p.data, "server", "tls-backup-tn-*.tar")); len(m) != 1 {
+		t.Errorf("the old tls dir was not backed up: %v", m)
+	}
+	// `remediate` (all phases) on such a device regenerates and restarts, without calling k3s
+	p3 := newPKI(t)
+	p3.legacyCert()
+	orig3, _ := os.ReadFile(filepath.Join(p3.cfg, "rsa_public.pem"))
+	p3.legacyPKI(false)
+	bin, calls := fakeK3s(t, t.TempDir(), true)
+	restarted := filepath.Join(p3.dir, "restarted")
+	p3.mustSh("tn_ca_remediate all", "K3S_BIN="+bin, "TN_K3S_RESTART_CMD=touch "+restarted)
+	if _, err := os.Stat(restarted); err != nil {
+		t.Error("k3s was not restarted")
+	}
+	if _, err := os.Stat(calls); err == nil {
+		t.Error("k3s was called although there is nothing to rotate")
+	}
+	p3.assertGoodPKI(orig3)
+	// re-running the bootstrap script on such a device is the other way to the same result
+	p2 := newPKI(t)
+	p2.legacyCert()
+	orig2, _ := os.ReadFile(filepath.Join(p2.cfg, "rsa_public.pem"))
+	p2.legacyPKI(false)
+	p2.mustSh("tn_k3s_ca_setup")
+	p2.assertGoodPKI(orig2)
+}
+
+func TestCheckStates(t *testing.T) {
+	p := newPKI(t)
+	p.legacyCert()
+	// an agent / fresh machine: nothing to check
+	if rc, o := p.check(); rc != 0 || !strings.Contains(o, "not-a-server") {
+		t.Errorf("no tls dir: rc=%d %s", rc, o)
+	}
+	// a legacy PKI whose key we do not hold (device files of another device)
+	p.legacyPKI(true)
+	if err := os.Remove(p.tls("root-ca.key")); err != nil {
+		t.Fatal(err)
+	}
+	other := newPKI(t)
+	other.legacyCert()
+	p.cfg = other.cfg
+	if rc, o := p.check(); rc != 4 || !strings.Contains(o, "foreign") {
+		t.Errorf("foreign CA: rc=%d %s", rc, o)
+	}
+	if out, err := p.sh("tn_ca_openssl; tn_ca_remediate prepare"); err == nil {
+		t.Errorf("prepare on a foreign CA succeeded:\n%s", out)
+	}
+}
+
+// On Debian and Ubuntu `info` is the GNU info reader. The library must not depend on a caller's
+// info/warn/fatal, which a stand-alone run does not have.
+func TestStandAloneDoesNotCallTheInfoBinary(t *testing.T) {
+	p := newPKI(t)
+	p.legacyCert()
+	p.legacyPKI(true)
+	bin := t.TempDir()
+	if err := os.WriteFile(filepath.Join(bin, "info"), []byte("#!/bin/sh\necho GNU-INFO-WAS-CALLED \"$*\"\nexit 1\n"), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	cmd := exec.Command("sh", libPath, "check", "--data-dir", p.data, "--config-dir", p.cfg)
+	cmd.Env = append(os.Environ(), "PATH="+bin+":"+os.Getenv("PATH"))
+	out, _ := cmd.CombinedOutput()
+	if strings.Contains(string(out), "GNU-INFO-WAS-CALLED") || !strings.Contains(string(out), "needs-rotation") {
+		t.Errorf("check output: %s", out)
+	}
+	// and the setup path that logs with [INFO] lines
+	q := newPKI(t)
+	q.legacyCert()
+	cmd = exec.Command("sh", "-c", "set -e; set -o noglob; umask 027; . "+libPath+"; tn_k3s_ca_setup")
+	cmd.Env = append(os.Environ(), "PATH="+bin+":"+os.Getenv("PATH"), "CONFIG_PATH="+q.cfg, "DATA_DIR="+q.data, "_DEVICE_ID=dev1", "_DOMAIN=test.local")
+	out, err := cmd.CombinedOutput()
+	if err != nil || strings.Contains(string(out), "GNU-INFO-WAS-CALLED") || !strings.Contains(string(out), "[INFO]") {
+		t.Errorf("setup without info/warn/fatal in the caller: %v\n%s", err, out)
+	}
+}
+
+func TestProgramMode(t *testing.T) {
+	p := newPKI(t)
+	p.legacyCert()
+	p.legacyPKI(true)
+	cmd := exec.Command("sh", libPath, "check", "--data-dir", p.data, "--config-dir", p.cfg)
+	out, err := cmd.CombinedOutput()
+	ee, ok := err.(*exec.ExitError)
+	if !ok || ee.ExitCode() != 2 || !strings.Contains(string(out), "needs-rotation") {
+		t.Errorf("sh tn-k3s-ca.sh check: %v\n%s", err, out)
+	}
+	// sourcing with the caller's own arguments must not start the program
+	cmd = exec.Command("sh", "-c", ". "+libPath+"; echo sourced")
+	if out, err := cmd.CombinedOutput(); err != nil || strings.TrimSpace(string(out)) != "sourced" {
+		t.Errorf("sourcing printed: %v %q", err, out)
+	}
+}
+
+// ---------------------------------------------------------------- re-review fixes
+
+// failingOpenssl puts a wrapper first in PATH that runs the real openssl, except that the
+// failN-th call of subcommand sub (counting from 1; the library's own capability probe
+// `ecparam ... -out /dev/null` is not counted) exits 1 without doing anything.
+func failingOpenssl(t *testing.T, sub string, failN int) {
+	t.Helper()
+	real, err := exec.LookPath("openssl")
+	if err != nil {
+		t.Skip("openssl not installed")
+	}
+	dir := t.TempDir()
+	script := `#!/bin/sh
+case "$*" in *" -out /dev/null"*) exec ` + real + ` "$@" ;; esac
+if [ "$1" = "` + sub + `" ]; then
+  n=$(cat "` + dir + `/n" 2>/dev/null || echo 0); n=$((n + 1)); echo "$n" > "` + dir + `/n"
+  if [ "$n" -ge ` + strconv.Itoa(failN) + ` ]; then echo "wrapper: failing openssl $1 (call $n)" >&2; exit 1; fi
+fi
+exec ` + real + ` "$@"
+`
+	if err := os.WriteFile(filepath.Join(dir, "openssl"), []byte(script), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	t.Setenv("PATH", dir+":"+os.Getenv("PATH"))
+}
+
+// A failing openssl step must fail the setup (the first bug: the status of the PKI subshell came
+// from its last command, `rm -rf .ca`, because errexit is ignored in an `if`/`||` context), and
+// must not leave a half PKI behind or change an existing one.
+func TestSetupFailsWhenAnOpensslStepFails(t *testing.T) {
+	for _, tc := range []struct {
+		sub string
+		n   int
+	}{{"genrsa", 1}, {"genrsa", 2}, {"req", 1}, {"req", 3}, {"ca", 1}, {"ca", 2}, {"ca", 6}, {"ecparam", 1}, {"ecparam", 5}} {
+		t.Run(tc.sub+"-"+strconv.Itoa(tc.n), func(t *testing.T) {
+			p := newPKI(t)
+			p.legacyCert()
+			failingOpenssl(t, tc.sub, tc.n)
+			out, err := p.sh("tn_k3s_ca_setup")
+			if err == nil {
+				t.Fatalf("setup succeeded although openssl %s failed:\n%s", tc.sub, out)
+			}
+			if !strings.Contains(out, "Cannot generate the k3s CA") && !strings.Contains(out, "PKI generation failed") {
+				t.Errorf("no error message:\n%s", out)
+			}
+			if _, err := os.Stat(p.tls("server-ca.crt")); err == nil {
+				t.Error("a (partial) server/tls was installed")
+			}
+			if m, _ := filepath.Glob(filepath.Join(p.data, "server", ".tn-tls-new.*")); len(m) != 0 {
+				t.Errorf("work dir left behind: %v", m)
+			}
+		})
+	}
+}
+
+// the same failure while replacing the PKI of a hung fresh bootstrap: the old tls dir stays
+func TestRemediateKeepsTheOldPKIWhenGenerationFails(t *testing.T) {
+	p := newPKI(t)
+	p.legacyCert()
+	p.legacyPKI(false)
+	before := sum(t, p.tls("server-ca.crt"))
+	failingOpenssl(t, "ca", 2)
+	if out, err := p.sh("tn_ca_remediate prepare"); err == nil {
+		t.Fatalf("prepare succeeded although openssl ca failed:\n%s", out)
+	}
+	if sum(t, p.tls("server-ca.crt")) != before {
+		t.Error("server/tls was replaced")
+	}
+	if m, _ := filepath.Glob(filepath.Join(p.data, "server", "tls-backup-tn-*.tar")); len(m) != 0 {
+		t.Errorf("backup made although nothing was replaced: %v", m)
+	}
+}
+
+// tn_ca_validate_pki is the second line of defence: it catches what the generator missed
+func TestValidatePKI(t *testing.T) {
+	p := newPKI(t)
+	p.legacyCert()
+	p.mustSh("tn_k3s_ca_setup")
+	p.mustSh("tn_ca_openssl; tn_ca_validate_pki " + filepath.Join(p.data, "server", "tls"))
+	for _, tc := range []struct{ name, cmd string }{
+		{"missing leaf", "rm etcd/peer-ca.pem"},
+		{"empty bundle", ": > server-ca.crt"},
+		{"root only bundle", "cat root-ca.pem > client-ca.crt"},
+		{"foreign key", "cp intermediate-ca.key server-ca.key"},
+		{"foreign leaf", "cp client-ca.pem server-ca.pem"},
+	} {
+		d := t.TempDir()
+		if out, err := exec.Command("cp", "-a", filepath.Join(p.data, "server", "tls")+"/.", d).CombinedOutput(); err != nil {
+			t.Fatalf("%v %s", err, out)
+		}
+		if out, err := exec.Command("sh", "-c", "cd "+d+" && "+tc.cmd).CombinedOutput(); err != nil {
+			t.Fatalf("%s: %v %s", tc.name, err, out)
+		}
+		if out, err := p.sh("tn_ca_openssl; tn_ca_validate_pki " + d); err == nil {
+			t.Errorf("%s: validation passed:\n%s", tc.name, out)
+		}
+	}
+}
+
+// ---- foreign CAs on an initialised data dir
+
+// foreignPKI: initialised legacy PKI whose root key is gone and whose device key is another one
+func (p *pki) foreignPKI() {
+	p.t.Helper()
+	p.legacyPKI(true)
+	if err := os.Remove(p.tls("root-ca.key")); err != nil {
+		p.t.Fatal(err)
+	}
+	other := newPKI(p.t)
+	other.legacyCert()
+	p.cfg = other.cfg
+}
+
+// A root that k3s refuses and that we cannot repair must stop the bootstrap: the installer
+// that runs next would upgrade k3s and brick the device.
+func TestSetupStopsOnAnUnusableForeignRoot(t *testing.T) {
+	p := newPKI(t)
+	p.legacyCert() // no keyCertSign
+	p.foreignPKI()
+	before := sum(t, p.tls("server-ca.crt"))
+	if rc, o := p.check(); rc != 4 {
+		t.Fatalf("check rc=%d %s", rc, o)
+	}
+	out, err := p.sh("tn_k3s_ca_setup")
+	if err == nil {
+		t.Fatalf("setup returned 0 on a foreign unusable root:\n%s", out)
+	}
+	for _, want := range []string{"not the Teknoir device CA", "must not be upgraded"} {
+		if !strings.Contains(out, want) {
+			t.Errorf("message lacks %q:\n%s", want, out)
+		}
+	}
+	if sum(t, p.tls("server-ca.crt")) != before {
+		t.Error("the foreign CA was changed")
+	}
+	// the whole rendered server script stops before the installer
+	var buf bytes.Buffer
+	if err := ServerTemplate.Execute(&buf, TemplateData{Domain: "test.cloud", DeviceID: "dev-1", K3SToken: "tok"}); err != nil {
+		t.Fatal(err)
+	}
+	if !strings.Contains(buf.String(), "\ntn_k3s_ca_setup\n") {
+		t.Error("the template does not call tn_k3s_ca_setup as a plain command (set -e must stop on its exit)")
+	}
+}
+
+func TestSetupStopsOnAnExpiredForeignRoot(t *testing.T) {
+	p := newPKI(t)
+	p.legacyCertArgs("-addext", "basicConstraints=critical,CA:TRUE", "-addext", "keyUsage=critical,keyCertSign", "-not_before", "20240301000000Z", "-not_after", "20250301000000Z")
+	p.foreignPKI()
+	if rc, o := p.check(); rc != 4 {
+		t.Fatalf("check rc=%d %s", rc, o)
+	}
+	out, err := p.sh("tn_k3s_ca_setup")
+	if err == nil || !strings.Contains(out, "must not be upgraded") {
+		t.Errorf("setup on an expired foreign root: %v\n%s", err, out)
+	}
+}
+
+// only "expires soon", with keyCertSign: k3s accepts it today, so the bootstrap goes on
+func TestSetupContinuesOnAForeignRootThatOnlyExpiresSoon(t *testing.T) {
+	p := newPKI(t)
+	p.legacyCertArgs("-addext", "basicConstraints=critical,CA:TRUE", "-addext", "keyUsage=critical,keyCertSign", "-days", "30")
+	if c := readCerts(t, filepath.Join(p.cfg, "rsa_public.pem"))[0]; time.Until(c.NotAfter) > 40*24*time.Hour {
+		t.Fatalf("test certificate is valid until %v", c.NotAfter)
+	}
+	p.foreignPKI()
+	before := sum(t, p.tls("server-ca.crt"))
+	if rc, o := p.check(); rc != 4 || !strings.Contains(o, "expires within 90 days") {
+		t.Fatalf("check rc=%d %s", rc, o)
+	}
+	out := p.mustSh("tn_k3s_ca_setup")
+	if !strings.Contains(out, "expires within 90 days") {
+		t.Errorf("no warning about the expiry:\n%s", out)
+	}
+	if sum(t, p.tls("server-ca.crt")) != before {
+		t.Error("the foreign CA was changed")
+	}
+}
+
+// ---- serial of the re-issued root
+
+func serialOf(t *testing.T, path string) string {
+	t.Helper()
+	return readCerts(t, path)[0].SerialNumber.Text(16)
+}
+
+// The re-issued root must not share issuer and serial with the original certificate (RFC 5280
+// 4.1.2.2; NSS: SEC_ERROR_REUSED_ISSUER_AND_SERIAL). OpenSSL 1.1.1 ignores -set_serial in
+// `x509 -signkey`, which the library works around; the compat suite runs this on 1.1.1.
+func TestReissuedRootHasANewSerial(t *testing.T) {
+	needTool(t, "sh")
+	needTool(t, "openssl")
+	for _, kind := range []string{"backstage", "device-controller"} {
+		t.Run(kind, func(t *testing.T) {
+			p := newPKI(t)
+			if kind == "backstage" {
+				p.legacyCert()
+			} else {
+				p.legacyCertArgs("-addext", "keyUsage=critical,digitalSignature,keyEncipherment", "-set_serial", "1")
+			}
+			orig := serialOf(t, filepath.Join(p.cfg, "rsa_public.pem"))
+			p.mustSh("tn_k3s_ca_setup")
+			if got := serialOf(t, p.tls("root-ca.pem")); got == orig || got == "1" {
+				t.Errorf("new root serial %s, original %s", got, orig)
+			}
+			// the remediation path re-issues too
+			q := newPKI(t)
+			q.legacyCert()
+			q.legacyPKI(true)
+			bin, _ := fakeK3s(t, t.TempDir(), true)
+			qorig := serialOf(t, filepath.Join(q.cfg, "rsa_public.pem"))
+			q.mustSh("tn_ca_remediate all", "K3S_BIN="+bin, "TN_K3S_RESTART_CMD=true")
+			if got := serialOf(t, q.tls("root-ca.pem")); got == qorig {
+				t.Errorf("remediated root keeps the original serial %s", got)
+			}
+		})
+	}
+}
diff --git a/pkg/templates/k3sexec_test.go b/pkg/templates/k3sexec_test.go
new file mode 100644
index 0000000..84cae91
--- /dev/null
+++ b/pkg/templates/k3sexec_test.go
@@ -0,0 +1,164 @@
+package templates
+
+import (
+	"os"
+	"os/exec"
+	"path/filepath"
+	"strings"
+	"testing"
+	"text/template"
+)
+
+// The server script builds INSTALL_K3S_EXEC BEFORE tn_inst_prepare, because the library reads it
+// (tn_inst_cgroup_configured_elsewhere): a fail-cgroupv1 that the caller put there means "the device
+// sets it itself". A flag that is only in INSTALL_K3S_EXEC reaches the unit when the installer has run,
+// so the drop-in is kept (or written) until then. If the script then rebuilt the variable without the
+// caller's value, the installer would get no flag and a k3s >= v1.35 would not start on cgroup v1.
+
+// serverPrologue is the real text of the rendered server script from "# BEGIN install-k3s-exec" to the
+// call of tn_inst_prepare: the arguments of the installer, the data dir, the guard, the release step.
+func serverPrologue(t *testing.T) string {
+	t.Helper()
+	out := renderK3S(t, ServerTemplate, "")
+	begin := strings.Index(out, "# BEGIN install-k3s-exec\n")
+	end := strings.Index(out, "\ntn_inst_prepare server\n")
+	if begin < 0 || end < begin {
+		t.Fatalf("the server script has no install-k3s-exec block before tn_inst_prepare (begin %d, end %d)", begin, end)
+	}
+	return out[begin : end+len("\ntn_inst_prepare server\n")]
+}
+
+func (i *inst) runPrologue(t *testing.T, tail string, env ...string) (string, error) {
+	t.Helper()
+	script := "set -e; set -o noglob; umask 027\n" +
+		"info() { echo '[INFO] ' \"$@\"; }; warn() { echo '[WARN] ' \"$@\" >&2; }; fatal() { echo '[ERROR] ' \"$@\" >&2; exit 1; }\n" +
+		"TN_K3S_CA_NO_MAIN=1; . " + libPath + "; . " + installLibPath + "\n" +
+		serverPrologue(t) + tail
+	cmd := exec.Command("sh", "-c", script)
+	for _, e := range os.Environ() {
+		if strings.HasPrefix(e, "INSTALL_K3S_") || strings.HasPrefix(e, "TN_K3S_") || strings.HasPrefix(e, "TN_CGROUP") || strings.HasPrefix(e, "OS_BUILD") || strings.HasPrefix(e, "K3S_BIN") || strings.HasPrefix(e, "DATA_DIR") || strings.HasPrefix(e, "USE_DOCKER") {
+			continue
+		}
+		cmd.Env = append(cmd.Env, e)
+	}
+	cmd.Env = append(cmd.Env, "TN_K3S_CONFIG_DIR="+i.k3sCfg, "K3S_BIN="+i.bin, "DATA_DIR="+filepath.Join(i.dir, "data"),
+		"TN_K3S_UNIT_FILE="+filepath.Join(i.dir, "no-such.service"), "PRODUCT=k3s",
+		"_K3S_TOKEN=tok", "_DEVICE_ID=dev-1", "_DOMAIN=test.cloud", "TN_K3S_PIN_SOURCE=default", "INSTALL_K3S_VERSION=v1.36.5+k3s1")
+	cmd.Env = append(cmd.Env, env...)
+	b, err := cmd.CombinedOutput()
+	return string(b), err
+}
+
+const baseExec = "server --token tok --tls-san dev-1.test.cloud --tls-san 10.0.0.10"
+
+func execOf(t *testing.T, out string) string {
+	t.Helper()
+	for _, l := range strings.Split(out, "\n") {
+		if strings.HasPrefix(l, "EXEC=") {
+			return strings.TrimPrefix(l, "EXEC=")
+		}
+	}
+	t.Fatalf("no EXEC line:\n%s", out)
+	return ""
+}
+
+// The reviewer's scenario: the caller gives the flag in INSTALL_K3S_EXEC, the host is cgroup v1, k3s
+// >= v1.35 is installed. The installer must still get the flag.
+func TestACallersFailCgroupV1ReachesTheInstaller(t *testing.T) {
+	i := newInst(t)
+	i.installed("v1.36.5+k3s1")
+	out, err := i.runPrologue(t, `echo "EXEC=$INSTALL_K3S_EXEC"`,
+		"TN_CGROUP_FSTYPE=tmpfs", "INSTALL_K3S_EXEC=--kubelet-arg=fail-cgroupv1=false")
+	if err != nil {
+		t.Fatalf("%v\n%s", err, out)
+	}
+	got := execOf(t, out)
+	if !strings.Contains(got, "fail-cgroupv1=false") {
+		t.Errorf("the flag does not reach the installer: INSTALL_K3S_EXEC=%q\n%s", got, out)
+	}
+	if !strings.HasPrefix(got, baseExec) {
+		t.Errorf("INSTALL_K3S_EXEC lost the arguments of the script: %q", got)
+	}
+	// the library saw the flag in INSTALL_K3S_EXEC; the installer gets it (asserted above), but until the
+	// unit is rewritten a restart of k3s reads nothing, so the drop-in is written as well
+	if _, err := os.Stat(i.dropin()); err != nil {
+		t.Errorf("no drop-in although the flag reaches the unit only after the installer:\n%s", out)
+	}
+}
+
+// A drop-in from an earlier run survives tn_inst_prepare when the caller's flag is in INSTALL_K3S_EXEC:
+// the CA step restarts k3s next, and the installer has not written the unit yet.
+func TestADropinSurvivesThePrologueWhenTheCallersFlagIsInInstallK3sExec(t *testing.T) {
+	i := newInst(t)
+	i.installed("v1.36.5+k3s1")
+	write(t, i.dropin(), "kubelet-arg+:\n  - \"fail-cgroupv1=false\"\n")
+	out, err := i.runPrologue(t, `echo "EXEC=$INSTALL_K3S_EXEC"`, "TN_CGROUP_FSTYPE=tmpfs", "INSTALL_K3S_EXEC=--kubelet-arg=fail-cgroupv1=false")
+	if err != nil {
+		t.Fatalf("%v\n%s", err, out)
+	}
+	if _, err := os.Stat(i.dropin()); err != nil {
+		t.Errorf("the drop-in was removed before the CA step and the installer:\n%s", out)
+	}
+}
+
+// tn_inst_finish runs right after the installer in both scripts, and not before.
+func TestFinishFollowsTheInstaller(t *testing.T) {
+	for name, tmpl := range map[string]*template.Template{"server": ServerTemplate, "agent": AgentTemplate} {
+		out := renderK3S(t, tmpl, "")
+		inst := strings.Index(out, "\n$SUDO ./k3s_installer.sh\n")
+		fin := strings.Index(out, "\ntn_inst_finish\n")
+		prep := strings.Index(out, "\ntn_inst_prepare "+name+"\n")
+		if prep < 0 || inst < prep || fin < inst || strings.Count(out, "\ntn_inst_finish\n") != 1 {
+			t.Errorf("%s: prepare %d, installer %d, finish %d (once, after the installer)", name, prep, inst, fin)
+		}
+	}
+}
+
+// Without a flag from the caller the drop-in is written and the arguments are exactly ours.
+func TestInstallExecIsOursWhenTheCallerGivesNone(t *testing.T) {
+	i := newInst(t)
+	i.installed("v1.36.5+k3s1")
+	out, err := i.runPrologue(t, `echo "EXEC=$INSTALL_K3S_EXEC"`, "TN_CGROUP_FSTYPE=tmpfs")
+	if err != nil {
+		t.Fatalf("%v\n%s", err, out)
+	}
+	if got := execOf(t, out); got != baseExec {
+		t.Errorf("INSTALL_K3S_EXEC=%q, want %q (no stray space)", got, baseExec)
+	}
+	if _, err := os.Stat(i.dropin()); err != nil {
+		t.Errorf("no drop-in on cgroup v1 with k3s 1.36:\n%s", out)
+	}
+}
+
+func TestInstallExecKeepsTheCallersOtherArgumentsAndAddsDocker(t *testing.T) {
+	i := newInst(t)
+	i.installed("v1.36.5+k3s1")
+	out, err := i.runPrologue(t, `echo "EXEC=$INSTALL_K3S_EXEC"`, "TN_CGROUP_FSTYPE=cgroup2fs",
+		"INSTALL_K3S_EXEC=--node-label=a=b", "USE_DOCKER=true")
+	if err != nil {
+		t.Fatalf("%v\n%s", err, out)
+	}
+	if got, want := execOf(t, out), baseExec+" --node-label=a=b --docker"; got != want {
+		t.Errorf("INSTALL_K3S_EXEC=%q, want %q", got, want)
+	}
+}
+
+// A data dir that disagrees with config.yaml is refused before tn_inst_prepare changes anything.
+func TestDataDirMismatchIsRefusedBeforeTheReleaseStepChangesAnything(t *testing.T) {
+	i := newInst(t)
+	i.installed("v1.36.5+k3s1")
+	write(t, filepath.Join(i.k3sCfg, "config.yaml"), "data-dir: "+filepath.Join(i.dir, "other")+"\n")
+	out, err := i.runPrologue(t, `echo "EXEC=$INSTALL_K3S_EXEC"`, "TN_CGROUP_FSTYPE=tmpfs")
+	if err == nil {
+		t.Fatalf("the script went on:\n%s", out)
+	}
+	if !strings.Contains(out, "sets data-dir:") || !strings.Contains(out, "The CA and k3s were not changed") {
+		t.Errorf("no refusal text:\n%s", out)
+	}
+	if _, err := os.Stat(i.dropin()); err == nil {
+		t.Errorf("the drop-in was written before the refusal:\n%s", out)
+	}
+	if strings.Contains(out, "Checking the k3s release") {
+		t.Errorf("tn_inst_prepare ran before the refusal:\n%s", out)
+	}
+}
diff --git a/pkg/templates/k3sfollow_test.go b/pkg/templates/k3sfollow_test.go
new file mode 100644
index 0000000..4542b25
--- /dev/null
+++ b/pkg/templates/k3sfollow_test.go
@@ -0,0 +1,970 @@
+package templates
+
+import (
+	"bytes"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"strings"
+	"testing"
+	"time"
+)
+
+// Tests of the follow-up review: an agent follows the k3s release of its server, the cgroup flag
+// is in place before the CA step restarts k3s, the restart and rotate-ca wait for a slow k3s, a k3s
+// whose version cannot be read is not touched, the flag goes in from v1.31 (atomically), a refusal
+// says what this run changed, and the data dir must agree with config.yaml.
+
+const agentURL = "https://srv:6443"
+
+// ---------------------------------------------------------------- the agent follows its server
+
+func TestAgentFollowsItsServer(t *testing.T) {
+	const (
+		v134 = "v1.34.11+k3s1"
+		v135 = "v1.35.9+k3s1"
+		v136 = "v1.36.5+k3s1"
+	)
+	for _, tc := range []struct {
+		name      string
+		installed string
+		pin       string // INSTALL_K3S_VERSION, "" = unset
+		source    string // TN_K3S_PIN_SOURCE
+		server    string // the release the server script published ("" = nothing published: 404)
+		anon      string // the release an anonymous /version gives ("" = 401/404)
+		raw       string // a raw content of the published file instead
+		anonBody  string // a raw answer of /version instead
+		env       []string
+		noURL     bool
+		wantRC    int
+		want      string // the RESULT line
+		msgs      []string
+		notMsgs   []string
+		curl      int // calls of curl, -1 = not checked
+	}{
+		// --- a new agent: the release of the server, never the pin of the script
+		{name: "server older than the default pin", pin: v136, source: "default", server: v134,
+			want: "version=" + v134 + " channel=unset action=install effective=" + v134, curl: 1,
+			msgs: []string{"runs " + v134, "the script's default " + v136 + " is not used", "the agent gets the release of its server"}},
+		{name: "server newer than the default pin", pin: v134, source: "default", server: v136,
+			want: "version=" + v136 + " channel=unset action=install effective=" + v136, curl: 1},
+		{name: "the default pin equals the server", pin: v136, source: "default", server: v136,
+			want: "version=" + v136 + " channel=unset action=install effective=" + v136, curl: 1, notMsgs: []string{"is not used"}},
+		{name: "no pin at all (stable)", source: "default", server: v135,
+			want: "version=" + v135 + " channel=unset action=install effective=" + v135, curl: 1},
+		{name: "the latest channel is not followed either", source: "default", server: v135, env: []string{"INSTALL_K3S_CHANNEL=latest"},
+			want: "version=" + v135 + " channel=unset action=install effective=" + v135, curl: 1},
+		{name: "an anonymous /version, one line of JSON", pin: v136, source: "default", anonBody: `{"major":"1","minor":"33","gitVersion":"v1.33.4+k3s1","goVersion":"go1.24"}`,
+			want: "version=v1.33.4+k3s1 channel=unset action=install effective=v1.33.4+k3s1", curl: 2, msgs: []string{"read from " + agentURL + "/version"}},
+		{name: "an anonymous /version", pin: v136, source: "default", anon: v135,
+			want: "version=" + v135 + " channel=unset action=install effective=" + v135, curl: 2},
+		{name: "the published file wins over /version", pin: v136, source: "default", server: v134, anon: v135,
+			want: "version=" + v134 + " channel=unset action=install effective=" + v134, curl: 1, msgs: []string{"read from " + agentURL + "/static/teknoir/k3s-version"}},
+		{name: "the published file with blanks and a CRLF", pin: v136, source: "default", raw: " v1.34.11+k3s1 \r",
+			want: "version=" + v134 + " channel=unset action=install effective=" + v134, curl: 1},
+		{name: "a trailing slash in K3S_URL", pin: v136, source: "default", server: v134, env: []string{"K3S_URL=" + agentURL + "/"},
+			want: "version=" + v134 + " channel=unset action=install effective=" + v134, curl: 1},
+		{name: "a server that fails twice and then answers", pin: v136, source: "default", server: v134, env: []string{"TN_TEST_FAIL_N=2"},
+			want: "version=" + v134 + " channel=unset action=install effective=" + v134, curl: 3},
+
+		// --- a release that was asked for
+		{name: "asked for: the same as the server", pin: v134, source: "flag", server: v134,
+			want: "version=" + v134 + " channel=unset action=install effective=" + v134, curl: 1, msgs: []string{"is the release of the server"}},
+		{name: "asked for: older than the server is installed with a warning", pin: v134, source: "env", server: v136,
+			want: "version=" + v134 + " channel=unset action=install effective=" + v134, curl: 1, msgs: []string{"OLDER than the release of the server", "installed as asked"}},
+		{name: "asked for: newer than the server is refused", pin: v136, source: "flag", server: v134, wantRC: 1, curl: 1,
+			msgs: []string{"refusing to install k3s " + v136 + " on this agent", "runs the older " + v134, "must not be newer than the apiserver", "TN_K3S_FORCE=true", "Nothing was changed"}},
+		{name: "asked for: newer than the server, forced", pin: v136, source: "env", server: v134, env: []string{"TN_K3S_FORCE=true"},
+			want: "version=" + v136 + " channel=unset action=install effective=" + v136, curl: 1, msgs: []string{"NEWER than the release of the server", "TN_K3S_FORCE=true"}},
+		{name: "asked for: a channel cannot be compared, the server wins", source: "flag", server: v135, env: []string{"INSTALL_K3S_CHANNEL=latest"},
+			want: "version=" + v135 + " channel=unset action=install effective=" + v135, curl: 1, msgs: []string{"not an exact release", "the release of the server is installed instead"}},
+
+		// --- the server cannot be asked
+		{name: "server down, default pin: refused", pin: v136, source: "default", wantRC: 1, curl: 2, env: []string{"TN_TEST_SERVER_DOWN=1", "TN_K3S_SERVER_VERSION_TRIES=2"},
+			msgs: []string{"cannot read the k3s release of the server at " + agentURL, "does not guess", "Is the server up", "INSTALL_K3S_VERSION=v1.xx.y+k3sN", "TN_K3S_FORCE=true", "Nothing was changed"}},
+		{name: "server down, default pin, three tries by default", pin: v136, source: "default", wantRC: 1, curl: 3, env: []string{"TN_TEST_SERVER_DOWN=1"}},
+		{name: "server down, asked for an exact release: installed with a warning", pin: v134, source: "flag", env: []string{"TN_TEST_SERVER_DOWN=1"},
+			want: "version=" + v134 + " channel=unset action=install effective=" + v134, curl: 3, msgs: []string{"cannot read the k3s release of the server", "installed as asked"}},
+		{name: "server down, forced", pin: v136, source: "default", env: []string{"TN_TEST_SERVER_DOWN=1", "TN_K3S_FORCE=true"},
+			want: "version=" + v136 + " channel=unset action=install effective=" + v136, curl: 3, msgs: []string{"TN_K3S_FORCE=true", "installed anyway"}},
+		{name: "server down, no pin, forced: the installer decides", source: "default", env: []string{"TN_TEST_SERVER_DOWN=1", "TN_K3S_FORCE=true"},
+			want: "version=unset channel=unset action=install effective=", curl: 3},
+		{name: "a server that does not publish its release (bootstrapped by an older script)", pin: v136, source: "default", wantRC: 1, curl: 2,
+			msgs:    []string{"cannot read the k3s release of the server", "does not publish its release", "run the server script again", "does not allow an anonymous /version", "INSTALL_K3S_VERSION=v1.xx.y+k3sN", "Nothing was changed"},
+			notMsgs: []string{"Is the server up"}},
+		{name: "an anonymous /version that is not k3s (rke2)", pin: v136, source: "default", anonBody: `{"gitVersion":"v1.34.11+rke2r1"}`, wantRC: 1, curl: 2},
+		{name: "a published file without a release", pin: v136, source: "default", raw: `<html>nope</html>`, wantRC: 1, curl: 2},
+		{name: "a blank published file", pin: v136, source: "default", raw: ` `, wantRC: 1, curl: 2},
+		{name: "a release without +k3s is no k3s release", pin: v136, source: "default", raw: `v1.34.11`, wantRC: 1, curl: 2},
+		{name: "a server that does not publish, asked for an exact release", pin: v134, source: "env",
+			want: "version=" + v134 + " channel=unset action=install effective=" + v134, curl: 2, msgs: []string{"installed as asked"}},
+		{name: "K3S_URL is not set", pin: v136, source: "default", noURL: true, wantRC: 1, curl: 0, msgs: []string{"K3S_URL is not set"}},
+		{name: "an OS build installs the pin without asking", pin: v136, source: "default", env: []string{"OS_BUILD=true"},
+			want: "version=" + v136 + " channel=unset action=install effective=" + v136, curl: 0, msgs: []string{"OS build"}},
+
+		// --- an agent that is installed
+		{name: "installed: kept, the server is not asked", installed: v134, pin: v136, source: "default", server: v136,
+			want: "version=" + v134 + " channel=unset action=keep effective=" + v134, curl: 0},
+		{name: "installed, server down: kept all the same", installed: v134, pin: v136, source: "default",
+			env: []string{"TN_TEST_SERVER_DOWN=1"}, want: "version=" + v134 + " channel=unset action=keep effective=" + v134, curl: 0},
+		{name: "installed, upgrade: to the release of the server", installed: v134, pin: v136, source: "default", server: v135, env: []string{"TN_K3S_UPGRADE=true"},
+			want: "version=" + v135 + " channel=unset action=upgrade effective=" + v135, curl: 1},
+		{name: "installed, upgrade, already there", installed: v135, pin: v136, source: "default", server: v135, env: []string{"TN_K3S_UPGRADE=true"},
+			want: "version=" + v135 + " channel=unset action=same effective=" + v135, curl: 1},
+		{name: "installed, upgrade over two minors is still refused", installed: v134, pin: v136, source: "default", server: v136, env: []string{"TN_K3S_UPGRADE=true"},
+			wantRC: 1, curl: 1, msgs: []string{"more than one minor version"}},
+		{name: "installed newer than the server: no downgrade", installed: v136, pin: v136, source: "default", server: v134, env: []string{"TN_K3S_UPGRADE=true"},
+			wantRC: 1, curl: 1, msgs: []string{"refusing to downgrade"}},
+		{name: "installed, upgrade, server down: refused", installed: v134, pin: v136, source: "default", env: []string{"TN_K3S_UPGRADE=true", "TN_TEST_SERVER_DOWN=1"},
+			wantRC: 1, curl: 3, msgs: []string{"cannot read the k3s release of the server"}},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			i := newInst(t)
+			i.installed(tc.installed)
+			env := append([]string{"TN_CGROUP_FSTYPE=cgroup2fs", "TN_K3S_PIN_SOURCE=" + tc.source}, tc.env...)
+			if !tc.noURL && !hasPrefix(env, "K3S_URL=") {
+				env = append(env, "K3S_URL="+agentURL)
+			}
+			if tc.pin != "" {
+				env = append(env, "INSTALL_K3S_VERSION="+tc.pin)
+			}
+			if tc.server != "" {
+				env = append(env, "TN_TEST_PUBLISHED="+tc.server)
+			}
+			if tc.raw != "" {
+				env = append(env, "TN_TEST_PUBLISHED="+tc.raw)
+			}
+			if tc.anon != "" {
+				env = append(env, "TN_TEST_SERVER_VERSION="+tc.anon)
+			}
+			if tc.anonBody != "" {
+				env = append(env, "TN_TEST_SERVER_BODY="+tc.anonBody)
+			}
+			out, err := i.run("tn_inst_prepare agent; "+resultLine, env...)
+			if rc := exitCode(err); rc != tc.wantRC {
+				t.Fatalf("rc=%d, want %d\n%s", rc, tc.wantRC, out)
+			}
+			if tc.wantRC == 0 {
+				if got := result(t, out); got != tc.want {
+					t.Errorf("result\n got  %s\n want %s\n%s", got, tc.want, out)
+				}
+			} else if strings.Contains(out, "RESULT") {
+				t.Errorf("the script went on after the refusal:\n%s", out)
+			}
+			for _, m := range tc.msgs {
+				if !strings.Contains(out, m) {
+					t.Errorf("output lacks %q:\n%s", m, out)
+				}
+			}
+			for _, m := range tc.notMsgs {
+				if strings.Contains(out, m) {
+					t.Errorf("output has %q:\n%s", m, out)
+				}
+			}
+			calls := i.curlCalls()
+			if tc.curl >= 0 {
+				if n := strings.Count(calls, "\n"); n != tc.curl {
+					t.Errorf("curl was called %d times, want %d:\n%s", n, tc.curl, calls)
+				}
+			}
+			if tc.curl > 0 {
+				want := agentURL + "/static/teknoir/k3s-version"
+				if !strings.Contains(calls, want+"\n") {
+					t.Errorf("curl did not ask %s:\n%s", want, calls)
+				}
+				// fails on HTTP errors, no certificate check, bounded
+				if !strings.Contains(calls, "-fsk --max-time 10 ") {
+					t.Errorf("curl flags: %s", calls)
+				}
+			}
+		})
+	}
+}
+
+func hasPrefix(list []string, p string) bool {
+	for _, e := range list {
+		if strings.HasPrefix(e, p) {
+			return true
+		}
+	}
+	return false
+}
+
+// A server never asks anybody: it installs the pin, and the cgroup logic follows the release
+// that is installed, which for an agent is the one of the server.
+func TestServerRoleNeverAsksAndAgentCgroupFollowsTheInstalledRelease(t *testing.T) {
+	i := newInst(t)
+	i.installed("")
+	out, err := i.run("tn_inst_prepare server; "+resultLine, "TN_CGROUP_FSTYPE=cgroup2fs", "K3S_URL="+agentURL, "TN_K3S_PIN_SOURCE=default",
+		"INSTALL_K3S_VERSION=v1.36.5+k3s1", "TN_TEST_PUBLISHED=v1.34.11+k3s1")
+	if err != nil || result(t, out) != "version=v1.36.5+k3s1 channel=unset action=install effective=v1.36.5+k3s1" {
+		t.Fatalf("%v\n%s", err, out)
+	}
+	if i.curlCalls() != "" {
+		t.Errorf("a server script asked a server: %s", i.curlCalls())
+	}
+
+	// cgroup v1 agent: the flag follows the release that will run, not the pin of the script
+	for _, tc := range []struct {
+		server string
+		file   bool
+	}{
+		{"v1.30.14+k3s1", false}, // the kubelet has no such flag: none written, although the default pin is v1.36.5
+		{"v1.31.0+k3s1", true},
+		{"v1.34.11+k3s1", true},
+		{"v1.36.5+k3s1", true},
+	} {
+		i := newInst(t)
+		i.installed("")
+		out, err := i.run("tn_inst_prepare agent", "TN_CGROUP_FSTYPE=tmpfs", "K3S_URL="+agentURL, "TN_K3S_PIN_SOURCE=default",
+			"INSTALL_K3S_VERSION=v1.36.5+k3s1", "TN_TEST_PUBLISHED="+tc.server)
+		if err != nil {
+			t.Fatalf("%s: %v\n%s", tc.server, err, out)
+		}
+		if _, serr := os.Stat(i.dropin()); (serr == nil) != tc.file {
+			t.Errorf("agent on %s: drop-in exists=%v, want %v\n%s", tc.server, serr == nil, tc.file, out)
+		}
+	}
+}
+
+// wget is used when there is no curl
+func TestServerVersionWithWgetOnly(t *testing.T) {
+	i := newInst(t)
+	i.installed("")
+	// a PATH with the usual tools, but no curl (and wget only in the first one)
+	mkbin := func(name string) string {
+		bin := filepath.Join(i.dir, name)
+		if err := os.MkdirAll(bin, 0o755); err != nil {
+			t.Fatal(err)
+		}
+		for _, tool := range []string{"sh", "sed", "tr", "cat", "find", "rm", "mv", "mkdir", "sleep", "awk", "stat", "grep", "tail", "dirname", "cut", "date", "env", "id", "head", "sort"} {
+			if p, err := exec.LookPath(tool); err == nil {
+				if err := os.Symlink(p, filepath.Join(bin, tool)); err != nil {
+					t.Fatal(err)
+				}
+			}
+		}
+		return bin
+	}
+	bin := mkbin("wgetonly")
+	wlog := filepath.Join(i.dir, "wget.log")
+	write(t, filepath.Join(bin, "wget"), "#!/bin/sh\necho \"$*\" >> '"+wlog+"'\nfor a in \"$@\"; do url=$a; done\ncase \"$url\" in */static/teknoir/k3s-version) echo v1.35.9+k3s1; exit 0 ;; esac\nexit 8\n")
+	if err := os.Chmod(filepath.Join(bin, "wget"), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	out, err := i.run("tn_inst_prepare agent; "+resultLine, "PATH="+bin, "TN_CGROUP_FSTYPE=cgroup2fs", "K3S_URL="+agentURL,
+		"TN_K3S_PIN_SOURCE=default", "INSTALL_K3S_VERSION=v1.36.5+k3s1")
+	if err != nil || result(t, out) != "version=v1.35.9+k3s1 channel=unset action=install effective=v1.35.9+k3s1" {
+		t.Fatalf("%v\n%s", err, out)
+	}
+	if !strings.Contains(readLog(wlog), agentURL+"/static/teknoir/k3s-version") || !strings.Contains(readLog(wlog), "--no-check-certificate") {
+		t.Errorf("wget: %s", readLog(wlog))
+	}
+	// and neither: refused, not guessed
+	out, err = i.run("tn_inst_prepare agent; "+resultLine, "PATH="+mkbin("neither"), "TN_CGROUP_FSTYPE=cgroup2fs", "K3S_URL="+agentURL,
+		"TN_K3S_PIN_SOURCE=default", "INSTALL_K3S_VERSION=v1.36.5+k3s1")
+	if exitCode(err) != 1 || strings.Contains(out, "RESULT") || !strings.Contains(out, "cannot read the k3s release of the server") {
+		t.Errorf("went on without curl and wget:\n%s", out)
+	}
+}
+
+// The generated agent script: the template says who chose the release, and the policy does the rest.
+func TestRenderedAgentPinSource(t *testing.T) {
+	needTool(t, "sh")
+	for _, tc := range []struct {
+		name   string
+		data   TemplateData
+		env    []string
+		server string
+		want   string
+	}{
+		{"default: the server wins", TemplateData{}, nil, "v1.34.11+k3s1", "version=v1.34.11+k3s1 channel=unset action=install"},
+		{"default, server newer", TemplateData{}, nil, "v1.37.1+k3s1", "version=v1.37.1+k3s1 channel=unset action=install"},
+		{"tnctl --k3s-version newer than the server: refused", TemplateData{K3SVersion: "v1.36.5+k3s1", K3SVersionExplicit: true}, nil, "v1.34.11+k3s1", ""},
+		{"tnctl --k3s-version equal", TemplateData{K3SVersion: "v1.34.11+k3s1", K3SVersionExplicit: true}, nil, "v1.34.11+k3s1", "version=v1.34.11+k3s1 channel=unset action=install"},
+		{"INSTALL_K3S_VERSION in the environment, newer: refused", TemplateData{}, []string{"INSTALL_K3S_VERSION=v1.37.1+k3s1"}, "v1.34.11+k3s1", ""},
+		{"INSTALL_K3S_VERSION in the environment, older", TemplateData{}, []string{"INSTALL_K3S_VERSION=v1.33.4+k3s1"}, "v1.34.11+k3s1", "version=v1.33.4+k3s1 channel=unset action=install"},
+		{"--k3s-version latest: the server wins", TemplateData{K3SVersion: "latest", K3SVersionExplicit: true}, nil, "v1.34.11+k3s1", "version=v1.34.11+k3s1 channel=unset action=install"},
+		{"--k3s-version stable (no pin): the server wins", TemplateData{K3SVersion: "stable", K3SVersionExplicit: true}, nil, "v1.34.11+k3s1", "version=v1.34.11+k3s1 channel=unset action=install"},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			var part bytes.Buffer
+			if err := AgentTemplate.ExecuteTemplate(&part, "k3s_version.sh.tmpl", tc.data); err != nil {
+				t.Fatal(err)
+			}
+			i := newInst(t)
+			i.installed("")
+			out, err := i.run(part.String()+"\ntn_inst_prepare agent; "+resultLine, append([]string{"TN_CGROUP_FSTYPE=cgroup2fs", "K3S_URL=" + agentURL, "TN_TEST_PUBLISHED=" + tc.server}, tc.env...)...)
+			if tc.want == "" {
+				if exitCode(err) != 1 || !strings.Contains(out, "refusing to install") {
+					t.Fatalf("not refused: %v\n%s", err, out)
+				}
+				return
+			}
+			if err != nil {
+				t.Fatalf("%v\n%s", err, out)
+			}
+			if got := result(t, out); !strings.HasPrefix(got, tc.want+" ") {
+				t.Errorf("got %q, want %q", got, tc.want)
+			}
+		})
+	}
+	// the source that the template records
+	for _, tc := range []struct {
+		data TemplateData
+		env  []string
+		want string
+	}{
+		{TemplateData{}, nil, "default"},
+		{TemplateData{K3SVersionExplicit: true}, nil, "flag"},
+		{TemplateData{}, []string{"INSTALL_K3S_VERSION=v1.34.11+k3s1"}, "env"},
+		{TemplateData{K3SVersionExplicit: true}, []string{"INSTALL_K3S_CHANNEL=latest"}, "env"},
+	} {
+		var part bytes.Buffer
+		if err := AgentTemplate.ExecuteTemplate(&part, "k3s_version.sh.tmpl", tc.data); err != nil {
+			t.Fatal(err)
+		}
+		i := newInst(t)
+		out, err := i.run(part.String()+"\necho \"SOURCE=$TN_K3S_PIN_SOURCE\"", tc.env...)
+		if err != nil || !strings.Contains(out, "SOURCE="+tc.want+"\n") {
+			t.Errorf("%+v %v: %v\n%s", tc.data, tc.env, err, out)
+		}
+	}
+}
+
+// ---------------------------------------------------------------- a k3s whose version cannot be read
+
+func TestUnreadableK3sVersionIsNotInstalledOver(t *testing.T) {
+	const pin = "INSTALL_K3S_VERSION=v1.36.5+k3s1"
+	garbage := func(i *inst) {
+		i.bin = filepath.Join(i.dir, "garbage-k3s")
+		write(i.t, i.bin, "#!/bin/sh\necho 'this is not k3s'\nexit 0\n")
+		_ = os.Chmod(i.bin, 0o755)
+	}
+	failing := func(i *inst) {
+		i.bin = filepath.Join(i.dir, "failing-k3s")
+		write(i.t, i.bin, "#!/bin/sh\necho 'Segmentation fault' >&2\nexit 139\n")
+		_ = os.Chmod(i.bin, 0o755)
+	}
+	datastore := func(i *inst) {
+		if err := os.MkdirAll(filepath.Join(i.dir, "data", "server", "db"), 0o755); err != nil {
+			t.Fatal(err)
+		}
+	}
+	for _, tc := range []struct {
+		name  string
+		setup func(*inst)
+		role  string
+	}{
+		{"binary that prints something else", garbage, "server"},
+		{"binary that crashes", failing, "server"},
+		{"datastore without a binary", datastore, "server"},
+		{"agent: binary that prints something else", garbage, "agent"},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			i := newInst(t)
+			i.installed("")
+			tc.setup(i)
+			env := []string{"TN_CGROUP_FSTYPE=cgroup2fs", "TN_K3S_PIN_SOURCE=flag", "K3S_URL=" + agentURL, "TN_TEST_PUBLISHED=v1.36.5+k3s1", pin}
+			out, err := i.run("tn_inst_prepare "+tc.role+"; "+resultLine, env...)
+			if exitCode(err) != 1 || strings.Contains(out, "RESULT") {
+				t.Fatalf("not refused (rc=%d):\n%s", exitCode(err), out)
+			}
+			for _, m := range []string{"version cannot be read", "does not install anything", "TN_K3S_FORCE=true", "Nothing was changed"} {
+				if !strings.Contains(out, m) {
+					t.Errorf("output lacks %q:\n%s", m, out)
+				}
+			}
+			if _, serr := os.Stat(i.dropin()); serr == nil {
+				t.Error("a drop-in was written although the run was refused")
+			}
+			// forced: the pin is installed, with a warning
+			out, err = i.run("tn_inst_prepare "+tc.role+"; "+resultLine, append(env, "TN_K3S_FORCE=true")...)
+			if err != nil || !strings.Contains(out, "TN_K3S_FORCE=true: going on as if k3s were not installed") ||
+				result(t, out) != "version=v1.36.5+k3s1 channel=unset action=install effective=v1.36.5+k3s1" {
+				t.Errorf("forced: %v\n%s", err, out)
+			}
+		})
+	}
+	// no binary, no datastore: a new device
+	i := newInst(t)
+	i.installed("")
+	if out, err := i.run("tn_inst_prepare server", "TN_CGROUP_FSTYPE=cgroup2fs", pin); err != nil || !strings.Contains(out, "k3s is not installed") {
+		t.Errorf("fresh device: %v\n%s", err, out)
+	}
+	// a readable binary with a datastore is the normal case
+	i = newInst(t)
+	i.installed("v1.34.11+k3s1")
+	datastore(i)
+	if out, err := i.run("tn_inst_prepare server; "+resultLine, "TN_CGROUP_FSTYPE=cgroup2fs", pin); err != nil || !strings.Contains(result(t, out), "action=keep") {
+		t.Errorf("installed: %v\n%s", err, out)
+	}
+	// a datastore in the data dir that was named
+	i = newInst(t)
+	i.installed("")
+	other := filepath.Join(i.dir, "elsewhere")
+	if err := os.MkdirAll(filepath.Join(other, "server", "db"), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if out, err := i.run("tn_inst_prepare server", "TN_CGROUP_FSTYPE=cgroup2fs", pin, "DATA_DIR="+other); exitCode(err) != 1 || !strings.Contains(out, other+"/server/db") {
+		t.Errorf("datastore of DATA_DIR: %v\n%s", err, out)
+	}
+}
+
+// ---------------------------------------------------------------- cgroup flag: atomic, idempotent
+
+func TestCgroupDropinIsWrittenAtomically(t *testing.T) {
+	i := newInst(t)
+	i.installed("")
+	env := []string{"TN_CGROUP_FSTYPE=tmpfs", "INSTALL_K3S_VERSION=v1.34.11+k3s1"}
+	dir := filepath.Dir(i.dropin())
+	// a leftover of a run that was killed in the middle
+	write(t, filepath.Join(dir, ".99-teknoir-cgroupv1.yaml.tmp.4242"), "half")
+	out, err := i.run("tn_inst_prepare server", env...)
+	if err != nil {
+		t.Fatalf("%v\n%s", err, out)
+	}
+	ents, _ := os.ReadDir(dir)
+	if len(ents) != 1 || ents[0].Name() != "99-teknoir-cgroupv1.yaml" {
+		var names []string
+		for _, e := range ents {
+			names = append(names, e.Name())
+		}
+		t.Errorf("config.yaml.d holds %v", names)
+	}
+	// idempotent: the file is not touched when it is right (same inode, same mtime)
+	st1, _ := os.Stat(i.dropin())
+	time.Sleep(1100 * time.Millisecond)
+	out, err = i.run("tn_inst_prepare server", env...)
+	st2, _ := os.Stat(i.dropin())
+	if err != nil || !strings.Contains(out, "already in place") || !os.SameFile(st1, st2) || !st1.ModTime().Equal(st2.ModTime()) {
+		t.Errorf("not idempotent: %v\n%s", err, out)
+	}
+	// a changed file is replaced in one step
+	write(t, i.dropin(), "kubelet-arg+:\n  - \"fail-cgroupv1=true\"\n")
+	if out, err = i.run("tn_inst_prepare server", env...); err != nil || !strings.Contains(string(mustRead(t, i.dropin())), "fail-cgroupv1=false") {
+		t.Errorf("not rewritten: %v\n%s", err, out)
+	}
+	// the temporary file is named like a hidden file that does not end in .yaml, and is moved into place
+	b := string(mustRead(t, filepath.Join("scripts", "tn-k3s-install.sh")))
+	if !strings.Contains(b, `_tn_tmp=$_tn_cdir/.$TN_INST_CGROUP_FILE.tmp.$$`) || !strings.Contains(b, `mv -f "$_tn_tmp" "$_tn_cfile"`) {
+		t.Error("the drop-in is not written through a temporary file")
+	}
+}
+
+func mustRead(t *testing.T, p string) []byte {
+	t.Helper()
+	b, err := os.ReadFile(p)
+	if err != nil {
+		t.Fatal(err)
+	}
+	return b
+}
+
+func TestCgroupDropinWriteFailureIsFatalAndLeavesNothingBehind(t *testing.T) {
+	if os.Geteuid() == 0 {
+		t.Skip("root can write anywhere")
+	}
+	i := newInst(t)
+	i.installed("")
+	dir := filepath.Dir(i.dropin())
+	if err := os.MkdirAll(dir, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.Chmod(dir, 0o555); err != nil {
+		t.Fatal(err)
+	}
+	defer os.Chmod(dir, 0o755)
+	out, err := i.run("tn_inst_prepare server", "TN_CGROUP_FSTYPE=tmpfs", "INSTALL_K3S_VERSION=v1.36.5+k3s1")
+	if exitCode(err) != 1 || !strings.Contains(out, "cannot write") {
+		t.Fatalf("rc=%d\n%s", exitCode(err), out)
+	}
+	if ents, _ := os.ReadDir(dir); len(ents) != 0 {
+		t.Errorf("left behind: %v", ents)
+	}
+}
+
+// ---------------------------------------------------------------- a refusal says what changed
+
+func TestRefusalsSayWhatThisRunChanged(t *testing.T) {
+	for _, tc := range []struct {
+		name string
+		env  []string
+	}{
+		{"downgrade", []string{"INSTALL_K3S_VERSION=v1.34.11+k3s1", "TN_K3S_UPGRADE=true", "TN_K3S_FORCE=true"}},
+		{"minor jump", []string{"INSTALL_K3S_VERSION=v1.36.5+k3s1", "TN_K3S_UPGRADE=true"}},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			// installed v1.35.9 for the jump (v1.35 -> v1.37 pin); for the downgrade the pin is older
+			installed := "v1.35.9+k3s1"
+			env := append([]string{"TN_CGROUP_FSTYPE=cgroup2fs"}, tc.env...)
+			if tc.name == "minor jump" {
+				installed = "v1.34.11+k3s1"
+			}
+			i := newInst(t)
+			i.installed(installed)
+			out, err := i.run("tn_inst_prepare server", env...)
+			if exitCode(err) != 1 || !strings.Contains(out, "Nothing was changed") {
+				t.Fatalf("without a change: rc=%d\n%s", exitCode(err), out)
+			}
+			changed := "the CA was rotated in the datastore of k3s (k3s certificate rotate-ca); the CA files in /x/server/tls were replaced; k3s was restarted"
+			i = newInst(t)
+			i.installed(installed)
+			out, err = i.run("tn_inst_prepare server", append(env, "TN_K3S_CA_CHANGED="+changed)...)
+			if exitCode(err) != 1 || strings.Contains(out, "Nothing was changed") ||
+				!strings.Contains(out, "The k3s release was not changed, but earlier in this run: "+changed) {
+				t.Fatalf("after a change: rc=%d\n%s", exitCode(err), out)
+			}
+		})
+	}
+	// the agent refusal too
+	i := newInst(t)
+	i.installed("")
+	out, err := i.run("tn_inst_prepare agent", "TN_CGROUP_FSTYPE=cgroup2fs", "TN_K3S_PIN_SOURCE=flag", "INSTALL_K3S_VERSION=v1.36.5+k3s1", "K3S_URL="+agentURL,
+		"TN_TEST_PUBLISHED=v1.34.11+k3s1", "TN_K3S_CA_CHANGED=k3s was restarted")
+	if exitCode(err) != 1 || strings.Contains(out, "Nothing was changed") || !strings.Contains(out, "earlier in this run: k3s was restarted") {
+		t.Fatalf("agent: rc=%d\n%s", exitCode(err), out)
+	}
+}
+
+// the CA library records what it changes
+func TestTheCAStepRecordsWhatItChanged(t *testing.T) {
+	p := newPKI(t)
+	p.legacyCert()
+	p.legacyPKI(true)
+	bin, _ := fakeK3sVersion(t, t.TempDir(), "v1.34.11+k3s1", true)
+	out := p.mustSh("tn_k3s_ca_setup; echo \"CHANGED=$TN_K3S_CA_CHANGED\"", "K3S_BIN="+bin, "TN_K3S_RESTART_CMD=true")
+	for _, want := range []string{"CHANGED=the CA was rotated in the datastore of k3s", "the CA files in " + p.data + "/server/tls were replaced", "k3s was restarted"} {
+		if !strings.Contains(out, want) {
+			t.Errorf("TN_K3S_CA_CHANGED lacks %q:\n%s", want, out)
+		}
+	}
+	// a fresh device: the PKI was generated; a second run changes nothing
+	q := newPKI(t)
+	q.legacyCert()
+	out = q.mustSh("tn_k3s_ca_setup; echo \"CHANGED=$TN_K3S_CA_CHANGED\"")
+	if !strings.Contains(out, "CHANGED=the k3s PKI in "+q.data+"/server/tls was generated") || strings.Contains(out, "restarted") {
+		t.Errorf("fresh setup:\n%s", out)
+	}
+	out = q.mustSh("tn_k3s_ca_setup; echo \"CHANGED=[$TN_K3S_CA_CHANGED]\"")
+	if !strings.Contains(out, "CHANGED=[]") {
+		t.Errorf("a second setup changed something:\n%s", out)
+	}
+}
+
+// ---------------------------------------------------------------- the order: flag before the CA step
+
+func TestServerScriptOrder(t *testing.T) {
+	out := renderK3S(t, ServerTemplate, "")
+	idx := func(s string) int { return strings.Index(out, s) }
+	pin := idx("\nexport INSTALL_K3S_VERSION=")
+	execArgs := idx("\n# BEGIN install-k3s-exec\n")
+	resolve := idx("\ntn_ca_resolve_datadir\n")
+	guard := idx("\ntn_ca_require_consistent_datadir\n")
+	prep := idx("\ntn_inst_prepare server\n")
+	ca := idx("\ntn_k3s_ca_setup\n")
+	inst := idx("\n$SUDO ./k3s_installer.sh")
+	if !(pin > 0 && pin < execArgs && execArgs < resolve && resolve < guard && guard < prep && prep < ca && ca < inst) {
+		t.Errorf("order: pin %d, INSTALL_K3S_EXEC %d, resolve datadir %d, data dir guard %d, tn_inst_prepare %d, tn_k3s_ca_setup %d, installer %d", pin, execArgs, resolve, guard, prep, ca, inst)
+	}
+	// INSTALL_K3S_EXEC is final before tn_inst_prepare reads it, and is not rebuilt after it
+	if strings.Count(out, "export INSTALL_K3S_EXEC=\"server") != 1 || idx("export INSTALL_K3S_EXEC=\"server") > prep {
+		t.Error("INSTALL_K3S_EXEC must be built once, before tn_inst_prepare server")
+	}
+	if strings.Count(out, "\ntn_inst_prepare server\n") != 1 {
+		t.Error("tn_inst_prepare is called more than once")
+	}
+	// the library functions are defined before they are called
+	for _, fn := range []string{"tn_ca_resolve_datadir()", "tn_ca_require_consistent_datadir()", "tn_inst_prepare()", "tn_k3s_ca_setup()"} {
+		if idx(fn) < 0 || idx(fn) > resolve {
+			t.Errorf("%s is not defined before its first call", fn)
+		}
+	}
+	// the agent has no CA step, and K3S_URL (to ask the server) is set before tn_inst_prepare
+	ag := renderK3S(t, AgentTemplate, "")
+	if strings.Contains(ag, "\ntn_k3s_ca_setup\n") {
+		t.Error("the agent script runs the CA step")
+	}
+	if !(strings.Index(ag, `export K3S_URL=${K3S_URL}`) > 0 && strings.Index(ag, `export K3S_URL=${K3S_URL}`) < strings.Index(ag, "\ntn_inst_prepare agent\n")) {
+		t.Error("the agent script must have K3S_URL before tn_inst_prepare agent")
+	}
+}
+
+// What the order buys on a device that an old script left hung: cgroup v1, a k3s >= v1.35 that exits
+// (and restarts itself in a loop), and a CA from before the fix. The kubelet flag is in place when
+// rotate-ca runs and when k3s is restarted.
+func TestTheKubeletFlagIsInPlaceBeforeTheCAStepTouchesK3s(t *testing.T) {
+	for _, tc := range []struct {
+		name  string
+		first string
+		want  string
+	}{
+		{"flag first, the server script", "tn_inst_prepare server", "dropin=yes"},
+		{"CA first, the old order", "tn_k3s_ca_setup", "dropin=no"},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			p := newPKI(t)
+			p.legacyCert()
+			p.legacyPKI(true)
+			dropin := filepath.Join(p.k3sCfg, "config.yaml.d", "99-teknoir-cgroupv1.yaml")
+			calls := filepath.Join(p.dir, "calls.log")
+			bin := filepath.Join(p.dir, "fake-k3s")
+			write(t, bin, "#!/bin/sh\nif [ \"$1\" = --version ]; then echo 'k3s version v1.36.5+k3s1 (0123abcd)'; echo 'go version go1.24.1'; exit 0; fi\n"+
+				"if [ -f '"+dropin+"' ]; then echo \"rotate dropin=yes\" >> '"+calls+"'; else echo \"rotate dropin=no\" >> '"+calls+"'; fi\nexit 0\n")
+			if err := os.Chmod(bin, 0o755); err != nil {
+				t.Fatal(err)
+			}
+			restart := "if [ -f '" + dropin + "' ]; then echo 'restart dropin=yes' >> '" + calls + "'; else echo 'restart dropin=no' >> '" + calls + "'; fi"
+			second := "tn_k3s_ca_setup"
+			if tc.first == "tn_k3s_ca_setup" {
+				second = "tn_inst_prepare server"
+			}
+			script := ". " + installLibPath + "; tn_ca_resolve_datadir; " + tc.first + "; " + second + `; echo "CHANGED=$TN_K3S_CA_CHANGED"`
+			out := p.mustSh(script, "K3S_BIN="+bin, "TN_K3S_RESTART_CMD="+restart, "TN_CGROUP_FSTYPE=tmpfs", "INSTALL_K3S_VERSION=v1.36.5+k3s1")
+			got := string(mustRead(t, calls))
+			for _, line := range []string{"rotate " + tc.want, "restart " + tc.want} {
+				if !strings.Contains(got, line) {
+					t.Errorf("%q not in the calls:\n%s\n%s", line, got, out)
+				}
+			}
+			if _, err := os.Stat(dropin); err != nil {
+				t.Errorf("the drop-in was never written:\n%s", out)
+			}
+		})
+	}
+}
+
+// ---------------------------------------------------------------- slow k3s: restart and rotate-ca
+
+func TestServiceTimeoutDefaultsToTenMinutes(t *testing.T) {
+	p := newPKI(t)
+	if out := p.mustSh(`tn_ca_svc_timeout`, "TN_K3S_SERVICE_TIMEOUT="); !strings.Contains(out, "600") {
+		t.Errorf("default timeout: %s", out)
+	}
+	if out := p.mustSh(`tn_ca_svc_timeout`, "TN_K3S_SERVICE_TIMEOUT=33"); !strings.Contains(out, "33") {
+		t.Errorf("explicit timeout: %s", out)
+	}
+	for _, f := range []string{"scripts/tn-k3s-ca.sh"} {
+		b := mustRead(t, f)
+		if strings.Contains(string(b), "(120)") && strings.Contains(string(b), "SERVICE_TIMEOUT  seconds that a stop, start or restart of k3s may take (120)") {
+			t.Errorf("%s still documents 120 s", f)
+		}
+	}
+}
+
+// fakeSlowSystemctl: `restart` takes long; the unit is `activating` for becomeActive seconds after
+// it started and `active` before and after. Every call is logged.
+func fakeSlowSystemctl(t *testing.T, becomeActive int) (log string) {
+	t.Helper()
+	dir := t.TempDir()
+	log = filepath.Join(dir, "systemctl.log")
+	write(t, filepath.Join(dir, "systemctl"), `#!/bin/sh
+echo "$*" >> '`+log+`'
+case "$1" in
+  is-active)
+    if [ -f '`+dir+`/restarted' ]; then
+      now=$(date +%s); then_=$(cat '`+dir+`/restarted')
+      if [ $((now - then_)) -lt `+itoa(becomeActive)+` ]; then echo activating; exit 3; fi
+    fi
+    echo active ;;
+  restart) date +%s > '`+dir+`/restarted'; sleep 20 ;;
+  cat) exit 0 ;;
+esac
+`)
+	if err := os.Chmod(filepath.Join(dir, "systemctl"), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	t.Setenv("PATH", dir+":"+os.Getenv("PATH"))
+	return log
+}
+
+func TestARestartThatIsSlowButGetsThereIsASuccess(t *testing.T) {
+	p := newPKI(t)
+	p.legacyCert()
+	p.legacyPKI(true)
+	write(t, p.unit, unitText())
+	fakeSlowSystemctl(t, 3)
+	bin, _ := fakeK3sVersion(t, t.TempDir(), "v1.34.11+k3s1", true)
+	start := time.Now()
+	out, err := p.sh("tn_ca_remediate all; echo \"CHANGED=$TN_K3S_CA_CHANGED\"", "K3S_BIN="+bin, "TN_K3S_SERVICE_TIMEOUT=1", "TN_K3S_READY_GRACE=20", "TN_K3S_READY_POLL=1")
+	if err != nil {
+		t.Fatalf("%v\n%s", err, out)
+	}
+	if d := time.Since(start); d > 15*time.Second {
+		t.Errorf("took %s", d)
+	}
+	for _, want := range []string{"did not finish within 1s: watching the unit", "k3s is active now", "k3s was restarted"} {
+		if !strings.Contains(out, want) {
+			t.Errorf("output lacks %q:\n%s", want, out)
+		}
+	}
+	if strings.Contains(out, "could not be restarted") {
+		t.Errorf("reported as a failure:\n%s", out)
+	}
+}
+
+func TestARestartThatNeverGetsThereIsStillReportedAfterTheGrace(t *testing.T) {
+	p := newPKI(t)
+	p.legacyCert()
+	p.legacyPKI(true)
+	write(t, p.unit, unitText())
+	fakeSlowSystemctl(t, 1000)
+	bin, _ := fakeK3sVersion(t, t.TempDir(), "v1.34.11+k3s1", true)
+	start := time.Now()
+	out, err := p.sh("tn_ca_remediate all", "K3S_BIN="+bin, "TN_K3S_SERVICE_TIMEOUT=1", "TN_K3S_READY_GRACE=3", "TN_K3S_READY_POLL=1")
+	if exitCode(err) != 5 {
+		t.Fatalf("rc=%d\n%s", exitCode(err), out)
+	}
+	if d := time.Since(start); d > 15*time.Second {
+		t.Errorf("took %s", d)
+	}
+	for _, want := range []string{"did not finish within 1s", "the unit was not active 3s later either", "datastore of k3s holds the new CA", "could not be restarted"} {
+		if !strings.Contains(out, want) {
+			t.Errorf("message lacks %q:\n%s", want, out)
+		}
+	}
+}
+
+// a k3s server that is still starting does not answer rotate-ca: it is tried again, but only when the
+// unit is there and starting or running
+func TestRotateCaIsTriedAgainWhileTheUnitStarts(t *testing.T) {
+	for _, tc := range []struct {
+		name      string
+		state     string
+		failFirst int
+		wantRC    int
+		wantCalls int
+	}{
+		{"unit activating: third try works", "activating", 2, 0, 3},
+		{"unit active: second try works", "active", 1, 0, 2},
+		{"unit activating, never answers", "activating", 100, 1, 3},
+		{"unit inactive: one try", "inactive", 100, 1, 1},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			p := newPKI(t)
+			p.legacyCert()
+			p.legacyPKI(true)
+			write(t, p.unit, unitText())
+			fakeSystemctl(t, tc.state, 0)
+			calls := filepath.Join(p.dir, "rotate.calls")
+			bin := filepath.Join(p.dir, "fake-k3s")
+			write(t, bin, "#!/bin/sh\nif [ \"$1\" = --version ]; then echo 'k3s version v1.34.11+k3s1 (0123abcd)'; exit 0; fi\n"+
+				"echo x >> '"+calls+"'\nn=$(wc -l < '"+calls+"')\nif [ \"$n\" -le "+itoa(tc.failFirst)+" ]; then echo 'connection refused' >&2; exit 1; fi\nexit 0\n")
+			if err := os.Chmod(bin, 0o755); err != nil {
+				t.Fatal(err)
+			}
+			start := time.Now()
+			out, err := p.sh("tn_ca_remediate all", "K3S_BIN="+bin, "TN_K3S_RESTART_CMD=true", "TN_K3S_ROTATE_TRIES=3", "TN_K3S_ROTATE_WAIT=1")
+			if exitCode(err) != tc.wantRC {
+				t.Fatalf("rc=%d, want %d\n%s", exitCode(err), tc.wantRC, out)
+			}
+			if n := strings.Count(string(readLog(calls)), "x\n"); n != tc.wantCalls {
+				t.Errorf("rotate-ca was called %d times, want %d\n%s", n, tc.wantCalls, out)
+			}
+			if d := time.Since(start); d > 12*time.Second {
+				t.Errorf("took %s", d)
+			}
+			if tc.wantRC == 1 && !strings.Contains(out, "were not changed") {
+				t.Errorf("a failed rotation does not say that the CA was not changed:\n%s", out)
+			}
+			if tc.wantRC == 0 && tc.wantCalls > 1 && !strings.Contains(out, "trying again in 1s") {
+				t.Errorf("no word about the retry:\n%s", out)
+			}
+		})
+	}
+}
+
+// ---------------------------------------------------------------- the data dir must agree with config.yaml
+
+func TestDataDirThatDisagreesWithConfigYamlIsRefused(t *testing.T) {
+	for _, tc := range []struct {
+		name   string
+		unit   func(dd string) string
+		file   string // relative to the k3s config dir
+		cfg    func(other string) string
+		useEnv bool // the data dir is given as DATA_DIR
+		wantOK bool
+		msgs   func(dd, other string) []string
+	}{
+		{name: "ExecStart --data-dir and another data-dir in config.yaml", unit: func(dd string) string { return unitText("--data-dir", dd) },
+			file: "config.yaml", cfg: func(o string) string { return "data-dir: " + o + "\n" },
+			msgs: func(dd, o string) []string {
+				return []string{"k3s runs from " + dd + " (ExecStart of k3s.service)", "config.yaml sets data-dir: " + o, "without --data-dir", "The CA and k3s were not changed"}
+			}},
+		{name: "ExecStart --data-dir=... and another data-dir in config.yaml.d", unit: func(dd string) string { return unitText("--data-dir=" + dd) },
+			file: "config.yaml.d/50-x.yaml", cfg: func(o string) string { return "data-dir: \"" + o + "\"\n" },
+			msgs: func(dd, o string) []string { return []string{"k3s runs from " + dd, "50-x.yaml sets data-dir: " + o} }},
+		{name: "an explicit DATA_DIR and another data-dir in config.yaml", unit: func(string) string { return unitText() }, useEnv: true,
+			file: "config.yaml", cfg: func(o string) string { return "data-dir: " + o + "\n" },
+			msgs: func(dd, o string) []string { return []string{"k3s runs from " + dd + " (--data-dir / DATA_DIR)"} }},
+		{name: "the same data dir in both, with a trailing slash", unit: func(dd string) string { return unitText("--data-dir", dd) },
+			file: "config.yaml", cfg: func(o string) string { return "data-dir: DD/\n" }, wantOK: true},
+		{name: "config.yaml is the source", unit: func(string) string { return unitText() },
+			file: "config.yaml", cfg: func(o string) string { return "data-dir: DD\n" }, wantOK: true},
+		{name: "no data-dir in config.yaml", unit: func(dd string) string { return unitText("--data-dir", dd) },
+			file: "config.yaml", cfg: func(o string) string { return "node-name: x\n" }, wantOK: true},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			p := newPKI(t)
+			p.legacyCert()
+			dd := filepath.Join(p.dir, "srv-k3s")
+			other := filepath.Join(p.dir, "var-other")
+			write(t, p.unit, tc.unit(dd))
+			write(t, filepath.Join(p.k3sCfg, tc.file), strings.ReplaceAll(tc.cfg(other), "DD", dd))
+			env := []string{"DATA_DIR="}
+			if tc.useEnv {
+				env = []string{"DATA_DIR=" + dd}
+			}
+			out, err := p.sh("tn_ca_resolve_datadir; if tn_ca_datadir_consistent; then echo CONSISTENT; else echo INCONSISTENT; fi", env...)
+			if err != nil {
+				t.Fatalf("%v\n%s", err, out)
+			}
+			if got := strings.Contains("\n"+out, "\nCONSISTENT"); got != tc.wantOK {
+				t.Errorf("consistent=%v, want %v\n%s", got, tc.wantOK, out)
+			}
+			if tc.wantOK {
+				return
+			}
+			// the setup stops, before it creates anything
+			setup, serr := p.sh("tn_k3s_ca_setup", env...)
+			if exitCode(serr) != 1 {
+				t.Fatalf("setup went on (rc=%d):\n%s", exitCode(serr), setup)
+			}
+			for _, m := range tc.msgs(dd, other) {
+				if !strings.Contains(setup, m) {
+					t.Errorf("message lacks %q:\n%s", m, setup)
+				}
+			}
+			for _, d := range []string{dd, other} {
+				if _, err := os.Stat(filepath.Join(d, "server")); err == nil {
+					t.Errorf("%s/server was created", d)
+				}
+			}
+		})
+	}
+}
+
+// the dash/bash differences of the new code are covered by the plain-shell test of the libraries;
+// this one runs the new install code under dash as well, as a device with /bin/sh = dash does
+func TestNewInstallCodeRunsUnderDash(t *testing.T) {
+	if _, err := exec.LookPath("dash"); err != nil {
+		t.Skip("no dash")
+	}
+	i := newInst(t)
+	i.installed("")
+	cmd := exec.Command("dash", "-c", "set -e; set -o noglob; umask 027; . "+installLibPath+"; tn_inst_prepare agent; "+resultLine)
+	cmd.Env = append(os.Environ(), "TN_K3S_CONFIG_DIR="+i.k3sCfg, "K3S_BIN="+i.bin, "DATA_DIR="+filepath.Join(i.dir, "data"), "TN_CGROUP_FSTYPE=tmpfs",
+		"K3S_URL="+agentURL, "TN_K3S_PIN_SOURCE=default", "INSTALL_K3S_VERSION=v1.36.5+k3s1", "TN_TEST_PUBLISHED=v1.35.9+k3s1")
+	out, err := cmd.CombinedOutput()
+	if err != nil || result(t, string(out)) != "version=v1.35.9+k3s1 channel=unset action=install effective=v1.35.9+k3s1" {
+		t.Fatalf("%v\n%s", err, out)
+	}
+	if _, err := os.Stat(i.dropin()); err != nil {
+		t.Error("no drop-in on cgroup v1")
+	}
+}
+
+// ---------------------------------------------------------------- the server publishes its release
+
+func (i *inst) published() string {
+	return filepath.Join(i.dir, "data", "server", "static", "teknoir", "k3s-version")
+}
+
+func TestServerPublishesItsRelease(t *testing.T) {
+	i := newInst(t)
+	i.installed("v1.34.11+k3s1")
+	out, err := i.run("tn_inst_publish_release")
+	if err != nil || !strings.Contains(out, "Published the k3s release v1.34.11+k3s1 for the agents") {
+		t.Fatalf("%v\n%s", err, out)
+	}
+	if got := string(mustRead(t, i.published())); got != "v1.34.11+k3s1\n" {
+		t.Errorf("file: %q", got)
+	}
+	// the library of the agent reads exactly that file back
+	ent, _ := os.ReadDir(filepath.Dir(i.published()))
+	if len(ent) != 1 {
+		t.Errorf("temporary files left: %v", ent)
+	}
+	// unchanged when right: same inode
+	st1, _ := os.Stat(i.published())
+	out, err = i.run("tn_inst_publish_release")
+	st2, _ := os.Stat(i.published())
+	if err != nil || !strings.Contains(out, "already published") || !os.SameFile(st1, st2) {
+		t.Errorf("not idempotent: %v\n%s", err, out)
+	}
+	// k3s was upgraded: the file follows
+	i.installed("v1.35.9+k3s1")
+	out, err = i.run("tn_inst_publish_release")
+	if err != nil || string(mustRead(t, i.published())) != "v1.35.9+k3s1\n" {
+		t.Errorf("not updated: %v\n%s", err, out)
+	}
+	// a leftover temporary file of a killed run does not matter
+	write(t, filepath.Join(filepath.Dir(i.published()), ".k3s-version.tmp.1"), "x")
+	i.installed("v1.36.5+k3s1")
+	if out, err = i.run("tn_inst_publish_release"); err != nil || string(mustRead(t, i.published())) != "v1.36.5+k3s1\n" {
+		t.Errorf("%v\n%s", err, out)
+	}
+}
+
+func TestPublishNeverFailsTheScript(t *testing.T) {
+	// the version of k3s cannot be read
+	i := newInst(t)
+	i.installed("")
+	out, err := i.run("tn_inst_publish_release; echo AFTER")
+	if err != nil || !strings.Contains(out, "AFTER") || !strings.Contains(out, "cannot read the release of the installed k3s") {
+		t.Errorf("%v\n%s", err, out)
+	}
+	if _, serr := os.Stat(i.published()); serr == nil {
+		t.Error("something was published")
+	}
+	// the directory is not writable
+	if os.Geteuid() != 0 {
+		j := newInst(t)
+		j.installed("v1.34.11+k3s1")
+		dd := filepath.Join(j.dir, "data")
+		if err := os.MkdirAll(dd, 0o555); err != nil {
+			t.Fatal(err)
+		}
+		defer os.Chmod(dd, 0o755)
+		out, err = j.run("tn_inst_publish_release; echo AFTER")
+		if err != nil || !strings.Contains(out, "AFTER") || !strings.Contains(out, "cannot publish the k3s release") {
+			t.Errorf("%v\n%s", err, out)
+		}
+	}
+}
+
+// what the server publishes is what an agent reads and follows
+func TestAgentReadsWhatTheServerPublishes(t *testing.T) {
+	srv := newInst(t)
+	srv.installed("v1.34.11+k3s1")
+	srv.mustRun("tn_inst_publish_release")
+	agent := newInst(t)
+	agent.installed("")
+	out, err := agent.run("tn_inst_prepare agent; "+resultLine, "TN_CGROUP_FSTYPE=cgroup2fs", "K3S_URL="+agentURL, "TN_K3S_PIN_SOURCE=default",
+		"INSTALL_K3S_VERSION=v1.36.5+k3s1", "TN_TEST_PUBLISHED="+strings.TrimSpace(string(mustRead(t, srv.published()))))
+	if err != nil || result(t, out) != "version=v1.34.11+k3s1 channel=unset action=install effective=v1.34.11+k3s1" {
+		t.Fatalf("%v\n%s", err, out)
+	}
+}
+
+func (i *inst) mustRun(script string, env ...string) string {
+	i.t.Helper()
+	out, err := i.run(script, env...)
+	if err != nil {
+		i.t.Fatalf("%v\n%s", err, out)
+	}
+	return out
+}
+
+func TestServerScriptPublishesAfterTheInstallerAndTheAgentDoesNot(t *testing.T) {
+	srv := renderK3S(t, ServerTemplate, "")
+	inst := strings.Index(srv, "\n$SUDO ./k3s_installer.sh")
+	pub := strings.Index(srv, "\ntn_inst_publish_release\n")
+	manifests := strings.Index(srv, `info "Install Teknoir Manifests"`)
+	if !(inst > 0 && inst < pub && pub < manifests) {
+		t.Errorf("installer %d, publish %d, manifests %d", inst, pub, manifests)
+	}
+	if ag := renderK3S(t, AgentTemplate, ""); strings.Contains(ag, "\ntn_inst_publish_release\n") {
+		t.Error("the agent script publishes a release")
+	}
+}
diff --git a/pkg/templates/k3sinstall_test.go b/pkg/templates/k3sinstall_test.go
new file mode 100644
index 0000000..21a3970
--- /dev/null
+++ b/pkg/templates/k3sinstall_test.go
@@ -0,0 +1,880 @@
+package templates
+
+import (
+	"bytes"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+// Offline tests of scripts/tn-k3s-install.sh: the k3s release policy of a re-run, and the kubelet
+// flag for cgroup v1 hosts. The docker harness in test/k3s-ca runs the same library with real k3s.
+
+const installLibPath = "scripts/tn-k3s-install.sh"
+
+type inst struct {
+	t       *testing.T
+	dir     string
+	k3sCfg  string // TN_K3S_CONFIG_DIR
+	bin     string // K3S_BIN (a fake k3s)
+	curlLog string // the calls of the fake curl
+}
+
+func newInst(t *testing.T) *inst {
+	t.Helper()
+	needTool(t, "sh")
+	i := &inst{t: t, dir: t.TempDir()}
+	i.k3sCfg = filepath.Join(i.dir, "rancher-k3s")
+	// the GNU info reader must never be called by the library
+	fake := filepath.Join(i.dir, "bin")
+	write(t, filepath.Join(fake, "info"), "#!/bin/sh\necho GNU-INFO-WAS-CALLED \"$*\" >&2\nexit 1\n")
+	if err := os.Chmod(filepath.Join(fake, "info"), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	// the server of an agent: `curl` answers like the supervisor of k3s. /static/teknoir/k3s-version is
+	// the release that the Teknoir server script published (TN_TEST_PUBLISHED, anything is served
+	// as it is); /version is the anonymous answer of a server that allows one (TN_TEST_SERVER_VERSION or
+	// TN_TEST_SERVER_BODY). Everything else is a 404 (curl -f: exit 22). TN_TEST_SERVER_DOWN: nothing
+	// answers (exit 7); TN_TEST_FAIL_N: the first N calls fail like that. Every call is logged.
+	i.curlLog = filepath.Join(i.dir, "curl.log")
+	write(t, filepath.Join(fake, "curl"), `#!/bin/sh
+echo "$*" >> '`+i.curlLog+`'
+for a in "$@"; do url=$a; done
+if [ -n "$TN_TEST_SERVER_DOWN" ]; then exit 7; fi
+n=$(wc -l < '`+i.curlLog+`'); if [ "$n" -le "${TN_TEST_FAIL_N:-0}" ]; then exit 7; fi
+case "$url" in
+  */static/teknoir/k3s-version)
+    if [ -n "$TN_TEST_PUBLISHED" ]; then printf '%s\n' "$TN_TEST_PUBLISHED"; exit 0; fi
+    exit 22 ;;
+  */version)
+    if [ -n "$TN_TEST_SERVER_BODY" ]; then printf '%s' "$TN_TEST_SERVER_BODY"; exit 0; fi
+    if [ -n "$TN_TEST_SERVER_VERSION" ]; then
+      printf '{\n  "major": "1",\n  "minor": "34",\n  "gitVersion": "%s",\n  "gitCommit": "0123abcd",\n  "goVersion": "go1.24.1"\n}' "$TN_TEST_SERVER_VERSION"; exit 0
+    fi
+    exit 22 ;;
+esac
+exit 22
+`)
+	if err := os.Chmod(filepath.Join(fake, "curl"), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	t.Setenv("PATH", fake+":"+os.Getenv("PATH"))
+	return i
+}
+
+// curlCalls is what the library asked the (fake) server for
+func (i *inst) curlCalls() string { return readLog(i.curlLog) }
+
+// installed makes `k3s --version` answer like the real one; "" = no k3s.
+func (i *inst) installed(version string) {
+	i.t.Helper()
+	i.bin = filepath.Join(i.dir, "fake-k3s")
+	if version == "" {
+		i.bin = filepath.Join(i.dir, "no-such-k3s")
+		return
+	}
+	script := "#!/bin/sh\nif [ \"$1\" = --version ]; then echo 'k3s version " + version + " (0123abcd)'; echo 'go version go1.24.1'; exit 0; fi\nexit 1\n"
+	write(i.t, i.bin, script)
+	if err := os.Chmod(i.bin, 0o755); err != nil {
+		i.t.Fatal(err)
+	}
+}
+
+// run sources the library under the bootstrap script shell options and runs script. Environment
+// of the machine that starts with INSTALL_K3S_, TN_K3S_ or TN_CGROUP is dropped.
+func (i *inst) run(script string, env ...string) (string, error) {
+	i.t.Helper()
+	full := "set -e; set -o noglob; umask 027; . " + installLibPath + "; " + script
+	cmd := exec.Command("sh", "-c", full)
+	for _, e := range os.Environ() {
+		if strings.HasPrefix(e, "INSTALL_K3S_") || strings.HasPrefix(e, "TN_K3S_") || strings.HasPrefix(e, "TN_CGROUP") || strings.HasPrefix(e, "OS_BUILD") || strings.HasPrefix(e, "K3S_BIN") || strings.HasPrefix(e, "K3S_URL") || strings.HasPrefix(e, "DATA_DIR") || strings.HasPrefix(e, "TN_TEST_") {
+			continue
+		}
+		cmd.Env = append(cmd.Env, e)
+	}
+	cmd.Env = append(cmd.Env, "TN_K3S_CONFIG_DIR="+i.k3sCfg, "K3S_BIN="+i.bin, "DATA_DIR="+filepath.Join(i.dir, "data"), "TN_K3S_SERVER_VERSION_WAIT=0")
+	cmd.Env = append(cmd.Env, env...)
+	out, err := cmd.CombinedOutput()
+	if bytes.Contains(out, []byte("GNU-INFO-WAS-CALLED")) {
+		i.t.Errorf("the info binary was called:\n%s", out)
+	}
+	return string(out), err
+}
+
+const resultLine = `echo "RESULT version=${INSTALL_K3S_VERSION-unset} channel=${INSTALL_K3S_CHANNEL-unset} action=$TN_INST_ACTION effective=$TN_INST_EFFECTIVE"`
+
+func result(t *testing.T, out string) string {
+	t.Helper()
+	for _, l := range strings.Split(out, "\n") {
+		if strings.HasPrefix(l, "RESULT ") {
+			return strings.TrimPrefix(l, "RESULT ")
+		}
+	}
+	t.Fatalf("no RESULT line:\n%s", out)
+	return ""
+}
+
+func (i *inst) dropin() string {
+	return filepath.Join(i.k3sCfg, "config.yaml.d", "99-teknoir-cgroupv1.yaml")
+}
+
+// ---------------------------------------------------------------- the library itself
+
+func TestK3sInstallLibraryIsPlainShell(t *testing.T) {
+	b, err := os.ReadFile(installLibPath)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if bytes.Contains(b, []byte("{{")) {
+		t.Fatal("the library is embedded as a template: it must not contain '{{'")
+	}
+	for _, sh := range []string{"sh", "dash", "bash"} {
+		if _, err := exec.LookPath(sh); err != nil {
+			continue
+		}
+		if out, err := exec.Command(sh, "-n", installLibPath).CombinedOutput(); err != nil {
+			t.Errorf("%s -n: %v\n%s", sh, err, out)
+		}
+	}
+	if string(b) != TnK3sInstallScript {
+		t.Error("embedded TnK3sInstallScript differs from the file")
+	}
+	for _, bad := range []string{"\ntrap ", "\n  trap ", "set +o noglob", "set -x", "local "} {
+		if strings.Contains(string(b), bad) {
+			t.Errorf("library must not contain %q", bad)
+		}
+	}
+}
+
+func TestVersionParseAndCompare(t *testing.T) {
+	i := newInst(t)
+	for _, tc := range []struct {
+		a, b string
+		want string // -1, 0, 1, or "err"
+	}{
+		{"v1.34.11+k3s1", "v1.36.5+k3s1", "-1"},
+		{"v1.36.5+k3s1", "v1.36.5+k3s1", "0"},
+		{"v1.36.5+k3s2", "v1.36.5+k3s1", "1"},
+		{"v1.36.10+k3s1", "v1.36.9+k3s3", "1"}, // numeric, not lexical
+		{"v1.9.0+k3s1", "v1.10.0+k3s1", "-1"},
+		{"v1.36.5", "v1.36.5+k3s1", "-1"}, // no revision is revision 0
+		{"v1.36.5+k3s1", "v1.36.4+k3s9", "1"},
+		{"v1.35.0", "v1.35.0", "0"},
+		{"stable", "v1.36.5+k3s1", "err"},
+		{"", "v1.36.5+k3s1", "err"},
+		{"v1.36.5+k3s1", "latest", "err"},
+		{"v1.36+k3s1", "v1.36.5+k3s1", "err"},
+		{"1.36.5+k3s1", "v1.36.5+k3s1", "err"},
+		{"v1.36.5-rc1+k3s1", "v1.36.5+k3s1", "err"},
+	} {
+		want := tc.want
+		out, err := i.run(`A='` + tc.a + `'; B='` + tc.b + `'; if tn_inst_cmp "$A" "$B"; then echo "CMP $TN_INST_CMP"; else echo "CMP err"; fi`)
+		if err != nil {
+			t.Fatalf("%q vs %q: %v\n%s", tc.a, tc.b, err, out)
+		}
+		if !strings.Contains(out, "CMP "+want+"\n") {
+			t.Errorf("%q vs %q: want %s, got\n%s", tc.a, tc.b, want, out)
+		}
+	}
+}
+
+func TestInstalledVersionIsReadFromTheRealOutput(t *testing.T) {
+	i := newInst(t)
+	for _, v := range []string{"v1.34.11+k3s1", "v1.36.5+k3s1", "v1.27.0+k3s2", "v1.30.2"} {
+		i.installed(v)
+		out, err := i.run(`tn_inst_installed_version; echo "INSTALLED=$TN_INST_INSTALLED"`)
+		if err != nil || !strings.Contains(out, "INSTALLED="+v+"\n") {
+			t.Errorf("%s: %v\n%s", v, err, out)
+		}
+	}
+	i.installed("")
+	out, err := i.run(`tn_inst_installed_version; echo "INSTALLED=$TN_INST_INSTALLED"`)
+	if err != nil || !strings.Contains(out, "INSTALLED=\n") {
+		t.Errorf("no k3s: %v\n%s", err, out)
+	}
+	// a K3S_BIN with arguments, like the harness' "docker exec srv k3s"
+	i.installed("v1.36.5+k3s1")
+	out, err = i.run(`tn_inst_installed_version; echo "INSTALLED=$TN_INST_INSTALLED"`, "K3S_BIN=env FAKE=1 "+i.bin)
+	if err != nil || !strings.Contains(out, "INSTALLED=v1.36.5+k3s1\n") {
+		t.Errorf("K3S_BIN with arguments: %v\n%s", err, out)
+	}
+}
+
+// ---------------------------------------------------------------- the release policy
+
+func TestReleasePolicy(t *testing.T) {
+	const pin = "v1.36.5+k3s1"
+	for _, tc := range []struct {
+		name      string
+		installed string
+		env       []string // besides INSTALL_K3S_VERSION=pin
+		pin       string   // default: pin
+		wantRC    int
+		want      string   // RESULT
+		msgs      []string // in the output
+		notMsgs   []string
+	}{
+		{name: "fresh device installs the pin", installed: "", want: "version=" + pin + " channel=unset action=install effective=" + pin},
+		{name: "re-run on the same release", installed: pin, want: "version=" + pin + " channel=unset action=same effective=" + pin, msgs: []string{"installed again, nothing is upgraded"}},
+		{name: "older k3s is KEPT, not upgraded", installed: "v1.34.11+k3s1",
+			want: "version=v1.34.11+k3s1 channel=unset action=keep effective=v1.34.11+k3s1",
+			msgs: []string{"k3s v1.34.11+k3s1 is kept", "TN_K3S_UPGRADE=true", "NOT installed"}},
+		{name: "newer k3s is kept, no downgrade", installed: "v1.37.0+k3s1",
+			want: "version=v1.37.0+k3s1 channel=unset action=keep effective=v1.37.0+k3s1",
+			msgs: []string{"OLDER than the installed", "cannot be downgraded"}},
+		{name: "a newer revision of the same patch is kept", installed: "v1.36.5+k3s2",
+			want: "version=v1.36.5+k3s2 channel=unset action=keep effective=v1.36.5+k3s2"},
+		{name: "channel pin and installed k3s: the installed release", installed: "v1.35.9+k3s1", pin: "-", env: []string{"INSTALL_K3S_CHANNEL=latest"},
+			want: "version=v1.35.9+k3s1 channel=unset action=keep effective=v1.35.9+k3s1"},
+		{name: "no pin at all (stable) and installed k3s", installed: "v1.35.9+k3s1", pin: "-",
+			want: "version=v1.35.9+k3s1 channel=unset action=keep effective=v1.35.9+k3s1"},
+		{name: "no pin at all and no k3s: the installer decides", installed: "", pin: "-",
+			want: "version=unset channel=unset action=install effective="},
+
+		// explicit opt-in
+		{name: "upgrade one minor", installed: "v1.35.9+k3s1", env: []string{"TN_K3S_UPGRADE=true"},
+			want: "version=" + pin + " channel=unset action=upgrade effective=" + pin, msgs: []string{"upgrading k3s from v1.35.9+k3s1 to " + pin}},
+		{name: "upgrade within the minor", installed: "v1.36.2+k3s1", env: []string{"TN_K3S_UPGRADE=true"},
+			want: "version=" + pin + " channel=unset action=upgrade effective=" + pin},
+		{name: "upgrade, same release", installed: pin, env: []string{"TN_K3S_UPGRADE=true"},
+			want: "version=" + pin + " channel=unset action=same effective=" + pin},
+		{name: "upgrade is refused over two minors", installed: "v1.34.11+k3s1", env: []string{"TN_K3S_UPGRADE=true"}, wantRC: 1,
+			msgs: []string{"more than one minor version", "v1.34 -> v1.36", "v1.35.x first", "TN_K3S_FORCE=true", "Nothing was changed"}},
+		{name: "upgrade over two minors with force warns", installed: "v1.34.11+k3s1", env: []string{"TN_K3S_UPGRADE=true", "TN_K3S_FORCE=true"},
+			want: "version=" + pin + " channel=unset action=upgrade effective=" + pin, msgs: []string{"skips minor versions", "backup"}},
+		{name: "force alone does not upgrade", installed: "v1.34.11+k3s1", env: []string{"TN_K3S_FORCE=true"},
+			want: "version=v1.34.11+k3s1 channel=unset action=keep effective=v1.34.11+k3s1"},
+		{name: "downgrade is refused with upgrade", installed: "v1.37.1+k3s1", env: []string{"TN_K3S_UPGRADE=true"}, wantRC: 1,
+			msgs: []string{"refusing to downgrade k3s from v1.37.1+k3s1 to " + pin, "Nothing was changed"}},
+		{name: "downgrade is refused with force too", installed: "v1.37.1+k3s1", env: []string{"TN_K3S_UPGRADE=true", "TN_K3S_FORCE=true"}, wantRC: 1,
+			msgs: []string{"refusing to downgrade"}},
+		{name: "a lower patch is a downgrade", installed: "v1.36.6+k3s1", env: []string{"TN_K3S_UPGRADE=true"}, wantRC: 1, msgs: []string{"refusing to downgrade"}},
+		{name: "a lower k3s revision is a downgrade", installed: "v1.36.5+k3s2", env: []string{"TN_K3S_UPGRADE=true"}, wantRC: 1, msgs: []string{"refusing to downgrade"}},
+		{name: "upgrade to a channel cannot be checked", installed: "v1.34.11+k3s1", pin: "-", env: []string{"TN_K3S_UPGRADE=true"},
+			want: "version=unset channel=unset action=upgrade effective=", msgs: []string{"not an exact release", "cannot be checked"}},
+		{name: "upgrade of a fresh device is just an install", installed: "", env: []string{"TN_K3S_UPGRADE=true"},
+			want: "version=" + pin + " channel=unset action=install effective=" + pin},
+		{name: "TN_K3S_UPGRADE=false is a keep", installed: "v1.34.11+k3s1", env: []string{"TN_K3S_UPGRADE=false"},
+			want: "version=v1.34.11+k3s1 channel=unset action=keep effective=v1.34.11+k3s1"},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			i := newInst(t)
+			i.installed(tc.installed)
+			env := append([]string{}, tc.env...)
+			p := tc.pin
+			if p == "" {
+				p = pin
+			}
+			script := ""
+			if p != "-" {
+				env = append(env, "INSTALL_K3S_VERSION="+p)
+			}
+			// cgroup v2: this test is about the release
+			env = append(env, "TN_CGROUP_FSTYPE=cgroup2fs")
+			script += "tn_inst_plan; " + resultLine
+			out, err := i.run(script, env...)
+			if rc := exitCode(err); rc != tc.wantRC {
+				t.Fatalf("rc=%d, want %d\n%s", rc, tc.wantRC, out)
+			}
+			if tc.wantRC == 0 {
+				if got := result(t, out); got != tc.want {
+					t.Errorf("result\n got  %s\n want %s\n%s", got, tc.want, out)
+				}
+			} else if strings.Contains(out, "RESULT") {
+				t.Errorf("the script went on after the refusal:\n%s", out)
+			}
+			for _, m := range tc.msgs {
+				if !strings.Contains(out, m) {
+					t.Errorf("output lacks %q:\n%s", m, out)
+				}
+			}
+			for _, m := range tc.notMsgs {
+				if strings.Contains(out, m) {
+					t.Errorf("output has %q:\n%s", m, out)
+				}
+			}
+		})
+	}
+}
+
+// ---------------------------------------------------------------- cgroup v1
+
+func TestCgroupV1WritesTheKubeletFlag(t *testing.T) {
+	const want = "kubelet-arg+:\n  - \"fail-cgroupv1=false\"\n"
+	for _, tc := range []struct {
+		name      string
+		installed string
+		version   string // INSTALL_K3S_VERSION
+		env       []string
+		file      bool
+		msgs      []string
+		notMsgs   []string
+	}{
+		{name: "cgroup v1 and k3s v1.36.5", version: "v1.36.5+k3s1", env: []string{"TN_CGROUP_FSTYPE=tmpfs"}, file: true,
+			msgs: []string{"cgroup v1 is deprecated", "Set the kubelet argument fail-cgroupv1=false"}},
+		{name: "the hybrid layout is v1", version: "v1.36.5+k3s1", env: []string{"TN_CGROUP_FSTYPE=tmpfs"}, file: true},
+		{name: "exactly v1.35.0", version: "v1.35.0+k3s1", env: []string{"TN_CGROUP_FSTYPE=tmpfs"}, file: true},
+		{name: "cgroup v1 and k3s v1.34.11: set for a later upgrade", version: "v1.34.11+k3s1", env: []string{"TN_CGROUP_FSTYPE=tmpfs"}, file: true,
+			msgs: []string{"cgroup v1 is deprecated", "starts on cgroup v1 without help", "an upgrade to v1.35 or newer"}},
+		{name: "exactly v1.31.0", version: "v1.31.0+k3s1", env: []string{"TN_CGROUP_FSTYPE=tmpfs"}, file: true},
+		{name: "cgroup v1 and k3s v1.30.14: the kubelet has no such flag", version: "v1.30.14+k3s1", env: []string{"TN_CGROUP_FSTYPE=tmpfs"}, file: false,
+			msgs: []string{"cgroup v1 is deprecated", "older than v1.31"}},
+		{name: "cgroup v2 needs nothing", version: "v1.36.5+k3s1", env: []string{"TN_CGROUP_FSTYPE=cgroup2fs"}, file: false, notMsgs: []string{"deprecated"}},
+		{name: "cgroup v1 and a channel: k3s is new", version: "", env: []string{"TN_CGROUP_FSTYPE=tmpfs"}, file: true},
+		{name: "an installed k3s that is kept decides", installed: "v1.34.11+k3s1", version: "v1.36.5+k3s1", env: []string{"TN_CGROUP_FSTYPE=tmpfs"}, file: true,
+			msgs: []string{"without help"}},
+		{name: "an old installed k3s that is kept gets no flag", installed: "v1.30.14+k3s1", version: "v1.36.5+k3s1", env: []string{"TN_CGROUP_FSTYPE=tmpfs"}, file: false,
+			msgs: []string{"older than v1.31"}},
+		{name: "upgrading to v1.36 needs it", installed: "v1.35.9+k3s1", version: "v1.36.5+k3s1", env: []string{"TN_CGROUP_FSTYPE=tmpfs", "TN_K3S_UPGRADE=true"}, file: true},
+		{name: "an OS build cannot tell: set it", version: "v1.36.5+k3s1", env: []string{"OS_BUILD=true", "TN_CGROUP_FSTYPE=cgroup2fs"}, file: true,
+			msgs: []string{"cannot tell whether the device uses cgroup v1"}},
+		{name: "TN_K3S_CGROUPV1=true forces", version: "v1.36.5+k3s1", env: []string{"TN_K3S_CGROUPV1=true", "TN_CGROUP_FSTYPE=cgroup2fs"}, file: true},
+		{name: "TN_K3S_CGROUPV1=false forces", version: "v1.36.5+k3s1", env: []string{"TN_K3S_CGROUPV1=false", "TN_CGROUP_FSTYPE=tmpfs"}, file: false},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			i := newInst(t)
+			i.installed(tc.installed)
+			env := append([]string{}, tc.env...)
+			if tc.version != "" {
+				env = append(env, "INSTALL_K3S_VERSION="+tc.version)
+			}
+			out, err := i.run("tn_inst_prepare server", env...)
+			if err != nil {
+				t.Fatalf("%v\n%s", err, out)
+			}
+			b, rerr := os.ReadFile(i.dropin())
+			if tc.file {
+				if rerr != nil || string(b[strings.Index(string(b), "\nkubelet-arg+:")+1:]) != want {
+					t.Errorf("drop-in: %v\n%s", rerr, b)
+				}
+				if !strings.Contains(string(b), "cgroup v2") {
+					t.Errorf("the drop-in does not say what to do about it:\n%s", b)
+				}
+			} else if rerr == nil {
+				t.Errorf("a drop-in was written:\n%s", b)
+			}
+			for _, m := range tc.msgs {
+				if !strings.Contains(out, m) {
+					t.Errorf("output lacks %q:\n%s", m, out)
+				}
+			}
+			for _, m := range tc.notMsgs {
+				if strings.Contains(out, m) {
+					t.Errorf("output has %q:\n%s", m, out)
+				}
+			}
+		})
+	}
+}
+
+func TestCgroupV1IsIdempotentAndKeepsTheUsersKubeletArgs(t *testing.T) {
+	i := newInst(t)
+	i.installed("")
+	userCfg := "kubelet-arg:\n  - max-pods=77\n  - \"eviction-hard=memory.available<100Mi\"\nnode-name: mine\n"
+	write(t, filepath.Join(i.k3sCfg, "config.yaml"), userCfg)
+	write(t, filepath.Join(i.k3sCfg, "config.yaml.d", "10-user.yaml"), "kubelet-arg+:\n  - v=2\n")
+	env := []string{"TN_CGROUP_FSTYPE=tmpfs", "INSTALL_K3S_VERSION=v1.36.5+k3s1"}
+	for n := 0; n < 3; n++ {
+		out, err := i.run("tn_inst_prepare server", env...)
+		if err != nil {
+			t.Fatalf("run %d: %v\n%s", n, err, out)
+		}
+		if n > 0 && !strings.Contains(out, "already in place") {
+			t.Errorf("run %d did not notice the file:\n%s", n, out)
+		}
+	}
+	if b, _ := os.ReadFile(filepath.Join(i.k3sCfg, "config.yaml")); string(b) != userCfg {
+		t.Errorf("config.yaml of the user was changed:\n%s", b)
+	}
+	if b, _ := os.ReadFile(filepath.Join(i.k3sCfg, "config.yaml.d", "10-user.yaml")); string(b) != "kubelet-arg+:\n  - v=2\n" {
+		t.Errorf("the user's drop-in was changed:\n%s", b)
+	}
+	m, _ := filepath.Glob(filepath.Join(i.k3sCfg, "config.yaml.d", "*"))
+	if len(m) != 2 {
+		t.Errorf("files: %v", m)
+	}
+	// ours is the last one in lexical order, so `+` appends to whatever came before
+	if filepath.Base(m[len(m)-1]) != "99-teknoir-cgroupv1.yaml" {
+		t.Errorf("order: %v", m)
+	}
+}
+
+func TestCgroupV1DropinGoesWhenNotNeeded(t *testing.T) {
+	i := newInst(t)
+	i.installed("")
+	env := []string{"TN_CGROUP_FSTYPE=tmpfs", "INSTALL_K3S_VERSION=v1.36.5+k3s1"}
+	i.run("tn_inst_prepare server", env...)
+	if _, err := os.Stat(i.dropin()); err != nil {
+		t.Fatal("not written")
+	}
+	// the device moved to cgroup v2
+	out, err := i.run("tn_inst_prepare server", "TN_CGROUP_FSTYPE=cgroup2fs", "INSTALL_K3S_VERSION=v1.36.5+k3s1")
+	if err != nil || !strings.Contains(out, "Removed") {
+		t.Fatalf("%v\n%s", err, out)
+	}
+	if _, err := os.Stat(i.dropin()); err == nil {
+		t.Error("the drop-in is still there on cgroup v2")
+	}
+}
+
+func TestCgroupV1RespectsTheDevicesOwnSetting(t *testing.T) {
+	// the device sets the flag in a file that the running k3s reads: our drop-in goes, theirs wins
+	for name, tc := range map[string]struct{ file, content string }{
+		"config.yaml":       {"config.yaml", "kubelet-arg:\n  - fail-cgroupv1=false\n"},
+		"config.yaml.d":     {"config.yaml.d/10-user.yaml", "kubelet-arg+:\n  - fail-cgroupv1=false\n"},
+		"config.yaml.d yml": {"config.yaml.d/10-user.yml", "kubelet-arg+: [\"fail-cgroupv1=false\"]\n"},
+		"trailing comment":  {"config.yaml", "kubelet-arg:\n  - 'fail-cgroupv1=false' # on purpose\n"},
+	} {
+		t.Run(name, func(t *testing.T) {
+			i := newInst(t)
+			i.installed("")
+			write(t, filepath.Join(i.k3sCfg, tc.file), tc.content)
+			write(t, i.dropin(), "kubelet-arg+:\n  - \"fail-cgroupv1=false\"\n")
+			out, err := i.run("tn_inst_prepare server", "TN_CGROUP_FSTYPE=tmpfs", "INSTALL_K3S_VERSION=v1.36.5+k3s1")
+			if err != nil || !strings.Contains(out, "set by the device itself") {
+				t.Fatalf("%v\n%s", err, out)
+			}
+			if _, err := os.Stat(i.dropin()); err == nil {
+				t.Error("our drop-in overrides the device's own setting")
+			}
+		})
+	}
+}
+
+// A comment, and fail-cgroupv1=true, are not "the device sets it itself": our drop-in is written, and an
+// existing one stays. (A device that sets fail-cgroupv1=true on cgroup v1 on purpose is not supported.)
+func TestCgroupV1DeviceSettingThatDoesNotCount(t *testing.T) {
+	for name, tc := range map[string]struct{ file, content string }{
+		"commented in config.yaml":         {"config.yaml", "kubelet-arg:\n  # - fail-cgroupv1=false\n  - v=2\n"},
+		"commented in config.yaml.d":       {"config.yaml.d/10-user.yaml", "#kubelet-arg+: [fail-cgroupv1=false]\n"},
+		"commented in a yml":               {"config.yaml.d/10-user.yml", "    # fail-cgroupv1=false\n"},
+		"true in config.yaml":              {"config.yaml", "kubelet-arg:\n  - fail-cgroupv1=true\n"},
+		"true in config.yaml.d":            {"config.yaml.d/10-user.yaml", "kubelet-arg+:\n  - fail-cgroupv1=true\n"},
+		"false only in a trailing comment": {"config.yaml", "kubelet-arg:\n  - v=2 # fail-cgroupv1=false\n"},
+		"a longer name":                    {"config.yaml", "kubelet-arg:\n  - fail-cgroupv1=falsey\n"},
+	} {
+		t.Run(name, func(t *testing.T) {
+			for _, withDropin := range []bool{false, true} {
+				i := newInst(t)
+				i.installed("")
+				write(t, filepath.Join(i.k3sCfg, tc.file), tc.content)
+				if withDropin {
+					write(t, i.dropin(), "kubelet-arg+:\n  - \"fail-cgroupv1=false\"\n")
+				}
+				out, err := i.run("tn_inst_prepare server", "TN_CGROUP_FSTYPE=tmpfs", "INSTALL_K3S_VERSION=v1.36.5+k3s1")
+				if err != nil || strings.Contains(out, "set by the device itself") || strings.Contains(out, "Removed") {
+					t.Fatalf("withDropin=%v: %v\n%s", withDropin, err, out)
+				}
+				if !strings.Contains(string(mustRead(t, i.dropin())), "fail-cgroupv1=false") {
+					t.Errorf("withDropin=%v: no drop-in\n%s", withDropin, out)
+				}
+			}
+		})
+	}
+	// the same in INSTALL_K3S_EXEC
+	for _, exec := range []string{"server --kubelet-arg=fail-cgroupv1=true", "server --kubelet-arg=fail-cgroupv1=falsey"} {
+		i := newInst(t)
+		i.installed("")
+		out, err := i.run("tn_inst_prepare server", "TN_CGROUP_FSTYPE=tmpfs", "INSTALL_K3S_VERSION=v1.36.5+k3s1", "INSTALL_K3S_EXEC="+exec)
+		if err != nil || strings.Contains(out, "set by the device itself") || !strings.Contains(string(mustRead(t, i.dropin())), "fail-cgroupv1=false") {
+			t.Errorf("%q: %v\n%s", exec, err, out)
+		}
+	}
+}
+
+// A fail-cgroupv1 that only the INSTALL_K3S_EXEC of the caller carries reaches the unit when the
+// installer has run. Until then a k3s that restarts (the CA step restarts it) or a device that reboots
+// reads no flag, so the drop-in must stay if it is there, and be written if it is not.
+func TestCgroupV1DropinStaysWhenTheOnlyOtherSettingIsInstallK3sExec(t *testing.T) {
+	exec := "INSTALL_K3S_EXEC=server --kubelet-arg=fail-cgroupv1=false"
+	env := []string{"TN_CGROUP_FSTYPE=tmpfs", "INSTALL_K3S_VERSION=v1.36.5+k3s1", exec}
+	// present: it stays, byte for byte
+	i := newInst(t)
+	i.installed("")
+	i.run("tn_inst_prepare server", "TN_CGROUP_FSTYPE=tmpfs", "INSTALL_K3S_VERSION=v1.36.5+k3s1")
+	before := string(mustRead(t, i.dropin()))
+	out, err := i.run("tn_inst_prepare server", env...)
+	if err != nil || !strings.Contains(out, "set by the device itself (INSTALL_K3S_EXEC)") || !strings.Contains(out, "stays until the installer") {
+		t.Fatalf("%v\n%s", err, out)
+	}
+	if _, err := os.Stat(i.dropin()); err != nil || string(mustRead(t, i.dropin())) != before {
+		t.Errorf("the drop-in did not survive tn_inst_prepare: %v", err)
+	}
+	if strings.Contains(out, "Removed") {
+		t.Errorf("something was removed:\n%s", out)
+	}
+	// absent: it is written
+	i = newInst(t)
+	i.installed("")
+	if out, err = i.run("tn_inst_prepare server", env...); err != nil {
+		t.Fatalf("%v\n%s", err, out)
+	}
+	if !strings.Contains(string(mustRead(t, i.dropin())), "fail-cgroupv1=false") {
+		t.Error("no drop-in although only INSTALL_K3S_EXEC has the flag")
+	}
+	// the flag is in a persistent file AND in INSTALL_K3S_EXEC: the file counts, ours goes
+	i = newInst(t)
+	i.installed("")
+	write(t, filepath.Join(i.k3sCfg, "config.yaml.d", "10-user.yaml"), "kubelet-arg+:\n  - fail-cgroupv1=false\n")
+	write(t, i.dropin(), "kubelet-arg+:\n  - \"fail-cgroupv1=false\"\n")
+	if out, err = i.run("tn_inst_prepare server", env...); err != nil || !strings.Contains(out, "10-user.yaml") {
+		t.Fatalf("%v\n%s", err, out)
+	}
+	if _, err := os.Stat(i.dropin()); err == nil {
+		t.Error("our drop-in stays although a persistent file has the flag")
+	}
+}
+
+// With no flag from the device at all the drop-in is written.
+func TestCgroupV1DropinIsWrittenWithoutAFlagFromTheDevice(t *testing.T) {
+	i := newInst(t)
+	i.installed("")
+	out, err := i.run("tn_inst_prepare server", "TN_CGROUP_FSTYPE=tmpfs", "INSTALL_K3S_VERSION=v1.36.5+k3s1", "INSTALL_K3S_EXEC=server --node-label=a=b")
+	if err != nil || !strings.Contains(string(mustRead(t, i.dropin())), "fail-cgroupv1=false") {
+		t.Fatalf("%v\n%s", err, out)
+	}
+}
+
+// An installed k3s older than v1.31 that is being upgraded cannot start with the flag: it is not
+// written (and an existing one is removed) before the installer, and tn_inst_finish writes it after.
+func TestCgroupV1FlagWaitsForTheInstallerWhenTheInstalledK3sIsTooOld(t *testing.T) {
+	for _, withDropin := range []bool{false, true} {
+		i := newInst(t)
+		i.installed("v1.30.14+k3s1")
+		if withDropin {
+			write(t, i.dropin(), "kubelet-arg+:\n  - \"fail-cgroupv1=false\"\n")
+		}
+		env := []string{"TN_CGROUP_FSTYPE=tmpfs", "INSTALL_K3S_VERSION=v1.31.4+k3s1", "TN_K3S_UPGRADE=true", "TN_K3S_PIN_SOURCE=flag"}
+		out, err := i.run("tn_inst_prepare server", env...)
+		if err != nil || !strings.Contains(out, "after the installer has upgraded it") {
+			t.Fatalf("%v\n%s", err, out)
+		}
+		if _, err := os.Stat(i.dropin()); err == nil {
+			t.Errorf("withDropin=%v: the old kubelet would read the flag before the installer ran\n%s", withDropin, out)
+		}
+		out, err = i.run("tn_inst_prepare server; tn_inst_finish", env...)
+		if err != nil || !strings.Contains(string(mustRead(t, i.dropin())), "fail-cgroupv1=false") {
+			t.Fatalf("withDropin=%v: not written after the installer: %v\n%s", withDropin, err, out)
+		}
+		// finish without a deferred write does nothing, and prepare resets it
+		i2 := newInst(t)
+		i2.installed("")
+		if out, err = i2.run("tn_inst_prepare server; tn_inst_finish", "TN_CGROUP_FSTYPE=tmpfs", "INSTALL_K3S_VERSION=v1.36.5+k3s1"); err != nil || strings.Contains(out, "held back") {
+			t.Errorf("%v\n%s", err, out)
+		}
+	}
+}
+
+// The installer starts the NEW release as soon as it has rewritten the unit, and v1.35 and newer do not
+// start on cgroup v1 without the flag. So when the drop-in has to wait (the installed k3s is older than
+// v1.31) and the release is not known to be older than v1.35, the flag is on INSTALL_K3S_EXEC from the first
+// start; tn_inst_finish writes the drop-in after the installer.
+func TestCgroupV1FlagIsOnTheInstallerCommandWhenTheDropinHasToWait(t *testing.T) {
+	const flag = "--kubelet-arg=fail-cgroupv1=false"
+	show := `; echo "EXEC=[${INSTALL_K3S_EXEC-unset}]"; if [ -e "$TN_K3S_CONFIG_DIR/config.yaml.d/99-teknoir-cgroupv1.yaml" ]; then echo DROPIN=yes; else echo DROPIN=no; fi`
+	for _, tc := range []struct {
+		name     string
+		env      []string
+		wantExec string // the whole INSTALL_K3S_EXEC after tn_inst_prepare
+		msg      string
+	}{
+		{name: "channel upgrade", env: []string{"INSTALL_K3S_CHANNEL=stable", "TN_K3S_UPGRADE=true", "INSTALL_K3S_EXEC=server --tls-san a"},
+			wantExec: "server --tls-san a " + flag, msg: "may need the flag on its first start"},
+		{name: "channel upgrade, no exec at all", env: []string{"INSTALL_K3S_CHANNEL=latest", "TN_K3S_UPGRADE=true"},
+			wantExec: flag},
+		{name: "a forced jump to v1.36.5", env: []string{"INSTALL_K3S_VERSION=v1.36.5+k3s1", "TN_K3S_UPGRADE=true", "TN_K3S_FORCE=true", "INSTALL_K3S_EXEC=agent"},
+			wantExec: "agent " + flag},
+		{name: "exact v1.35.0 (a jump too, forced)", env: []string{"INSTALL_K3S_VERSION=v1.35.0+k3s1", "TN_K3S_UPGRADE=true", "TN_K3S_FORCE=true", "INSTALL_K3S_EXEC=server"},
+			wantExec: "server " + flag},
+		{name: "exact v1.31.14 does not need it on its first start", env: []string{"INSTALL_K3S_VERSION=v1.31.14+k3s1", "TN_K3S_UPGRADE=true", "INSTALL_K3S_EXEC=server"},
+			wantExec: "server"},
+		{name: "a channel named v1.31 does not need it either", env: []string{"INSTALL_K3S_CHANNEL=v1.31", "TN_K3S_UPGRADE=true", "INSTALL_K3S_EXEC=server"},
+			wantExec: "server"},
+		{name: "already on the command of the caller: not twice", env: []string{"INSTALL_K3S_CHANNEL=stable", "TN_K3S_UPGRADE=true", "INSTALL_K3S_EXEC=server " + flag},
+			wantExec: "server " + flag, msg: "already has fail-cgroupv1=false"},
+		{name: "already on the command of the caller, spelled with a space", env: []string{"INSTALL_K3S_CHANNEL=stable", "TN_K3S_UPGRADE=true", "INSTALL_K3S_EXEC=server --kubelet-arg fail-cgroupv1=false"},
+			wantExec: "server --kubelet-arg fail-cgroupv1=false"},
+		{name: "true on the command of the caller is not the flag", env: []string{"INSTALL_K3S_CHANNEL=stable", "TN_K3S_UPGRADE=true", "INSTALL_K3S_EXEC=server --kubelet-arg=fail-cgroupv1=true"},
+			wantExec: "server --kubelet-arg=fail-cgroupv1=true " + flag},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			i := newInst(t)
+			i.installed("v1.30.14+k3s1")
+			env := append([]string{"TN_CGROUP_FSTYPE=tmpfs", "TN_K3S_PIN_SOURCE=flag"}, tc.env...)
+			out, err := i.run("tn_inst_prepare server"+show, env...)
+			if err != nil {
+				t.Fatalf("%v\n%s", err, out)
+			}
+			if !strings.Contains(out, "EXEC=["+tc.wantExec+"]\n") {
+				t.Errorf("want INSTALL_K3S_EXEC %q:\n%s", tc.wantExec, out)
+			}
+			if strings.Count(out, "fail-cgroupv1=false") > 0 && strings.Count(strings.SplitN(strings.SplitN(out, "EXEC=[", 2)[1], "]", 2)[0], "fail-cgroupv1=false") > 1 {
+				t.Errorf("the flag is on the command twice:\n%s", out)
+			}
+			if !strings.Contains(out, "DROPIN=no") {
+				t.Errorf("the drop-in must wait for the installer:\n%s", out)
+			}
+			if tc.msg != "" && !strings.Contains(out, tc.msg) {
+				t.Errorf("output lacks %q:\n%s", tc.msg, out)
+			}
+			// after the installer: the drop-in
+			out, err = i.run("tn_inst_prepare server; tn_inst_finish"+show, env...)
+			if err != nil || !strings.Contains(out, "DROPIN=yes") || !strings.Contains(string(mustRead(t, i.dropin())), "fail-cgroupv1=false") {
+				t.Errorf("not written after the installer: %v\n%s", err, out)
+			}
+		})
+	}
+	// the exec of a re-run, when the installed k3s is new enough, is left alone
+	i := newInst(t)
+	i.installed("v1.34.11+k3s1")
+	out, err := i.run("tn_inst_prepare server"+show, "TN_CGROUP_FSTYPE=tmpfs", "INSTALL_K3S_EXEC=server")
+	if err != nil || !strings.Contains(out, "EXEC=[server]\n") {
+		t.Errorf("%v\n%s", err, out)
+	}
+	// cgroup v2: nothing at all
+	i = newInst(t)
+	i.installed("v1.30.14+k3s1")
+	out, err = i.run("tn_inst_prepare server"+show, "TN_CGROUP_FSTYPE=cgroup2fs", "INSTALL_K3S_CHANNEL=stable", "TN_K3S_UPGRADE=true", "INSTALL_K3S_EXEC=server")
+	if err != nil || !strings.Contains(out, "EXEC=[server]\n") || !strings.Contains(out, "DROPIN=no") {
+		t.Errorf("%v\n%s", err, out)
+	}
+	// the device already has the flag in a file k3s reads: no command line flag either
+	i = newInst(t)
+	i.installed("v1.30.14+k3s1")
+	write(t, filepath.Join(i.k3sCfg, "config.yaml.d", "10-user.yaml"), "kubelet-arg+:\n  - fail-cgroupv1=false\n")
+	out, err = i.run("tn_inst_prepare server"+show, "TN_CGROUP_FSTYPE=tmpfs", "INSTALL_K3S_CHANNEL=stable", "TN_K3S_UPGRADE=true", "INSTALL_K3S_EXEC=server")
+	if err != nil || !strings.Contains(out, "EXEC=[server]\n") {
+		t.Errorf("%v\n%s", err, out)
+	}
+}
+
+// the kubelet flag is only ever added for the agent and the server script, through the same call
+func TestAgentRoleUsesTheSameCgroupLogic(t *testing.T) {
+	i := newInst(t)
+	i.installed("")
+	if out, err := i.run("tn_inst_prepare agent", "TN_CGROUP_FSTYPE=tmpfs", "INSTALL_K3S_VERSION=v1.36.5+k3s1", "TN_K3S_PIN_SOURCE=env", "K3S_URL=https://srv:6443", "TN_TEST_SERVER_VERSION=v1.36.5+k3s1"); err != nil || !strings.Contains(out, "(agent)") {
+		t.Fatalf("%v\n%s", err, out)
+	}
+	if _, err := os.Stat(i.dropin()); err != nil {
+		t.Error("not written for the agent")
+	}
+}
+
+func TestRealCgroupDetectionDoesNotFail(t *testing.T) {
+	// no override: the host decides, and whatever it is the call must succeed
+	i := newInst(t)
+	i.installed("")
+	if out, err := i.run("tn_inst_prepare server", "INSTALL_K3S_VERSION=v1.36.5+k3s1"); err != nil {
+		t.Fatalf("%v\n%s", err, out)
+	}
+}
+
+// ---------------------------------------------------------------- config.yaml
+
+func TestConfigEnsure(t *testing.T) {
+	i := newInst(t)
+	f := filepath.Join(i.dir, "etc", "config.yaml")
+	run := func(key, text string) string {
+		t.Helper()
+		out, err := i.run(`tn_inst_config_ensure "$F" "$K" "$T"`, "F="+f, "K="+key, "T="+text)
+		if err != nil {
+			t.Fatalf("%v\n%s", err, out)
+		}
+		return out
+	}
+	read := func() string { b, _ := os.ReadFile(f); return string(b) }
+
+	run("disable", "disable:\n  - traefik")
+	run("node-name", "node-name: teknoir-master")
+	if got := read(); got != "disable:\n  - traefik\nnode-name: teknoir-master\n" {
+		t.Fatalf("fresh file:\n%s", got)
+	}
+	// again: nothing changes
+	if out := run("disable", "disable:\n  - traefik"); !strings.Contains(out, "already sets") {
+		t.Errorf("no message:\n%s", out)
+	}
+	run("node-name", "node-name: other")
+	if got := read(); got != "disable:\n  - traefik\nnode-name: teknoir-master\n" {
+		t.Fatalf("second run:\n%s", got)
+	}
+
+	// a file of the device owner: kept as it is, a missing key is appended on its own line
+	write(t, f, "# mine\nkubelet-arg:\n  - max-pods=77\nnode-name: custom\ndisable+:\n  - servicelb") // no trailing newline
+	run("disable", "disable:\n  - traefik")
+	run("node-name", "node-name: teknoir-master")
+	run("data-dir", "data-dir: /opt/k3s")
+	want := "# mine\nkubelet-arg:\n  - max-pods=77\nnode-name: custom\ndisable+:\n  - servicelb\ndata-dir: /opt/k3s\n"
+	if got := read(); got != want {
+		t.Errorf("owner's file:\n%s\nwant:\n%s", got, want)
+	}
+
+	// only a TOP-LEVEL key counts; CRLF is fine
+	write(t, f, "x:\n  node-name: nested\r\nother: 1\r\n")
+	run("node-name", "node-name: teknoir-master")
+	if got := read(); !strings.HasSuffix(got, "node-name: teknoir-master\n") {
+		t.Errorf("a nested key was taken for the top-level one:\n%s", got)
+	}
+	write(t, f, "node-name: crlf\r\n")
+	if out := run("node-name", "node-name: teknoir-master"); !strings.Contains(out, "already sets") {
+		t.Errorf("crlf key not found:\n%s", out)
+	}
+	// a comment that mentions the key is not the key
+	write(t, f, "# node-name: old\n")
+	run("node-name", "node-name: teknoir-master")
+	if got := read(); got != "# node-name: old\nnode-name: teknoir-master\n" {
+		t.Errorf("comment:\n%s", got)
+	}
+}
+
+// ---------------------------------------------------------------- the generated scripts
+
+func TestScriptsEmbedTheInstallLibraryAndCallItBeforeTheInstaller(t *testing.T) {
+	for name, tpl := range map[string]*struct{ out string }{
+		"server": {renderK3S(t, ServerTemplate, "")},
+		"agent":  {renderK3S(t, AgentTemplate, "")},
+	} {
+		out := tpl.out
+		call := "\ntn_inst_prepare " + name + "\n"
+		for _, want := range []string{"tn_inst_prepare()", "tn_inst_plan()", "tn_inst_cgroup()", call} {
+			if !strings.Contains(out, want) {
+				t.Errorf("%s script lacks %q", name, want)
+			}
+		}
+		iPrep := strings.Index(out, call)
+		iPin := strings.Index(out, "\nexport INSTALL_K3S_VERSION=")
+		iInst := strings.Index(out, "\n$SUDO ./k3s_installer.sh")
+		if !(iPin >= 0 && iPin < iPrep && iPrep < iInst) {
+			t.Errorf("%s: the order is pin %d, tn_inst_prepare %d, installer %d", name, iPin, iPrep, iInst)
+		}
+		// the library comes before its first use
+		if strings.Index(out, "tn_inst_prepare()") > iPrep {
+			t.Errorf("%s: library after the call", name)
+		}
+	}
+	// the docker server variant installs no k3s at all
+	if strings.Contains(DockerServerTemplateStr, "tn-k3s-install") {
+		t.Error("the docker variant embeds the install library")
+	}
+	// the server writes config.yaml without clobbering it
+	srv := renderK3S(t, ServerTemplate, "")
+	if strings.Contains(srv, "tee ${K3S_CONFIG_PATH}/config.yaml") {
+		t.Error("the server script still overwrites config.yaml")
+	}
+	for _, want := range []string{`tn_inst_config_ensure ${K3S_CONFIG_PATH}/config.yaml disable`, `tn_inst_config_ensure ${K3S_CONFIG_PATH}/config.yaml node-name "node-name: teknoir-master"`} {
+		if !strings.Contains(srv, want) {
+			t.Errorf("server script lacks %q", want)
+		}
+	}
+}
+
+func renderData(t *testing.T, d TemplateData) (server, agent string) {
+	t.Helper()
+	var s, a bytes.Buffer
+	if err := ServerTemplate.Execute(&s, d); err != nil {
+		t.Fatal(err)
+	}
+	if err := AgentTemplate.Execute(&a, d); err != nil {
+		t.Fatal(err)
+	}
+	return s.String(), a.String()
+}
+
+func TestUpgradeAndForceDefaultsInTheScripts(t *testing.T) {
+	base := TemplateData{Domain: "test.cloud", DeviceID: "dev-1", K3SToken: "tok"}
+	s, a := renderData(t, base)
+	for name, out := range map[string]string{"server": s, "agent": a} {
+		if len(exportsOf(out, "TN_K3S_UPGRADE"))+len(exportsOf(out, "TN_K3S_FORCE")) != 0 {
+			t.Errorf("%s: upgrade/force are on by default", name)
+		}
+	}
+	up := base
+	up.K3SUpgrade = true
+	s, a = renderData(t, up)
+	for name, out := range map[string]string{"server": s, "agent": a} {
+		if got := exportsOf(out, "TN_K3S_UPGRADE"); len(got) != 1 || got[0] != `export TN_K3S_UPGRADE="${TN_K3S_UPGRADE:-true}"` {
+			t.Errorf("%s upgrade: %q", name, got)
+		}
+		if len(exportsOf(out, "TN_K3S_FORCE")) != 0 {
+			t.Errorf("%s: force without --force", name)
+		}
+	}
+	fo := up
+	fo.K3SForce = true
+	s, a = renderData(t, fo)
+	for name, out := range map[string]string{"server": s, "agent": a} {
+		if got := exportsOf(out, "TN_K3S_FORCE"); len(got) != 1 || got[0] != `export TN_K3S_FORCE="${TN_K3S_FORCE:-true}"` {
+			t.Errorf("%s force: %q", name, got)
+		}
+		// set before tn_inst_prepare runs
+		if strings.Index(out, "export TN_K3S_FORCE=") > strings.Index(out, "\ntn_inst_prepare ") {
+			t.Errorf("%s: force is set after tn_inst_prepare", name)
+		}
+	}
+	// every combination of pins parses
+	for _, d := range []TemplateData{up, fo, {K3SForce: true}} {
+		for _, v := range []string{"", "stable", "latest", "v1.34.11+k3s1"} {
+			d.K3SVersion = v
+			s, a := renderData(t, d)
+			for name, out := range map[string]string{"server": s, "agent": a} {
+				f := filepath.Join(t.TempDir(), "s.sh")
+				if err := os.WriteFile(f, []byte(out), 0o600); err != nil {
+					t.Fatal(err)
+				}
+				for _, sh := range []string{"sh", "dash"} {
+					if _, err := exec.LookPath(sh); err != nil {
+						continue
+					}
+					if o, err := exec.Command(sh, "-n", f).CombinedOutput(); err != nil {
+						t.Errorf("%s %s %q: %v\n%s", sh, name, v, err, o)
+					}
+				}
+			}
+		}
+	}
+}
+
+// What the generated script does between the pin and the installer, run for real with the
+// rendered pin lines: the defaults come from the template, the environment overrides them.
+func TestRenderedPinThroughThePolicy(t *testing.T) {
+	needTool(t, "sh")
+	for _, tc := range []struct {
+		name      string
+		data      TemplateData
+		installed string
+		env       []string
+		wantRC    int
+		want      string
+	}{
+		{"fresh device, default", TemplateData{}, "", nil, 0, "version=v1.36.5+k3s1 channel=unset action=install"},
+		{"re-run keeps", TemplateData{}, "v1.34.11+k3s1", nil, 0, "version=v1.34.11+k3s1 channel=unset action=keep"},
+		{"--k3s-upgrade, one minor", TemplateData{K3SUpgrade: true}, "v1.35.9+k3s1", nil, 0, "version=v1.36.5+k3s1 channel=unset action=upgrade"},
+		{"--k3s-upgrade, two minors", TemplateData{K3SUpgrade: true}, "v1.34.11+k3s1", nil, 1, ""},
+		{"--k3s-upgrade --force, two minors", TemplateData{K3SUpgrade: true, K3SForce: true}, "v1.34.11+k3s1", nil, 0, "version=v1.36.5+k3s1 channel=unset action=upgrade"},
+		{"--k3s-upgrade, env says no", TemplateData{K3SUpgrade: true}, "v1.35.9+k3s1", []string{"TN_K3S_UPGRADE=false"}, 0, "version=v1.35.9+k3s1 channel=unset action=keep"},
+		{"env opts in", TemplateData{}, "v1.35.9+k3s1", []string{"TN_K3S_UPGRADE=true"}, 0, "version=v1.36.5+k3s1 channel=unset action=upgrade"},
+		{"env pin beats the template pin on a new device", TemplateData{}, "", []string{"INSTALL_K3S_VERSION=v1.34.11+k3s1"}, 0, "version=v1.34.11+k3s1 channel=unset action=install"},
+		{"latest channel, installed", TemplateData{K3SVersion: "latest"}, "v1.35.9+k3s1", nil, 0, "version=v1.35.9+k3s1 channel=unset action=keep"},
+		{"stable, fresh", TemplateData{K3SVersion: "stable"}, "", nil, 0, "version=unset channel=unset action=install"},
+		{"latest, fresh", TemplateData{K3SVersion: "latest"}, "", nil, 0, "version=unset channel=latest action=install"},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			var part bytes.Buffer
+			if err := ServerTemplate.ExecuteTemplate(&part, "k3s_version.sh.tmpl", tc.data); err != nil {
+				t.Fatal(err)
+			}
+			i := newInst(t)
+			i.installed(tc.installed)
+			out, err := i.run(part.String()+"\ntn_inst_prepare server; "+resultLine, append([]string{"TN_CGROUP_FSTYPE=cgroup2fs"}, tc.env...)...)
+			if rc := exitCode(err); rc != tc.wantRC {
+				t.Fatalf("rc=%d\n%s", rc, out)
+			}
+			if tc.wantRC == 0 {
+				if got := result(t, out); !strings.HasPrefix(got, tc.want+" ") && got != tc.want {
+					t.Errorf("got %q, want %q", got, tc.want)
+				}
+			}
+		})
+	}
+}
diff --git a/pkg/templates/partials/k3s_version.sh.tmpl b/pkg/templates/partials/k3s_version.sh.tmpl
new file mode 100644
index 0000000..97469b8
--- /dev/null
+++ b/pkg/templates/partials/k3s_version.sh.tmpl
@@ -0,0 +1,22 @@
+{{- /* The k3s release of the installer. Used by the server and the agent script with the same data. */ -}}
+# Who chose the k3s release: the person who runs this script (INSTALL_K3S_VERSION / INSTALL_K3S_CHANNEL in the
+# environment, or `tnctl bootstrap --k3s-version`) or the default of this script. An agent installs the
+# release of its server unless it was asked for one (it is then refused if it is newer than the server).
+if [ -n "${INSTALL_K3S_VERSION:-}${INSTALL_K3S_CHANNEL:-}" ]; then TN_K3S_PIN_SOURCE=env; else TN_K3S_PIN_SOURCE={{if .K3SVersionExplicit}}flag{{else}}default{{end}}; fi
+export TN_K3S_PIN_SOURCE
+{{if .K3SPin}}# k3s is pinned to {{.K3SPin}} (tnctl bootstrap --k3s-version). Override when running the script:
+#   INSTALL_K3S_VERSION=v1.xx.y+k3sN sh bootstrap_*.sh      (an agent must run the version of its server)
+# This is the release for a NEW device: a re-run on a device with k3s installed keeps the installed version
+# (TN_K3S_UPGRADE=true, tnctl bootstrap --k3s-upgrade, replaces it; never a downgrade).
+export INSTALL_K3S_VERSION="${INSTALL_K3S_VERSION:-{{.K3SPin}}}"
+{{else if .K3SChannel}}# k3s follows the {{.K3SChannel}} channel (tnctl bootstrap --k3s-version {{.K3SChannel}}). Pin a release with:
+#   INSTALL_K3S_VERSION=v1.xx.y+k3sN sh bootstrap_*.sh
+export INSTALL_K3S_CHANNEL="${INSTALL_K3S_CHANNEL:-{{.K3SChannel}}}"
+{{else}}# k3s follows the installer's default channel, stable (tnctl bootstrap --k3s-version stable). Pin a release with:
+#   INSTALL_K3S_VERSION=v1.xx.y+k3sN sh bootstrap_*.sh
+{{end -}}
+{{if .K3SUpgrade}}# tnctl bootstrap --k3s-upgrade: the release above replaces an installed k3s (never a downgrade). TN_K3S_UPGRADE=false overrides.
+export TN_K3S_UPGRADE="${TN_K3S_UPGRADE:-true}"
+{{end}}{{if .K3SForce}}# tnctl bootstrap --force: an upgrade over several minor versions is allowed. TN_K3S_FORCE=false overrides.
+export TN_K3S_FORCE="${TN_K3S_FORCE:-true}"
+{{end -}}
diff --git a/pkg/templates/scripts/tn-k3s-ca.sh b/pkg/templates/scripts/tn-k3s-ca.sh
new file mode 100644
index 0000000..0b316e3
--- /dev/null
+++ b/pkg/templates/scripts/tn-k3s-ca.sh
@@ -0,0 +1,1159 @@
+#!/bin/sh
+# tn-k3s-ca.sh - the custom k3s CA of a Teknoir device: setup, check, remediate.
+#
+# Background. A Teknoir device uses its own certificate (Device CR settings,
+# /etc/teknoir/rsa_public.pem + rsa_private.pem) as the ROOT of the k3s cluster
+# CA and issues the intermediate and the five leaf CAs below it. k3s v1.34.12,
+# v1.35.9, v1.36.5, v1.37.1 and later (k3s-io/k3s#14699, "Improve CA hash
+# validation") drop every certificate without the keyCertSign key usage from the
+# CA bundle before they build the trust pool. The device certificates of the
+# platform never had keyCertSign, so such a k3s refuses to start
+# ("CA cert validation failed ... x509: certificate signed by unknown authority").
+#
+# The fix is to give the root the missing key usage. The root is re-issued from
+# the SAME key and subject (and subject key identifier): a new self-signed root
+# with CA:TRUE and keyCertSign, valid 20 years. Everything signed below the old
+# root stays valid (same key, same subject), and the device files are never
+# modified.
+#
+# Three ways to use this file:
+#
+#   . tn-k3s-ca.sh; tn_k3s_ca_setup     bootstrap scripts (sourced): creates the
+#                                       PKI of a new device, leaves an
+#                                       initialised one alone, repairs an old one
+#   sh tn-k3s-ca.sh check               is the root of this device acceptable to k3s?
+#   sh tn-k3s-ca.sh remediate           repair a device bootstrapped with the old root
+#
+# POSIX sh. It runs under `set -e` and `set -o noglob` (as the bootstrap scripts
+# do) and does not change shell options, traps or the working directory of the
+# caller. Sourcing it defines functions only.
+#
+# Environment (all optional when run as a program):
+#   CONFIG_PATH    directory with rsa_public.pem and rsa_private.pem (/etc/teknoir)
+#   DATA_DIR       k3s data dir. When it is not set (and no --data-dir is given) it is resolved the way
+#                  k3s resolves it, see tn_ca_resolve_datadir: an explicit DATA_DIR/--data-dir, then
+#                  --data-dir/-d in the ExecStart of the k3s systemd unit, then the last data-dir in
+#                  /etc/rancher/k3s/config.yaml.d/*.yaml, then data-dir in /etc/rancher/k3s/config.yaml,
+#                  then K3S_DATA_DIR of the unit's environment, then /var/lib/rancher/k3s
+#   PRODUCT        k3s
+#   _DEVICE_ID, _DOMAIN   used in the CN of the generated CAs (taken from the
+#                  existing CAs when not set)
+#   K3S_BIN        k3s command used by `rotate-ca` (k3s)
+#   TN_K3S_RESTART_CMD    restarts k3s after a remediation (systemctl restart k3s)
+#   TN_K3S_SERVICE_TIMEOUT  seconds that a stop, start or restart of k3s may take (600: a Raspberry Pi or a
+#                  Jetson with a large datastore takes minutes); then the unit is watched for TN_K3S_READY_GRACE
+#                  more seconds (120) and only after that reported as failed instead of hanging (the k3s unit
+#                  waits forever for a k3s that cannot start)
+#   TN_K3S_READY_GRACE, TN_K3S_READY_POLL   seconds to keep polling the unit for 'active' after a restart that
+#                  timed out (120), and the interval between polls (5)
+#   TN_K3S_ROTATE_TRIES, TN_K3S_ROTATE_WAIT   `k3s certificate rotate-ca` needs a k3s server that answers. When the
+#                  k3s unit is starting (or just restarted) it is tried up to this many times (6), this many
+#                  seconds apart (10). Without a k3s unit it is tried once
+#   TN_K3S_STOP_CMD, TN_K3S_START_CMD   stop/start k3s around the replacement of server/tls when the
+#                  PKI is regenerated (systemctl stop|start k3s). Without TN_K3S_STOP_CMD k3s is only
+#                  stopped if the systemd unit is active, and then started again
+#   TN_K3S_CONFIG_DIR     /etc/rancher/k3s (config.yaml and config.yaml.d)
+#   TN_K3S_UNIT_FILE      a unit file to read instead of `systemctl cat k3s.service` (tests)
+#   TN_K3S_CA_AUTO_REMEDIATE  true (default) / false: a re-run of a bootstrap script
+#                  repairs an initialised data dir itself; false stops with advice
+#
+# check exit codes:
+#   0  ok (the root is acceptable to k3s, or this is not a server: no k3s server unit and no
+#      server/tls/server-ca.crt)
+#   2  needs-rotation: initialised data dir, root unusable => `remediate`
+#   3  needs-regeneration: data dir never initialised, PKI unusable => `remediate`
+#      (or re-run the bootstrap script)
+#   4  foreign: the root is unusable or expires soon but we do not hold its key (not a Teknoir CA);
+#      or no-server-data: a k3s server unit exists but the data dir that was resolved has no
+#      server/tls/server-ca.crt (k3s has not started yet, or its data dir is elsewhere: pass --data-dir)
+#   1  error
+#
+# remediate exit codes: 0 done, 1 failed (nothing changed, except the saved backup), 2 usage,
+#   4 foreign/no server data, 5 the CA WAS changed but a later step failed (finalize or the k3s restart):
+#   the datastore holds the new CA, do not roll back; the message says how to continue.
+#
+# Rollback limits. The backups (server/tls-backup-tn-<ts>.tar, the newest 3 are kept) hold server/tls
+# only. `k3s certificate rotate-ca` also writes the new CA into the datastore of k3s, which this tool
+# does not back up: once it has succeeded, restoring the tar alone does not go back (the files and
+# the datastore would disagree). A real rollback needs a snapshot of the datastore taken before
+# (stop k3s, copy DATA_DIR/server/db). The staged files are not committed before rotate-ca
+# succeeded, and a failing rotate-ca leaves the device as it was.
+
+TN_K3S_CA_LIB_VERSION=1
+export TN_K3S_CA_LIB_VERSION
+
+# ----------------------------------------------------------------- messages
+# The library prints with its own functions, in the format of header.sh.tmpl. It must not use a
+# caller's info/warn/fatal (there may be none: a stand-alone run) and must not trust `info`
+# to be a function either: on Debian/Ubuntu it is the GNU info reader.
+tn_ca_info() { echo '[INFO] ' "$@"; }
+tn_ca_warn() { echo '[WARN] ' "$@" >&2; }
+tn_ca_fatal() { echo '[ERROR] ' "$@" >&2; exit 1; }
+
+# ----------------------------------------------------------------- small helpers
+
+# Select the openssl binary (3.x if installed side by side, as on some distros).
+tn_ca_openssl() {
+  if command -v openssl-3 >/dev/null 2>&1; then
+    OPENSSL=openssl-3
+  elif command -v openssl >/dev/null 2>&1; then
+    OPENSSL=openssl
+  else
+    tn_ca_warn "openssl not found"
+    return 1
+  fi
+  if ! "$OPENSSL" ecparam -name prime256v1 -genkey -noout -out /dev/null >/dev/null 2>&1; then
+    tn_ca_warn "openssl missing Elliptic Curve (ecparam) support"
+    return 1
+  fi
+  return 0
+}
+
+tn_ca_ts() { date +%Y%m%dT%H%M%S; }
+
+# tn_ca_changed TEXT: records, in TN_K3S_CA_CHANGED (exported), what this run has changed on the device
+# for good. A later refusal (the k3s release policy, a failing step) says it instead of claiming that
+# nothing was changed.
+tn_ca_changed() {
+  if [ -n "${TN_K3S_CA_CHANGED:-}" ]; then TN_K3S_CA_CHANGED="$TN_K3S_CA_CHANGED; $1"; else TN_K3S_CA_CHANGED=$1; fi
+  export TN_K3S_CA_CHANGED
+}
+
+# tn_ca_split PEMFILE DIR: write every certificate of PEMFILE to DIR/c<N>.pem, N from 0.
+# Echoes the number of certificates.
+tn_ca_split() {
+  mkdir -p "$2" || return 1
+  awk -v d="$2" '
+    /-----BEGIN CERTIFICATE-----/ { f = sprintf("%s/c%d.pem", d, n); n++ }
+    f { print > f }
+    /-----END CERTIFICATE-----/ { if (f != "") close(f); f = "" }
+    END { print n + 0 }' "$1"
+}
+
+# tn_ca_fp CERT: sha256 fingerprint
+tn_ca_fp() { "$OPENSSL" x509 -in "$1" -noout -fingerprint -sha256 | cut -d= -f2; }
+
+# tn_ca_pubhash_cert CERT / tn_ca_pubhash_key KEY: sha256 of the public key (SPKI)
+tn_ca_pubhash_cert() { "$OPENSSL" x509 -in "$1" -noout -pubkey 2>/dev/null | sha256sum | cut -d' ' -f1; }
+tn_ca_pubhash_key() { "$OPENSSL" pkey -in "$1" -pubout 2>/dev/null | sha256sum | cut -d' ' -f1; }
+
+# tn_ca_ski CERT: subject key identifier as printed by openssl, or empty
+tn_ca_ski() {
+  "$OPENSSL" x509 -in "$1" -noout -text 2>/dev/null |
+    awk '/X509v3 Subject Key Identifier/ { getline; gsub(/[ \t]/, ""); print; exit }'
+}
+
+# tn_ca_has_certsign CERT
+tn_ca_has_certsign() { "$OPENSSL" x509 -in "$1" -noout -text 2>/dev/null | grep -q 'Certificate Sign'; }
+
+# tn_ca_dir_ok DIR: a data dir whose server/token exists was started by k3s once
+tn_ca_initialised() { [ -s "$1/server/token" ]; }
+
+# tn_ca_lastcert BUNDLE OUTFILE: write the last (root) certificate of BUNDLE
+tn_ca_lastcert() {
+  _tn_w=$(mktemp -d) || return 1
+  _tn_n=$(tn_ca_split "$1" "$_tn_w")
+  if [ "${_tn_n:-0}" -lt 1 ]; then rm -rf "$_tn_w"; return 1; fi
+  cp "$_tn_w/c$((_tn_n - 1)).pem" "$2"
+  rm -rf "$_tn_w"
+}
+
+# Bundles k3s reads (leaf first, root last), relative to server/tls.
+TN_CA_BUNDLES="server-ca.crt client-ca.crt request-header-ca.crt etcd/peer-ca.crt etcd/server-ca.crt intermediate-ca.crt root-ca.crt"
+
+# ----------------------------------------------------------------- the k3s data dir
+
+# The data dir of a k3s server, resolved the way k3s resolves it (verified against rancher/k3s
+# v1.36.5: a command line flag beats config.yaml.d/*.yaml, which beats config.yaml). First match wins:
+#   1. an explicit DATA_DIR (the environment, or --data-dir of this tool)
+#   2. --data-dir DIR, --data-dir=DIR, -d DIR or -d=DIR in the ExecStart of the k3s systemd unit
+#   3. the last data-dir in /etc/rancher/k3s/config.yaml.d/*.yaml (lexical order)
+#   4. data-dir in /etc/rancher/k3s/config.yaml
+#   5. K3S_DATA_DIR in the environment of the unit (Environment=, EnvironmentFile=)
+#   6. /var/lib/rancher/k3s
+# Sets and exports DATA_DIR and TN_CA_DATADIR_SRC (where it came from). Reading only; no globbing
+# (the bootstrap scripts run with noglob). A data-dir with white space in it is not supported.
+
+tn_ca_unit_name() { echo "${PRODUCT:-k3s}.service"; }
+
+# tn_ca_unit_text: the text of the k3s server unit (merged with drop-ins when systemd tells), or fail
+tn_ca_unit_text() {
+  _tn_un=$(tn_ca_unit_name)
+  if [ -n "${TN_K3S_UNIT_FILE:-}" ]; then
+    [ -r "$TN_K3S_UNIT_FILE" ] && cat "$TN_K3S_UNIT_FILE"
+    return
+  fi
+  if command -v systemctl >/dev/null 2>&1 && systemctl cat "$_tn_un" 2>/dev/null; then return 0; fi
+  for _tn_uf in "/etc/systemd/system/$_tn_un" "/lib/systemd/system/$_tn_un" "/usr/lib/systemd/system/$_tn_un"; do
+    if [ -r "$_tn_uf" ]; then cat "$_tn_uf"; return 0; fi
+  done
+  return 1
+}
+
+# tn_ca_unit_exists: is there a k3s SERVER unit (k3s.service; an agent has k3s-agent.service)
+tn_ca_unit_exists() { tn_ca_unit_text >/dev/null 2>&1; }
+
+# tn_ca_yaml_datadir FILE: the value of the last top-level `data-dir:` key, or nothing
+tn_ca_yaml_datadir() {
+  [ -r "$1" ] || return 0
+  awk '
+    { sub(/\r$/, "") }
+    /^data-dir[ \t]*:/ {
+      v = $0; sub(/^data-dir[ \t]*:[ \t]*/, "", v)
+      q = substr(v, 1, 1)
+      if (q == "\"" || q == "\047") { v = substr(v, 2); i = index(v, q); if (i > 0) v = substr(v, 1, i - 1) }
+      else { sub(/[ \t]+#.*$/, "", v); sub(/^#.*$/, "", v); sub(/[ \t]+$/, "", v) }
+      val = v
+    }
+    END { if (val != "") print val }' "$1"
+}
+
+# tn_ca_unit_datadir: --data-dir/-d of the last ExecStart= of the unit, or nothing
+tn_ca_unit_datadir() {
+  tn_ca_unit_text 2>/dev/null | awk '
+    cont { line = $0; if (line ~ /\\[ \t]*$/) { sub(/\\[ \t]*$/, "", line); buf = buf " " line } else { buf = buf " " line; cont = 0; last = buf; buf = "" } ; next }
+    /^ExecStart=/ {
+      line = $0; sub(/^ExecStart=/, "", line)
+      if (line ~ /\\[ \t]*$/) { sub(/\\[ \t]*$/, "", line); buf = line; cont = 1 } else { last = line }
+      next }
+    END {
+      if (cont) last = buf
+      gsub(/["\047]/, "", last); sub(/^[ \t]*[-@+!:]+/, "", last)
+      n = split(last, t, /[ \t]+/); val = ""
+      for (i = 1; i <= n; i++) {
+        if ((t[i] == "--data-dir" || t[i] == "-d") && i < n) val = t[i + 1]
+        else if (t[i] ~ /^--data-dir=/) val = substr(t[i], 12)
+        else if (t[i] ~ /^-d=/) val = substr(t[i], 4)
+      }
+      if (val != "") print val }'
+}
+
+# tn_ca_unit_env_datadir: K3S_DATA_DIR from Environment=/EnvironmentFile= of the unit
+tn_ca_unit_env_datadir() {
+  _tn_ut=$(tn_ca_unit_text 2>/dev/null) || return 0
+  _tn_ev=$(printf '%s\n' "$_tn_ut" | sed -n 's/^Environment=.*K3S_DATA_DIR=\([^ "]*\).*/\1/p' | tail -n 1)
+  if [ -z "$_tn_ev" ]; then
+    for _tn_ef in $(printf '%s\n' "$_tn_ut" | sed -n 's/^EnvironmentFile=-\{0,1\}//p'); do
+      [ -r "$_tn_ef" ] || continue
+      _tn_v=$(sed -n 's/^K3S_DATA_DIR=//p' "$_tn_ef" | tail -n 1 | sed "s/^['\"]//; s/['\"]\$//")
+      [ -z "$_tn_v" ] || _tn_ev=$_tn_v
+    done
+  fi
+  [ -z "$_tn_ev" ] || echo "$_tn_ev"
+}
+
+tn_ca_resolve_datadir() {
+  _tn_pr=${PRODUCT:-k3s}
+  if [ -n "${DATA_DIR:-}" ]; then
+    # our own earlier resolution keeps its source; anything else was given by the caller
+    if [ "${TN_CA_DATADIR_RES:-}" != "$DATA_DIR" ]; then TN_CA_DATADIR_SRC="--data-dir / DATA_DIR"; fi
+    export DATA_DIR TN_CA_DATADIR_SRC; return 0
+  fi
+  _tn_cd=${TN_K3S_CONFIG_DIR:-/etc/rancher/$_tn_pr}
+  _tn_v=$(tn_ca_unit_datadir)
+  if [ -n "$_tn_v" ]; then DATA_DIR=$_tn_v; TN_CA_DATADIR_SRC="ExecStart of $(tn_ca_unit_name)"; fi
+  if [ -z "$_tn_v" ] && [ -d "$_tn_cd/config.yaml.d" ]; then
+    for _tn_f in $(find "$_tn_cd/config.yaml.d" -maxdepth 1 -type f -name '*.yaml' 2>/dev/null | LC_ALL=C sort); do
+      _tn_x=$(tn_ca_yaml_datadir "$_tn_f")
+      if [ -n "$_tn_x" ]; then _tn_v=$_tn_x; TN_CA_DATADIR_SRC=$_tn_f; fi
+    done
+    [ -z "$_tn_v" ] || DATA_DIR=$_tn_v
+  fi
+  if [ -z "$_tn_v" ]; then
+    _tn_v=$(tn_ca_yaml_datadir "$_tn_cd/config.yaml")
+    if [ -n "$_tn_v" ]; then DATA_DIR=$_tn_v; TN_CA_DATADIR_SRC="$_tn_cd/config.yaml"; fi
+  fi
+  if [ -z "$_tn_v" ]; then
+    _tn_v=$(tn_ca_unit_env_datadir)
+    if [ -n "$_tn_v" ]; then DATA_DIR=$_tn_v; TN_CA_DATADIR_SRC="K3S_DATA_DIR of $(tn_ca_unit_name)"; fi
+  fi
+  if [ -z "$_tn_v" ]; then DATA_DIR=/var/lib/rancher/$_tn_pr; TN_CA_DATADIR_SRC=default; fi
+  TN_CA_DATADIR_RES=$DATA_DIR
+  export DATA_DIR TN_CA_DATADIR_SRC TN_CA_DATADIR_RES
+}
+
+# tn_ca_datadir_consistent: 0 if DATA_DIR is the data dir that the config files of k3s set, or they set
+# none. Sets TN_CA_CFG_DATADIR / TN_CA_CFG_DATADIR_SRC to the config file's value and file otherwise.
+# The k3s installer writes a new unit WITHOUT --data-dir and K3S_DATA_DIR: from then on k3s takes its data
+# dir from the config files. A DATA_DIR that came from anywhere else (the ExecStart of the old unit,
+# K3S_DATA_DIR, the caller) and differs from them would send k3s to a different directory, with the
+# CA we prepared, and the cluster, left behind.
+tn_ca_datadir_consistent() {
+  TN_CA_CFG_DATADIR=; TN_CA_CFG_DATADIR_SRC=
+  _tn_cd=${TN_K3S_CONFIG_DIR:-/etc/rancher/${PRODUCT:-k3s}}
+  if [ -d "$_tn_cd/config.yaml.d" ]; then
+    for _tn_f in $(find "$_tn_cd/config.yaml.d" -maxdepth 1 -type f -name '*.yaml' 2>/dev/null | LC_ALL=C sort); do
+      _tn_x=$(tn_ca_yaml_datadir "$_tn_f")
+      if [ -n "$_tn_x" ]; then TN_CA_CFG_DATADIR=$_tn_x; TN_CA_CFG_DATADIR_SRC=$_tn_f; fi
+    done
+  fi
+  if [ -z "$TN_CA_CFG_DATADIR" ]; then
+    _tn_x=$(tn_ca_yaml_datadir "$_tn_cd/config.yaml")
+    if [ -n "$_tn_x" ]; then TN_CA_CFG_DATADIR=$_tn_x; TN_CA_CFG_DATADIR_SRC=$_tn_cd/config.yaml; fi
+  fi
+  [ -n "$TN_CA_CFG_DATADIR" ] || return 0
+  _tn_a=$(printf '%s\n' "$DATA_DIR" | sed 's|//*|/|g; s|\(.\)/$|\1|')
+  _tn_b=$(printf '%s\n' "$TN_CA_CFG_DATADIR" | sed 's|//*|/|g; s|\(.\)/$|\1|')
+  [ "$_tn_a" = "$_tn_b" ]
+}
+
+# tn_ca_require_consistent_datadir: tn_ca_datadir_consistent, or stop with advice. Needs DATA_DIR (call
+# tn_ca_resolve_datadir first). A server script calls it right after tn_ca_resolve_datadir, before the
+# k3s release step changes anything; tn_k3s_ca_setup calls it again (cheap, and the library stays safe on its own).
+tn_ca_require_consistent_datadir() {
+  tn_ca_datadir_consistent ||
+    tn_ca_fatal "k3s runs from ${DATA_DIR} (${TN_CA_DATADIR_SRC}), but ${TN_CA_CFG_DATADIR_SRC} sets data-dir: ${TN_CA_CFG_DATADIR}. The k3s installer that follows writes a new unit without --data-dir, after which k3s would start from ${TN_CA_CFG_DATADIR}: an empty directory, with its own new CA, and the cluster in ${DATA_DIR} left behind. Make them agree first: either set data-dir in ${TN_CA_CFG_DATADIR_SRC} to ${DATA_DIR} (if that is where the cluster is), or remove that line and run this script again. The CA and k3s were not changed"
+}
+
+# ----------------------------------------------------------------- the root certificate
+
+# tn_ca_reissue_root SRC_CERT KEY OUT_CERT
+# New self-signed root from the SAME key and subject as SRC_CERT (and the same subject key
+# identifier), with CA:TRUE and keyUsage keyCertSign, valid 7300 days and a random 128-bit
+# serial (never the serial of SRC_CERT). The extensions of SRC_CERT are not carried over (no
+# duplicates, no extendedKeyUsage).
+tn_ca_reissue_root() {
+  _tn_rw=$(mktemp -d) || return 1
+  _tn_rski=$(tn_ca_ski "$1")
+  [ -n "$_tn_rski" ] || _tn_rski='hash'
+  cat > "$_tn_rw/root.cnf" <<EOF
+[v3_root]
+subjectKeyIdentifier = $_tn_rski
+authorityKeyIdentifier = keyid:always
+basicConstraints = critical, CA:true
+keyUsage = critical, digitalSignature, keyEncipherment, keyCertSign, cRLSign
+EOF
+  _tn_serial=$("$OPENSSL" rand -hex 16) || { rm -rf "$_tn_rw"; return 1; }
+  # Not `x509 -in SRC -signkey KEY -set_serial`: OpenSSL 1.1.1 (Jetson Ubuntu 18.04/20.04,
+  # Raspberry Pi bullseye) silently ignores -set_serial there and the new root would keep the
+  # serial of SRC, so two different certificates would share issuer and serial (RFC 5280
+  # 4.1.2.2; NSS rejects that). `x509 -req` honours it on every version. The request carries
+  # the subject and public key of SRC only; the extensions come from root.cnf.
+  { "$OPENSSL" x509 -x509toreq -in "$1" -signkey "$2" -out "$_tn_rw/root.csr" &&
+    "$OPENSSL" x509 -req -in "$_tn_rw/root.csr" -signkey "$2" -extfile "$_tn_rw/root.cnf" -extensions v3_root \
+      -set_serial "0x$_tn_serial" -days 7300 -sha256 -out "$3"; } >/dev/null 2>&1
+  _tn_rc=$?
+  rm -rf "$_tn_rw"
+  if [ "$_tn_rc" -ne 0 ]; then tn_ca_warn "cannot re-issue the root certificate from $1"; return 1; fi
+  tn_ca_has_certsign "$3" || { tn_ca_warn "re-issued root has no keyCertSign"; return 1; }
+  if [ "$("$OPENSSL" x509 -in "$1" -noout -serial 2>/dev/null)" = "$("$OPENSSL" x509 -in "$3" -noout -serial 2>/dev/null)" ]; then
+    tn_ca_warn "re-issued root has the serial of the original certificate (this openssl ignores -set_serial)"
+  fi
+}
+
+# ----------------------------------------------------------------- PKI generation
+
+# tn_ca_generate_pki TLS_DIR ROOT_CERT ROOT_KEY SUFFIX
+# TLS_DIR must exist and be empty. Creates root-ca.{pem,key,crt}, intermediate-ca.*, the five
+# leaf CAs and service.key in it exactly as the old bootstrap scripts did, below ROOT_CERT.
+# Runs in a subshell: the caller's directory and traps are not touched.
+tn_ca_generate_pki() {
+  (
+    # `set -e` is only a convenience here: this function is always called in an `if`/`||`
+    # context, where every POSIX shell ignores errexit, even when it is set again in a
+    # subshell. So EVERY step ends in `|| exit 1`, and the caller validates the result.
+    set -e
+    tls=$1 root=$2 rkey=$3 suffix=$4
+    product=${PRODUCT:-k3s}
+    cd "$tls" || exit 1
+    mkdir -p etcd .ca/certs || exit 1
+    cp "$root" root-ca.pem || exit 1
+    cp "$rkey" root-ca.key || exit 1
+    : > .ca/index || exit 1
+    "$OPENSSL" rand -hex 8 > .ca/serial || exit 1
+    cat > .ca/config <<'EOF' || exit 1
+[ca]
+default_ca = ca_default
+[ca_default]
+dir = ./.ca
+database = $dir/index
+serial = $dir/serial
+new_certs_dir = $dir/certs
+default_md = sha256
+policy = policy_anything
+[policy_anything]
+commonName = supplied
+[req]
+distinguished_name = req_distinguished_name
+[req_distinguished_name]
+[v3_ca]
+subjectKeyIdentifier = hash
+authorityKeyIdentifier = keyid:always
+basicConstraints = critical, CA:true
+keyUsage = critical, digitalSignature, keyEncipherment, keyCertSign
+EOF
+    if "$OPENSSL" version | grep -qF 'OpenSSL 3'; then GENRSA_FLAGS=-traditional; else GENRSA_FLAGS=; fi
+
+    # a CN is at most 64 characters (long device names used to break the bootstrap here)
+    cn() { printf '%s' "$1" | cut -c1-64; }
+    # quiet openssl, but show what it said when it fails
+    quiet() { "$@" > .ca/log 2>&1 || { cat .ca/log >&2; return 1; }; }
+    # tn_issue CSR OUT SIGNER_KEY SIGNER_CERT. Requests go through files, not a pipe: no
+    # /dev/stdin (missing in some chroots), and a failing `req` is not hidden by the pipeline.
+    tn_issue() {
+      quiet "$OPENSSL" ca -batch -notext -days 3700 -in "$1" -out "$2" \
+        -keyfile "$3" -cert "$4" -config .ca/config -extensions v3_ca
+    }
+
+    tn_ca_info "Generating Kubernetes service account issuer RSA key"
+    # shellcheck disable=SC2086
+    quiet "$OPENSSL" genrsa $GENRSA_FLAGS -out service.key 2048 || exit 1
+
+    cat root-ca.pem > root-ca.crt || exit 1
+
+    tn_ca_info "Generating intermediate certificate authority RSA key and certificate"
+    # shellcheck disable=SC2086
+    quiet "$OPENSSL" genrsa $GENRSA_FLAGS -out intermediate-ca.key 4096 || exit 1
+    quiet "$OPENSSL" req -new -nodes -subj "/CN=$(cn "${product}-intermediate-ca@${suffix}")" \
+      -key intermediate-ca.key -out .ca/req.csr || exit 1
+    tn_issue .ca/req.csr intermediate-ca.pem root-ca.key root-ca.pem || exit 1
+    cat intermediate-ca.pem root-ca.pem > intermediate-ca.crt || exit 1
+
+    # a new leaf CA for every control-plane and etcd component
+    for TYPE in client server request-header etcd/peer etcd/server; do
+      name="${product}-$(echo "$TYPE" | tr / -)-ca"
+      tn_ca_info "Generating ${name} leaf certificate authority EC key and certificate"
+      quiet "$OPENSSL" ecparam -name prime256v1 -genkey -noout -out "${TYPE}-ca.key" || exit 1
+      quiet "$OPENSSL" req -new -nodes -subj "/CN=$(cn "${name}@${suffix}")" -key "${TYPE}-ca.key" \
+        -out .ca/req.csr || exit 1
+      tn_issue .ca/req.csr "${TYPE}-ca.pem" intermediate-ca.key intermediate-ca.pem || exit 1
+      cat "${TYPE}-ca.pem" intermediate-ca.pem root-ca.pem > "${TYPE}-ca.crt" || exit 1
+    done
+    rm -rf .ca || exit 1
+  )
+}
+
+# tn_ca_validate_pki TLS_DIR: 0 only if TLS_DIR holds a complete PKI: every file k3s reads is
+# there and not empty, the bundles have the expected number of certificates, every key matches
+# its certificate, and the intermediate and all leaf CAs chain to root-ca.pem. Warns about the
+# first problem. Run on a freshly generated directory BEFORE it replaces the live one.
+tn_ca_validate_pki() {
+  _tn_vd=$1
+  for _tn_f in root-ca.pem root-ca.key root-ca.crt service.key intermediate-ca.pem intermediate-ca.key intermediate-ca.crt \
+    client-ca.pem client-ca.key client-ca.crt server-ca.pem server-ca.key server-ca.crt \
+    request-header-ca.pem request-header-ca.key request-header-ca.crt \
+    etcd/peer-ca.pem etcd/peer-ca.key etcd/peer-ca.crt etcd/server-ca.pem etcd/server-ca.key etcd/server-ca.crt; do
+    [ -s "$_tn_vd/$_tn_f" ] || { tn_ca_warn "generated PKI is incomplete: $_tn_f is missing or empty"; return 1; }
+  done
+  _tn_vw=$(mktemp -d) || return 1
+  _tn_vok=1
+  for _tn_t in intermediate client server request-header etcd/peer etcd/server; do
+    _tn_c=$_tn_vd/${_tn_t}-ca.pem
+    "$OPENSSL" verify -CAfile "$_tn_vd/root-ca.pem" -untrusted "$_tn_vd/intermediate-ca.pem" "$_tn_c" >/dev/null 2>&1 ||
+      { tn_ca_warn "generated PKI: ${_tn_t}-ca.pem does not chain to root-ca.pem"; _tn_vok=0; break; }
+    [ "$(tn_ca_pubhash_cert "$_tn_c")" = "$(tn_ca_pubhash_key "$_tn_vd/${_tn_t}-ca.key")" ] ||
+      { tn_ca_warn "generated PKI: ${_tn_t}-ca.key does not belong to ${_tn_t}-ca.pem"; _tn_vok=0; break; }
+    case $_tn_t in intermediate) _tn_want=2 ;; *) _tn_want=3 ;; esac
+    rm -rf "$_tn_vw/b"
+    _tn_n=$(tn_ca_split "$_tn_vd/${_tn_t}-ca.crt" "$_tn_vw/b")
+    [ "${_tn_n:-0}" -eq "$_tn_want" ] ||
+      { tn_ca_warn "generated PKI: ${_tn_t}-ca.crt holds ${_tn_n:-0} certificates, expected $_tn_want"; _tn_vok=0; break; }
+  done
+  if [ "$_tn_vok" = 1 ]; then
+    [ "$(tn_ca_pubhash_cert "$_tn_vd/root-ca.pem")" = "$(tn_ca_pubhash_key "$_tn_vd/root-ca.key")" ] ||
+      { tn_ca_warn "generated PKI: root-ca.key does not belong to root-ca.pem"; _tn_vok=0; }
+  fi
+  rm -rf "$_tn_vw"
+  [ "$_tn_vok" = 1 ]
+}
+
+# ----------------------------------------------------------------- state of a data dir
+
+# tn_ca_find_key DATA_DIR ROOT_CERT -> sets TN_CA_KEY to a private key file whose public
+# key matches ROOT_CERT (server/tls/root-ca.key first, then the device key); returns 1 if none.
+tn_ca_find_key() {
+  TN_CA_KEY=; TN_CA_UNREADABLE=
+  _tn_want=$(tn_ca_pubhash_cert "$2")
+  [ -n "$_tn_want" ] || return 1
+  for _tn_k in "$1/server/tls/root-ca.key" "${CONFIG_PATH:-/etc/teknoir}/rsa_private.pem"; do
+    [ -f "$_tn_k" ] || continue
+    [ -r "$_tn_k" ] || { TN_CA_UNREADABLE=$_tn_k; continue; }
+    if [ "$(tn_ca_pubhash_key "$_tn_k")" = "$_tn_want" ]; then TN_CA_KEY=$_tn_k; return 0; fi
+  done
+  return 1
+}
+
+# tn_ca_state DATA_DIR
+# Sets TN_CA_STATE and TN_CA_MSG; returns the `check` exit code.
+#   not-a-server        no server/tls/server-ca.crt and no k3s server unit (an agent node, or nothing
+#                       installed yet)
+#   no-server-data      a k3s server unit exists but there is no server/tls/server-ca.crt in the data
+#                       dir we resolved: k3s has not started yet, or its data dir is somewhere else.
+#                       Never reported as ok (rc 4)
+#   ok                  the root has keyCertSign and is valid for more than 90 days
+#   needs-rotation      initialised, root unusable, we hold the key
+#   needs-regeneration  never initialised, PKI unusable, we hold the key
+#   foreign             root unusable and we do not hold its key
+# Also sets TN_CA_ROOT_USABLE: 0 when k3s refuses the root as it is (a multi-certificate bundle
+# whose root has no keyCertSign, or an expired root), 1 otherwise (including "expires soon").
+tn_ca_state() {
+  TN_CA_STATE=; TN_CA_MSG=; TN_CA_ROOT_USABLE=1
+  _tn_tls=$1/server/tls
+  if [ ! -f "$_tn_tls/server-ca.crt" ]; then
+    if tn_ca_unit_exists; then
+      TN_CA_STATE=no-server-data
+      TN_CA_MSG="the k3s server unit $(tn_ca_unit_name) exists, but $_tn_tls/server-ca.crt does not (data dir $1, taken from ${TN_CA_DATADIR_SRC:-the caller}): k3s has not started yet, or its data dir is elsewhere. Check 'systemctl cat $(tn_ca_unit_name)' and ${TN_K3S_CONFIG_DIR:-/etc/rancher/${PRODUCT:-k3s}}/config.yaml*, then pass --data-dir DIR"
+      return 4
+    fi
+    TN_CA_STATE=not-a-server; TN_CA_MSG="no $_tn_tls/server-ca.crt and no k3s server unit: nothing to check"; return 0
+  fi
+  _tn_sw=$(mktemp -d) || return 1
+  if ! tn_ca_lastcert "$_tn_tls/server-ca.crt" "$_tn_sw/root.pem"; then
+    rm -rf "$_tn_sw"; TN_CA_STATE=error; TN_CA_MSG="cannot read the root certificate from $_tn_tls/server-ca.crt"; return 1
+  fi
+  _tn_ncert=$(tn_ca_split "$_tn_tls/server-ca.crt" "$_tn_sw/b")
+  _tn_why=
+  TN_CA_ROOT_USABLE=1   # 0: k3s refuses this root now (no keyCertSign in a bundle, or expired)
+  if [ "$_tn_ncert" -gt 1 ] && ! tn_ca_has_certsign "$_tn_sw/root.pem"; then
+    _tn_why="the root certificate has no keyCertSign"; TN_CA_ROOT_USABLE=0
+  fi
+  if ! "$OPENSSL" x509 -in "$_tn_sw/root.pem" -noout -checkend 0 >/dev/null 2>&1; then
+    TN_CA_ROOT_USABLE=0
+    [ -n "$_tn_why" ] || _tn_why="the root certificate is expired"
+  elif [ -z "$_tn_why" ] && ! "$OPENSSL" x509 -in "$_tn_sw/root.pem" -noout -checkend 7776000 >/dev/null 2>&1; then
+    _tn_why="the root certificate expires within 90 days"
+  fi
+  if [ -z "$_tn_why" ]; then
+    rm -rf "$_tn_sw"; TN_CA_STATE=ok; TN_CA_MSG="the root certificate is acceptable to k3s"; return 0
+  fi
+  if ! tn_ca_find_key "$1" "$_tn_sw/root.pem" && [ -n "$TN_CA_UNREADABLE" ]; then
+    rm -rf "$_tn_sw"; TN_CA_STATE=error; TN_CA_MSG="cannot read $TN_CA_UNREADABLE: run as root"; return 1
+  fi
+  if tn_ca_find_key "$1" "$_tn_sw/root.pem"; then
+    if tn_ca_initialised "$1"; then
+      TN_CA_STATE=needs-rotation; TN_CA_MSG="$_tn_why: k3s v1.34.12/v1.35.9/v1.36.5/v1.37.1 and later will refuse to start; run: sh tn-k3s-ca.sh remediate"
+      rm -rf "$_tn_sw"; return 2
+    fi
+    TN_CA_STATE=needs-regeneration; TN_CA_MSG="$_tn_why, and k3s never finished its first start here: the PKI can simply be regenerated; run: sh tn-k3s-ca.sh remediate"
+    rm -rf "$_tn_sw"; return 3
+  fi
+  TN_CA_STATE=foreign; TN_CA_MSG="$_tn_why, but this is not the Teknoir device CA (no matching key in $_tn_tls/root-ca.key or ${CONFIG_PATH:-/etc/teknoir}/rsa_private.pem)"
+  rm -rf "$_tn_sw"; return 4
+}
+
+# tn_ca_suffix DATA_DIR: "<device-id>.<domain>" for the CN of new CAs
+tn_ca_suffix() {
+  if [ -n "${_DEVICE_ID:-}" ] && [ -n "${_DOMAIN:-}" ]; then echo "${_DEVICE_ID}.${_DOMAIN}"; return 0; fi
+  _tn_f=$1/server/tls/intermediate-ca.pem
+  if [ -f "$_tn_f" ]; then
+    _tn_cn=$("$OPENSSL" x509 -in "$_tn_f" -noout -subject 2>/dev/null | sed -n 's/.*CN *= *//p' | sed 's/,.*//')
+    case $_tn_cn in *@*) echo "${_tn_cn#*@}"; return 0 ;; esac
+  fi
+  echo "$(hostname 2>/dev/null || echo device).local"
+}
+
+# ----------------------------------------------------------------- setup (sourced by the bootstrap scripts)
+
+# tn_ca_pki_current DATA_DIR: 0 if the PKI in server/tls is complete, belongs to the current
+# device key, has a usable root and chains from the leaf CAs to it.
+tn_ca_pki_current() {
+  _tn_tls=$1/server/tls
+  for _tn_f in $TN_CA_BUNDLES root-ca.pem root-ca.key service.key intermediate-ca.pem intermediate-ca.key; do
+    [ -s "$_tn_tls/$_tn_f" ] || return 1
+  done
+  tn_ca_state "$1" >/dev/null || return 1
+  [ "$TN_CA_STATE" = ok ] || return 1
+  [ "$(tn_ca_pubhash_cert "$_tn_tls/root-ca.pem")" = "$(tn_ca_pubhash_key "${CONFIG_PATH:-/etc/teknoir}/rsa_private.pem")" ] || return 1
+  _tn_cw=$(mktemp -d) || return 1
+  _tn_cok=0
+  tn_ca_split "$_tn_tls/server-ca.crt" "$_tn_cw" >/dev/null
+  if "$OPENSSL" verify -CAfile "$_tn_tls/root-ca.pem" -untrusted "$_tn_tls/intermediate-ca.pem" "$_tn_cw/c0.pem" >/dev/null 2>&1; then _tn_cok=1; fi
+  rm -rf "$_tn_cw"
+  [ "$_tn_cok" = 1 ]
+}
+
+# tn_ca_backup_tls DATA_DIR: tar server/tls (if it holds anything) to server/tls-backup-tn-<ts>.tar.
+# The tars hold keys: the newest 3 are kept.
+tn_ca_backup_tls() {
+  [ -d "$1/server/tls" ] || return 0
+  _tn_bk="$1/server/tls-backup-tn-$(tn_ca_ts).tar"
+  ( umask 077; tar -C "$1/server" -cf "$_tn_bk" tls ) || { tn_ca_warn "cannot back up $1/server/tls"; return 1; }
+  chmod 600 "$_tn_bk" 2>/dev/null || true
+  for _tn_o in $(find "$1/server" -maxdepth 1 -type f -name 'tls-backup-tn-*.tar' 2>/dev/null | LC_ALL=C sort |
+    awk '{ a[NR] = $0 } END { for (i = 1; i <= NR - 3; i++) print a[i] }'); do rm -f "$_tn_o"; done
+  tn_ca_info "Previous CA files saved to $_tn_bk"
+}
+
+# tn_ca_run_bounded SECONDS CMD...: run CMD, give up (return 124) after SECONDS. The k3s unit has
+# TimeoutStartSec=0, so `systemctl start|restart` of a k3s that cannot start (the very case this tool
+# repairs) never returns. Without `timeout` (very old coreutils) the command runs unbounded.
+tn_ca_run_bounded() {
+  _tn_rb=$1; shift
+  if command -v timeout >/dev/null 2>&1; then timeout "$_tn_rb" "$@"; else "$@"; fi
+}
+tn_ca_svc_timeout() { echo "${TN_K3S_SERVICE_TIMEOUT:-600}"; }
+
+# tn_ca_unit_state: the ActiveState of the k3s unit (active, activating, ...), or nothing
+tn_ca_unit_state() {
+  command -v systemctl >/dev/null 2>&1 || return 0
+  systemctl is-active "$(tn_ca_unit_name)" 2>/dev/null || true
+}
+
+# k3s around the replacement of server/tls. Stopped if the unit runs OR is starting (activating: a
+# k3s that hangs in its first start, or restarts in a loop, is exactly the device that is repaired
+# here, and it would rewrite files under us), never when there is no unit (a bootstrap of a new
+# device has no k3s yet), and started again only if we stopped it.
+tn_ca_k3s_active() {
+  if [ -n "${TN_K3S_STOP_CMD:-}" ]; then return 0; fi
+  case $(tn_ca_unit_state) in active|activating|reloading) return 0 ;; esac
+  return 1
+}
+# tn_ca_k3s_ready: the unit is up and READY (Type=notify: k3s said so). Only that state.
+tn_ca_k3s_ready() { [ "$(tn_ca_unit_state)" = active ]; }
+tn_ca_k3s_stop() {
+  if [ -n "${TN_K3S_STOP_CMD:-}" ]; then tn_ca_run_bounded "$(tn_ca_svc_timeout)" sh -c "$TN_K3S_STOP_CMD"
+  else tn_ca_run_bounded "$(tn_ca_svc_timeout)" systemctl stop "$(tn_ca_unit_name)"; fi
+}
+tn_ca_k3s_start() {
+  if [ -n "${TN_K3S_START_CMD:-}" ]; then tn_ca_run_bounded "$(tn_ca_svc_timeout)" sh -c "$TN_K3S_START_CMD"
+  else tn_ca_run_bounded "$(tn_ca_svc_timeout)" systemctl start "$(tn_ca_unit_name)"; fi
+}
+
+# tn_ca_guard_unknown_datadir DATA_DIR: 0 if it is fine to go on. A data dir that k3s never
+# initialised (no server/token) while the k3s unit is up and READY means that k3s runs from a
+# DIFFERENT data dir than the one we resolved (a --config file, a drop-in we do not read ...):
+# generating a CA here would not touch the CA that k3s uses, and the installer that follows would
+# upgrade a k3s whose CA was never checked.
+tn_ca_guard_unknown_datadir() {
+  tn_ca_initialised "$1" && return 0
+  tn_ca_k3s_ready || return 0
+  tn_ca_warn "the k3s unit $(tn_ca_unit_name) is active and ready, but the data dir $1 (taken from ${TN_CA_DATADIR_SRC:-the caller}) was never initialised by k3s (no server/token): k3s runs from another data dir, so the CA that k3s uses was not looked at. Find it ('systemctl cat $(tn_ca_unit_name)', ${TN_K3S_CONFIG_DIR:-/etc/rancher/${PRODUCT:-k3s}}/config.yaml*, k3s server --config) and run again with DATA_DIR=/that/dir (or --data-dir). The CA and k3s were not changed"
+  return 1
+}
+
+# tn_ca_install_pki DATA_DIR SUFFIX: build a complete new PKI from the device certificate and
+# replace server/tls with it. The data dir must not be initialised. Order: generate and validate in
+# a work dir; stop k3s (if it runs: a hung start would rewrite files under us); back server/tls up;
+# move the old dir aside (rename); check that the target is gone; move the new dir in; validate the
+# INSTALLED result. Any failure puts the old dir back and starts k3s again if it was stopped.
+tn_ca_install_pki() {
+  _tn_dd=$1 _tn_sfx=$2
+  _tn_cfg=${CONFIG_PATH:-/etc/teknoir}
+  [ -s "$_tn_cfg/rsa_public.pem" ] && [ -s "$_tn_cfg/rsa_private.pem" ] ||
+    { tn_ca_warn "device certificate or key missing in $_tn_cfg"; return 1; }
+  mkdir -p "$_tn_dd/server" || return 1
+  _tn_new=$(mktemp -d "$_tn_dd/server/.tn-tls-new.XXXXXX") || return 1
+  _tn_rt=$(mktemp -d) || { rm -rf "$_tn_new"; return 1; }
+  tn_ca_info "Re-issuing the device certificate as the k3s root CA (keyCertSign)"
+  if ! tn_ca_reissue_root "$_tn_cfg/rsa_public.pem" "$_tn_cfg/rsa_private.pem" "$_tn_rt/root.pem"; then
+    rm -rf "$_tn_new" "$_tn_rt"; return 1
+  fi
+  mkdir -p "$_tn_new/etcd"
+  if ! tn_ca_generate_pki "$_tn_new" "$_tn_rt/root.pem" "$_tn_cfg/rsa_private.pem" "$_tn_sfx"; then
+    tn_ca_warn "PKI generation failed"
+    rm -rf "$_tn_new" "$_tn_rt"; return 1
+  fi
+  if ! tn_ca_validate_pki "$_tn_new"; then
+    tn_ca_warn "the generated PKI is not usable: $_tn_dd/server/tls was not changed"
+    rm -rf "$_tn_new" "$_tn_rt"; return 1
+  fi
+  rm -rf "$_tn_rt"
+  _tn_tlsd=$_tn_dd/server/tls
+  _tn_stopped=0
+  if tn_ca_k3s_active; then
+    tn_ca_info "Stopping k3s while $_tn_tlsd is replaced"
+    if ! tn_ca_k3s_stop; then
+      tn_ca_warn "cannot stop k3s: $_tn_tlsd was not changed"
+      rm -rf "$_tn_new"; return 1
+    fi
+    _tn_stopped=1
+  fi
+  _tn_aside=
+  _tn_ok=1
+  if [ -d "$_tn_tlsd" ]; then
+    tn_ca_backup_tls "$_tn_dd" || _tn_ok=0
+    # keep an old service account key so tokens issued before stay valid
+    if [ "$_tn_ok" = 1 ] && [ -s "$_tn_tlsd/service.key" ]; then
+      cat "$_tn_tlsd/service.key" >> "$_tn_new/service.key" || _tn_ok=0
+    fi
+    if [ "$_tn_ok" = 1 ]; then
+      _tn_aside=$_tn_dd/server/.tn-tls-old.$(tn_ca_ts).$$
+      if ! mv "$_tn_tlsd" "$_tn_aside"; then _tn_aside=; _tn_ok=0; fi
+    fi
+  fi
+  if [ "$_tn_ok" = 1 ]; then
+    if [ -e "$_tn_tlsd" ] || [ -L "$_tn_tlsd" ]; then
+      tn_ca_warn "$_tn_tlsd is still there after it was moved aside: not replacing it"; _tn_ok=0
+    elif ! mv "$_tn_new" "$_tn_tlsd"; then
+      tn_ca_warn "cannot move the new PKI to $_tn_tlsd"; _tn_ok=0
+    else
+      chmod 750 "$_tn_tlsd" 2>/dev/null || true
+      tn_ca_validate_pki "$_tn_tlsd" || { tn_ca_warn "the installed PKI in $_tn_tlsd does not validate"; _tn_ok=0; }
+    fi
+  fi
+  if [ "$_tn_ok" != 1 ]; then
+    if [ -n "$_tn_aside" ]; then
+      rm -rf "$_tn_tlsd"
+      if mv "$_tn_aside" "$_tn_tlsd"; then tn_ca_warn "the previous $_tn_tlsd was restored"
+      else tn_ca_warn "CANNOT RESTORE the previous server/tls: it is in $_tn_aside (a backup tar is next to it)"; fi
+    fi
+    rm -rf "$_tn_new"
+    if [ "$_tn_stopped" = 1 ]; then
+      tn_ca_k3s_start || tn_ca_warn "k3s was stopped and could not be started again: start it yourself (systemctl start $(tn_ca_unit_name))"
+    fi
+    return 1
+  fi
+  [ -z "$_tn_aside" ] || rm -rf "$_tn_aside"
+  tn_ca_changed "the k3s PKI in $_tn_tlsd was generated from the device certificate"
+  if [ "$_tn_stopped" = 1 ]; then
+    if tn_ca_k3s_start; then
+      tn_ca_changed "k3s was stopped and started again"
+    else
+      tn_ca_changed "k3s was stopped and could not be started again"
+      tn_ca_warn "the new CA is installed, but k3s could not be started: start it yourself (systemctl start $(tn_ca_unit_name))"
+    fi
+  fi
+  return 0
+}
+
+# tn_k3s_ca_setup: the bootstrap step. Uses CONFIG_PATH, DATA_DIR, PRODUCT, _DEVICE_ID, _DOMAIN.
+#   never started   -> create the PKI below the re-issued root
+#   started, ok     -> leave everything alone (re-running a bootstrap script is safe)
+#   started, old    -> repair it first (TN_K3S_CA_AUTO_REMEDIATE=false: stop with advice)
+#   started, foreign (not the Teknoir device CA, we hold no key): left alone while k3s still
+#                      accepts its root; otherwise STOP (exit 1): the k3s installer that follows
+#                      would upgrade k3s and the device would no longer start
+tn_k3s_ca_setup() {
+  tn_ca_info "Prepare K3s CA Certs"
+  export PRODUCT="${PRODUCT:-k3s}"
+  tn_ca_openssl || tn_ca_fatal "openssl not found or missing Elliptic Curve (ecparam) support."
+  tn_ca_info "Using ${OPENSSL}: $("$OPENSSL" version)"
+  tn_ca_resolve_datadir
+  tn_ca_info "k3s data dir: ${DATA_DIR} (${TN_CA_DATADIR_SRC})"
+  tn_ca_require_consistent_datadir
+  _tn_cfg=${CONFIG_PATH:-/etc/teknoir}
+  [ -s "$_tn_cfg/rsa_public.pem" ] && [ -s "$_tn_cfg/rsa_private.pem" ] ||
+    tn_ca_fatal "device certificate or key missing in $_tn_cfg"
+
+  if tn_ca_initialised "$DATA_DIR"; then
+    tn_ca_state "$DATA_DIR" || true
+    case $TN_CA_STATE in
+      ok|not-a-server)
+        [ "$TN_CA_STATE" != ok ] || tn_ca_clean_stages "$DATA_DIR"
+        tn_ca_info "k3s has already started on this device: the existing CA is left alone ($TN_CA_STATE: $TN_CA_MSG)"
+        return 0 ;;
+      foreign)
+        # not the Teknoir device CA: we cannot repair it. A root k3s refuses must stop the
+        # bootstrap, or the installer below would upgrade k3s and brick the device.
+        if [ "$TN_CA_ROOT_USABLE" != 1 ]; then
+          tn_ca_fatal "$TN_CA_MSG. The k3s CA of this device cannot be repaired here, and a k3s upgrade would stop it from starting: k3s must not be upgraded. The CA and k3s were not changed. Restore the matching CA key, or contact Teknoir support"
+        fi
+        tn_ca_warn "$TN_CA_MSG"
+        tn_ca_info "k3s has already started on this device: the existing CA is left alone (its root still has keyCertSign; it only expires soon, so replace this CA before it does)"
+        return 0 ;;
+      needs-rotation)
+        tn_ca_warn "$TN_CA_MSG"
+        if [ "${TN_K3S_CA_AUTO_REMEDIATE:-true}" != true ]; then
+          tn_ca_fatal "TN_K3S_CA_AUTO_REMEDIATE is not true: run 'sh tn-k3s-ca.sh remediate' and then this script again, or the k3s installer below will break the device"
+        fi
+        tn_ca_info "Repairing the CA of this device before k3s is installed or updated"
+        _tn_rr=0
+        tn_ca_remediate all || _tn_rr=$?
+        case $_tn_rr in
+          0) return 0 ;;
+          5) tn_ca_fatal "the k3s CA of this device WAS changed (see above: the datastore of k3s holds the new CA), but a later step failed. Do not roll back and do not run the k3s installer yet: fix that step, make sure k3s is running, then run this script again" ;;
+          *) tn_ca_fatal "CA remediation failed; the device was not changed beyond the saved backup. See the messages above" ;;
+        esac ;;
+      *) tn_ca_fatal "unexpected CA state '$TN_CA_STATE': $TN_CA_MSG" ;;
+    esac
+  fi
+
+  # not initialised here. If k3s is nevertheless up and ready, it runs from another data dir.
+  tn_ca_guard_unknown_datadir "$DATA_DIR" || tn_ca_fatal "cannot tell which data dir k3s uses (see above)"
+  if tn_ca_pki_current "$DATA_DIR"; then
+    tn_ca_clean_stages "$DATA_DIR"
+    tn_ca_info "A valid CA already exists in ${DATA_DIR}/server/tls (k3s has not started yet): keeping it"
+    return 0
+  fi
+  tn_ca_install_pki "$DATA_DIR" "$(tn_ca_suffix "$DATA_DIR")" || tn_ca_fatal "Cannot generate the k3s CA"
+  return 0
+}
+
+# ----------------------------------------------------------------- remediation
+
+# A staged rotation lives in DATA_DIR/server/.tn-ca-rotate-<ts>/ (mode 700):
+#   server/tls/   the new bootstrap data for `k3s certificate rotate-ca --path`
+#   trust.pem     the server-ca of the running server, trusted via SSL_CERT_FILE for the call
+#   ROTATE_CMD    the exact command; touches ROTATED when it succeeds
+# `finalize` copies the new files into server/tls once ROTATED exists, and removes the dir.
+
+tn_ca_newest_stage() { # DATA_DIR -> prints the newest staging dir, or nothing
+  find "$1/server" -maxdepth 1 -type d -name '.tn-ca-rotate-*' 2>/dev/null | LC_ALL=C sort | tail -n 1
+}
+
+# tn_ca_clean_stages DATA_DIR: remove every staging dir of a rotation (.tn-ca-rotate-*) and every work
+# dir of a regeneration that was interrupted (.tn-tls-old.* and .tn-tls-new.*: the previous server/tls
+# that was moved aside, and the new one before it was moved in). Only when the CA is fine: they all
+# hold copies of the CA keys, and a crashed run leaves them behind.
+tn_ca_clean_stages() {
+  find "$1/server" -maxdepth 1 -type d \( -name '.tn-ca-rotate-*' -o -name '.tn-tls-old.*' -o -name '.tn-tls-new.*' \) 2>/dev/null |
+    while read -r _tn_cs; do
+      rm -rf "$_tn_cs" && tn_ca_info "Removed the leftover staging dir $_tn_cs (it held copies of the CA keys)"
+    done
+  return 0
+}
+
+tn_ca_k3s_bin() { echo "${K3S_BIN:-k3s}"; }
+
+# tn_ca_rotate_supported: 0 if the k3s binary has `certificate rotate-ca` or its version cannot be
+# told, 1 if it is too old (added in v1.24.12, v1.25.8, v1.26.3; every v1.27+ has it). Sets
+# TN_CA_K3S_VERSION.
+tn_ca_rotate_supported() {
+  TN_CA_K3S_VERSION=
+  _tn_vo=$($(tn_ca_k3s_bin) --version 2>/dev/null | sed -n '1s/^.*version v\{0,1\}\([0-9][0-9]*\)\.\([0-9][0-9]*\)\.\([0-9][0-9]*\).*$/\1 \2 \3/p') || return 0
+  [ -n "$_tn_vo" ] || return 0
+  IFS=' ' read -r _tn_vma _tn_vmi _tn_vpa <<EOV
+$_tn_vo
+EOV
+  TN_CA_K3S_VERSION=v$_tn_vma.$_tn_vmi.$_tn_vpa
+  [ "$_tn_vma" -eq 1 ] || return 0
+  case $_tn_vmi in
+    24) [ "$_tn_vpa" -ge 12 ] ;;
+    25) [ "$_tn_vpa" -ge 8 ] ;;
+    26) [ "$_tn_vpa" -ge 3 ] ;;
+    *) [ "$_tn_vmi" -ge 27 ] ;;
+  esac
+}
+
+tn_ca_warn_rotate_unsupported() {
+  tn_ca_warn "k3s $TN_CA_K3S_VERSION has no 'k3s certificate rotate-ca' (it came with v1.24.12, v1.25.8 and v1.26.3; every v1.27+ has it), so the root CA cannot be replaced on this k3s. The CA and k3s were not changed."
+  tn_ca_warn "This k3s keeps running with its current CA (the keyCertSign check came with v1.34.12/v1.35.9/v1.36.5/v1.37.1). Do not upgrade it to one of those yet: upgrade it one minor version at a time to a release that is older than that but has rotate-ca (v1.27 to v1.34.11), then run remediate again, and only then go on."
+}
+
+# prepare: stage a rotation (initialised), or regenerate the PKI in place (never started)
+tn_ca_prepare() {
+  _tn_dd=$1
+  tn_ca_state "$_tn_dd" || _tn_rc=$?
+  _tn_rc=${_tn_rc:-0}
+  case $TN_CA_STATE in
+    not-a-server) tn_ca_info "$TN_CA_MSG"; return 0 ;;
+    ok) tn_ca_clean_stages "$_tn_dd"; tn_ca_info "root CA already fine: nothing to do"; return 0 ;;
+    foreign|no-server-data) tn_ca_warn "$TN_CA_MSG"; return 4 ;;
+    needs-regeneration)
+      tn_ca_warn "$TN_CA_MSG"
+      tn_ca_guard_unknown_datadir "$_tn_dd" || return 4
+      tn_ca_info "Regenerating the PKI in $_tn_dd/server/tls (k3s never finished a start on this device)"
+      tn_ca_install_pki "$_tn_dd" "$(tn_ca_suffix "$_tn_dd")" || return 1
+      tn_ca_info "Done. k3s starts from the new CA. Nothing to rotate."
+      return 0 ;;
+    needs-rotation) ;;
+    *) tn_ca_warn "$TN_CA_MSG"; return 1 ;;
+  esac
+
+  if ! tn_ca_rotate_supported; then tn_ca_warn_rotate_unsupported; return 1; fi
+  if [ -d "$_tn_dd/server/db/etcd" ]; then
+    tn_ca_warn "this server uses embedded etcd: with several servers, read https://docs.k3s.io/cli/certificate first; this tool was tested with one server (sqlite)"
+  fi
+  _tn_tls=$_tn_dd/server/tls
+  _tn_ts=$(tn_ca_ts)
+  _tn_s=$_tn_dd/server/.tn-ca-rotate-$_tn_ts
+  # earlier unfinished stagings hold copies of the keys: drop them
+  find "$_tn_dd/server" -maxdepth 1 -type d -name '.tn-ca-rotate-*' -exec rm -rf {} + 2>/dev/null || true
+  ( umask 077; mkdir -p "$_tn_s/server/tls/etcd" "$_tn_s/w" ) || return 1
+  tn_ca_split "$_tn_tls/server-ca.crt" "$_tn_s/w" >/dev/null || { rm -rf "$_tn_s"; return 1; }
+  tn_ca_lastcert "$_tn_tls/server-ca.crt" "$_tn_s/oldroot.pem" || { rm -rf "$_tn_s"; return 1; }
+  tn_ca_find_key "$_tn_dd" "$_tn_s/oldroot.pem" || { rm -rf "$_tn_s"; return 1; }
+  _tn_key=$TN_CA_KEY
+  tn_ca_reissue_root "$_tn_s/oldroot.pem" "$_tn_key" "$_tn_s/newroot.pem" || { rm -rf "$_tn_s"; return 1; }
+  _tn_oldfp=$(tn_ca_fp "$_tn_s/oldroot.pem")
+
+  # a copy of everything k3s keeps there (keys, service.key, bundles)
+  ( cd "$_tn_tls" && tar -cf - . ) | ( cd "$_tn_s/server/tls" && tar -xf - ) || { rm -rf "$_tn_s"; return 1; }
+  rm -rf "$_tn_s/server/tls/.ca"
+  # every bundle: the old root replaced by the new one, all other certificates kept. This function
+  # runs in an `||` context, where `set -e` does not exist: EVERY write is checked, and each rebuilt
+  # bundle is verified before anything is handed to rotate-ca.
+  _tn_newfp=$(tn_ca_fp "$_tn_s/newroot.pem") || { rm -rf "$_tn_s"; return 1; }
+  _tn_rbok=1
+  for _tn_b in $TN_CA_BUNDLES; do
+    [ -f "$_tn_tls/$_tn_b" ] || continue
+    rm -rf "$_tn_s/b" "$_tn_s/v"
+    mkdir -p "$_tn_s/b" "$_tn_s/v" || { _tn_rbok=0; break; }
+    _tn_n=$(tn_ca_split "$_tn_tls/$_tn_b" "$_tn_s/b") || { _tn_rbok=0; break; }
+    if [ "${_tn_n:-0}" -lt 1 ]; then tn_ca_warn "$_tn_b holds no certificate"; _tn_rbok=0; break; fi
+    : > "$_tn_s/server/tls/$_tn_b" || { _tn_rbok=0; break; }
+    _tn_i=0
+    while [ "$_tn_i" -lt "$_tn_n" ]; do
+      if [ "$(tn_ca_fp "$_tn_s/b/c$_tn_i.pem")" = "$_tn_oldfp" ]; then
+        cat "$_tn_s/newroot.pem" >> "$_tn_s/server/tls/$_tn_b" || { _tn_rbok=0; break; }
+      else
+        cat "$_tn_s/b/c$_tn_i.pem" >> "$_tn_s/server/tls/$_tn_b" || { _tn_rbok=0; break; }
+      fi
+      _tn_i=$((_tn_i + 1))
+    done
+    [ "$_tn_rbok" = 1 ] || break
+    # the rebuilt bundle: as many certificates as before, and the new root last
+    _tn_m=$(tn_ca_split "$_tn_s/server/tls/$_tn_b" "$_tn_s/v") || _tn_m=
+    if [ "${_tn_m:-x}" != "$_tn_n" ]; then
+      tn_ca_warn "the rebuilt $_tn_b holds ${_tn_m:-no} certificates, the original $_tn_n"; _tn_rbok=0; break
+    fi
+    if [ "$(tn_ca_fp "$_tn_s/v/c$((_tn_n - 1)).pem")" != "$_tn_newfp" ]; then
+      tn_ca_warn "the last certificate of the rebuilt $_tn_b is not the new root (unexpected layout of the original bundle)"
+      _tn_rbok=0; break
+    fi
+  done
+  if [ "$_tn_rbok" != 1 ]; then
+    tn_ca_warn "cannot rebuild the CA bundles (disk full? unexpected layout?): the CA and k3s were not changed"
+    rm -rf "$_tn_s"; return 1
+  fi
+  rm -rf "$_tn_s/b" "$_tn_s/v"
+  cp "$_tn_s/newroot.pem" "$_tn_s/server/tls/root-ca.pem" || { rm -rf "$_tn_s"; return 1; }
+
+  # every leaf CA must verify through the new root
+  for _tn_b in server-ca.crt client-ca.crt request-header-ca.crt etcd/peer-ca.crt etcd/server-ca.crt; do
+    [ -f "$_tn_s/server/tls/$_tn_b" ] || continue
+    rm -rf "$_tn_s/b"; mkdir -p "$_tn_s/b"
+    tn_ca_split "$_tn_s/server/tls/$_tn_b" "$_tn_s/b" >/dev/null
+    if ! "$OPENSSL" verify -CAfile "$_tn_s/newroot.pem" -untrusted "$_tn_s/server/tls/intermediate-ca.crt" "$_tn_s/b/c0.pem" >/dev/null 2>&1; then
+      tn_ca_warn "the new root does not verify $_tn_b: the CA and k3s were not changed"
+      rm -rf "$_tn_s"; return 1
+    fi
+  done
+  rm -rf "$_tn_s/b"
+
+  # k3s only accepts the new bundle if the OLD root can still vouch for the chain (it verifies the
+  # new leaf CAs with the old chain). An old root that is expired or not yet valid, that has no
+  # basicConstraints or CA:FALSE, or that has a keyUsage without keyCertSign (the device-controller
+  # certificates) cannot (Go refuses such a parent), however good the new bundle is. Verified above
+  # with openssl; then k3s's own check is skipped (--force). The explicit tests are followed by a
+  # general one: if openssl cannot verify the OLD chain against the old root, but the new chain
+  # verifies (done above), the old root is no voucher either.
+  _tn_force=; _tn_fwhy=
+  _tn_otxt=$("$OPENSSL" x509 -in "$_tn_s/oldroot.pem" -noout -text 2>/dev/null)
+  _tn_obc=$(printf '%s\n' "$_tn_otxt" | awk '/X509v3 Basic Constraints/ { getline; print; exit }')
+  if ! "$OPENSSL" x509 -in "$_tn_s/oldroot.pem" -noout -checkend 0 >/dev/null 2>&1; then
+    _tn_fwhy="the old root has expired"
+  elif [ -z "$_tn_obc" ]; then
+    _tn_fwhy="the old root has no basicConstraints"
+  elif printf '%s\n' "$_tn_obc" | grep -q 'CA:FALSE'; then
+    _tn_fwhy="the old root has CA:FALSE"
+  elif printf '%s\n' "$_tn_otxt" | grep -q 'X509v3 Key Usage' && ! tn_ca_has_certsign "$_tn_s/oldroot.pem"; then
+    _tn_fwhy="the old root has a key usage without keyCertSign"
+  else
+    _tn_vout=$("$OPENSSL" verify -CAfile "$_tn_s/oldroot.pem" -untrusted "$_tn_tls/intermediate-ca.crt" "$_tn_s/w/c0.pem" 2>&1) ||
+      _tn_fwhy="openssl cannot verify the old chain against the old root ($(printf '%s\n' "$_tn_vout" | grep -i 'error' | head -n 1 | sed 's/^error [0-9]* at [0-9]* depth lookup: *//'))"
+  fi
+  if [ -n "$_tn_fwhy" ]; then
+    _tn_force=' --force'
+    tn_ca_info "rotate-ca will use --force ($_tn_fwhy, so k3s cannot verify the new CA bundle against it); the new bundle was verified here"
+  fi
+  tn_ca_backup_tls "$_tn_dd" || { rm -rf "$_tn_s"; return 1; }
+  cp "$_tn_s/w/c0.pem" "$_tn_s/trust.pem" || { rm -rf "$_tn_s"; return 1; }
+  rm -rf "$_tn_s/w" "$_tn_s/oldroot.pem"
+  # SSL_CERT_FILE: a post-fix k3s that refuses the old root still has to talk to its own
+  # supervisor. Trusting the running server's own leaf CA for this one call allows that.
+  printf '%s\n' "SSL_CERT_FILE='$_tn_s/trust.pem' $(tn_ca_k3s_bin) certificate rotate-ca --data-dir '$_tn_dd' --path '$_tn_s/server'$_tn_force && touch '$_tn_s/ROTATED'" > "$_tn_s/ROTATE_CMD" ||
+    { rm -rf "$_tn_s"; return 1; }
+  tn_ca_info "Staged $_tn_s"
+  tn_ca_info "Next: run its ROTATE_CMD against the running k3s server (remediate --phase rotate), then --phase finalize and restart k3s"
+}
+
+# rotate: run ROTATE_CMD of the newest staging
+tn_ca_rotate() {
+  _tn_s=$(tn_ca_newest_stage "$1")
+  if [ -z "$_tn_s" ]; then
+    tn_ca_state "$1" >/dev/null || true
+    case $TN_CA_STATE in needs-regeneration|ok|not-a-server) tn_ca_info "nothing to rotate"; return 0 ;; esac
+    tn_ca_warn "no staged rotation in $1/server: run 'remediate --phase prepare' first"; return 1
+  fi
+  [ -f "$_tn_s/ROTATE_CMD" ] || { tn_ca_warn "$_tn_s has no ROTATE_CMD"; return 1; }
+  if ! tn_ca_rotate_supported; then tn_ca_warn_rotate_unsupported; return 1; fi
+  tn_ca_info "Rotating the CA in the running k3s server (rotate-ca)"
+  # rotate-ca talks to the k3s server. One that is starting right now (a unit that was just restarted, or
+  # one that restarts itself in a loop, like a k3s that a cgroup v1 host made exit) does not answer yet:
+  # try again for a while, but only when systemd says that the unit is there and starting or running
+  _tn_tries=1
+  case $(tn_ca_unit_state) in active|activating|reloading) _tn_tries=${TN_K3S_ROTATE_TRIES:-6} ;; esac
+  _tn_try=1
+  while ! sh -c "$(cat "$_tn_s/ROTATE_CMD")"; do
+    if [ "$_tn_try" -ge "$_tn_tries" ]; then
+      tn_ca_warn "k3s certificate rotate-ca failed. Is the k3s server running (systemctl status k3s)? A server that refuses the old root is fine, it only has to be up."
+      tn_ca_warn "The CA of k3s and its files in $1/server/tls were not changed. To go back to a working state: stop k3s and install the previous k3s patch release (v1.34.11, v1.35.8, v1.36.4 or v1.37.0), then run remediate again."
+      return 1
+    fi
+    tn_ca_info "rotate-ca failed (attempt $_tn_try of $_tn_tries): the k3s server may still be starting; trying again in ${TN_K3S_ROTATE_WAIT:-10}s"
+    sleep "${TN_K3S_ROTATE_WAIT:-10}"
+    _tn_try=$((_tn_try + 1))
+  done
+  tn_ca_changed "the CA was rotated in the datastore of k3s (k3s certificate rotate-ca)"
+}
+
+# finalize: put the rotated files on disk (k3s keeps them in step with its datastore)
+tn_ca_finalize() {
+  _tn_dd=$1
+  _tn_s=$(tn_ca_newest_stage "$_tn_dd")
+  if [ -z "$_tn_s" ]; then tn_ca_info "nothing to finalize"; return 0; fi
+  [ -f "$_tn_s/ROTATED" ] || { tn_ca_warn "the rotation in $_tn_s has not completed (no ROTATED marker): not touching $_tn_dd/server/tls"; return 1; }
+  for _tn_f in $TN_CA_BUNDLES root-ca.pem; do
+    [ -f "$_tn_s/server/tls/$_tn_f" ] || continue
+    cp "$_tn_s/server/tls/$_tn_f" "$_tn_dd/server/tls/$_tn_f.tn-new" && mv "$_tn_dd/server/tls/$_tn_f.tn-new" "$_tn_dd/server/tls/$_tn_f" || return 1
+  done
+  rm -rf "$_tn_s"
+  tn_ca_changed "the CA files in $_tn_dd/server/tls were replaced"
+  tn_ca_info "CA files updated in $_tn_dd/server/tls"
+}
+
+# tn_ca_restart: restart k3s, but not forever (TN_K3S_SERVICE_TIMEOUT, 600 s): the unit waits for a
+# k3s that may never become ready. `systemctl restart` that is given up on leaves the unit starting,
+# so the unit is watched for TN_K3S_READY_GRACE (120) more seconds: a slow device that gets there is a
+# success. Otherwise a timeout is a failure (return 124): the caller reports that the CA WAS changed
+# and k3s did not come back in time.
+tn_ca_restart() {
+  _tn_rt=$(tn_ca_svc_timeout)
+  _tn_rrc=0 _tn_watched=""
+  _tn_gw=0
+  if [ -n "${TN_K3S_RESTART_CMD:-}" ]; then
+    tn_ca_info "Restarting k3s: $TN_K3S_RESTART_CMD"
+    tn_ca_run_bounded "$_tn_rt" sh -c "$TN_K3S_RESTART_CMD" || _tn_rrc=$?
+  elif command -v systemctl >/dev/null 2>&1 && systemctl cat "$(tn_ca_unit_name)" >/dev/null 2>&1; then
+    tn_ca_info "Restarting k3s"
+    tn_ca_run_bounded "$_tn_rt" systemctl restart "$(tn_ca_unit_name)" || _tn_rrc=$?
+  else
+    tn_ca_warn "restart k3s yourself now (no systemd unit found and TN_K3S_RESTART_CMD is not set)"
+    return 0
+  fi
+  if [ "$_tn_rrc" -eq 124 ] && [ -z "${TN_K3S_RESTART_CMD:-}" ]; then
+    _tn_gr=${TN_K3S_READY_GRACE:-120} _tn_gp=${TN_K3S_READY_POLL:-5} _tn_watched=1
+    tn_ca_info "the restart of k3s did not finish within ${_tn_rt}s: watching the unit for up to ${_tn_gr}s more"
+    while :; do
+      if tn_ca_k3s_ready; then
+        tn_ca_info "k3s is active now (${_tn_gw}s after the restart gave up)"
+        _tn_rrc=0
+        break
+      fi
+      [ "$_tn_gw" -lt "$_tn_gr" ] || break
+      sleep "$_tn_gp"
+      _tn_gw=$((_tn_gw + _tn_gp))
+    done
+  fi
+  if [ "$_tn_rrc" -eq 124 ]; then
+    if [ -n "${_tn_watched:-}" ]; then
+      tn_ca_warn "the restart of k3s did not finish within ${_tn_rt}s (TN_K3S_SERVICE_TIMEOUT), and the unit was not active ${_tn_gw}s later either: it is still starting, or it cannot start"
+    else
+      tn_ca_warn "the restart of k3s did not finish within ${_tn_rt}s (TN_K3S_SERVICE_TIMEOUT): it is still starting, or it cannot start"
+    fi
+  elif [ "$_tn_rrc" -eq 0 ]; then
+    tn_ca_changed "k3s was restarted"
+  fi
+  return "$_tn_rrc"
+}
+
+# After this point the CA has been changed (rotated in the datastore, or the PKI regenerated):
+# a failure must not claim that the device is unchanged. Return code 5.
+tn_ca_warn_changed_finalize() {
+  tn_ca_warn "k3s certificate rotate-ca SUCCEEDED: the datastore of k3s already holds the new CA. Only putting the new files into $1/server/tls failed (see above: disk space? permissions?). Do not roll back. Fix that, then run: sh tn-k3s-ca.sh remediate --phase finalize, and restart k3s."
+}
+tn_ca_warn_changed_restart() { # DATA_DIR WAS
+  if [ "$2" = needs-rotation ]; then
+    tn_ca_warn "k3s certificate rotate-ca SUCCEEDED: the datastore of k3s holds the new CA, and so does $1/server/tls, but k3s could not be restarted."
+  else
+    tn_ca_warn "The PKI in $1/server/tls was regenerated (the previous one is in $1/server/tls-backup-tn-*.tar), but k3s could not be restarted."
+  fi
+  tn_ca_warn "Look at: systemctl status $(tn_ca_unit_name); journalctl -u $(tn_ca_unit_name) -n 50. Then restart it: systemctl restart $(tn_ca_unit_name). Do not roll back files: restoring the backup tar does not undo a rotation (see 'Rollback limits' at the top of this file)."
+}
+
+# tn_ca_remediate PHASE   (prepare | rotate | finalize | all)
+tn_ca_remediate() {
+  tn_ca_openssl || return 1
+  tn_ca_resolve_datadir
+  _tn_dd=$DATA_DIR
+  case $1 in
+    prepare) tn_ca_prepare "$_tn_dd" ;;
+    rotate) tn_ca_rotate "$_tn_dd" ;;
+    finalize) tn_ca_finalize "$_tn_dd" ;;
+    all)
+      tn_ca_state "$_tn_dd" >/dev/null || true
+      case $TN_CA_STATE in
+        ok) tn_ca_clean_stages "$_tn_dd"; tn_ca_info "$TN_CA_MSG"; return 0 ;;
+        not-a-server) tn_ca_info "$TN_CA_MSG"; return 0 ;;
+      esac
+      _tn_was=$TN_CA_STATE
+      _tn_s=$(tn_ca_newest_stage "$_tn_dd")
+      if [ "$_tn_was" = needs-rotation ] && [ -n "$_tn_s" ] && [ -f "$_tn_s/ROTATED" ]; then
+        # an earlier run rotated the CA in the datastore and stopped before the files were copied:
+        # do not stage and rotate again
+        tn_ca_info "A completed rotation is waiting in $_tn_s: finalizing it"
+        tn_ca_finalize "$_tn_dd" || { tn_ca_warn_changed_finalize "$_tn_dd"; return 5; }
+      else
+        tn_ca_prepare "$_tn_dd" || return $?
+        if [ "$_tn_was" = needs-rotation ]; then
+          tn_ca_rotate "$_tn_dd" || return 1
+          tn_ca_finalize "$_tn_dd" || { tn_ca_warn_changed_finalize "$_tn_dd"; return 5; }
+        fi
+      fi
+      tn_ca_restart || { tn_ca_warn_changed_restart "$_tn_dd" "$_tn_was"; return 5; }
+      ;;
+    *) tn_ca_warn "unknown phase '$1' (prepare, rotate, finalize or all)"; return 2 ;;
+  esac
+}
+
+# tn_ca_check: print the state, exit code as documented at the top
+tn_ca_check() {
+  tn_ca_openssl || return 1
+  tn_ca_resolve_datadir
+  echo "tn-k3s-ca: data dir ${DATA_DIR} (${TN_CA_DATADIR_SRC})" >&2
+  _tn_rc=0
+  tn_ca_state "$DATA_DIR" || _tn_rc=$?
+  echo "tn-k3s-ca: ${TN_CA_STATE}: ${TN_CA_MSG}"
+  return "$_tn_rc"
+}
+
+# ----------------------------------------------------------------- program mode
+
+tn_ca_usage() {
+  cat <<'EOF'
+usage: sh tn-k3s-ca.sh check [--data-dir DIR] [--config-dir DIR]
+       sh tn-k3s-ca.sh remediate [--phase prepare|rotate|finalize|all] [--data-dir DIR] [--config-dir DIR]
+
+check       Is the k3s root CA of this device acceptable to k3s v1.34.12/v1.35.9/v1.36.5/v1.37.1+?
+            exit 0 ok, 2 needs rotation, 3 needs regeneration, 4 foreign CA or no server data found,
+            1 error. Without --data-dir the data dir is resolved the way k3s does (ExecStart of the
+            k3s unit, config.yaml.d/*.yaml, config.yaml, default /var/lib/rancher/k3s)
+remediate   Re-issue the root with keyCertSign (same key and subject) and put it in place.
+            Phases: prepare (offline, stages the new files), rotate (k3s certificate rotate-ca against
+            the running server), finalize (copy the files), all (those three plus a k3s restart).
+            A device whose k3s never finished its first start gets its PKI regenerated instead.
+Run as root on the device. Environment: K3S_BIN, TN_K3S_RESTART_CMD, TN_K3S_STOP_CMD,
+TN_K3S_START_CMD, TN_K3S_SERVICE_TIMEOUT (seconds for a stop/start/restart of k3s, 600), CONFIG_PATH, DATA_DIR.
+EOF
+}
+
+tn_ca_main() {
+  _tn_cmd=$1; shift
+  _tn_phase=all
+  while [ $# -gt 0 ]; do
+    case $1 in
+      --phase|--data-dir|--config-dir)
+        if [ $# -lt 2 ] || [ -z "$2" ]; then tn_ca_warn "$1 needs a value"; tn_ca_usage >&2; return 2; fi
+        case $1 in
+          --phase) _tn_phase=$2 ;;
+          --data-dir) DATA_DIR=$2 ;;
+          --config-dir) CONFIG_PATH=$2 ;;
+        esac
+        shift 2 ;;
+      -h|--help) tn_ca_usage; return 0 ;;
+      *) tn_ca_usage >&2; return 2 ;;
+    esac
+  done
+  [ -z "${CONFIG_PATH:-}" ] || export CONFIG_PATH
+  [ -z "${DATA_DIR:-}" ] || export DATA_DIR
+  case $_tn_cmd in
+    check) tn_ca_check ;;
+    remediate)
+      [ "$(id -u)" -eq 0 ] || { tn_ca_warn "run as root"; return 1; }
+      tn_ca_remediate "$_tn_phase" ;;
+  esac
+}
+
+# Only the command words start the program: sourcing this file defines functions and nothing
+# else. (A bootstrap script passes no arguments of its own; the template that embeds this file
+# sets TN_K3S_CA_NO_MAIN anyway.)
+case "${1:-}" in
+  check|remediate)
+    if [ -z "${TN_K3S_CA_NO_MAIN:-}" ]; then
+      CONFIG_PATH=${CONFIG_PATH:-/etc/teknoir}
+      tn_ca_main "$@"
+      exit $?
+    fi
+    ;;
+esac
diff --git a/pkg/templates/scripts/tn-k3s-install.sh b/pkg/templates/scripts/tn-k3s-install.sh
new file mode 100644
index 0000000..6efea7f
--- /dev/null
+++ b/pkg/templates/scripts/tn-k3s-install.sh
@@ -0,0 +1,586 @@
+#!/bin/sh
+# tn-k3s-install.sh - what a Teknoir bootstrap script decides before it runs the k3s installer:
+# which k3s release (a re-run keeps what is installed), and whether the kubelet must be told that
+# cgroup v1 is acceptable. Used by the server and the agent script (sourced), next to
+# tn-k3s-ca.sh (the server only).
+#
+#   . tn-k3s-install.sh; tn_inst_prepare server|agent       (once, right before the installer)
+#   tn_inst_finish                                           (once, right after the installer)
+#   tn_inst_config_ensure FILE KEY TEXT                      (config.yaml without clobbering it)
+#
+# POSIX sh. It runs under `set -e` and `set -o noglob` (as the bootstrap scripts do) and does not
+# change shell options, traps or the working directory of the caller. Sourcing defines functions only.
+#
+# ---------------------------------------------------------------- version policy
+# A bootstrap script is meant to be re-run (it repairs the CA, refreshes the manifests). It must not
+# upgrade k3s as a side effect: the pin in the script (INSTALL_K3S_VERSION, `tnctl bootstrap
+# --k3s-version`) is the release for a NEW device.
+#   - k3s is not installed:   the pin is installed (a SERVER; an agent: see below).
+#   - the version cannot be read although a k3s binary or DATA_DIR/server/db exists: REFUSED (the
+#                             installer would install or replace k3s blind), unless TN_K3S_FORCE=true.
+#   - k3s is installed:       its version is KEPT. The exact installed release is handed to the
+#                             installer (which then only rewrites the unit and the symlinks), and
+#                             a different pin is reported and ignored.
+#   - TN_K3S_UPGRADE=true     (tnctl bootstrap --k3s-upgrade) lets the pin replace the installed
+#                             release. A pin below the installed release is refused (k3s does not
+#                             downgrade: the datastore has been migrated), and so is a jump of more
+#                             than one minor version (v1.34 -> v1.36) unless TN_K3S_FORCE=true
+#                             (tnctl bootstrap --force): Kubernetes supports one minor at a time.
+#                             A channel (stable, latest) cannot be compared before the installer
+#                             resolves it: that is only a warning, pin an exact release to get the checks.
+#
+# An AGENT follows its server. A kubelet must never be newer than the apiserver it joins, so a new
+# agent (and an agent that TN_K3S_UPGRADE=true replaces) does not install the pin of the script: it
+# reads the release of the server and installs exactly that one. Where the release comes from: k3s
+# does NOT answer /version to an anonymous caller (its apiserver runs with anonymous-auth=false: 401,
+# verified with v1.30, v1.34 and v1.36), and the join token is only good for the supervisor
+# endpoints. So the Teknoir SERVER script publishes the release it runs (tn_inst_publish_release) as
+# <DATA_DIR>/server/static/teknoir/k3s-version, which k3s serves without authentication at
+#     https://<K3S_URL>/static/teknoir/k3s-version
+# and the agent reads that file (then, for a server that allows anonymous access, /version). The
+# pin only counts when the person who runs the script asked for it (`tnctl bootstrap --k3s-version`, or
+# INSTALL_K3S_VERSION in the environment; TN_K3S_PIN_SOURCE=flag|env, the template sets it): then it is
+# installed if it is not newer than the server (older gets a warning), and refused if it is. When the
+# server's release cannot be read (down, unreachable, bootstrapped by a script that does not publish it
+# yet): an explicit exact pin is installed with a warning, and otherwise the script REFUSES, unless
+# TN_K3S_FORCE=true. An OS image build (OS_BUILD) cannot reach the server and installs the pin. The
+# cgroup logic below is keyed on the release that is installed.
+#
+# ---------------------------------------------------------------- cgroup v1
+# Kubernetes >= 1.35: the kubelet refuses to start on a cgroup v1 host (failCgroupV1 defaults to
+# true) and k3s does not change that. Jetson L4T r32/r35 and Ubuntu 18.04/20.04 are cgroup v1. When
+# the host is on cgroup v1 (stat -fc %T /sys/fs/cgroup is not cgroup2fs), or cannot be told (an OS
+# build runs elsewhere than the device), and the k3s that will run is >= v1.31 (the kubelet knows
+# the flag since 1.31; it only matters from 1.35, but a later upgrade, by hand or by the k3s
+# installer alone, must not stop the kubelet), the script writes (atomically, only when it differs)
+#     /etc/rancher/k3s/config.yaml.d/99-teknoir-cgroupv1.yaml:   kubelet-arg+: ["fail-cgroupv1=false"]
+# `kubelet-arg+` APPENDS to the kubelet-arg of config.yaml and the other files (verified with
+# rancher/k3s v1.36.5, a kubelet-arg already in config.yaml is kept); the flag is harmless on a
+# cgroup v2 host. A fail-cgroupv1 that the device sets itself is respected. cgroup v1 is
+# deprecated upstream: move the device to cgroup v2 (kernel command line
+# systemd.unified_cgroup_hierarchy=1, or a newer OS release).
+#
+# Order of effects. Everything before the installer (tn_inst_prepare, the CA step, the download) can
+# be interrupted by a restart of k3s (the CA step restarts it) or by a reboot of the device, and the
+# running k3s then reads the configuration again. So tn_inst_prepare only makes changes that are safe
+# for the k3s that is running NOW, and never takes a protection away before its replacement is in place:
+#   - the drop-in is REMOVED early only when the running k3s does not need it: the host is on cgroup v2;
+#     the release that will run is older than v1.31 (an older kubelet fails on the unknown flag); or the
+#     device sets fail-cgroupv1 in a PERSISTENT config file that k3s already reads (config.yaml or another
+#     config.yaml.d/*.yaml). A fail-cgroupv1 only in INSTALL_K3S_EXEC reaches the unit when the installer
+#     has run, so until then the drop-in stays (or is written): the same value twice is harmless, and
+#     the command line wins when they differ.
+#   - the drop-in is WRITTEN early, except when the k3s that is installed now is older than v1.31 (an
+#     upgrade): its kubelet would fail on the flag if it restarted before the installer replaced it.
+#     That write waits for tn_inst_finish, after the installer. An existing drop-in is removed at once in
+#     that case, because the old kubelet cannot take it.
+#   - but the installer starts the NEW release as soon as it has rewritten the unit, and a release >= v1.35
+#     refuses to start on cgroup v1 without the flag (install.sh's `systemctl restart` fails, and under
+#     `set -e` the script stops before tn_inst_finish: a k3s that crash-loops). So when the write is held
+#     back and the release the installer will start is not KNOWN to be older than v1.35 (a channel such as
+#     stable or latest, or an exact v1.35 or newer, also with TN_K3S_FORCE=true), the flag is appended to
+#     INSTALL_K3S_EXEC (--kubelet-arg=fail-cgroupv1=false, once, and exported): it is then in the NEW unit
+#     from its first start and the old, running kubelet never sees it. An exact v1.31 - v1.34 does not need
+#     it on its first start (it accepts it, it only ignores it on cgroup v1), so it gets none. tn_inst_finish
+#     still writes the drop-in afterwards, which is what keeps later runs and upgrades safe.
+#
+# What counts as "the device sets fail-cgroupv1 itself": an uncommented line that sets it to false in
+# config.yaml, config.yaml.d/*.yaml or *.yml (not our own file), or in INSTALL_K3S_EXEC. A comment does
+# not count, and neither does fail-cgroupv1=true: then the drop-in is written (and kept) as usual, and
+# it wins, because kubelet-arg+ comes after. A device that sets fail-cgroupv1=true on a cgroup v1 host
+# on purpose is not supported (the kubelet of v1.35 and newer cannot start there anyway); delete the
+# drop-in and set cgroup v2 instead.
+#
+# Environment (all optional):
+#   INSTALL_K3S_VERSION, INSTALL_K3S_CHANNEL   the pin of the script (read, and set to what the installer must get)
+#   TN_K3S_UPGRADE      true: the pin may replace an installed k3s
+#   TN_K3S_FORCE        true: allow an upgrade across more than one minor version; an agent newer than its
+#                       server, or without knowing the version of its server; a k3s whose version cannot be read
+#   TN_K3S_PIN_SOURCE   who chose INSTALL_K3S_VERSION: flag / env (the person who runs the script) or
+#                       default (the template); the template sets it, an agent follows the server unless it is flag/env
+#   K3S_URL             the server of an agent (https://host:6443)
+#   TN_K3S_SERVER_VERSION_TRIES, TN_K3S_SERVER_VERSION_WAIT   tries (3) and seconds between them (3) to reach the
+#                       server; a server that answers without a release is not asked again
+#   DATA_DIR            the k3s data dir (/var/lib/rancher/k3s), where a datastore says that k3s is there
+#   TN_K3S_CGROUPV1     true / false: do not detect, take this as the answer
+#   TN_CGROUP_FSTYPE    the file system type of /sys/fs/cgroup, instead of `stat` (tests)
+#   K3S_BIN             the k3s command used to read the installed version (k3s, then /usr/local/bin/k3s)
+#   TN_K3S_CONFIG_DIR   /etc/rancher/k3s
+#   OS_BUILD            set by the OS image builds: the host is not the device, cgroup cannot be detected
+
+TN_K3S_INSTALL_LIB_VERSION=3
+export TN_K3S_INSTALL_LIB_VERSION
+
+# ----------------------------------------------------------------- messages
+# Own functions, in the format of header.sh.tmpl: a caller's info/warn/fatal may not exist, and `info`
+# can be the GNU info reader.
+tn_inst_info() { echo '[INFO] ' "$@"; }
+tn_inst_warn() { echo '[WARN] ' "$@" >&2; }
+tn_inst_fatal() { echo '[ERROR] ' "$@" >&2; exit 1; }
+
+# tn_inst_state_note: how a refusal describes the device. This library has changed nothing when it
+# refuses; the CA step (tn-k3s-ca.sh) may have, earlier in the same run, and then says exactly what.
+tn_inst_state_note() {
+  if [ -n "${TN_K3S_CA_CHANGED:-}" ]; then
+    printf 'The k3s release was not changed, but earlier in this run: %s' "$TN_K3S_CA_CHANGED"
+  else
+    printf 'Nothing was changed'
+  fi
+}
+
+# ----------------------------------------------------------------- versions
+
+# tn_inst_parse VERSION: sets TN_INST_MAJ TN_INST_MIN TN_INST_PAT TN_INST_REV from vMAJ.MIN.PAT[+k3sREV]
+# (REV 0 when there is none). Fails for anything else (stable, latest, a commit).
+tn_inst_parse() {
+  TN_INST_MAJ=; TN_INST_MIN=; TN_INST_PAT=; TN_INST_REV=
+  _tn_pv=$(printf '%s\n' "$1" | sed -n 's/^v\([0-9][0-9]*\)\.\([0-9][0-9]*\)\.\([0-9][0-9]*\)\(+k3s\([0-9][0-9]*\)\)\{0,1\}$/\1 \2 \3 \5/p')
+  [ -n "$_tn_pv" ] || return 1
+  IFS=' ' read -r TN_INST_MAJ TN_INST_MIN TN_INST_PAT TN_INST_REV <<EOV
+$_tn_pv
+EOV
+  TN_INST_REV=${TN_INST_REV:-0}
+}
+
+# tn_inst_cmp A B: sets TN_INST_CMP to -1, 0 or 1 (A older, equal, newer than B). Fails if either
+# is not an exact release.
+tn_inst_cmp() {
+  tn_inst_parse "$1" || return 1
+  _tn_a="$TN_INST_MAJ $TN_INST_MIN $TN_INST_PAT $TN_INST_REV"
+  tn_inst_parse "$2" || return 1
+  _tn_b="$TN_INST_MAJ $TN_INST_MIN $TN_INST_PAT $TN_INST_REV"
+  TN_INST_CMP=$(printf '%s\n%s\n' "$_tn_a" "$_tn_b" | awk 'NR == 1 { for (i = 1; i <= 4; i++) a[i] = $i } NR == 2 {
+    for (i = 1; i <= 4; i++) { if (a[i] + 0 < $i + 0) { print -1; exit } if (a[i] + 0 > $i + 0) { print 1; exit } } print 0 }')
+}
+
+# the k3s command that reads the installed version
+tn_inst_k3s_cmd() {
+  if [ -n "${K3S_BIN:-}" ]; then echo "$K3S_BIN"
+  elif command -v k3s >/dev/null 2>&1; then echo k3s
+  elif [ -x /usr/local/bin/k3s ]; then echo /usr/local/bin/k3s
+  else echo k3s; fi
+}
+
+# tn_inst_installed_version: sets TN_INST_INSTALLED to the release of the installed k3s
+# (v1.34.11+k3s1) or to nothing when there is none.
+tn_inst_installed_version() {
+  TN_INST_INSTALLED=$($(tn_inst_k3s_cmd) --version 2>/dev/null | sed -n '1s/^.*version \(v[0-9][0-9]*\.[0-9][0-9]*\.[0-9][0-9]*\(+k3s[0-9][0-9]*\)\{0,1\}\).*$/\1/p') || TN_INST_INSTALLED=
+}
+
+# tn_inst_k3s_present: 0 if there is a k3s binary or a server datastore, whatever its version is.
+# Sets TN_INST_PRESENT to what was found.
+tn_inst_k3s_present() {
+  TN_INST_PRESENT=
+  _tn_first=
+  for _tn_w in $(tn_inst_k3s_cmd); do _tn_first=$_tn_w; break; done
+  if [ -n "$_tn_first" ] && _tn_found=$(command -v "$_tn_first" 2>/dev/null) && [ -n "$_tn_found" ]; then
+    TN_INST_PRESENT="the k3s command $_tn_found"; return 0
+  fi
+  if [ -d "${DATA_DIR:-/var/lib/rancher/k3s}/server/db" ]; then
+    TN_INST_PRESENT="the datastore ${DATA_DIR:-/var/lib/rancher/k3s}/server/db"; return 0
+  fi
+  return 1
+}
+
+# tn_inst_http_get URL: the body on stdout. Returns 0 for 2xx, 1 when the server ANSWERED with an error
+# (404: no such file, 401: no anonymous access), 2 when it could not be reached (or there is neither curl
+# nor wget). No certificate check: the answer decides which release to install and nothing else (the
+# server is the one this device joins with its token anyway).
+tn_inst_http_get() {
+  _tn_hc=0
+  if command -v curl >/dev/null 2>&1; then
+    curl -fsk --max-time 10 "$1" || _tn_hc=$?
+    case $_tn_hc in 0) return 0 ;; 22) return 1 ;; *) return 2 ;; esac
+  elif command -v wget >/dev/null 2>&1; then
+    wget -qO- --no-check-certificate -T 10 "$1" || _tn_hc=$?
+    case $_tn_hc in 0) return 0 ;; 8) return 1 ;; *) return 2 ;; esac
+  fi
+  return 2
+}
+
+# tn_inst_server_version URL: sets TN_INST_SERVER to the k3s release the server at URL runs
+# (v1.34.11+k3s1) and TN_INST_SERVER_SRC to where it was read, or leaves them empty (and sets
+# TN_INST_SERVER_WHY to unreachable or no-release). Fails when it cannot tell. Two places, in this order:
+#   <URL>/static/teknoir/k3s-version   the file that the Teknoir server script publishes (anonymous)
+#   <URL>/version                      gitVersion, for a server that allows anonymous access (k3s does not by default)
+tn_inst_server_version() {
+  TN_INST_SERVER=; TN_INST_SERVER_SRC=; TN_INST_SERVER_WHY=unreachable
+  _tn_su=${1%/}
+  _tn_sv_max=${TN_K3S_SERVER_VERSION_TRIES:-3}
+  _tn_sv_try=0
+  while [ "$_tn_sv_try" -lt "$_tn_sv_max" ]; do
+    _tn_sv_try=$((_tn_sv_try + 1))
+    _tn_unreach=0
+    _tn_rc=0
+    _tn_body=$(tn_inst_http_get "$_tn_su/static/teknoir/k3s-version" 2>/dev/null) || _tn_rc=$?
+    if [ "$_tn_rc" = 0 ]; then
+      TN_INST_SERVER=$(printf '%s' "$_tn_body" | tr -d ' \t\r\n' | sed -n 's/^\(v[0-9][0-9]*\.[0-9][0-9]*\.[0-9][0-9]*+k3s[0-9][0-9]*\)$/\1/p')
+      if [ -n "$TN_INST_SERVER" ]; then TN_INST_SERVER_SRC=$_tn_su/static/teknoir/k3s-version; return 0; fi
+    elif [ "$_tn_rc" = 2 ]; then
+      _tn_unreach=1
+    fi
+    if [ "$_tn_unreach" = 0 ]; then
+      _tn_rc=0
+      _tn_body=$(tn_inst_http_get "$_tn_su/version" 2>/dev/null) || _tn_rc=$?
+      if [ "$_tn_rc" = 0 ]; then
+        # {"major":"1","minor":"34","gitVersion":"v1.34.11+k3s1",...}, over several lines or one
+        TN_INST_SERVER=$(printf '%s\n' "$_tn_body" | tr -d '\n' | sed -n 's/^.*"gitVersion"[[:space:]]*:[[:space:]]*"\(v[0-9][0-9]*\.[0-9][0-9]*\.[0-9][0-9]*+k3s[0-9][0-9]*\)".*$/\1/p')
+        if [ -n "$TN_INST_SERVER" ]; then TN_INST_SERVER_SRC=$_tn_su/version; return 0; fi
+      elif [ "$_tn_rc" = 2 ]; then
+        _tn_unreach=1
+      fi
+    fi
+    # the server answered, but has no release to give: asking again does not help
+    if [ "$_tn_unreach" = 0 ]; then TN_INST_SERVER_WHY=no-release; return 1; fi
+    if [ "$_tn_sv_try" -lt "$_tn_sv_max" ]; then sleep "${TN_K3S_SERVER_VERSION_WAIT:-3}"; fi
+  done
+  return 1
+}
+
+# tn_inst_publish_release: a SERVER script calls it after the k3s installer. Publishes the installed
+# release as <DATA_DIR>/server/static/teknoir/k3s-version; k3s serves server/static without
+# authentication (https://<server>:6443/static/teknoir/k3s-version), and an agent script reads it to
+# install the release of its server. Written atomically; unchanged when it is right; it never fails the
+# script. An out-of-band upgrade of k3s leaves it saying the older release, which is the safe direction
+# (an agent may be older than its server, never newer): a re-run of the server script updates it.
+tn_inst_publish_release() {
+  tn_inst_installed_version
+  if [ -z "$TN_INST_INSTALLED" ]; then
+    tn_inst_warn "cannot read the release of the installed k3s: it is not published, so agents cannot follow this server (they need INSTALL_K3S_VERSION)"
+    return 0
+  fi
+  _tn_pd=${DATA_DIR:-/var/lib/rancher/k3s}/server/static/teknoir
+  _tn_pf=$_tn_pd/k3s-version
+  if [ -f "$_tn_pf" ] && [ "$(cat "$_tn_pf" 2>/dev/null)" = "$TN_INST_INSTALLED" ]; then
+    tn_inst_info "the k3s release $TN_INST_INSTALLED is already published for the agents ($_tn_pf)"
+    return 0
+  fi
+  _tn_pt=$_tn_pd/.k3s-version.tmp.$$
+  if mkdir -p "$_tn_pd" && printf '%s\n' "$TN_INST_INSTALLED" > "$_tn_pt" && mv -f "$_tn_pt" "$_tn_pf"; then
+    tn_inst_info "Published the k3s release $TN_INST_INSTALLED for the agents: $_tn_pf (served at /static/teknoir/k3s-version)"
+  else
+    rm -f "$_tn_pt" 2>/dev/null || true
+    tn_inst_warn "cannot publish the k3s release to $_tn_pf: agents cannot follow this server (they need INSTALL_K3S_VERSION)"
+  fi
+  return 0
+}
+
+# ----------------------------------------------------------------- the release to install
+
+# tn_inst_agent_target: for an agent that is to be installed (or replaced): which release. Sets and
+# exports INSTALL_K3S_VERSION (and unsets INSTALL_K3S_CHANNEL) or exits through tn_inst_fatal.
+tn_inst_agent_target() {
+  _tn_pin=${INSTALL_K3S_VERSION:-}
+  _tn_exp=0
+  case ${TN_K3S_PIN_SOURCE:-default} in flag|env) _tn_exp=1 ;; esac
+  if [ -n "${OS_BUILD:-}" ]; then
+    tn_inst_warn "OS build: the k3s server is not reachable from here, so the release of the agent cannot follow it. ${_tn_pin:-The release the installer picks} is installed: the server must run this release or a newer one"
+    return 0
+  fi
+  TN_INST_SERVER=
+  if [ -z "${K3S_URL:-}" ]; then
+    tn_inst_warn "K3S_URL is not set: the k3s release of the server cannot be read"
+  else
+    tn_inst_info "Reading the k3s release of the server at ${K3S_URL%/}"
+    tn_inst_server_version "$K3S_URL" || true
+  fi
+  if [ -n "$TN_INST_SERVER" ]; then
+    tn_inst_info "the k3s server at $K3S_URL runs $TN_INST_SERVER (read from $TN_INST_SERVER_SRC)"
+    if [ "$_tn_exp" = 1 ] && [ -n "$_tn_pin" ] && tn_inst_cmp "$_tn_pin" "$TN_INST_SERVER"; then
+      case $TN_INST_CMP in
+        0) tn_inst_info "the requested release $_tn_pin is the release of the server" ;;
+        -1) tn_inst_warn "the requested release $_tn_pin is OLDER than the release of the server ($TN_INST_SERVER): it is installed as asked. An agent should run the release of its server (Kubernetes supports a kubelet up to three minor versions older than the apiserver)" ;;
+        *) if [ "${TN_K3S_FORCE:-}" = true ]; then
+             tn_inst_warn "the requested release $_tn_pin is NEWER than the release of the server ($TN_INST_SERVER); TN_K3S_FORCE=true: it is installed anyway. A kubelet newer than its apiserver is not supported"
+           else
+             tn_inst_fatal "refusing to install k3s $_tn_pin on this agent: the server at $K3S_URL runs the older $TN_INST_SERVER, and a kubelet must not be newer than the apiserver it joins. Without --k3s-version (INSTALL_K3S_VERSION) the agent gets the release of its server, $TN_INST_SERVER. Or upgrade the server first, or set TN_K3S_FORCE=true. $(tn_inst_state_note)"
+           fi ;;
+      esac
+      return 0
+    fi
+    if [ "$_tn_exp" = 1 ]; then
+      tn_inst_warn "the requested k3s release (${_tn_pin:-${INSTALL_K3S_CHANNEL:-stable}}) is not an exact release, so it cannot be compared with the server: the release of the server is installed instead"
+    elif [ -n "$_tn_pin" ] && [ "$_tn_pin" != "$TN_INST_SERVER" ]; then
+      tn_inst_info "the script's default $_tn_pin is not used: an agent runs the release of its server"
+    fi
+    INSTALL_K3S_VERSION=$TN_INST_SERVER
+    export INSTALL_K3S_VERSION
+    unset INSTALL_K3S_CHANNEL
+    tn_inst_info "the agent gets the release of its server: $TN_INST_SERVER"
+    return 0
+  fi
+  # the server cannot be asked
+  if [ "$_tn_exp" = 1 ] && [ -n "$_tn_pin" ] && tn_inst_parse "$_tn_pin"; then
+    tn_inst_warn "cannot read the k3s release of the server at ${K3S_URL:-(K3S_URL is not set)}: the requested $_tn_pin is installed as asked. The server must run this release or a newer one"
+    return 0
+  fi
+  if [ "${TN_K3S_FORCE:-}" = true ]; then
+    tn_inst_warn "cannot read the k3s release of the server at ${K3S_URL:-(K3S_URL is not set)}; TN_K3S_FORCE=true: ${_tn_pin:-the release the installer picks} is installed anyway. If the server runs an older release, this agent will not work"
+    return 0
+  fi
+  case ${TN_INST_SERVER_WHY:-unreachable} in
+    no-release) _tn_why="The server answered, but does not publish its release: it was bootstrapped by a script that does not yet (run the server script again: it keeps k3s as it is and publishes its release), and k3s does not allow an anonymous /version." ;;
+    *) _tn_why="Is the server up and reachable from this device? Start it and run this script again." ;;
+  esac
+  tn_inst_fatal "cannot read the k3s release of the server at ${K3S_URL:-(K3S_URL is not set)} (${K3S_URL:-https://<server>:6443}/static/teknoir/k3s-version): an agent must not run a newer k3s than its server, so this script does not guess. $_tn_why Or say which release the server runs: INSTALL_K3S_VERSION=v1.xx.y+k3sN (tnctl bootstrap --k3s-version), or set TN_K3S_FORCE=true to install ${_tn_pin:-the release the installer picks} anyway. $(tn_inst_state_note)"
+}
+
+# tn_inst_plan: applies the policy at the top. Reads INSTALL_K3S_VERSION / INSTALL_K3S_CHANNEL,
+# sets and exports them for the installer. Sets TN_INST_INSTALLED, TN_INST_ACTION
+# (install|same|keep|upgrade) and TN_INST_EFFECTIVE (the exact release that will run, or nothing
+# when only a channel is known). Exits through tn_inst_fatal when it refuses.
+tn_inst_plan() {
+  tn_inst_installed_version
+  if [ -z "$TN_INST_INSTALLED" ] && tn_inst_k3s_present; then
+    if [ "${TN_K3S_FORCE:-}" = true ]; then
+      tn_inst_warn "$TN_INST_PRESENT exists, but its k3s version cannot be read; TN_K3S_FORCE=true: going on as if k3s were not installed. The installer may replace it with ${INSTALL_K3S_VERSION:-${INSTALL_K3S_CHANNEL:-the release the installer picks}}, without the upgrade and downgrade checks"
+    else
+      tn_inst_fatal "$TN_INST_PRESENT exists, but its k3s version cannot be read ('$(tn_inst_k3s_cmd) --version' gave no release), so this script cannot tell whether the installer would upgrade it, downgrade it or break its datastore, and does not install anything. Look at '$(tn_inst_k3s_cmd) --version' and at the datastore; repair or remove k3s on purpose, or set TN_K3S_FORCE=true to install anyway. $(tn_inst_state_note)"
+    fi
+  fi
+  if [ "${TN_INST_ROLE:-server}" = agent ] && { [ -z "$TN_INST_INSTALLED" ] || [ "${TN_K3S_UPGRADE:-}" = true ]; }; then
+    tn_inst_agent_target
+  fi
+  _tn_t=${INSTALL_K3S_VERSION:-}
+  _tn_want=${_tn_t:-${INSTALL_K3S_CHANNEL:-the default channel of the k3s installer (stable)}}
+  TN_INST_ACTION=install
+  TN_INST_EFFECTIVE=
+  if [ -z "$TN_INST_INSTALLED" ]; then
+    TN_INST_EFFECTIVE=$_tn_t
+    if [ -n "$_tn_t" ]; then tn_inst_info "k3s is not installed: installing $_tn_t"; else tn_inst_info "k3s is not installed: installing $_tn_want"; fi
+    return 0
+  fi
+  tn_inst_info "k3s $TN_INST_INSTALLED is installed on this device"
+
+  if [ "${TN_K3S_UPGRADE:-}" != true ]; then
+    # keep: an exact release is not "newer", it is "this one"
+    TN_INST_EFFECTIVE=$TN_INST_INSTALLED
+    if [ "$_tn_t" = "$TN_INST_INSTALLED" ]; then
+      TN_INST_ACTION=same
+      tn_inst_info "k3s $TN_INST_INSTALLED is the requested release: it is installed again, nothing is upgraded"
+      return 0
+    fi
+    TN_INST_ACTION=keep
+    INSTALL_K3S_VERSION=$TN_INST_INSTALLED
+    export INSTALL_K3S_VERSION
+    unset INSTALL_K3S_CHANNEL
+    if tn_inst_cmp "$_tn_t" "$TN_INST_INSTALLED" && [ "$TN_INST_CMP" = -1 ]; then
+      tn_inst_warn "the requested k3s release $_tn_t is OLDER than the installed $TN_INST_INSTALLED: k3s cannot be downgraded, $TN_INST_INSTALLED is kept"
+    else
+      tn_inst_warn "k3s $TN_INST_INSTALLED is kept; the requested $_tn_want is NOT installed. A re-run of this script repairs the device, it does not upgrade k3s. To upgrade, run it with TN_K3S_UPGRADE=true (tnctl bootstrap --k3s-upgrade), one minor version at a time"
+    fi
+    return 0
+  fi
+
+  # TN_K3S_UPGRADE=true
+  if ! tn_inst_cmp "$_tn_t" "$TN_INST_INSTALLED"; then
+    TN_INST_ACTION=upgrade
+    tn_inst_warn "TN_K3S_UPGRADE=true with $_tn_want, which is not an exact release: the k3s installer picks the release, so a downgrade or a jump over several minor versions cannot be checked. Pin an exact release (INSTALL_K3S_VERSION=v1.xx.y+k3sN) to get those checks"
+    return 0
+  fi
+  TN_INST_EFFECTIVE=$_tn_t
+  case $TN_INST_CMP in
+    0) TN_INST_ACTION=same; tn_inst_info "k3s $TN_INST_INSTALLED is the requested release: nothing to upgrade"; return 0 ;;
+    -1) tn_inst_fatal "refusing to downgrade k3s from $TN_INST_INSTALLED to $_tn_t: k3s cannot go back (the datastore has been migrated by the newer release). $(tn_inst_state_note). Pin $TN_INST_INSTALLED or a newer release, or restore the device from a backup" ;;
+  esac
+  tn_inst_parse "$TN_INST_INSTALLED"; _tn_imaj=$TN_INST_MAJ; _tn_imin=$TN_INST_MIN
+  tn_inst_parse "$_tn_t"
+  if [ "$TN_INST_MAJ" != "$_tn_imaj" ] || [ $((TN_INST_MIN - _tn_imin)) -gt 1 ]; then
+    if [ "${TN_K3S_FORCE:-}" = true ]; then
+      tn_inst_warn "upgrading k3s from $TN_INST_INSTALLED to $_tn_t skips minor versions (TN_K3S_FORCE=true). Kubernetes supports one minor version at a time: this can leave the cluster in a state that does not start. Have a backup of the datastore"
+    else
+      tn_inst_fatal "refusing to upgrade k3s from $TN_INST_INSTALLED to $_tn_t: that is more than one minor version (v$_tn_imaj.$_tn_imin -> v$TN_INST_MAJ.$TN_INST_MIN). Upgrade one minor at a time (to v$_tn_imaj.$((_tn_imin + 1)).x first), or set TN_K3S_FORCE=true (tnctl bootstrap --force) if you know what you are doing. $(tn_inst_state_note)"
+    fi
+  fi
+  TN_INST_ACTION=upgrade
+  tn_inst_info "upgrading k3s from $TN_INST_INSTALLED to $_tn_t (TN_K3S_UPGRADE=true). A server must be upgraded before its agents"
+}
+
+# ----------------------------------------------------------------- cgroup v1
+
+TN_INST_CGROUP_FILE=99-teknoir-cgroupv1.yaml
+
+# tn_inst_cgroup_state: prints v1 (cgroup v1 or hybrid), v2 or unknown
+tn_inst_cgroup_state() {
+  case ${TN_K3S_CGROUPV1:-} in true) echo v1; return 0 ;; false) echo v2; return 0 ;; esac
+  # an OS image is built on another machine than the one it will run on
+  if [ -n "${OS_BUILD:-}" ]; then echo unknown; return 0; fi
+  _tn_cg=${TN_CGROUP_FSTYPE:-}
+  [ -n "$_tn_cg" ] || _tn_cg=$(stat -fc %T /sys/fs/cgroup 2>/dev/null) || _tn_cg=
+  case $_tn_cg in
+    cgroup2fs) echo v2 ;;
+    '') echo unknown ;;
+    *) echo v1 ;;   # tmpfs: cgroup v1, or the hybrid layout
+  esac
+}
+
+# tn_inst_cgroup_flag_in_text: reads TEXT on stdin; 0 if an uncommented part of it sets fail-cgroupv1 to
+# false (kubelet-arg: ["fail-cgroupv1=false"], - fail-cgroupv1=false, --kubelet-arg=fail-cgroupv1=false).
+# A whole-line or trailing YAML comment is dropped first; fail-cgroupv1=true does not match.
+tn_inst_cgroup_flag_in_text() {
+  sed 's/^[[:space:]]*#.*$//; s/[[:space:]]#.*$//' | grep -Eiq 'fail-cgroupv1[[:space:]]*=[[:space:]]*false([^A-Za-z0-9_]|$)'
+}
+
+# tn_inst_cgroup_configured_elsewhere: 0 if the device sets fail-cgroupv1=false itself (not in our file).
+# Sets TN_INST_CGROUP_WHERE to where, and TN_INST_CGROUP_PERSISTENT to 1 when that is a config file that
+# the running k3s reads (config.yaml, config.yaml.d/*.yaml and *.yml), and to 0 when it is only INSTALL_K3S_EXEC
+# (which reaches the unit when the installer has run). Files win over INSTALL_K3S_EXEC. A comment, and
+# fail-cgroupv1=true, do not count.
+tn_inst_cgroup_configured_elsewhere() {
+  _tn_cd=${TN_K3S_CONFIG_DIR:-/etc/rancher/k3s}
+  TN_INST_CGROUP_WHERE=; TN_INST_CGROUP_PERSISTENT=0
+  for _tn_cf in "$_tn_cd/config.yaml" $(find "$_tn_cd/config.yaml.d" -maxdepth 1 -type f \( -name '*.yaml' -o -name '*.yml' \) 2>/dev/null | LC_ALL=C sort); do
+    [ -r "$_tn_cf" ] || continue
+    [ "$_tn_cf" != "$_tn_cd/config.yaml.d/$TN_INST_CGROUP_FILE" ] || continue
+    if tn_inst_cgroup_flag_in_text < "$_tn_cf"; then TN_INST_CGROUP_WHERE=$_tn_cf; TN_INST_CGROUP_PERSISTENT=1; return 0; fi
+  done
+  if printf '%s\n' "${INSTALL_K3S_EXEC:-}" | tn_inst_cgroup_flag_in_text; then TN_INST_CGROUP_WHERE=INSTALL_K3S_EXEC; return 0; fi
+  return 1
+}
+
+tn_inst_cgroup_remove() { # FILE WHY
+  [ -f "$1" ] || return 0
+  rm -f "$1" || { tn_inst_warn "cannot remove $1"; return 0; }
+  tn_inst_info "Removed $1 ($2)"
+}
+
+# tn_inst_cgroup: writes or removes the drop-in, see the top. Uses TN_INST_EFFECTIVE (the release
+# that will run; nothing = a channel, taken as new enough: stable and latest are >= v1.35; a channel
+# named vMAJ.MIN is read as that minor). The flag goes in from v1.31, where the kubelet learned it (an
+# older kubelet would not start with an unknown argument).
+tn_inst_cgroup() {
+  _tn_cdir=${TN_K3S_CONFIG_DIR:-/etc/rancher/k3s}/config.yaml.d
+  _tn_cfile=$_tn_cdir/$TN_INST_CGROUP_FILE
+  TN_INST_CGROUP_DEFERRED=
+  _tn_cst=$(tn_inst_cgroup_state)
+  if [ "$_tn_cst" = v2 ]; then
+    tn_inst_cgroup_remove "$_tn_cfile" "this host uses cgroup v2"
+    return 0
+  fi
+  _tn_eff=${TN_INST_EFFECTIVE:-}
+  if [ -z "$_tn_eff" ]; then
+    case ${INSTALL_K3S_CHANNEL:-} in v[0-9]*.[0-9]*) tn_inst_parse "${INSTALL_K3S_CHANNEL}.0" && _tn_eff=${INSTALL_K3S_CHANNEL}.0 ;; esac
+  fi
+  _tn_flagok=1 _tn_must=1
+  if [ -n "$_tn_eff" ] && tn_inst_cmp "$_tn_eff" v1.31.0 && [ "$TN_INST_CMP" = -1 ]; then _tn_flagok=0; fi
+  if [ -n "$_tn_eff" ] && tn_inst_cmp "$_tn_eff" v1.35.0 && [ "$TN_INST_CMP" = -1 ]; then _tn_must=0; fi
+  if [ "$_tn_cst" = v1 ]; then
+    tn_inst_warn "this host uses cgroup v1 (or the hybrid layout). cgroup v1 is deprecated: Kubernetes >= 1.35 refuses to start the kubelet on it. Move the device to cgroup v2 (kernel command line systemd.unified_cgroup_hierarchy=1, or a newer OS release)"
+  else
+    tn_inst_info "cannot tell whether the device uses cgroup v1 (OS build, or no /sys/fs/cgroup): the kubelet flag is set to be safe, it is harmless on cgroup v2"
+  fi
+  if [ "$_tn_flagok" = 0 ]; then
+    tn_inst_info "k3s $_tn_eff is older than v1.31 (its kubelet has no fail-cgroupv1 flag) and starts on cgroup v1 without help"
+    tn_inst_cgroup_remove "$_tn_cfile" "k3s is older than v1.31"
+    return 0
+  fi
+  if [ "$_tn_must" = 0 ]; then
+    tn_inst_info "k3s $_tn_eff starts on cgroup v1 without help; the kubelet flag is set anyway, so that an upgrade to v1.35 or newer (also one made by hand) does not stop the kubelet"
+  fi
+  if tn_inst_cgroup_configured_elsewhere; then
+    if [ "$TN_INST_CGROUP_PERSISTENT" = 1 ]; then
+      tn_inst_info "fail-cgroupv1=false is set by the device itself ($TN_INST_CGROUP_WHERE): left as it is"
+      tn_inst_cgroup_remove "$_tn_cfile" "the device sets fail-cgroupv1=false itself, in a file that k3s reads"
+      return 0
+    fi
+    # only on the command line of the installer: k3s does not read it until the unit is rewritten, so the
+    # drop-in must keep protecting a k3s that restarts before that. The same value twice does no harm.
+    tn_inst_info "fail-cgroupv1=false is set by the device itself ($TN_INST_CGROUP_WHERE): left as it is. The drop-in $_tn_cfile stays until the installer has put it in the unit; the same value twice is harmless, and the one on the command line wins"
+  fi
+  # an installed k3s older than v1.31 (about to be upgraded) cannot start with the flag
+  if [ -n "${TN_INST_INSTALLED:-}" ] && tn_inst_cmp "$TN_INST_INSTALLED" v1.31.0 && [ "$TN_INST_CMP" = -1 ]; then
+    TN_INST_CGROUP_DEFERRED=1
+    tn_inst_info "the installed k3s $TN_INST_INSTALLED is older than v1.31: the kubelet flag is set after the installer has upgraded it, not before"
+    tn_inst_cgroup_remove "$_tn_cfile" "the installed k3s is older than v1.31 and cannot take the flag until it is upgraded"
+    # The installer starts the new release as soon as it has written the unit. From v1.35 that kubelet
+    # does not start on cgroup v1 without the flag, and tn_inst_finish would never run (the installer's
+    # restart fails under set -e). So the unit gets the flag from its first start, through INSTALL_K3S_EXEC:
+    # the old kubelet, which is running now, never reads it. Not needed for an exact v1.31 - v1.34.
+    if [ "$_tn_must" = 1 ]; then
+      if printf '%s\n' "${INSTALL_K3S_EXEC:-}" | tn_inst_cgroup_flag_in_text; then
+        tn_inst_info "INSTALL_K3S_EXEC already has fail-cgroupv1=false: the new unit carries it from its first start"
+      else
+        INSTALL_K3S_EXEC="${INSTALL_K3S_EXEC:+$INSTALL_K3S_EXEC }--kubelet-arg=fail-cgroupv1=false"
+        export INSTALL_K3S_EXEC
+        tn_inst_info "k3s ${_tn_eff:-from a channel} may need the flag on its first start: --kubelet-arg=fail-cgroupv1=false is added to INSTALL_K3S_EXEC, so that the new unit has it. The old kubelet does not read it"
+      fi
+    fi
+    return 0
+  fi
+  tn_inst_cgroup_write
+}
+
+# tn_inst_cgroup_write: the drop-in, written atomically and only when it differs
+tn_inst_cgroup_write() {
+  _tn_cdir=${TN_K3S_CONFIG_DIR:-/etc/rancher/k3s}/config.yaml.d
+  _tn_cfile=$_tn_cdir/$TN_INST_CGROUP_FILE
+  _tn_want=$(printf '%s\n' \
+    '# Written by the Teknoir bootstrap script. Kubernetes >= 1.35 refuses to start the kubelet on cgroup v1' \
+    '# unless this is false. cgroup v1 is deprecated: move the device to cgroup v2 and delete this file.' \
+    '# "kubelet-arg+" appends to the kubelet-arg of config.yaml; harmless on cgroup v2.' \
+    'kubelet-arg+:' \
+    '  - "fail-cgroupv1=false"')
+  if [ -f "$_tn_cfile" ] && [ "$(cat "$_tn_cfile")" = "$_tn_want" ]; then
+    tn_inst_info "kubelet-arg fail-cgroupv1=false is already in place ($_tn_cfile)"
+    return 0
+  fi
+  # atomically: k3s may be restarting in a loop right now and must never read half a file. The temporary
+  # name does not end in .yaml, so k3s does not read it either.
+  _tn_tmp=$_tn_cdir/.$TN_INST_CGROUP_FILE.tmp.$$
+  if mkdir -p "$_tn_cdir" && find "$_tn_cdir" -maxdepth 1 -name ".$TN_INST_CGROUP_FILE.tmp.*" -exec rm -f {} + &&
+     printf '%s\n' "$_tn_want" > "$_tn_tmp" && mv -f "$_tn_tmp" "$_tn_cfile"; then
+    :
+  else
+    rm -f "$_tn_tmp" 2>/dev/null || true
+    tn_inst_fatal "cannot write $_tn_cfile: k3s >= v1.35 would not start on this cgroup v1 host"
+  fi
+  tn_inst_info "Set the kubelet argument fail-cgroupv1=false in $_tn_cfile (k3s ${TN_INST_EFFECTIVE:-from a channel} on cgroup v1)"
+}
+
+# ----------------------------------------------------------------- config.yaml
+
+# tn_inst_yaml_has_key FILE KEY: is there a top-level KEY (or KEY+) in FILE
+tn_inst_yaml_has_key() {
+  [ -r "$1" ] || return 1
+  awk -v k="$2" '{ sub(/\r$/, "") } $0 ~ ("^" k "\\+?[ \t]*:") { f = 1 } END { exit f ? 0 : 1 }' "$1"
+}
+
+# tn_inst_config_ensure FILE KEY TEXT: appends TEXT (the YAML of the key, may be several lines) to
+# FILE unless FILE has the top-level KEY already. A config.yaml that the device owner has edited is
+# never rewritten: a re-run of a bootstrap script used to replace it, and lost every key it did not know.
+tn_inst_config_ensure() {
+  if tn_inst_yaml_has_key "$1" "$2"; then
+    tn_inst_info "$1 already sets '$2': kept"
+    return 0
+  fi
+  mkdir -p "$(dirname "$1")" || return 1
+  if [ -s "$1" ] && [ -n "$(tail -c 1 "$1")" ]; then echo >> "$1" || return 1; fi
+  printf '%s\n' "$3" >> "$1" || return 1
+  tn_inst_info "$1: added '$2'"
+}
+
+# ----------------------------------------------------------------- the entry point
+
+# tn_inst_prepare ROLE: the release policy, then cgroup v1. Call it after INSTALL_K3S_VERSION /
+# INSTALL_K3S_CHANNEL (and INSTALL_K3S_EXEC, if the device sets fail-cgroupv1 there) are set and
+# before the k3s installer. A SERVER script calls it BEFORE tn_k3s_ca_setup: the kubelet flag must be in
+# place before the CA step restarts k3s, or a k3s that a cgroup v1 host made exit would not be up for
+# rotate-ca (it restarts itself every few seconds and reads the flag then). The CA step must in turn
+# run before the installer. An agent has no CA step.
+tn_inst_prepare() {
+  TN_INST_ROLE=${1:-server}
+  tn_inst_info "Checking the k3s release and the cgroup version ($TN_INST_ROLE)"
+  tn_inst_plan
+  tn_inst_cgroup
+}
+
+# tn_inst_finish: call it right after the k3s installer succeeded. Writes the kubelet flag that
+# tn_inst_prepare held back because the k3s that was installed then could not take it (see "Order of
+# effects"). Nothing to do otherwise.
+tn_inst_finish() {
+  if [ -n "${TN_INST_CGROUP_DEFERRED:-}" ]; then
+    TN_INST_CGROUP_DEFERRED=
+    tn_inst_info "The installer has run: setting the kubelet flag that was held back"
+    tn_inst_cgroup_write
+  fi
+}
diff --git a/pkg/templates/server.sh.tmpl b/pkg/templates/server.sh.tmpl
index e011413..2dff3f6 100644
--- a/pkg/templates/server.sh.tmpl
+++ b/pkg/templates/server.sh.tmpl
@@ -12,6 +12,13 @@
 #   INSTALL_WATCHDOG=true (default: false, enable or disable the teknoir watchdog service)
 #   USE_DOCKER=true (default: false, enable the use of docker as container runtime for k3sm inly works for k3s < 1.24)
 #   CREATE_USER=false (default: ask, create a user for the device without asking)
+#   TN_K3S_CA_AUTO_REMEDIATE=false (default: true; a re-run on a device bootstrapped with the old
+#                          root CA repairs it before k3s is touched. false stops with advice instead)
+#   TN_K3S_UPGRADE=true (default: false; a re-run KEEPS the installed k3s version. true lets the pin
+#                          below replace it: never a downgrade, never more than one minor version)
+#   TN_K3S_FORCE=true (default: false; allows an upgrade over more than one minor version)
+#   TN_K3S_CGROUPV1=true|false (default: detected; on cgroup v1 with k3s >= v1.31 the kubelet gets
+#                          fail-cgroupv1=false, see /etc/rancher/k3s/config.yaml.d/99-teknoir-cgroupv1.yaml)
 
 
 TMP=$(mktemp -dt)
@@ -34,120 +41,50 @@ info "Teknoir bootstrapping...${TMP}"
 {{template "variables.sh.tmpl" .}}
 
 {{template "keys.sh.tmpl" .}}
-info "Prepare K3s CA Certs"
-export PRODUCT="${PRODUCT:-k3s}"
-export DATA_DIR="${DATA_DIR:-/var/lib/rancher/${PRODUCT}}"
-
-if command -v openssl-3 >/dev/null 2>&1; then
-  OPENSSL=openssl-3
-else
-  OPENSSL=openssl
-fi
-
-info "Using ${OPENSSL}: $(${OPENSSL} version)"
-
-if ! ${OPENSSL} ecparam -name prime256v1 -genkey -noout -out /dev/null >/dev/null 2>&1; then
-  fatal "openssl not found or missing Elliptic Curve (ecparam) support."
-fi
-
-${OPENSSL} version | grep -qF 'OpenSSL 3' && OPENSSL_GENRSA_FLAGS=-traditional
-
-mkdir -p "${DATA_DIR}/server/tls/etcd"
-
-cp ${CONFIG_PATH}/rsa_public.pem ${DATA_DIR}/server/tls/root-ca.pem
-cp ${CONFIG_PATH}/rsa_private.pem ${DATA_DIR}/server/tls/root-ca.key
-
-cd "${DATA_DIR}/server/tls"
-
-# Set up temporary openssl configuration
-mkdir -p ".ca/certs"
-trap "rm -rf .ca" EXIT
-touch .ca/index
-openssl rand -hex 8 > .ca/serial
-cat >.ca/config <<'EOF'
-[ca]
-default_ca = ca_default
-[ca_default]
-dir = ./.ca
-database = $dir/index
-serial = $dir/serial
-new_certs_dir = $dir/certs
-default_md = sha256
-policy = policy_anything
-[policy_anything]
-commonName = supplied
-[req]
-distinguished_name = req_distinguished_name
-[req_distinguished_name]
-[v3_ca]
-subjectKeyIdentifier = hash
-authorityKeyIdentifier = keyid:always
-basicConstraints = critical, CA:true
-keyUsage = critical, digitalSignature, keyEncipherment, keyCertSign
-EOF
-
-if [ -e service.key ]; then
-  info "Generating additional Kubernetes service account issuer RSA key"
-  OLD_SERVICE_KEY="$(cat service.key)"
-else
-  info "Generating Kubernetes service account issuer RSA key"
-fi
-${OPENSSL} genrsa ${OPENSSL_GENRSA_FLAGS:-} -out service.key 2048
-echo "${OLD_SERVICE_KEY}" >> service.key
-
-cat root-ca.pem > root-ca.crt
-
-if [ ! -e root-ca.key ]; then
-  fatal "Cannot generate intermediate certificate without root certificate private key"
-fi
-
-info "Generating intermediate certificate authority RSA key and certificate"
-${OPENSSL} genrsa ${OPENSSL_GENRSA_FLAGS:-} -out intermediate-ca.key 4096
-${OPENSSL} req -new -nodes \
-               -subj "/CN=${PRODUCT}-intermediate-ca@${_DEVICE_ID}.${_DOMAIN}" \
-               -key intermediate-ca.key |
-${OPENSSL} ca  -batch -notext -days 3700 \
-               -in /dev/stdin \
-               -out intermediate-ca.pem \
-               -keyfile root-ca.key \
-               -cert root-ca.pem \
-               -config .ca/config \
-               -extensions v3_ca
-
-cat intermediate-ca.pem root-ca.pem > intermediate-ca.crt
-
-if [ ! -e intermediate-ca.key ]; then
-  fatal "Cannot generate leaf certificates without intermediate certificate private key"
+# The k3s CA of the device: the device certificate becomes the root CA (re-issued with
+# keyCertSign, which k3s >= v1.34.12/v1.35.9/v1.36.5/v1.37.1 requires). The library is also
+# available stand-alone as pkg/templates/scripts/tn-k3s-ca.sh (check / remediate).
+TN_K3S_CA_NO_MAIN=1
+{{template "tn-k3s-ca.sh" .}}
+# The k3s release policy (a re-run keeps the installed k3s) and the cgroup v1 kubelet flag.
+{{template "tn-k3s-install.sh" .}}
+
+{{template "k3s_version.sh.tmpl" .}}
+# Order: (0) the arguments of the k3s installer, (1) the k3s release policy and the cgroup v1 kubelet
+# flag, (2) the CA, (3) the k3s installer.
+# (0) comes first because (1) reads INSTALL_K3S_EXEC: it must see what the installer will get, or a
+# fail-cgroupv1 that the caller put there would be taken as "set by the device" (the drop-in removed)
+# and then lost when the variable is rebuilt. A value the caller gave is kept, after ours.
+# (1) comes before the CA step: it refuses before anything on the device is changed, and the kubelet
+# flag is in place when the CA step restarts k3s (a k3s that a cgroup v1 host made exit restarts itself
+# in a loop, and has to be up for rotate-ca). The data dir is looked up first, the way the CA step does
+# it, because a k3s datastore there decides whether a k3s whose version cannot be read is installed; a
+# data dir that disagrees with config.yaml is refused here, before (1) changes anything.
+# BEGIN install-k3s-exec
+export INSTALL_K3S_EXEC="server --token ${_K3S_TOKEN} --tls-san ${_DEVICE_ID}.${_DOMAIN} --tls-san 10.0.0.10${INSTALL_K3S_EXEC:+ ${INSTALL_K3S_EXEC}}"
+if [ "${USE_DOCKER}" = true ]; then
+    info "Use docker container-runtime for K3s"
+    export INSTALL_K3S_EXEC="${INSTALL_K3S_EXEC} --docker"
 fi
-
-# Generate new leaf CAs for all the control-plane and etcd components
-for TYPE in client server request-header etcd/peer etcd/server; do
-  CERT_NAME="${PRODUCT}-$(echo ${TYPE} | tr / -)-ca"
-  info "Generating ${CERT_NAME} leaf certificate authority EC key and certificate"
-  ${OPENSSL} ecparam -name prime256v1 -genkey -noout -out ${TYPE}-ca.key
-  ${OPENSSL} req -new -nodes \
-                 -subj "/CN=${CERT_NAME}@${_DEVICE_ID}.${_DOMAIN}" \
-                 -key ${TYPE}-ca.key |
-  ${OPENSSL} ca  -batch -notext -days 3700 \
-                 -in /dev/stdin \
-                 -out ${TYPE}-ca.pem \
-                 -keyfile intermediate-ca.key \
-                 -cert intermediate-ca.pem \
-                 -config .ca/config \
-                 -extensions v3_ca
-  cat ${TYPE}-ca.pem \
-      intermediate-ca.pem \
-      root-ca.pem > ${TYPE}-ca.crt
-done
+# END install-k3s-exec
+tn_ca_resolve_datadir
+tn_ca_require_consistent_datadir
+tn_inst_prepare server
+tn_k3s_ca_setup
 
 info "Install Rancher K3s"
 export K3S_CONFIG_PATH=/etc/rancher/k3s
 $SUDO mkdir -p ${K3S_CONFIG_PATH}
-$SUDO tee ${K3S_CONFIG_PATH}/config.yaml > /dev/null << EOL
-disable:
-  - traefik
-node-name: teknoir-master
-EOL
+# A re-run must not replace a config.yaml that already exists (it may hold keys of the device owner,
+# like a kubelet-arg): the Teknoir keys are added when they are missing.
+tn_inst_config_ensure ${K3S_CONFIG_PATH}/config.yaml disable "disable:
+  - traefik"
+tn_inst_config_ensure ${K3S_CONFIG_PATH}/config.yaml node-name "node-name: teknoir-master"
+# The CA above was made in ${DATA_DIR}, the data dir that k3s uses on this device. The file just
+# written and the unit that the installer writes (it has no --data-dir) must keep it there.
+if [ "${DATA_DIR}" != "/var/lib/rancher/k3s" ]; then
+    tn_inst_config_ensure ${K3S_CONFIG_PATH}/config.yaml data-dir "data-dir: ${DATA_DIR}"
+fi
 cat >/etc/sysctl.d/teknoir-k3s.conf << EOF
 fs.inotify.max_user_instances=1024
 EOF
@@ -168,18 +105,20 @@ if [ ${OS_BUILD} ]; then
     $SUDO sed -i "s#-d /run/systemd#true#g" k3s_installer.sh
 fi
 
-export INSTALL_K3S_EXEC="server --token ${_K3S_TOKEN} --tls-san ${_DEVICE_ID}.${_DOMAIN} --tls-san 10.0.0.10 ${INSTALL_K3S_EXEC}"
-if [ "${USE_DOCKER}" = true ]; then
-    info "Use docker container-runtime for K3s"
-    export INSTALL_K3S_EXEC="${INSTALL_K3S_EXEC} --docker"
-fi
-
+# The release (INSTALL_K3S_VERSION) and the kubelet flag were decided by tn_inst_prepare above.
 export INSTALL_K3S_SYMLINK=force
 $SUDO ./k3s_installer.sh
+# The kubelet flag that had to wait for the installer (an installed k3s older than v1.31 that was upgraded)
+tn_inst_finish
+
+# Tell the agents which k3s release this server runs: they install exactly that one (a kubelet must not be
+# newer than its apiserver), and k3s does not answer /version to an anonymous caller. Served by k3s at
+# https://<server>:6443/static/teknoir/k3s-version.
+tn_inst_publish_release
 
 info "Install Teknoir Manifests"
-$SUDO mkdir -p /var/lib/rancher/k3s/server/manifests
-$SUDO tee /var/lib/rancher/k3s/server/manifests/teknoir.yaml > /dev/null << EOL
+$SUDO mkdir -p ${DATA_DIR}/server/manifests
+$SUDO tee ${DATA_DIR}/server/manifests/teknoir.yaml > /dev/null << EOL
 {{template "manifests.yaml.tmpl" .}}
 EOL
 
diff --git a/pkg/templates/templates_test.go b/pkg/templates/templates_test.go
index 6cae5bb..a05c289 100644
--- a/pkg/templates/templates_test.go
+++ b/pkg/templates/templates_test.go
@@ -2,6 +2,9 @@ package templates
 
 import (
 	"bytes"
+	"os"
+	"os/exec"
+	"path/filepath"
 	"strings"
 	"testing"
 	"text/template"
@@ -62,3 +65,121 @@ func TestTemplates_Execution(t *testing.T) {
 		})
 	}
 }
+
+// ---------------------------------------------------------------- the k3s pin
+
+func renderK3S(t *testing.T, tpl *template.Template, version string) string {
+	t.Helper()
+	var buf bytes.Buffer
+	if err := tpl.Execute(&buf, TemplateData{Domain: "test.cloud", DeviceID: "dev-1", K3SToken: "tok", K3SVersion: version}); err != nil {
+		t.Fatal(err)
+	}
+	return buf.String()
+}
+
+// installer lines of the script: the exports before ./k3s_installer.sh
+func exportsOf(out, name string) []string {
+	var lines []string
+	for _, l := range strings.Split(out, "\n") {
+		if strings.HasPrefix(l, "export "+name+"=") {
+			lines = append(lines, l)
+		}
+	}
+	return lines
+}
+
+func TestK3SPinDefaultsForServerAndAgent(t *testing.T) {
+	if DefaultK3SVersion != "v1.36.5+k3s1" {
+		t.Errorf("default pin %s", DefaultK3SVersion)
+	}
+	for name, tpl := range map[string]*template.Template{"server": ServerTemplate, "agent": AgentTemplate} {
+		for _, v := range []string{"", DefaultK3SVersion} {
+			out := renderK3S(t, tpl, v)
+			want := `export INSTALL_K3S_VERSION="${INSTALL_K3S_VERSION:-v1.36.5+k3s1}"`
+			if got := exportsOf(out, "INSTALL_K3S_VERSION"); len(got) != 1 || got[0] != want {
+				t.Errorf("%s (version %q): %q", name, v, got)
+			}
+			// the pin is set before the installer runs
+			if strings.Index(out, "INSTALL_K3S_VERSION=") > strings.Index(out, "\n$SUDO ./k3s_installer.sh") {
+				t.Errorf("%s: the pin comes after the installer", name)
+			}
+		}
+	}
+}
+
+func TestK3SPinOverridesAndChannels(t *testing.T) {
+	for name, tpl := range map[string]*template.Template{"server": ServerTemplate, "agent": AgentTemplate} {
+		out := renderK3S(t, tpl, "v1.34.11+k3s1")
+		if got := exportsOf(out, "INSTALL_K3S_VERSION"); len(got) != 1 || !strings.Contains(got[0], "v1.34.11+k3s1") || strings.Contains(strings.Join(exportsOf(out, "INSTALL_K3S_VERSION"), ""), "v1.36.5") {
+			t.Errorf("%s override: %q", name, got)
+		}
+		// stable keeps the old behaviour: nothing is exported
+		out = renderK3S(t, tpl, "stable")
+		if len(exportsOf(out, "INSTALL_K3S_VERSION"))+len(exportsOf(out, "INSTALL_K3S_CHANNEL")) != 0 {
+			t.Errorf("%s stable exports a version or channel", name)
+		}
+		if !strings.Contains(out, "stable") {
+			t.Errorf("%s stable: no note", name)
+		}
+		out = renderK3S(t, tpl, "latest")
+		if got := exportsOf(out, "INSTALL_K3S_CHANNEL"); len(got) != 1 || !strings.Contains(got[0], "latest") || len(exportsOf(out, "INSTALL_K3S_VERSION")) != 0 {
+			t.Errorf("%s latest: %q", name, got)
+		}
+	}
+}
+
+// server and agent of one cluster get the same version from one TemplateData
+func TestK3SPinIsTheSameForServerAndAgent(t *testing.T) {
+	for _, v := range []string{"", "v1.35.9+k3s1", "stable", "latest"} {
+		s := exportsOf(renderK3S(t, ServerTemplate, v), "INSTALL_K3S_VERSION")
+		a := exportsOf(renderK3S(t, AgentTemplate, v), "INSTALL_K3S_VERSION")
+		if strings.Join(s, "|") != strings.Join(a, "|") {
+			t.Errorf("version %q: server %q, agent %q", v, s, a)
+		}
+	}
+}
+
+func TestValidateK3SVersion(t *testing.T) {
+	for _, ok := range []string{"", "stable", "latest", "v1.36.5+k3s1", "v1.34.11+k3s2", "v1.27.0+k3s10"} {
+		if err := ValidateK3SVersion(ok); err != nil {
+			t.Errorf("%q: %v", ok, err)
+		}
+	}
+	for _, bad := range []string{"1.36.5+k3s1", "v1.36.5", "v1.36", "v1.36.5-rc1+k3s1", "testing", "v1.36.5+k3s1; rm -rf /", "$(id)", "v1.36.5+k3s1\n", "`x`", "\"", " stable"} {
+		if err := ValidateK3SVersion(bad); err == nil {
+			t.Errorf("%q was accepted", bad)
+		}
+	}
+}
+
+// the rendered scripts parse, with every kind of pin
+func TestRenderedScriptsParseWithEveryPin(t *testing.T) {
+	if _, err := exec.LookPath("sh"); err != nil {
+		t.Skip("sh not installed")
+	}
+	for name, tpl := range map[string]*template.Template{"server": ServerTemplate, "agent": AgentTemplate} {
+		for _, v := range []string{"", "v1.34.11+k3s1", "stable", "latest"} {
+			f := filepath.Join(t.TempDir(), "s.sh")
+			if err := os.WriteFile(f, []byte(renderK3S(t, tpl, v)), 0o600); err != nil {
+				t.Fatal(err)
+			}
+			if o, err := exec.Command("sh", "-n", f).CombinedOutput(); err != nil {
+				t.Errorf("%s %q: sh -n: %v\n%s", name, v, err, o)
+			}
+		}
+	}
+}
+
+// The CA is made in the data dir that setup resolved; the manifests and the config written
+// afterwards must use the same one.
+func TestServerScriptUsesTheResolvedDataDir(t *testing.T) {
+	out := renderK3S(t, ServerTemplate, "")
+	for _, want := range []string{"${DATA_DIR}/server/manifests", `tn_inst_config_ensure ${K3S_CONFIG_PATH}/config.yaml data-dir "data-dir: ${DATA_DIR}"`} {
+		if !strings.Contains(out, want) {
+			t.Errorf("server script lacks %q", want)
+		}
+	}
+	if strings.Contains(out, "/var/lib/rancher/k3s/server/manifests") {
+		t.Error("manifests are still written to a hard-coded data dir")
+	}
+}
diff --git a/test/k3s-ca/README.md b/test/k3s-ca/README.md
index d006e43..ed0016b 100644
--- a/test/k3s-ca/README.md
+++ b/test/k3s-ca/README.md
@@ -91,6 +91,7 @@ hung k3s cannot stall a run.
 | `remediation` (S5-S7) | persistent data dirs: **S5** bootstrap legacy on v1.34.11 with an agent and a marker ConfigMap, remediate, upgrade through the fix to v1.36.5 (`check` = 0, second remediate = no-op); **S6** bricked (v1.34.11 -> v1.36.5 swap, datastore initialised): rotate through the running post-fix server; **S7** hung fresh bootstrap (legacy CA directly on v1.36.5, `server/token` never written): nothing to rotate, `prepare` regenerates the PKI in place and k3s starts from it. The downgrade fallback (pre-fix patch -> remediate -> upgrade) runs only if S6/S7 fail | see the table printed by the run |
 | `rerun` (S8) | `lib` setup on v1.36.5, Ready, setup again on the initialised dir: tls sha256 unchanged, k3s restarts Ready | |
 | `host` (S9, S10) | as root on the host, with `K3S_BIN='docker exec <srv> k3s'`, `TN_K3S_RESTART_CMD='docker restart <srv>'`, data dir bind-mounted at an identical path (needs passwordless sudo). **S9** `remediate --phase all`. **S10** `tn_k3s_ca_setup` sourced under `set -e`/noglob on a device bootstrapped with the old root repairs the CA itself, k3s then upgrades to v1.36.5 with the marker intact, and a second setup is a no-op | |
+| `install` (S11-S13) | needs `TN_K3S_INSTALL_LIB`. **S11** `tn_inst_prepare` with `TN_K3S_CGROUPV1=true` (this host is cgroup v2) against an `/etc/rancher/k3s` that holds a user `kubelet-arg: max-pods=77`, then a real k3s from that directory: k3s >= v1.31 (the kubelet knows the flag from then on; v1.30.14, v1.31.14, v1.34.11, v1.36.5 are run) must be started with `fail-cgroupv1=false` and keep `max-pods=77` (the `k3s.io/node-args` annotation), an older k3s gets no drop-in. **S12** the installed release is read from the real `k3s --version` output (`K3S_BIN='docker run --rm rancher/k3s:<tag>'`): a different pin is ignored (keep), an upgrade over several minors and any downgrade are refused, and a k3s whose version cannot be read is refused. **S13** the agent follows its server (k3s answers `/version` with 401 to anonymous callers, so the server script publishes `server/static/teknoir/k3s-version`, which k3s serves without authentication): `tn_inst_publish_release` runs with the real k3s binary of the image on the data dir of a real server (v1.34.11 and v1.36.5) before it starts and again when it is up; a helper container on its network (with curl) runs `tn_inst_prepare agent` with `K3S_URL` and a default pin of the other release, reads the real server and must settle on the server's release; a real agent container of exactly that release then joins and must be Ready; a pin that was asked for and is newer than the server, a server whose file is removed (real `/version` is 401), and an unreachable server, are refused | READY / PASS |
 | `openssl-compat` | the library's setup, run twice per generator under `/bin/sh` (dash) in distro containers, no k3s (see below) | PASS everywhere |
 | `all` | everything above | |
 
@@ -128,7 +129,7 @@ example `--compat-images "debian:bookworm linux/arm64/ubuntu:22.04"`.
 ## Options
 
 ```
---suite S[,S...]        control|fresh|legacy-with-cert|agent|remediation|rerun|host|openssl-compat|all
+--suite S[,S...]        control|fresh|legacy-with-cert|agent|remediation|rerun|host|install|openssl-compat|all
 --versions "V ..."      --gens "G ..."      --ca-mode lib|proper (agent suite)
 --agent-os-trust yes|no|both                --helpers "ubuntu:20.04 debian:bookworm" (remediation)
 --compat-images "..."   --helper-image IMG  -j N (default 4)
@@ -152,7 +153,8 @@ is skipped with a message (a `SKIP` row) when the hook is absent.
 
 | variable | meaning |
 |---|---|
-| `TN_K3S_CA_LIB` | path of `tn-k3s-ca.sh` (cli: `pkg/templates/scripts/tn-k3s-ca.sh`; bootstrap-device: `templates/04_tn_k3s_ca_lib.sh`). It is **sourced** (`. file`, no arguments, must not run anything) in a shell that has `set -e`, `set -o noglob`, `umask 027` and `info`/`warn`/`fatal` as in `header.sh.tmpl` (`shim.sh`), with `CONFIG_PATH` (a dir holding `rsa_public.pem` and `rsa_private.pem`), `DATA_DIR`, `PRODUCT=k3s`, `_DEVICE_ID`, `_DOMAIN` set, and must provide `tn_k3s_ca_setup`. As a program (`sh tn-k3s-ca.sh check\|remediate [--phase prepare\|rotate\|finalize\|all] [--data-dir D]`) it is the remediation tool |
+| `TN_K3S_CA_LIB` | path of `tn-k3s-ca.sh` (cli: `pkg/templates/scripts/tn-k3s-ca.sh`; bootstrap-device: `templates/04_tn_k3s_ca_lib.sh`). It is **sourced** (`. file`, no arguments, must not run anything) in a shell that has `set -e`, `set -o noglob`, `umask 027` and `info`/`warn`/`fatal` as in `header.sh.tmpl` (`shim.sh`), with `CONFIG_PATH` (a dir holding `rsa_public.pem` and `rsa_private.pem`), `DATA_DIR` (explicit; a run without it resolves the data dir of k3s, see the top of the library), `PRODUCT=k3s`, `_DEVICE_ID`, `_DOMAIN` set, and must provide `tn_k3s_ca_setup`. As a program (`sh tn-k3s-ca.sh check\|remediate [--phase prepare\|rotate\|finalize\|all] [--data-dir D]`) it is the remediation tool |
+| `TN_K3S_INSTALL_LIB` | path of `tn-k3s-install.sh` (cli: `pkg/templates/scripts/tn-k3s-install.sh`; bootstrap-device: `templates/04_tn_k3s_install_lib.sh`), the k3s release policy and cgroup v1 handling. Sourced like the CA library (`shim.sh`), provides `tn_inst_prepare` and `tn_inst_plan`. Only the `install` suite uses it |
 | `TN_REMEDIATE_PREPARE` | command run in a helper container (root, data dir at `/var/lib/rancher/k3s`, the library at `/tn/tn-k3s-ca.sh`, device files at `/etc/teknoir`, `DATA_DIR` and `K3S_BIN=k3s` in the environment). Default: `sh /tn/tn-k3s-ca.sh remediate --phase prepare --data-dir /var/lib/rancher/k3s` |
 | rotate command | not a variable: for an initialised datastore the prepare phase must leave the exact command in `$DATA_DIR/server/.tn-ca-rotate-*/ROTATE_CMD` (the newest one is used). The harness runs it with `docker exec <server> sh -c "$(cat ROTATE_CMD)"`. A datastore that k3s never initialised (S7) has nothing to rotate: prepare may leave no `ROTATE_CMD` there, and only there (S5/S6 fail without it) |
 | `TN_REMEDIATE_FINALIZE` | like PREPARE for the finalize phase. The harness then runs `docker restart <server>` |
diff --git a/test/k3s-ca/cmd/k3sverify/main.go b/test/k3s-ca/cmd/k3sverify/main.go
index 8e9503a..ab8dcc3 100644
--- a/test/k3s-ca/cmd/k3sverify/main.go
+++ b/test/k3s-ca/cmd/k3sverify/main.go
@@ -270,6 +270,11 @@ func CheckRoot(root, orig *x509.Certificate, key crypto.Signer, now time.Time, w
 		if len(orig.SubjectKeyId) != 0 && !bytes.Equal(root.SubjectKeyId, orig.SubjectKeyId) {
 			add("SKI differs from the original certificate")
 		}
+		// two different certificates with the same issuer and serial break RFC 5280 4.1.2.2
+		// (NSS: SEC_ERROR_REUSED_ISSUER_AND_SERIAL); OpenSSL 1.1.1 `x509 -signkey` ignores -set_serial
+		if bytes.Equal(root.RawIssuer, orig.RawIssuer) && root.SerialNumber.Cmp(orig.SerialNumber) == 0 && !bytes.Equal(root.Raw, orig.Raw) {
+			add("serial number equals the original certificate's (same issuer and serial, different certificate)")
+		}
 		if !orig.PublicKey.(interface{ Equal(crypto.PublicKey) bool }).Equal(root.PublicKey) {
 			add("public key differs from the original certificate")
 		}
diff --git a/test/k3s-ca/cmd/k3sverify/main_test.go b/test/k3s-ca/cmd/k3sverify/main_test.go
index 12882c8..b61ccb0 100644
--- a/test/k3s-ca/cmd/k3sverify/main_test.go
+++ b/test/k3s-ca/cmd/k3sverify/main_test.go
@@ -231,6 +231,14 @@ func TestCheckRoot(t *testing.T) {
 	if p := CheckRoot(rootEKU, orig.cert, key, now, 7300); !strings.Contains(strings.Join(p, "\n"), "extendedKeyUsage") {
 		t.Fatalf("EKU not reported: %v", p)
 	}
+	// serial of the original reused (what OpenSSL 1.1.1 `x509 -signkey -set_serial` produces)
+	same := *good
+	same.SerialNumber = orig.cert.SerialNumber
+	der, _ = x509.CreateCertificate(rand.Reader, &same, &same, &key.PublicKey, key)
+	rootSame, _ := x509.ParseCertificate(der)
+	if p := CheckRoot(rootSame, orig.cert, key, now, 7300); !strings.Contains(strings.Join(p, "\n"), "serial number equals") {
+		t.Fatalf("reused serial not reported: %v", p)
+	}
 	// subject differs
 	sub := *good
 	sub.Subject = pkix.Name{CommonName: "other"}
diff --git a/test/k3s-ca/compat/assert.sh b/test/k3s-ca/compat/assert.sh
index 6dec777..5032383 100644
--- a/test/k3s-ca/compat/assert.sh
+++ b/test/k3s-ca/compat/assert.sh
@@ -19,6 +19,8 @@ command -v openssl >/dev/null 2>&1 || { echo "RESULT * FAIL openssl missing in i
 echo "# $(uname -m) $(openssl version) sh=$(readlink -f /bin/sh 2>/dev/null || echo sh)"
 
 sum() { sha256sum "$1" | cut -d' ' -f1; }
+# serial of a certificate, as openssl prints it on any version ("serial=..."), lower case
+serial() { openssl x509 -in "$1" -noout -serial | sed 's/^serial=//' | tr 'A-F' 'a-f' | sed 's/^0*//'; }
 
 one() { # GEN
   g=$1
@@ -27,6 +29,7 @@ one() { # GEN
   mkdir -p "$w/etc" "$w/data"
   cp "$src/rsa_public.pem" "$src/rsa_private.pem" "$w/etc/"
   pub0=$(sum "$w/etc/rsa_public.pem"); prv0=$(sum "$w/etc/rsa_private.pem")
+  ser0=$(serial "$w/etc/rsa_public.pem")
   # 1+2: run the setup twice (the second run must be idempotent in its guarantees)
   for run in 1 2; do
     (
@@ -57,6 +60,11 @@ one() { # GEN
     pk1=$(openssl x509 -in "$t/root-ca.pem" -noout -pubkey | sha256sum | cut -d' ' -f1)
     pk2=$(openssl pkey -in "$w/etc/rsa_private.pem" -pubout 2>/dev/null | sha256sum | cut -d' ' -f1)
     [ "$pk1" = "$pk2" ] || { echo "RESULT $g FAIL run $run: root public key != device key"; rm -rf "$w"; return; }
+    # a new serial: issuer + serial of two different certificates must be unique (OpenSSL 1.1.1
+    # silently ignores -set_serial in `x509 -signkey`, which the library works around)
+    ser1=$(serial "$t/root-ca.pem")
+    { [ -n "$ser1" ] && [ "$ser1" != "$ser0" ]; } ||
+      { echo "RESULT $g FAIL run $run: re-issued root has the serial $ser1 of the original certificate"; rm -rf "$w"; return; }
     # the device files must never change
     [ "$(sum "$w/etc/rsa_public.pem")" = "$pub0" ] && [ "$(sum "$w/etc/rsa_private.pem")" = "$prv0" ] ||
       { echo "RESULT $g FAIL run $run: rsa_public.pem/rsa_private.pem were modified"; rm -rf "$w"; return; }
@@ -74,6 +82,7 @@ remed() { # GEN
   w=$(mktemp -d)
   mkdir -p "$w/etc" "$w/data/server/tls"
   cp "$GENDIR/$g/rsa_public.pem" "$GENDIR/$g/rsa_private.pem" "$w/etc/"
+  ser0=$(serial "$w/etc/rsa_public.pem")
   printf '#!/bin/sh\necho "$*" >> "%s/k3s.calls"\n' "$w" > "$w/fake-k3s"
   chmod 755 "$w/fake-k3s"
   if ! out=$( (
@@ -97,6 +106,9 @@ remed() { # GEN
   if ! out=$("$BIN/k3sverify" -orig "$w/etc/rsa_public.pem" -key "$w/etc/rsa_private.pem" -days 7300 "$w/data/server/tls" 2>&1); then
     echo "RESULT $g-remediate FAIL k3sverify after remediation: $(echo "$out" | grep '^FAIL' | head -3 | tr '\n' ' ' | cut -c1-300)"; rm -rf "$w"; return
   fi
+  ser1=$(serial "$w/data/server/tls/root-ca.pem")
+  { [ -n "$ser1" ] && [ "$ser1" != "$ser0" ]; } ||
+    { echo "RESULT $g-remediate FAIL remediated root has the serial $ser1 of the original certificate"; rm -rf "$w"; return; }
   if ls -a "$w/data/server" | grep -q '^\.tn-ca-rotate'; then echo "RESULT $g-remediate FAIL staging dir left behind"; rm -rf "$w"; return; fi
   echo "RESULT $g-remediate PASS check 2 -> remediate -> check 0"
   rm -rf "$w"
@@ -107,3 +119,116 @@ for g in $GENS; do
   one "$g"
   if openssl x509 -in "$GENDIR/$g/rsa_public.pem" -noout -text | grep -q 'Certificate Sign'; then :; else remed "$g"; fi
 done
+
+# The k3s install library (release policy, cgroup v1 flag, config.yaml) under the same /bin/sh and
+# the same awk/sed/stat of this image (mawk on Debian/Ubuntu, 32-bit arm, ...). No k3s needed.
+install_lib_check() {
+  IL=/tn/tn-k3s-install.sh
+  [ -f "$IL" ] || return 0
+  w=$(mktemp -d)
+  printf '#!/bin/sh\necho "k3s version v1.34.11+k3s1 (0123abcd)"\necho "go version go1.24.1"\n' > "$w/k3s"; chmod +x "$w/k3s"
+  printf '#!/bin/sh\necho "k3s version v1.30.14+k3s1 (0123abcd)"\necho "go version go1.22.12"\n' > "$w/k3s130"; chmod +x "$w/k3s130"
+  if ! out=$(
+      cd "$w" &&
+      env -u INSTALL_K3S_VERSION "K3S_BIN=$w/k3s" "TN_K3S_CONFIG_DIR=$w/cfg" TN_CGROUP_FSTYPE=tmpfs INSTALL_K3S_VERSION=v1.36.5+k3s1 sh -c '
+        set -e; set -o noglob; umask 027
+        . "$1"
+        # versions: numeric compare, k3s revision, garbage
+        tn_inst_cmp v1.36.10+k3s1 v1.36.9+k3s3; [ "$TN_INST_CMP" = 1 ] || { echo "cmp patch $TN_INST_CMP"; exit 1; }
+        tn_inst_cmp v1.9.0+k3s1 v1.10.0+k3s1; [ "$TN_INST_CMP" = -1 ] || { echo "cmp minor $TN_INST_CMP"; exit 1; }
+        tn_inst_cmp v1.36.5+k3s2 v1.36.5+k3s1; [ "$TN_INST_CMP" = 1 ] || { echo "cmp revision $TN_INST_CMP"; exit 1; }
+        if tn_inst_cmp stable v1.36.5+k3s1; then echo "stable parsed"; exit 1; fi
+        # installed v1.34.11, pin v1.36.5: kept; the drop-in is written from v1.31 (a later upgrade to
+        # v1.35 would otherwise stop the kubelet), so it is there for 1.34
+        tn_inst_prepare server
+        [ "$INSTALL_K3S_VERSION" = v1.34.11+k3s1 ] || { echo "pin not kept: $INSTALL_K3S_VERSION"; exit 1; }
+        [ -s "$TN_K3S_CONFIG_DIR/config.yaml.d/99-teknoir-cgroupv1.yaml" ] || { echo "no drop-in for k3s 1.34 (flag is set from v1.31)"; exit 1; }
+        # installed v1.30.14: its kubelet does not know the flag (an unknown argument would stop it): no
+        # drop-in, and the installed release is kept (in a subshell: tn_inst_prepare exports the release)
+        (
+          K3S_BIN="$3"; TN_K3S_CONFIG_DIR="$TN_K3S_CONFIG_DIR/v130"; INSTALL_K3S_VERSION=v1.36.5+k3s1
+          export K3S_BIN TN_K3S_CONFIG_DIR INSTALL_K3S_VERSION
+          tn_inst_prepare server
+          [ "$INSTALL_K3S_VERSION" = v1.30.14+k3s1 ] || { echo "pin not kept for 1.30: $INSTALL_K3S_VERSION"; exit 1; }
+          [ ! -e "$TN_K3S_CONFIG_DIR/config.yaml.d/99-teknoir-cgroupv1.yaml" ] || { echo "drop-in for k3s 1.30"; exit 1; }
+        ) || exit 1
+        # upgrade over two minors is refused (in a subshell: tn_inst_fatal exits)
+        if ( INSTALL_K3S_VERSION=v1.36.5+k3s1 TN_K3S_UPGRADE=true tn_inst_plan ) >/dev/null 2>&1; then echo "two-minor upgrade allowed"; exit 1; fi
+        # one minor, cgroup v1: the drop-in appears, twice is the same
+        K3S_BIN="$2" INSTALL_K3S_VERSION=v1.35.9+k3s1 TN_K3S_UPGRADE=true tn_inst_prepare server
+        K3S_BIN="$2" INSTALL_K3S_VERSION=v1.35.9+k3s1 TN_K3S_UPGRADE=true tn_inst_prepare server
+        grep -q "fail-cgroupv1=false" "$TN_K3S_CONFIG_DIR/config.yaml.d/99-teknoir-cgroupv1.yaml" || { echo "no drop-in"; exit 1; }
+        # the device'"'"'s own fail-cgroupv1: in INSTALL_K3S_EXEC only -> the drop-in stays (a restart before the
+        # installer would read no flag); in a config.yaml.d file k3s reads -> ours goes; none -> written
+        D=config.yaml.d/99-teknoir-cgroupv1.yaml
+        (
+          TN_K3S_CONFIG_DIR="$TN_K3S_CONFIG_DIR/exec"; K3S_BIN="$2"; INSTALL_K3S_VERSION=v1.34.11+k3s1
+          export TN_K3S_CONFIG_DIR K3S_BIN INSTALL_K3S_VERSION
+          tn_inst_prepare server
+          INSTALL_K3S_EXEC="server --kubelet-arg=fail-cgroupv1=false" tn_inst_prepare server
+          [ -s "$TN_K3S_CONFIG_DIR/$D" ] || { echo "drop-in removed although the flag is only in INSTALL_K3S_EXEC"; exit 1; }
+          rm -f "$TN_K3S_CONFIG_DIR/$D"
+          INSTALL_K3S_EXEC="server --kubelet-arg=fail-cgroupv1=false" tn_inst_prepare server
+          [ -s "$TN_K3S_CONFIG_DIR/$D" ] || { echo "drop-in not written for a flag only in INSTALL_K3S_EXEC"; exit 1; }
+          printf "kubelet-arg+:\n  - fail-cgroupv1=false\n" > "$TN_K3S_CONFIG_DIR/config.yaml.d/10-user.yaml"
+          tn_inst_prepare server
+          [ ! -e "$TN_K3S_CONFIG_DIR/$D" ] || { echo "drop-in kept although config.yaml.d/10-user.yaml has the flag"; exit 1; }
+        ) || exit 1
+        # installed v1.30.14 upgraded to v1.31: no flag before the installer, written by tn_inst_finish
+        (
+          K3S_BIN="$3"; TN_K3S_CONFIG_DIR="$TN_K3S_CONFIG_DIR/up"; INSTALL_K3S_VERSION=v1.31.4+k3s1; TN_K3S_UPGRADE=true
+          export K3S_BIN TN_K3S_CONFIG_DIR INSTALL_K3S_VERSION TN_K3S_UPGRADE
+          tn_inst_prepare server
+          [ ! -e "$TN_K3S_CONFIG_DIR/$D" ] || { echo "flag written for an installed k3s 1.30 before the installer"; exit 1; }
+          tn_inst_finish
+          [ -s "$TN_K3S_CONFIG_DIR/$D" ] || { echo "flag not written by tn_inst_finish"; exit 1; }
+        ) || exit 1
+        # installed v1.30.14 upgraded to a channel (or to v1.36 with TN_K3S_FORCE): the installer starts a release
+        # that needs the flag on its first start, so INSTALL_K3S_EXEC carries it (once), the drop-in comes after
+        (
+          K3S_BIN="$3"; TN_K3S_CONFIG_DIR="$TN_K3S_CONFIG_DIR/ch"; TN_K3S_UPGRADE=true; INSTALL_K3S_EXEC="server --tls-san a"
+          export K3S_BIN TN_K3S_CONFIG_DIR TN_K3S_UPGRADE INSTALL_K3S_EXEC
+          unset INSTALL_K3S_VERSION; INSTALL_K3S_CHANNEL=stable; export INSTALL_K3S_CHANNEL
+          tn_inst_prepare server; tn_inst_prepare server
+          [ "$INSTALL_K3S_EXEC" = "server --tls-san a --kubelet-arg=fail-cgroupv1=false" ] || { echo "channel upgrade: INSTALL_K3S_EXEC=$INSTALL_K3S_EXEC"; exit 1; }
+          [ ! -e "$TN_K3S_CONFIG_DIR/$D" ] || { echo "channel upgrade: drop-in before the installer"; exit 1; }
+          tn_inst_finish
+          [ -s "$TN_K3S_CONFIG_DIR/$D" ] || { echo "channel upgrade: no drop-in after the installer"; exit 1; }
+        ) || exit 1
+        (
+          K3S_BIN="$3"; TN_K3S_CONFIG_DIR="$TN_K3S_CONFIG_DIR/ex131"; TN_K3S_UPGRADE=true; INSTALL_K3S_EXEC=server; INSTALL_K3S_VERSION=v1.31.14+k3s1
+          export K3S_BIN TN_K3S_CONFIG_DIR TN_K3S_UPGRADE INSTALL_K3S_EXEC INSTALL_K3S_VERSION
+          tn_inst_prepare server
+          [ "$INSTALL_K3S_EXEC" = server ] || { echo "v1.31.14 got a flag on the command: $INSTALL_K3S_EXEC"; exit 1; }
+        ) || exit 1
+        # a comment and fail-cgroupv1=true are not the device setting it itself: the drop-in is written
+        (
+          TN_K3S_CONFIG_DIR="$TN_K3S_CONFIG_DIR/nocount"; K3S_BIN="$2"; INSTALL_K3S_VERSION=v1.34.11+k3s1
+          export TN_K3S_CONFIG_DIR K3S_BIN INSTALL_K3S_VERSION
+          mkdir -p "$TN_K3S_CONFIG_DIR/config.yaml.d"
+          printf "kubelet-arg+:\n  # - fail-cgroupv1=false\n  - fail-cgroupv1=true\n" > "$TN_K3S_CONFIG_DIR/config.yaml.d/10-user.yaml"
+          printf "# fail-cgroupv1=false\n" > "$TN_K3S_CONFIG_DIR/config.yaml"
+          tn_inst_prepare server
+          [ -s "$TN_K3S_CONFIG_DIR/$D" ] || { echo "drop-in missing: a comment or =true counted as the device setting"; exit 1; }
+          printf "kubelet-arg+: [\"fail-cgroupv1=false\"]\n" > "$TN_K3S_CONFIG_DIR/config.yaml.d/20-user.yml"
+          tn_inst_prepare server
+          [ ! -e "$TN_K3S_CONFIG_DIR/$D" ] || { echo "drop-in kept although a .yml has the flag"; exit 1; }
+        ) || exit 1
+        # config.yaml: keys are added once, the owner'"'"'s file is kept
+        printf "kubelet-arg: max-pods=77\nnode-name: mine" > "$TN_K3S_CONFIG_DIR/config.yaml"
+        tn_inst_config_ensure "$TN_K3S_CONFIG_DIR/config.yaml" node-name "node-name: x"
+        tn_inst_config_ensure "$TN_K3S_CONFIG_DIR/config.yaml" disable "disable:
+  - traefik"
+        tn_inst_config_ensure "$TN_K3S_CONFIG_DIR/config.yaml" disable "disable:
+  - traefik"
+        [ "$(cat "$TN_K3S_CONFIG_DIR/config.yaml")" = "kubelet-arg: max-pods=77
+node-name: mine
+disable:
+  - traefik" ] || { echo "config.yaml:"; cat "$TN_K3S_CONFIG_DIR/config.yaml"; exit 1; }
+      ' sh "$IL" "$w/k3s" "$w/k3s130" 2>&1 ); then
+    echo "RESULT install-lib FAIL $(echo "$out" | tail -3 | tr '\n' ' ' | cut -c1-300)"; rm -rf "$w"; return
+  fi
+  echo "RESULT install-lib PASS versions, keep/refuse, cgroup v1 drop-in (from v1.31, flag on the installer command), config.yaml"
+  rm -rf "$w"
+}
+install_lib_check
diff --git a/test/k3s-ca/legacy-ca.sh b/test/k3s-ca/legacy-ca.sh
index 1f05b39..3677e44 100644
--- a/test/k3s-ca/legacy-ca.sh
+++ b/test/k3s-ca/legacy-ca.sh
@@ -19,8 +19,9 @@
 # Environment: PRODUCT (default k3s). OPENSSL is detected as in the template.
 # Needs info() and fatal(); fallbacks are defined below.
 
-command -v info >/dev/null 2>&1 || info() { echo '[INFO] ' "$@"; }
-command -v fatal >/dev/null 2>&1 || fatal() { echo '[ERROR] ' "$@" >&2; exit 1; }
+# (`command -v info` would find the GNU info reader on Debian/Ubuntu: ask for a function)
+case $(type info 2>/dev/null) in *function*) ;; *) info() { echo '[INFO] ' "$@"; } ;; esac
+case $(type fatal 2>/dev/null) in *function*) ;; *) fatal() { echo '[ERROR] ' "$@" >&2; exit 1; } ;; esac
 
 tn_legacy_ca() {
   _tn_tls=$1 _tn_cert=$2 _tn_key=$3 _tn_suffix=${4:-device-0.test.local}
diff --git a/test/k3s-ca/lib/cases.sh b/test/k3s-ca/lib/cases.sh
index 435e941..a127b9c 100644
--- a/test/k3s-ca/lib/cases.sh
+++ b/test/k3s-ca/lib/cases.sh
@@ -9,6 +9,7 @@ FAIL_AFTER=${FAIL_AFTER:-45}  # 'CA cert validation failed' repeating this long
 HELPER_IMAGE=${HELPER_IMAGE:-debian:bookworm}
 DATA_CT=/var/lib/rancher/k3s   # data dir path inside helper and k3s containers (S9 uses the host path)
 CA_LIB=${TN_K3S_CA_LIB:-}
+INSTALL_LIB=${TN_K3S_INSTALL_LIB:-}
 
 rand_hex() { head -c "${1:-16}" /dev/urandom | od -An -tx1 | tr -d ' \n'; }
 
@@ -23,6 +24,7 @@ short_name() {
 h_mounts() { # WORK GEN
   HM=(-v "$1/k3s:$DATA_CT" -v "$(gen_dir "$2"):/etc/teknoir:ro" -v "$HERE:/h:ro" -v "$OUT/bin:/tnbin:ro")
   if [ -n "$CA_LIB" ]; then HM+=(-v "$CA_LIB:/tn/tn-k3s-ca.sh:ro"); fi
+  if [ -n "$INSTALL_LIB" ]; then HM+=(-v "$INSTALL_LIB:/tn/tn-k3s-install.sh:ro"); fi
   return 0
 }
 
diff --git a/test/k3s-ca/lib/docker.sh b/test/k3s-ca/lib/docker.sh
index 61e1354..5e78baa 100644
--- a/test/k3s-ca/lib/docker.sh
+++ b/test/k3s-ca/lib/docker.sh
@@ -77,6 +77,22 @@ DOCKERFILE
   printf '%s' "$tag"
 }
 
+# helper_curl_image: helper_image debian:bookworm plus curl (the install library asks the server of an
+# agent for its release with curl). Cached like the other helper images.
+helper_curl_image() {
+  local base tag=tn-k3sca-helper:debian-bookworm-curl
+  base=$(helper_image debian:bookworm)
+  if ! docker image inspect "$tag" >/dev/null 2>&1; then
+    log "building helper image $tag" >&2
+    docker build -q --label tn-k3sca-cache=1 -t "$tag" - >&2 <<DOCKERFILE || die "cannot build $tag"
+FROM $base
+ENV DEBIAN_FRONTEND=noninteractive
+RUN apt-get update >/dev/null 2>&1; apt-get install -y --no-install-recommends curl && rm -rf /var/lib/apt/lists/*
+DOCKERFILE
+  fi
+  printf '%s' "$tag"
+}
+
 # d_helper IMAGE [docker run args...] -- COMMAND...: run a short-lived labelled container as root.
 d_helper() {
   local image=$1; shift
diff --git a/test/k3s-ca/lib/suites.sh b/test/k3s-ca/lib/suites.sh
index 8d4f19a..28ceb05 100644
--- a/test/k3s-ca/lib/suites.sh
+++ b/test/k3s-ca/lib/suites.sh
@@ -382,7 +382,7 @@ run_compat() { # SPEC (platform/image or image)
   tag=$(helper_image "$image" "$platform") || { result_write openssl-compat "$name" - - lib PASS ERROR 0 "cannot build helper image"; return 0; }
   out="$OUT/logs/$name.out"
   docker run --rm --label "$LABEL" --name "$PREFIX-$name" ${platform:+--platform "$platform"} \
-    -v "$OUT/gen:/gens:ro" -v "$HERE/compat:/c:ro" -v "$HERE:/h:ro" -v "$(compat_bin_dir "$platform"):/tnbin:ro" -v "$CA_LIB:/tn/tn-k3s-ca.sh:ro" \
+    -v "$OUT/gen:/gens:ro" -v "$HERE/compat:/c:ro" -v "$HERE:/h:ro" -v "$(compat_bin_dir "$platform"):/tnbin:ro" -v "$CA_LIB:/tn/tn-k3s-ca.sh:ro" ${INSTALL_LIB:+-v "$INSTALL_LIB:/tn/tn-k3s-install.sh:ro"} \
     -e "GENS=$COMPAT_GENS" "$tag" sh /c/assert.sh > "$out" 2>&1 || true
   local seen=""
   while IFS= read -r line; do
@@ -409,3 +409,228 @@ suite_openssl_compat() {
     pool_run "$(compat_name "$spec")" run_compat "$spec"
   done
 }
+
+# ------------------------------------------------------------ install: release policy and cgroup v1 flag
+# The library tn-k3s-install.sh ($TN_K3S_INSTALL_LIB) against real k3s.
+
+need_install_lib() { # SUITE
+  if [ -z "$INSTALL_LIB" ] || [ ! -f "$INSTALL_LIB" ]; then
+    log "suite $1 needs the install library: set TN_K3S_INSTALL_LIB=/path/to/tn-k3s-install.sh (skipped)"
+    result_write "$1" "$1:needs-install-lib" - - lib READY SKIP 0 "TN_K3S_INSTALL_LIB not set"
+    return 1
+  fi
+  return 0
+}
+
+# S11 cgroup: the kubelet flag of a cgroup v1 host, on a real k3s. The helper container runs
+# tn_inst_prepare with TN_K3S_CGROUPV1=true (this host is cgroup v2, so the detection is overridden)
+# against an /etc/rancher/k3s that already has a user kubelet-arg; then k3s starts from that
+# directory. k3s >= v1.35 must get fail-cgroupv1=false and keep the user's argument; older k3s gets nothing.
+scenario_install_cgroup() { # SCEN TAG
+  local scen=$1 tag t0 ver args want
+  tag=$(ver_tag "$2")
+  case_init "$scen"; t0=$(now)
+  ver=${tag/-k3s/+k3s}
+  d_pull "$K3S_IMAGE:$tag" || true
+  mkdir -p "$WORK/etc-rancher/k3s"
+  printf 'kubelet-arg: max-pods=77\n' > "$WORK/etc-rancher/k3s/config.yaml"
+  h_mounts "$WORK" "$(gens_for bs-o111 | cut -d' ' -f1)"
+  d_helper "$(helper_image debian:bookworm)" "${HM[@]}" -v "$WORK/etc-rancher:/etc/rancher" \
+    -e "INSTALL_K3S_VERSION=$ver" -e TN_K3S_CGROUPV1=true -- \
+    sh -c ". /h/shim.sh; . /tn/tn-k3s-install.sh; tn_inst_prepare server; tn_inst_prepare server" >"$OUT/logs/$CASE.prepare.log" 2>&1 ||
+    { step "$scen" 1-prepare "$tag" - lib READY ERROR $(( $(now) - t0 )) "tn_inst_prepare failed (see log)"; case_end; return 0; }
+  # the flag goes in from v1.31 (the kubelet knows it from then on); only >= v1.35 needs it
+  if [ "$(ver_minor "$tag")" -ge 31 ]; then want=yes; else want=no; fi
+  # (root-owned, mode 750: look from inside a container)
+  local dropin=/etc/rancher/k3s/config.yaml.d/99-teknoir-cgroupv1.yaml have=no
+  if d_helper "$(helper_image debian:bookworm)" -v "$WORK/etc-rancher:/etc/rancher" -- test -s "$dropin"; then have=yes; fi
+  if [ "$want" = yes ] && [ "$have" = no ]; then
+    step "$scen" 1-prepare "$tag" - lib READY ERROR $(( $(now) - t0 )) "no drop-in written for k3s $tag"; case_end; return 0
+  fi
+  if [ "$want" = no ] && [ "$have" = yes ]; then
+    step "$scen" 1-prepare "$tag" - lib READY ERROR $(( $(now) - t0 )) "a drop-in was written for k3s $tag (< v1.31)"; case_end; return 0
+  fi
+  srv_up "$tag"; wait_k3s server "$SRV" "$T_SERVER" "$SINCE"
+  if [ "$W_STATE" != READY ]; then step "$scen" 2-k3s-starts "$tag" - lib READY "$W_STATE" $(( $(now) - t0 )) "$W_NOTE"; save_logs "$SRV" server; case_end; return 0; fi
+  args=$(kc "$SRV" get nodes -o 'jsonpath={.items[0].metadata.annotations.k3s\.io/node-args}' 2>/dev/null)
+  if ! printf '%s' "$args" | grep -q 'max-pods=77'; then
+    step "$scen" 2-k3s-starts "$tag" - lib READY ERROR $(( $(now) - t0 )) "the user's kubelet-arg max-pods=77 was lost: $args"
+  elif [ "$want" = yes ] && ! printf '%s' "$args" | grep -q 'fail-cgroupv1=false'; then
+    step "$scen" 2-k3s-starts "$tag" - lib READY ERROR $(( $(now) - t0 )) "fail-cgroupv1=false is not in the k3s arguments: $args"
+  elif [ "$want" = no ] && printf '%s' "$args" | grep -q 'fail-cgroupv1'; then
+    step "$scen" 2-k3s-starts "$tag" - lib READY ERROR $(( $(now) - t0 )) "fail-cgroupv1 was passed to k3s $tag: $args"
+  else
+    step "$scen" 2-k3s-starts "$tag" - lib READY READY $(( $(now) - t0 )) "kubelet-arg max-pods=77 kept$([ "$want" = yes ] && echo ', fail-cgroupv1=false passed')"
+  fi
+  save_logs "$SRV" server
+  case_end
+}
+
+# S12 policy: the version of the installed k3s is read from the real `k3s --version` output
+# (K3S_BIN='docker run --rm rancher/k3s:<tag>'), and the policy decides on it.
+scenario_install_policy() { # SCEN TAG
+  local scen=$1 tag t0 ver out other
+  tag=$(ver_tag "$2")
+  case_init "$scen"; t0=$(now)
+  ver=${tag/-k3s/+k3s}
+  d_pull "$K3S_IMAGE:$tag" || true
+  mkdir -p "$WORK/cfg"
+  # run_policy PIN [ENV...]: prints the output and a last line RC=<exit code> (it runs in a command substitution)
+  run_policy() {
+    local pin=$1 rc=0; shift
+    env "K3S_BIN=docker run --rm $K3S_IMAGE:$tag" "INSTALL_K3S_VERSION=$pin" "TN_K3S_CONFIG_DIR=$WORK/cfg" TN_CGROUP_FSTYPE=cgroup2fs "$@" \
+      sh -c '. "$1"; . "$2"; tn_inst_plan; echo "RESULT version=$INSTALL_K3S_VERSION action=$TN_INST_ACTION"' sh "$HERE/shim.sh" "$INSTALL_LIB" 2>&1 || rc=$?
+    echo "RC=$rc"
+  }
+  P_RC=0
+  # 1. the installed release is recognised: asking for the same one is "same"
+  out=$(run_policy "$ver"); P_RC=$(printf '%s' "$out" | sed -n 's/^RC=//p')
+  if [ "$P_RC" = 0 ] && printf '%s' "$out" | grep -q "RESULT version=$ver action=same"; then
+    step "$scen" 1-recognised "$tag" - lib READY READY $(( $(now) - t0 )) "installed $ver read from k3s --version"
+  else
+    step "$scen" 1-recognised "$tag" - lib READY ERROR $(( $(now) - t0 )) "rc=$P_RC: $(printf '%s' "$out" | tail -2 | tr '\n' ' ' | cut -c1-200)"
+  fi
+  # 2. another pin is ignored: the installed release is kept
+  t0=$(now); other=v1.99.0+k3s1
+  out=$(run_policy "$other"); P_RC=$(printf '%s' "$out" | sed -n 's/^RC=//p')
+  if [ "$P_RC" = 0 ] && printf '%s' "$out" | grep -q "RESULT version=$ver action=keep"; then
+    step "$scen" 2-keeps "$tag" - lib READY READY $(( $(now) - t0 )) "pin $other ignored, $ver kept"
+  else
+    step "$scen" 2-keeps "$tag" - lib READY ERROR $(( $(now) - t0 )) "rc=$P_RC: $(printf '%s' "$out" | tail -2 | tr '\n' ' ' | cut -c1-200)"
+  fi
+  # 3. an upgrade over several minors, and any downgrade, are refused
+  t0=$(now)
+  out=$(run_policy "v1.99.0+k3s1" TN_K3S_UPGRADE=true); P_RC=$(printf '%s' "$out" | sed -n 's/^RC=//p')
+  if [ "$P_RC" = 1 ] && printf '%s' "$out" | grep -q 'more than one minor version'; then
+    step "$scen" 3-refuses-jump "$tag" - lib READY READY $(( $(now) - t0 )) "upgrade to $other refused"
+  else
+    step "$scen" 3-refuses-jump "$tag" - lib READY ERROR $(( $(now) - t0 )) "rc=$P_RC: $(printf '%s' "$out" | tail -2 | tr '\n' ' ' | cut -c1-200)"
+  fi
+  t0=$(now)
+  out=$(run_policy "v1.20.0+k3s1" TN_K3S_UPGRADE=true TN_K3S_FORCE=true); P_RC=$(printf '%s' "$out" | sed -n 's/^RC=//p')
+  if [ "$P_RC" = 1 ] && printf '%s' "$out" | grep -q 'refusing to downgrade'; then
+    step "$scen" 4-refuses-downgrade "$tag" - lib READY READY $(( $(now) - t0 )) "downgrade refused even with TN_K3S_FORCE=true"
+  else
+    step "$scen" 4-refuses-downgrade "$tag" - lib READY ERROR $(( $(now) - t0 )) "rc=$P_RC: $(printf '%s' "$out" | tail -2 | tr '\n' ' ' | cut -c1-200)"
+  fi
+  case_end
+}
+
+# S13 follow: an agent installs the k3s release of its SERVER, not the pin of the script. k3s does not
+# answer /version anonymously (401, on every release), so the server script publishes the release it
+# runs as server/static/teknoir/k3s-version, which k3s serves without authentication. Here: the server
+# side runs tn_inst_publish_release with the REAL k3s binary (the rancher/k3s image) on the data dir
+# before the server starts (like an OS build) and again when it is up; a helper container on the same
+# network runs tn_inst_prepare agent with K3S_URL=https://<server>:6443 and a default pin that is NOT the
+# server's release: it must read the real server and settle on the server's release. Then a real k3s agent
+# of exactly that release joins and must be Ready. A pin that was asked for and is newer than the server
+# is refused; a server that publishes nothing is refused; an unreachable server is refused.
+scenario_install_follow() { # SCEN TAG
+  local scen=$1 tag t0 ver pin rc out agent_tag
+  tag=$(ver_tag "$2")
+  case_init "$scen"; t0=$(now)
+  ver=${tag/-k3s/+k3s}
+  # a default pin that differs from the server: the other one of v1.34.11 / v1.36.5
+  if [ "$ver" = v1.36.5+k3s1 ]; then pin=v1.34.11+k3s1; else pin=v1.36.5+k3s1; fi
+  d_pull "$K3S_IMAGE:$tag" || true
+  ca_prepare lib "$(gens_for bs-o111 | cut -d' ' -f1)" "$HELPER_IMAGE" "$WORK" "dev.test.local" ||
+    { step "$scen" 1-server-ready "$tag" - lib READY ERROR 0 "CA preparation failed"; case_end; return 0; }
+  # the server script publishes the release it runs, with the real k3s binary of the image, before k3s starts
+  publish_release() { # -> output of tn_inst_publish_release
+    h_mounts "$WORK" "$(gens_for bs-o111 | cut -d' ' -f1)"
+    d_helper "$K3S_IMAGE:$tag" --entrypoint sh "${HM[@]}" -e "DATA_DIR=$DATA_CT" -- \
+      -c '. /h/shim.sh; . /tn/tn-k3s-install.sh; tn_inst_publish_release' 2>&1
+  }
+  out=$(publish_release) || true
+  echo "$out" > "$OUT/logs/$CASE.publish.log"
+  srv_up "$tag"; wait_k3s server "$SRV" "$T_SERVER" "$SINCE"
+  step "$scen" 1-server-ready "$tag" - lib READY "$W_STATE" $(( $(now) - t0 )) "$W_NOTE"
+  [ "$W_STATE" = READY ] || { save_logs "$SRV" server; case_end; return 0; }
+  # k3s starting on a data dir that has the file must not remove it, and serves it without authentication
+  t0=$(now)
+  out=$(publish_release) || true
+  if printf '%s' "$out" | grep -q "already published"; then
+    step "$scen" 1b-published "$tag" - lib READY READY $(( $(now) - t0 )) "file survived the first start of k3s; a second publish changes nothing"
+  else
+    step "$scen" 1b-published "$tag" - lib READY ERROR $(( $(now) - t0 )) "$(printf '%s' "$out" | tail -2 | tr '\n' ' ' | cut -c1-200)"
+  fi
+
+  # run_follow PIN SOURCE URL [ENV...]: prints the output and a last line RC=<exit code>
+  run_follow() {
+    local pin=$1 source=$2 url=$3 rc=0; shift 3
+    h_mounts "$WORK" "$(gens_for bs-o111 | cut -d' ' -f1)"
+    d_helper "$(helper_curl_image)" --network "$NET" "${HM[@]}" \
+      -e "K3S_URL=$url" -e "INSTALL_K3S_VERSION=$pin" -e "TN_K3S_PIN_SOURCE=$source" -e TN_CGROUP_FSTYPE=cgroup2fs \
+      -e TN_K3S_CONFIG_DIR=/tmp/k3s-cfg -e TN_K3S_SERVER_VERSION_WAIT=1 -e K3S_BIN=/nonexistent/k3s -e DATA_DIR=/tmp/no-k3s "$@" -- \
+      sh -c '. /h/shim.sh; . /tn/tn-k3s-install.sh; tn_inst_prepare agent; echo "RESULT version=$INSTALL_K3S_VERSION"' 2>&1 || rc=$?
+    echo "RC=$rc"
+  }
+
+  # 2. the default pin is not the server's release: the agent gets the server's
+  t0=$(now)
+  out=$(run_follow "$pin" default "https://$SRV_HOST:6443")
+  echo "$out" > "$OUT/logs/$CASE.follow.log"
+  rc=$(printf '%s' "$out" | sed -n 's/^RC=//p')
+  if [ "$rc" = 0 ] && printf '%s' "$out" | grep -q "RESULT version=$ver\$"; then
+    step "$scen" 2-agent-follows "$tag" - lib READY READY $(( $(now) - t0 )) "default pin $pin ignored, the real server published $ver"
+  else
+    step "$scen" 2-agent-follows "$tag" - lib READY ERROR $(( $(now) - t0 )) "rc=$rc: $(printf '%s' "$out" | tail -3 | tr '\n' ' ' | cut -c1-240)"
+    save_logs "$SRV" server; case_end; return 0
+  fi
+
+  # 3. a real agent of exactly that release joins
+  t0=$(now); agent_tag=${ver/+k3s/-k3s}
+  agt_up "$agent_tag"
+  wait_k3s agent "$AGT" "$T_AGENT" "$ASINCE" "$SRV" "$AGT_HOST"
+  step "$scen" 3-agent-joins "$agent_tag" - lib READY "$([ "$W_STATE" = READY ] && echo READY || echo "AGENT-$W_STATE")" $(( $(now) - t0 )) "agent $agent_tag, server $tag $W_NOTE"
+  save_logs "$AGT" agent
+
+  # 4. a release that was asked for and is newer than the server is refused
+  t0=$(now)
+  out=$(run_follow v1.99.0+k3s1 flag "https://$SRV_HOST:6443")
+  rc=$(printf '%s' "$out" | sed -n 's/^RC=//p')
+  if [ "$rc" = 1 ] && printf '%s' "$out" | grep -q "refusing to install k3s v1.99.0+k3s1 on this agent" && ! printf '%s' "$out" | grep -q '^RESULT'; then
+    step "$scen" 4-refuses-newer "$tag" - lib READY READY $(( $(now) - t0 )) "v1.99.0 refused, the server runs $ver"
+  else
+    step "$scen" 4-refuses-newer "$tag" - lib READY ERROR $(( $(now) - t0 )) "rc=$rc: $(printf '%s' "$out" | tail -3 | tr '\n' ' ' | cut -c1-240)"
+  fi
+
+  # 4b. a server that publishes nothing gives an agent nothing to follow (k3s answers /version with 401 to
+  # an anonymous caller): refused, and the message says why. The file is removed for this step.
+  t0=$(now)
+  h_mounts "$WORK" "$(gens_for bs-o111 | cut -d' ' -f1)"
+  d_helper "$(helper_image debian:bookworm)" "${HM[@]}" -- rm -f "$DATA_CT/server/static/teknoir/k3s-version"
+  out=$(run_follow "$pin" default "https://$SRV_HOST:6443")
+  rc=$(printf '%s' "$out" | sed -n 's/^RC=//p')
+  if [ "$rc" = 1 ] && printf '%s' "$out" | grep -q "does not publish its release" && ! printf '%s' "$out" | grep -q '^RESULT'; then
+    step "$scen" 4b-refuses-unpublished "$tag" - lib READY READY $(( $(now) - t0 )) "nothing published, /version is 401: refused"
+  else
+    step "$scen" 4b-refuses-unpublished "$tag" - lib READY ERROR $(( $(now) - t0 )) "rc=$rc: $(printf '%s' "$out" | tail -3 | tr '\n' ' ' | cut -c1-240)"
+  fi
+
+  # 5. an unreachable server is refused (the script does not guess), unless the release was asked for
+  t0=$(now)
+  out=$(run_follow "$pin" default "https://no-such-server.invalid:6443" -e TN_K3S_SERVER_VERSION_TRIES=1)
+  rc=$(printf '%s' "$out" | sed -n 's/^RC=//p')
+  if [ "$rc" = 1 ] && printf '%s' "$out" | grep -q "cannot read the k3s release of the server" && ! printf '%s' "$out" | grep -q '^RESULT'; then
+    step "$scen" 5-refuses-unreachable "$tag" - lib READY READY $(( $(now) - t0 )) "no answer from the server: refused"
+  else
+    step "$scen" 5-refuses-unreachable "$tag" - lib READY ERROR $(( $(now) - t0 )) "rc=$rc: $(printf '%s' "$out" | tail -3 | tr '\n' ' ' | cut -c1-240)"
+  fi
+  save_logs "$SRV" server
+  case_end
+}
+
+suite_install() {
+  SUITE=install
+  need_install_lib install || return 0
+  local v
+  for v in $(versions_for "v1.30.14 v1.31.14 v1.34.11 v1.36.5"); do
+    pool_run "inst-cgroup-$(ver_slug "$v")" scenario_install_cgroup "inst-cgroup-$(ver_slug "$v")" "$v"
+    pool_run "inst-policy-$(ver_slug "$v")" scenario_install_policy "inst-policy-$(ver_slug "$v")" "$v"
+  done
+  # the agent follows its server: a pre-fix and a post-fix release, each with a default pin of the other kind
+  for v in $(versions_for "v1.34.11 v1.36.5"); do
+    pool_run "inst-follow-$(ver_slug "$v")" scenario_install_follow "inst-follow-$(ver_slug "$v")" "$v"
+  done
+}
diff --git a/test/k3s-ca/run.sh b/test/k3s-ca/run.sh
index 6056b26..b6b88cf 100755
--- a/test/k3s-ca/run.sh
+++ b/test/k3s-ca/run.sh
@@ -14,7 +14,7 @@ usage() {
   cat <<'USAGE'
 usage: run.sh [options]
 
-  --suite S[,S...]        control | fresh | legacy-with-cert | agent | remediation | rerun | host | openssl-compat | all
+  --suite S[,S...]        control | fresh | legacy-with-cert | agent | remediation | rerun | host | install | openssl-compat | all
                           (default: control)
   --versions "V ..."      k3s versions (v1.34.11, 1.36.5, v1.36.5+k3s1, stable, latest, v1.33 = newest of a channel);
                           space or comma separated; default depends on the suite
@@ -36,7 +36,7 @@ usage: run.sh [options]
   --list                  print the cases and exit
   -h, --help
 
-Hooks (environment): TN_K3S_CA_LIB, TN_REMEDIATE_PREPARE, TN_REMEDIATE_FINALIZE, TN_REMEDIATE_CHECK (see README).
+Hooks (environment): TN_K3S_CA_LIB, TN_K3S_INSTALL_LIB, TN_REMEDIATE_PREPARE, TN_REMEDIATE_FINALIZE, TN_REMEDIATE_CHECK (see README).
 USAGE
 }
 
@@ -75,7 +75,7 @@ done
 . "$HERE/lib/cases.sh"
 . "$HERE/lib/suites.sh"
 
-[ "$SUITES" = all ] && SUITES="control fresh legacy-with-cert agent remediation rerun host openssl-compat"
+[ "$SUITES" = all ] && SUITES="control fresh legacy-with-cert agent remediation rerun host install openssl-compat"
 case $EXPECT_OVERRIDE in ""|READY|FAIL) ;; *) die "--expect must be READY or FAIL" ;; esac
 export EXPECT_OVERRIDE
 if [ -n "$DEVICE_CERT$DEVICE_KEY" ]; then
@@ -148,6 +148,7 @@ needed_gens() {
       agent) g=$(gens_for "bs-o111 go-sha1") ;;
       remediation) g=$(gens_for "bs-o111 go-sha1 expired") ;;
       openssl-compat) g=$(gens_for "$GEN_LEGACY $GEN_FIXED") ;;
+      install) g=$(gens_for "bs-o111") ;;
       *) die "unknown suite '$s'" ;;
     esac
     list="$list $g"
@@ -193,6 +194,7 @@ for s in $SUITES; do
     remediation) suite_remediation ;;
     rerun) suite_rerun ;;
     host) suite_host ;;
+    install) suite_install ;;
     openssl-compat) suite_openssl_compat ;;
   esac
 done