Guides on tsvinc

Enable Wake-on-LAN on Fedora with a Realtek r8169 NIC

Mon, 02 Nov 2026 00:00:00 +0000

This sets magic-packet Wake-on-LAN on the wired NetworkManager connection of a Fedora-family host with a Realtek r8169 NIC, so the NIC stays awake after shutdown and the host powers on when a MikroTik router sends /tool/wol.

Tested on: four Fedora-family hosts with Realtek r8169 NICs (the workstation and a mini PC on Fedora, the gaming PC on Bazzite, the storage box on Fedora), set with the script below; wake from power-off tested on two of them with a MikroTik router's /tool/wol. The setting was re-checked on the workstation on 2026-11-02 (Fedora 44 NetworkManager 1.56.1, ethtool 7.1, kernel 7.2.13).
Not verified: OS, NetworkManager, ethtool and RouterOS versions of the first run [UNVERIFIED: not recorded]; a wake test on the other two hosts; the rollback.
Needs: root on the host; Wake-on-LAN enabled in the BIOS/UEFI setup (check it there; I know of no way to read it from Linux); a wired link to the same LAN segment as the router; a RouterOS login that may run /tool/wol.
Time: 5 min per host, plus one power-off test.
Risk: the test powers the host off. After the change, anyone on the LAN segment who knows the NIC's MAC can power the host on: these NICs report Supports Wake-on: pumbg, with no s, so they cannot check a SecureOn password, and RouterOS's /tool/wol cannot send one either. Reversible: see Undo.

Before you start#

Placeholders used below:
- <IF>: the wired interface name (mine: enp1s0).
- <CONN>: the NetworkManager connection on that interface (mine: Wired connection 1).
- <MAC>: the MAC address of <IF>.
- <BRIDGE>: the router interface that faces the host's LAN segment (mine: bridge).
Check that the wired NIC uses r8169:
```
$ readlink -f /sys/class/net/enp1s0/device/driver
/sys/bus/pci/drivers/r8169
```
Expected: a path ending in r8169. The steps set generic NetworkManager and ethtool options, but r8169 is the only driver I ran them on.

Find the active wired connection and its device:

$ nmcli -t -f NAME,DEVICE,TYPE c show --active | grep 802-3-ethernet
Wired connection 1:enp1s0:802-3-ethernet

Record the current values; Undo sets them back. In a root shell, run nmcli -g 802-3-ethernet.wake-on-lan c show '<CONN>' and ethtool <IF> | grep Wake-on. On all four of my hosts the first printed default, and ethtool showed Supports Wake-on: pumbg and Wake-on: d, with Wake-on-LAN already on in the BIOS. d means the NIC wakes on nothing; ethtool(8) lists the letters, and g is the magic packet.
Note the MAC for the router step: cat /sys/class/net/<IF>/address.

Steps#

Save the script as enable-wol.sh. It walks every active wired connection, sets 802-3-ethernet.wake-on-lan magic in NetworkManager (stored in the connection, applied on every activation) and wol g with ethtool (applied now, no reconnect), then prints both values back.

#!/bin/bash
# Enable Wake-on-LAN (magic packet) on the wired NetworkManager connection. Run as root.
# Persistent: NM applies it on every activation. Immediate: ethtool, no reconnect.
set -euo pipefail
E=$(command -v ethtool || echo /usr/sbin/ethtool)
nmcli -t -f NAME,DEVICE,TYPE c show --active | while IFS=: read -r n dev t; do
  [ "$t" = 802-3-ethernet ] || continue
  nmcli c modify "$n" 802-3-ethernet.wake-on-lan magic
  "$E" -s "$dev" wol g
  echo "$(hostname) $dev '$n': nm=$(nmcli -g 802-3-ethernet.wake-on-lan c show "$n") $("$E" "$dev" | grep -E '^\s*Wake-on:' | xargs)"
done

Run it as root.
```
sudo bash ./enable-wol.sh
```
Expected: one line per wired connection, in the form <hostname> <IF> '<CONN>': nm=<VALUE> Wake-on: <LETTERS>, ending in nm=magic Wake-on: g. All four hosts printed that ending. I did not keep the full lines, so none is shown here. The script runs with set -euo pipefail: if a command fails, it stops there with a non-zero exit, without a line for that connection.
Power the host off.
```
sudo systemctl poweroff
```
Expected: the host shuts down. Leave its power cable in: Wake-on-LAN needs standby power at the NIC.
Send the magic packet from the router.
```
/tool/wol mac=<MAC> interface=<BRIDGE>
```
Expected: the host powers on and boots. In my test I powered two hosts off at 22:45:53, sent the packet at 22:46:21, and they booted at 22:46:40 and 22:46:45, 19 s and 24 s after the packet. If it stays off: see Failure modes, row 1.

Verify#

After the wake, in a root shell on the host, run ethtool <IF> | grep Wake-on. Expected: Wake-on: g. On my woken hosts Wake-on: g was still set after boot. NetworkManager applies magic on every activation of the connection; the ethtool call in the script only sets it right away, without a reconnect.
The NetworkManager value can be read without root. On the workstation on 2026-11-02:
```
$ nmcli -g 802-3-ethernet.wake-on-lan c show "Wired connection 1"
magic
```
Expected: magic.

Undo / rollback#

In a root shell, set back the values you recorded in Before you start (mine: default and d). The script changed every active wired connection: repeat this for each <CONN> and <IF> it printed.
```
nmcli c modify '<CONN>' 802-3-ethernet.wake-on-lan default
ethtool -s <IF> wol d
```
[UNVERIFIED: rollback not exercised]

Failure modes#

Symptom (exact message)	Cause	Fix
The host does not wake from power-off although the BIOS has Wake-on-LAN on; root `ethtool <IF>` shows `Wake-on: d`	the connection had `802-3-ethernet.wake-on-lan default`, and the NIC was powered down at shutdown	steps 1-2: set `magic` on the connection
`netlink error: Operation not permitted`, and no `Wake-on` lines in the output	ethtool run as a normal user: reading Wake-on needs root	run `ethtool <IF>` from a root shell

Field notes#

2026-11-02, the workstation, Fedora 44 (KDE Plasma Desktop Edition), kernel 7.2.13-200.fc44, NetworkManager 1.56.1, ethtool 7.1, r8169 on enp1s0: re-checked as a normal user. NetworkManager still had magic on the wired connection. ethtool printed netlink error: Operation not permitted and the rest of the link settings, with no Wake-on lines at all, so a user-level ethtool cannot show the NIC's Wake-on state. I did not re-read Wake-on as root this time.
2026-10-20 [UNVERIFIED: date from my project notes, not from the run's output], four hosts (the workstation and a mini PC on Fedora, the gaming PC on Bazzite, the storage box on Fedora), all Realtek r8169, versions not recorded: Wake-on-LAN was on in the BIOS of every host, and none of them stayed wakeable: ethtool showed Supports Wake-on: pumbg with Wake-on: d, and the wired NetworkManager connection had 802-3-ethernet.wake-on-lan default, so the NIC powered down at shutdown. I ran enable-wol.sh on all four; each printed nm=magic Wake-on: g. Then (same day or later, the test's date was not recorded) I powered two of them off at 22:45:53, sent /tool/wol mac=<MAC> interface=bridge from the MikroTik router at 22:46:21, and they booted at 22:46:40 and 22:46:45. Wake-on: g was still set after boot.

Notes#

Why I needed it: the hosts run on power stations that keep their outlets live through an outage, so a host that upsmon shut down never sees power disappear and never comes back by itself (the observer design post). That design has the observer send Wake-on-LAN after an outage; here I sent the packet from the router by hand. When a station's output did drop on 2026-11-02, the storage box came back by itself, probably through the BIOS power-on-after-AC-loss setting, which I have not checked (three shutdowns, three causes). The upsmon side is in Run upsmon as a NUT secondary on Fedora and Fedora Atomic.
Only g: the NICs also support p, u, m and b (wake on PHY activity, unicast, multicast, broadcast); each of those can wake the host on ordinary traffic. I enabled the magic packet only.
default is not "off" by name: per the nmcli settings reference, default means "use global settings", and ignore stops NetworkManager from managing Wake-on-LAN at all. A global value in NetworkManager.conf (ethernet.wake-on-lan) is another way to set it for every connection; I have not tried it.
ethtool path: the script uses ethtool from PATH and falls back to /usr/sbin/ethtool.
Router without interface=: per the MikroTik docs, RouterOS then sends the packet as an IP broadcast from the default gateway interface. I always gave the interface.

Sources#

nmcli settings reference, 802-3-ethernet.wake-on-lan: the flag values magic, default (use global settings) and ignore.
NetworkManager.conf: ethernet.wake-on-lan as a global per-device default.
ethtool(8): the wol letters p u m b a g s f d.
MikroTik RouterOS: Wake on LAN: /tool wol with mac and interface; no SecureOn support.

Install Window Maker as a startx session on Gentoo

Mon, 02 Nov 2026 00:00:00 +0000

Install Window Maker 0.96.0 and four dockapps on Gentoo, seed the per-user defaults, autostart the dockapps in the Dock, and give startx a client script that runs wmaker. End state: the packages are installed, ~/GNUstep is seeded, and startx ~/.xinitrc-windowmaker is ready to run. I logged into it on 2026-11-02 (Field notes).

Tested on: ThinkPad Yoga 370 (20JH, i5-7300U), Gentoo amd64 23.0 desktop profile (default/linux/amd64/23.0/desktop), OpenRC, x86-64-v3 binhost; x11-wm/windowmaker-0.96.0-r1, x11-base/xorg-server-21.1.24, x11-apps/xinit-1.4.4 (2026-11-02).
Not verified: the minimal client script (step 8) and the rollback. Everything else was checked structurally (packages, files, sh -n, wdread, the tty menu branch with a stub startx) and then in a real login on 2026-11-02 (Field notes).
Needs: root (sudo) for emerge and /etc/portage; a working Xorg with startx (x11-apps/xinit); a tty login. Optional: OpenRC user services and a tty session menu, which is how my box starts sessions (steps 9 to 11); step 10's script also sources my ~/.config/x11/common, which this manual does not create.
Time: 15 min: my first run took 13 min, from writing package.use (00:19) to the autostart lines (00:32). With my USE flags Window Maker builds from source (3 min 13 s here) and wmsystemtray always does.
Risk: low and reversible. Only new files under /etc/portage and ~, plus six new packages. wmaker.inst --batch overwrites ~/GNUstep/Defaults/WindowMaker without asking if it already exists: back it up first.

Before you start#

You are on a 23.0 profile and have Xorg and startx:

$ eselect profile show
Current /etc/portage/make.profile symlink:
  default/linux/amd64/23.0/desktop
$ qlist -Iv x11-base/xorg-server
x11-base/xorg-server-21.1.24
$ qlist -Iv x11-apps/xinit
x11-apps/xinit-1.4.4

Expected: an amd64 profile; both packages installed. If qlist prints nothing, install Xorg first; this manual does not cover it.

Back up any existing Window Maker user config (step 5 overwrites it):
```
[ -d ~/GNUstep ] && cp -a ~/GNUstep ~/GNUstep.bak-$(date +%F)
```
No wmaker is running. Steps 5 and 6 edit files a running Window Maker reads:
```
$ pgrep -x wmaker; echo rc=$?
rc=1
```
Expected: rc=1 (no process).

Steps#

Set Window Maker's USE flags.
```
echo 'x11-wm/windowmaker png jpeg webp xinerama xpm nls xrandr' | sudo tee /etc/portage/package.use/windowmaker
```
```
$ cat /etc/portage/package.use/windowmaker
x11-wm/windowmaker png jpeg webp xinerama xpm nls xrandr
```
Expected: the one line. xinerama and xrandr are what keep the binhost package from being used (step 2). The binhost build of 0.96.0-r1 has gif jpeg nls png tiff webp xpm and neither of them. Without them, the binary package matches. xinerama adds Xinerama multi-monitor geometry queries (use.desc); xrandr enables XRandR extension support (metadata.xml).

Emerge Window Maker.

$ sudo emerge --ask x11-wm/windowmaker
…
[ebuild  N     ] x11-wm/windowmaker-0.96.0-r1  USE="gif jpeg nls png tiff webp xinerama xpm xrandr -imagemagick -modelock"

!!! The following binary packages have been ignored due to non matching USE:

    =x11-wm/windowmaker-0.96.0-r1 -xinerama -xrandr
…
>>> Completed (1 of 1) x11-wm/windowmaker-0.96.0-r1::gentoo

Expected: Completed (1 of 1). [ebuild means a source build, [binary a binhost package. The "ignored due to non matching USE" lines are a notice, not an error (Failure modes, row 3).

Accept the ~amd64 keyword for wmsystemtray. It is the only one of the four dockapps without a stable amd64 keyword (KEYWORDS="~amd64 ~ppc64 ~x86"). Write it without a version, so later releases are accepted too:
```
$ echo 'x11-plugins/wmsystemtray ~amd64' | sudo tee /etc/portage/package.accept_keywords/wmsystemtray
x11-plugins/wmsystemtray ~amd64
```
Expected: the line echoed back. If you skip this step, step 4 fails with Failure modes, row 2.

Emerge the dockapps from x11-plugins. The category is x11-plugins, not x11-misc (Failure modes, row 1).

$ sudo emerge --ask x11-plugins/wmclock x11-plugins/wmifs x11-plugins/wmmemload x11-plugins/wmsystemtray
…
[binary  N g   ] x11-libs/libdockapp-0.7.3-1  USE="X -static-libs"
[binary  N g   ] x11-plugins/wmclock-1.0.16-r1-2
[binary  N g   ] x11-plugins/wmmemload-0.1.8-r1-1
[ebuild  N    ~] x11-plugins/wmsystemtray-1.4-r3
[binary  N g   ] x11-plugins/wmifs-1.9-1
…
>>> Jobs: 5 of 5 complete                                               Load avg: 1.02, 1.19, 1.13

Expected: 5 of 5 complete. libdockapp comes in as a dependency. Only wmsystemtray builds from source.

Seed ~/GNUstep with wmaker.inst --batch. It needs no X display. This copies the stock WindowMaker defaults, generates WMRootMenu with wmgenmenu, and creates Library/WindowMaker/ with an executable autostart:
```
$ wmaker.inst --batch
Installing WindowMaker 0.96.0 for current user...
Creating ~/GNUstep user directory
Copying defaults database...
Creating icon library directory ~/GNUstep/Library/Icons
Creating WindowMaker data library directory ~/GNUstep/Library/WindowMaker
Creating style library ~/GNUstep/Library/WindowMaker/Styles
Creating theme library ~/GNUstep/Library/WindowMaker/Themes
Creating bg image library ~/GNUstep/Library/WindowMaker/Backgrounds
Creating icon setup library ~/GNUstep/Library/WindowMaker/IconSets
Creating pixmap library ~/GNUstep/Library/WindowMaker/Pixmaps
Installation Finished
$ ls ~/GNUstep/Defaults
WMRootMenu
WindowMaker
```
Expected: Installation Finished and the two files. (This transcript is from a re-run on the same box with a scratch HOME; the first seed's output was not saved. Paths shortened to ~.)

WarningRun wmaker.inst --batch once

Batch mode never prompts. On a second run it replaces Defaults/WindowMaker with the stock file and regenerates WMRootMenu, so every edit made in steps 6 onward is lost. autostart survives because it is copied only if absent. Proof: Failure modes, row 4. To refresh only the menu, use wmgenmenu > ~/GNUstep/Defaults/WMRootMenu.
Stop Window Maker painting over your wallpaper (optional). The stock WorkspaceBack is a solid colour. If something draws the root window before wmaker starts (my x11/common does, step 10), set it to (none):
```
$ wdread WindowMaker WorkspaceBack
(solid, "rgb:50/50/75")
$ wdwrite WindowMaker WorkspaceBack '(none)'
$ wdread WindowMaker WorkspaceBack
(none)
```
Expected: (none) on read-back. (Transcript from the same scratch HOME as step 5; my real defaults read (none) too, see Verify.) Skip this step if Window Maker is the only thing that sets a background.

Start the dockapps from autostart. Window Maker runs this script before it starts handling events and waits for it to exit, so every command gets a trailing &. It also runs the script again on every Restart (root menu), while the first dockapps are still alive, so each line starts its program only if it is not already running. wmmemload -b -c leaves buffers and page cache out of "used" memory; without it the meter read 86% on a box with 13 GiB available. The file must stay executable. Append the four lines under the stock comment header:

cat >> ~/GNUstep/Library/WindowMaker/autostart <<'EOF'
pgrep -x wmclock >/dev/null || wmclock &
pgrep -x wmifs >/dev/null || wmifs &
pgrep -x wmmemload >/dev/null || wmmemload -b -c &
pgrep -x wmsystemtray >/dev/null || wmsystemtray &
EOF

(Transcript from a scratch HOME; my live file has one more dockapp, wmix, and a comment.)

$ tail -4 ~/GNUstep/Library/WindowMaker/autostart
pgrep -x wmclock >/dev/null || wmclock &
pgrep -x wmifs >/dev/null || wmifs &
pgrep -x wmmemload >/dev/null || wmmemload -b -c &
pgrep -x wmsystemtray >/dev/null || wmsystemtray &
$ sh -n ~/GNUstep/Library/WindowMaker/autostart; echo rc=$?
rc=0
$ stat -c "%A %n" ~/GNUstep/Library/WindowMaker/autostart
-rwxr-xr-x ~/GNUstep/Library/WindowMaker/autostart

Expected: the four lines, rc=0, x bits set.

Write a minimal startx client script. One file per window manager, so startx can be pointed at it:
```
cat > ~/.xinitrc-windowmaker <<'EOF'
#!/bin/sh
exec wmaker
EOF
chmod 755 ~/.xinitrc-windowmaker
```
```
$ cat ~/.xinitrc-windowmaker
#!/bin/sh
exec wmaker
$ sh -n ~/.xinitrc-windowmaker; echo rc=$?
rc=0
$ stat -c "%A %n" ~/.xinitrc-windowmaker
-rwxr-xr-x ~/.xinitrc-windowmaker
```
Expected: rc=0 and x bits set. exec wmaker is also what upstream's install page puts in ~/.xinitrc. (Transcript from a scratch HOME, paths shortened to ~; on my box this file is the longer script in step 10.) [UNVERIFIED: this minimal script was not started; my box runs the step 10 script]
(My box) Give the session its own OpenRC user runlevel. My session daemons are OpenRC user services; each window manager gets a runlevel with default stacked in, so entering it never stops dbus or PipeWire. Skip steps 9 to 11 if you don't run user services or a tty menu. The two commands are from my rebuild notes (the original run was not captured); the output below is from 2026-11-02 20:56:
```
mkdir -p ~/.config/rc/runlevels/windowmaker
rc-update --user -s add default windowmaker
```
```
$ rc-status --user windowmaker
Runlevel: windowmaker
Stacked Runlevel: default
 dbus                                                  [  started 20:41:24 (0) ]
 pipewire                                              [  started 20:41:24 (0) ]
 wireplumber                                           [  started 20:41:24 (0) ]
 pipewire-pulse                                        [  started 20:41:24 (0) ]
```
Expected: Stacked Runlevel: default. I add no services of my own to this runlevel: my terminal and notification services there need Wayland.

(My box) Replace the client script with the glue version. This is my ~/.xinitrc-windowmaker as it is on the box. It needs two things this manual does not create: ~/.config/x11/common (my shared X startup: keyboard layout, settings daemon, wallpaper, idle lock), and, for the openrc lines, the runlevel from step 9. /bin/sh stops at a failed ., so without that file wmaker never starts. In the comments, "the Path-B chooser" is the tty menu in step 11 and sway-session is my Wayland launcher. It runs wmaker without exec so the script can leave the runlevel after Window Maker exits:

#!/bin/sh
# X session: Window Maker. Launched by the Path-B chooser via
# `startx ~/.xinitrc-windowmaker -- vtN`.
#
# Shared startup (env, xkb layout, xsettingsd, cursor, root colour, .Xdefaults)
# lives in ~/.config/x11/common so the bare X WMs cannot drift apart.
. "$HOME/.config/x11/common"

export XDG_CURRENT_DESKTOP=WindowMaker

# Enter this WM's own OpenRC user runlevel. `default` (dbus/pipewire/wireplumber)
# is stacked into it, and -n (--no-stop) makes entry purely additive, so this can
# never stop the session bus out from under us. Done here rather than in each
# WM's own config so all the bare X WMs share one mechanism.
openrc -U -n windowmaker

# NOTE: deliberately not `exec` -- this script must outlive the WM to run the
# teardown below, exactly as /usr/local/bin/sway-session does.
#
# Window Maker provides its own Dock and Clip, so no external panel/bar is
# started here (unlike openbox/fvwm3, which run a standalone xfce4-panel).
# Dockapps go in ~/GNUstep/Library/WindowMaker/autostart if wanted.
#
# ~/GNUstep/Defaults/ was seeded with `wmaker.inst --batch`, so the user
# defaults database (WindowMaker, WMRootMenu) exists and edits go here instead
# of the read-only /etc/X11/WindowMaker fallback. Re-seed only if it is missing.
wmaker

# WM has exited. Leave its runlevel so any WM-bound service stops rather than
# lingering with a dead display. `default` is stacked, so dbus/pipewire survive;
# pam_openrc stops those at PAM session close.
openrc -U default >/dev/null 2>&1

$ sh -n ~/.xinitrc-windowmaker; echo rc=$?
rc=0

Expected: rc=0.

(My box) Add the session to the tty menu. My tty1 login runs a small menu script (~/.local/bin/session-chooser) whose startx_session function execs startx "$HOME/.xinitrc-$1" -- vtN, with N taken from the current tty. All ten digits were already used, so Window Maker got a letter. One line goes into the menu's list of printf lines, the other into the case before the *) fallback:
```
printf '   [w] windowmaker (X11)\n'
```
```
	w|W) startx_session windowmaker ;;
```
Checked with stubs for startx and sway-session on PATH, a scratch HOME holding a copy of the step 10 script, and the real menu script driven through script:
```
$ printf 'w\n' | script -qec 'bash /home/user/.local/bin/session-chooser' /dev/null | tail -3
   [w] windowmaker (X11)

  session [1]: STUB startx ~/.xinitrc-windowmaker -- vt0
```
Expected: the stub prints the startx line. vt0 is the pseudo-terminal's number under script; on tty1 it is vt1. An unmatched key still falls through to my default session (STUB sway-session).
Start the session. Log in on a tty and run:
```
startx ~/.xinitrc-windowmaker -- vt1
```
Use the number of the tty you are on in place of 1.

Lock OpenCode 2.x to your self-hosted model

Mon, 02 Nov 2026 00:00:00 +0000

Two config lines make OpenCode 2.x send prompts only to your self-hosted OpenAI-compatible model, and a self-contained script proves which model a headless run picks.

Tested on: OpenCode V2 (npm @opencode/cli) 2.2.5, headless opencode run, throwaway HOME, first in a container with no network, then with the PoC below behind a dead proxy (2026-11-02). The no-model case was also run on 2.2.0.
Not verified: the interactive TUI, a fresh install's first-run screens, 2.2.1 to 2.2.4, a config with both lines at once, "model" alone with the local server down, a full personal config.
Needs: an opencode 2.x binary, a local OpenAI-compatible model server already configured as a provider (one way: /guides/serve-local-models-to-opencode-llama-router/), python3 for the PoC. No opencode.ai account and no API key.
Time: about 10 min, my estimate, not timed (the PoC caps each of its three runs at 60 s).
Risk: low. You edit one config file after copying it; the PoC points HOME and the four XDG_* directories it sets (config, data, state, cache) at a mktemp -d directory and starts a server on 127.0.0.1:18765 for the length of the run.

Before you start#

Placeholders used below:
- <CONFIG>: your global OpenCode config file. The PoC writes its own as $XDG_CONFIG_HOME/opencode/opencode.json inside a throwaway HOME, so on a default setup this is ~/.config/opencode/opencode.json.
- <PROVIDER_ID>: the key of your local provider under "provider" in <CONFIG>. The PoC uses local.
- <MODEL_ID>: the key of your model under that provider's "models". The PoC uses qwen-local.
- <OPENCODE_BIN>: path to the opencode 2.x binary; the PoC defaults to opencode on PATH.
Check the version with <OPENCODE_BIN> --version. Mine printed opencode v2.2.5 (it is also the PoC's first output line).
Back up the config before step 3:
```
cp <CONFIG> <CONFIG>.bak
```

Record MQTT topics to a MikroTik router's SSD

Mon, 02 Nov 2026 00:00:00 +0000

This runs mosquitto_sub in a RouterOS 7.24 container and appends every message on a set of MQTT topics to a file on the router's SSD, one file per UTC day, with a timestamp on each line.

Tested on: a MikroTik router with RouterOS 7.24, the container package and a USB SSD (usb1-part1), image eclipse-mosquitto:2.1.2-alpine pulled from Docker Hub, broker in another container on the same container bridge (2026-11-02). The stop-signal behaviour of run.sh was re-checked in Docker 29.9.2 on Fedora 44 the same day.
Not verified: the rollback; the day switch of the file name (the recorder has run for less than a day); this exact order (my first deploy named another container's envlist, and I moved the running container to mqttrec later the same day); and the commands of steps 1, 3 and 6 as written here: my notes record what each step did, not these exact lines.
Needs: a container bridge with a gateway address on the router and an MQTT broker reachable from it; the router's container registry set to Docker Hub; a read-only MQTT user; SSH and SCP to the router; an external disk with free space.
Time: 20 min plus the image pull.
Risk: low. The container only opens an outbound MQTT connection and writes to one directory. Nothing rotates or deletes the files: about 3.5 to 5 MB a day, so a large SSD lasts decades, a small USB stick does not. Rollback removes one container, one mount, one envlist, one bridge port and one veth.

Before you start#

Placeholders used below:

Placeholder	Meaning (mine)
`<ROUTER>`	SSH `user@address` of the router, plus your own `-i <KEY>` options
`<DISK>`	the external disk (`usb1-part1`)
`<CT_BRIDGE>`	the bridge your containers' veths are ports of (`bridge-containers`)
`<CT_ADDR>` / `<CT_GW>`	a free address on that bridge for the recorder, and the bridge's gateway (`172.17.0.5`, `172.17.0.1`)
`<BROKER_IP>`	the broker's address as seen from the container bridge (`172.17.0.3`)
`<MQTT_USER>` / `<MQTT_PASSWORD>`	the read-only MQTT login the recorder uses

The registry is Docker Hub. remote-image pulls from the registry set in /container/config, and MikroTik's documented default is https://lscr.io/. Check registry-url in ssh <ROUTER> '/container/config/print'; if it isn't Docker Hub, set it as MikroTik's page shows: /container/config/set registry-url=https://registry-1.docker.io.
The broker accepts the read-only user and lets it subscribe to the topics you put into run.sh in step 2.
Backup: take a config export before step 1 (/export file=<DISK>/backups/<NAME>) and copy it off the router.

Confine a coding agent's HTTPS to an allowlist with bwrap

Sat, 31 Oct 2026 00:00:00 +0000

Run a command (a coding agent, a build, a shell) in a bubblewrap sandbox whose only way out is HTTPS through a small proxy on the host that lets through the hosts on your list and refuses the rest.

Tested on: Fedora Linux 44 (KDE), kernel 7.2.13-200.fc44.x86_64, bubblewrap 0.12.0, Python 3.14.8, curl 8.18.0, Node.js v22.23.1 (2026-10-31).
Not verified: running a coding agent inside the sandbox. The test commands were curl, Python, bash and Node's fetch, run from a test script.
Needs: Linux with bubblewrap (bwrap) and Python 3; curl for the tests. No root. Node.js for the two fetch checks only.
Time: not timed. The scripted re-run of the whole procedure, failure captures included, took 3 s (13:44:32 to 13:44:35); that is script speed, not the time to set this up by hand.
Risk: low and reversible. Nothing outside the working directory and the project directory changes, and the proxy runs as your user. The project directory is mounted read-write, so the command inside can change or delete files there.

Before you start#

Check the tools. My run:

$ bwrap --version; python3 --version; curl --version | head -1; /usr/bin/node --version; uname -r; grep PRETTY_NAME /etc/os-release
bubblewrap 0.12.0
Python 3.14.8
curl 8.18.0 (x86_64-redhat-linux-gnu) libcurl/8.18.0 OpenSSL/3.5.9 zlib/1.3.1.zlib-ng brotli/1.2.1 libidn2/2.3.8 libpsl/0.21.5 libssh/0.12.2/openssl/zlib nghttp2/1.68.0 ngtcp2/1.22.1 nghttp3/1.18.0 mit-krb5/1.22.2 OpenLDAP/2.6.15
v22.23.1
7.2.13-200.fc44.x86_64
PRETTY_NAME="Fedora Linux 44 (KDE Plasma Desktop Edition)"

Pick a working directory for the scripts. Every command below runs from it, and the proxy's files go in run/ under it. In the output below it is shown as /home/user/egress.
Placeholders, used only in step 8:
- <PROJECT_DIR>: the directory the sandboxed command may read and write. It appears as /work inside.
- <AGENT>: the command to run in the sandbox.
- <INSTALL_DIR>: the directory the agent is installed in, if it is not under /usr.
Back up or commit <PROJECT_DIR> before you run anything in it: the sandbox mounts it read-write.

How it fits together, from the two scripts:

Load gpu_unlock before nvidia on Bazzite for an RTX 3090

Mon, 26 Oct 2026 00:00:00 +0000

This installs the gpu_unlock kernel module on Bazzite so that it runs from the initramfs, before nvidia binds the card, and leaves an RTX 3090 with full-rate FP16/BF16 (FP32-accumulate) and TF32 tensor math on every boot that carries the kernel option gpu_unlock.targets=all.

Tested on: Bazzite 44.20261023 (bazzite-nvidia-open image, kernel 7.2.9-ogc3.1.fc44), NVIDIA open driver 615.78.08, RTX 3090 (10de:2204) with VBIOS 94.02.26.80.8C, Secure Boot off; gpu-unlock at upstream commit af28cbb, NVIDIA firmware pin 610.43.03 (2026-10-26).
Not verified: the redo after an image update brings a new kernel (none has arrived yet); the file-removal half of Undo; the login check on a real failed boot (tested with its override variables only); Secure Boot; any card other than this one RTX 3090; the boot-menu keys in Recovery come from Bazzite's docs.
Needs: a login user that can read the kernel log with journalctl -k (on the tested box: a member of wheel); an rpm-ostree image that puts nvidia in its initramfs (Bazzite's nvidia and nvidia-open images do); a GA102/GA103/GA104/GA106 GeForce card from the upstream list; sudo; about 340 MB of downloads; a keyboard on the box to reach the hidden boot menu.
Time: 30 min (plus one full power off).
Risk: if the unlock fails partway, the card can stay unusable until a full power off; on a single-GPU box that is a black screen, recovered from the boot menu (Recovery below). Reversible: the option lives in one deployment, the speed selectors do not survive a power off. Step 11 (optional) removes the rollback entry for good.

The steps replace upstream's make install (DKMS plus packages), which cannot work on rpm-ostree: /usr is read-only, and the image's prebuilt initramfs loads nvidia before anything on the root file system runs. Here the module, its firmware and a loader script live in /etc, rpm-ostree initramfs-etc adds them to the initramfs as an overlay, and a modprobe.d install rule runs the loader before every load of nvidia.

Simulate a cold start without rebooting or drop_caches

Mon, 26 Oct 2026 00:00:00 +0000

Drop one file you own from the Linux page cache with posix_fadvise(POSIX_FADV_DONTNEED), prove it with fincore, and start the program cold, as on the first start after a reboot, with no root and no reboot.

Tested on: an 8-core Ryzen 7 8845HS mini PC, Fedora 44, kernel 7.2.10-200.fc44, util-linux fincore 2.41.5, Python 3.14.8, Docker 29.9.2 (rootful, cgroup v2, systemd cgroup driver), image debian:bookworm-slim (2026-10-26). The file was a 67 MiB native executable built on the host and bind-mounted read-only into the container.
Not verified: the cgroupfs Docker driver (its cgroup path differs from the one in step 8); rootless Docker and Podman; filesystems other than the btrfs /home used here.
Needs: Python 3, fincore from util-linux, read access to the file, and ownership of it (or write access) if fincore is to show the result. Docker only for the container part. No sudo.
Time: 5 min.
Risk: none to data. The eviction drops clean cached pages of one file; the next read of that file, by any process on the host, comes from disk. Nothing to undo.

Before you start#

Every transcript ran in one scratch directory. app/demo-micronaut is the file to evict, a native executable; app/ is the directory the container mounts. Replace both with your own file and directory. Port 18080 is a free host port on the test box.

fincore and Python 3 are installed:

$ fincore --version
fincore from util-linux 2.41.5
$ python3 --version
Python 3.14.8

You own the file. fincore reports honest numbers only for a file you own or could write (Failure modes, row 2):
```
$ stat -c '%U %n' app/demo-micronaut
user app/demo-micronaut
```
For the container part: Docker uses the systemd cgroup driver on cgroup v2, which gives the cgroup path used in step 8:
```
$ docker info --format '{{.CgroupDriver}} cgroup v{{.CgroupVersion}}'
systemd cgroup v2
```
The container reads the file through a bind mount of a host directory (-v "$PWD/app:/app:ro"). A file inside an image layer under Docker's data root cannot be opened by a normal user and cannot be evicted this way (Failure modes, row 3).

Steps#

Save the eviction script as evict.py.

import os, sys

for path in sys.argv[1:]:
    fd = os.open(path, os.O_RDONLY)
    try:
        os.posix_fadvise(fd, 0, 0, os.POSIX_FADV_DONTNEED)
    finally:
        os.close(fd)

Offset 0 and length 0 cover the whole file. The script prints nothing and exits 0 even when the kernel keeps pages; only step 6 tells you whether it worked.

Make sure no container is running the file.
```
$ docker ps --filter volume=/app --format '{{.Names}} {{.Status}}'
```
Expected: no output (volume= matches the mount destination inside the container). If a name is printed, remove that container first: pages a running process has mapped stay in the cache (Failure modes, row 1).
Check what is cached now.
```
$ fincore app/demo-micronaut
  RES PAGES  SIZE FILE
52.2M 13373 67.4M app/demo-micronaut
```
RES is the part of the file in the page cache. Here 52.2M was left over from an earlier start.
Write out dirty pages of the file.
```
$ sync app/demo-micronaut
```
Expected: no output. posix_fadvise(2) does not free dirty pages that have not been written back. On the test box a freshly written 64 MiB file reached 0 B without this step, so it is a cheap precaution, not a fix for an observed failure.
Evict the file.
```
$ python3 evict.py app/demo-micronaut
```
Expected: no output, exit status 0.
Confirm nothing of the file is cached.
```
$ fincore app/demo-micronaut
RES PAGES  SIZE FILE
 0B     0 67.4M app/demo-micronaut
```
Expected: 0B and 0 pages. Anything else: Failure modes, rows 1 and 2.

Start the program; it is now the first reader of the file. Here a native binary in a container with a 64 MiB limit (-m 64m):

$ docker run -d --name cold-demo -m 64m --memory-swap 64m -p 127.0.0.1:18080:8080 -v "$PWD/app:/app:ro" debian:bookworm-slim /app/demo-micronaut -XX:MaxHeapSize=32m
feb26a504b88824bbac72cd6835307764c0ccbcc33f7ab44759041e4900437d2
$ for i in $(seq 100); do curl -sf http://127.0.0.1:18080/hello && break; sleep 0.2; done; echo
{"runtime":"native","pid":1,"framework":"micronaut"}

Expected: the container ID, then the first answer from the app. Wait with a loop like this one, not with curl --retry (Failure modes, row 4).

Read what the container's cgroup was charged for the page cache.
```
$ grep -E '^(anon|file|file_mapped) ' /sys/fs/cgroup/system.slice/docker-$(docker inspect -f '{{.Id}}' cold-demo).scope/memory.stat
anon 10444800
file 54722560
file_mapped 32153600
```
Expected: a large file value, here 54,722,560 bytes (52.2 MiB). The container read the binary first, so the page cache it loaded counts against its own memory limit. A warm start shows file at or near 0 (Verify).

Remove the container. The next start is warm again.

$ docker rm -f cold-demo
cold-demo
$ fincore app/demo-micronaut
  RES PAGES  SIZE FILE
52.2M 13360 67.4M app/demo-micronaut

The cold start left 52.2M of the file in the cache.

For several rounds, evict before every start. Save as cold-rounds.sh:

#!/usr/bin/env bash
# Three cold starts of a bind-mounted binary; the page cache is evicted before each one.
set -u
BIN=app/demo-micronaut
for round in 1 2 3; do
  python3 evict.py "$BIN"
  fincore "$BIN" | tail -1
  docker run -d --name cold-demo -m 64m --memory-swap 64m -p 127.0.0.1:18080:8080 \
    -v "$PWD/app:/app:ro" debian:bookworm-slim /app/demo-micronaut -XX:MaxHeapSize=32m > /dev/null
  for i in $(seq 100); do curl -sf http://127.0.0.1:18080/hello > /dev/null && break; sleep 0.2; done
  cg=/sys/fs/cgroup/system.slice/docker-$(docker inspect -f '{{.Id}}' cold-demo).scope
  echo "round $round: $(curl -s http://127.0.0.1:18080/hello) $(grep '^file ' "$cg/memory.stat")"
  docker rm -f cold-demo > /dev/null
done

$ bash cold-rounds.sh
 0B     0 67.4M app/demo-micronaut
round 1: {"runtime":"native","pid":1,"framework":"micronaut"} file 54546432
 0B     0 67.4M app/demo-micronaut
round 2: {"runtime":"native","pid":1,"framework":"micronaut"} file 54960128
 0B     0 67.4M app/demo-micronaut
round 3: {"runtime":"native","pid":1,"framework":"micronaut"} file 54734848

Expected: 0B before every round and a similar file value in each. A round with an empty answer after round N: did not start within the 20 s the loop waits.

Verify#

The cold start is real when fincore showed 0B right before the start (step 6) and the container's file counter is large (step 8). For the comparison, start the same container warm: read the whole file first, then start it.

Enable VA-API HEVC decode on Fedora with an AMD GPU

Sun, 25 Oct 2026 00:00:00 +0000

Make an AMD GPU decode HEVC (Main and Main 10) through VA-API on Fedora 44 by installing RPM Fusion's mesa-va-drivers-freeworld, after checking that the hardware decodes HEVC and Fedora's own driver doesn't offer it.

Tested on: Fedora 44 desktop (KDE Plasma 6.7, X11), AMD Radeon 780M iGPU (radeonsi, phoenix), kernel 7.2.10-200.fc44, Mesa 26.2.5-1.fc44, mesa-va-drivers-freeworld 26.2.5-1.fc44, libva 2.23.0-3.fc44 (VA-API 1.23), libdrm 2.4.134-1.fc44, ffmpeg 8.1.3-1.fc44 (RPM Fusion), mpv 0.41.0-5.fc44 (2026-10-25).
Not verified: decoding a real H.264 clip (the H.264 profiles appear in step 11, but no H.264 clip was decoded); Haruna, browsers or other players with the new driver; Intel or NVIDIA GPUs; other distributions; Vulkan video decode; Wayland; 32-bit (i686) VA-API programs, and RPM Fusion's i686 build of mesa-va-drivers-freeworld (not installed here); what dnf does when Fedora ships a newer Mesa before RPM Fusion rebuilds this package (only the version pin was observed); the rollback.
Needs: an AMD GPU on the amdgpu kernel driver with render node /dev/dri/renderD128; the RPM Fusion free repository; RPM Fusion's ffmpeg for the test clips; mpv for the player check; python3; sudo for the install. The two scripts attached to this page: amdgpu_video_caps.py and va_profiles.py.
Time: 15 min.
Risk: low. One package is added and nothing is removed (step 7). While it is installed, every 64-bit VA-API program on the host that doesn't set LIBVA_DRIVERS_PATH gets RPM Fusion's driver, which lists no JPEG decode profile. That driver file is a link to libgallium, the Mesa library that Fedora's EGL and GLX libraries and GBM's DRI backend also link, and the x86_64 package that step 8 installs puts its own copy ahead of Fedora's on the 64-bit linker path, so Fedora's 64-bit builds of those resolve to RPM Fusion's copy too; the 32-bit (i686) builds on this box keep Fedora's (Notes). The package pins the Mesa version, so each new Mesa version needs a matching rebuild from RPM Fusion. Undo: remove the package (not exercised).

Before you start#

Package versions and vendors:

$ rpm -q --qf '%{NAME}-%{VERSION}-%{RELEASE} %{VENDOR}\n' ffmpeg ffmpeg-libs mpv libva libdrm mesa-dri-drivers
ffmpeg-8.1.3-1.fc44 RPM Fusion
ffmpeg-libs-8.1.3-1.fc44 RPM Fusion
mpv-0.41.0-5.fc44 Fedora Project
libva-2.23.0-3.fc44 Fedora Project
libva-2.23.0-3.fc44 Fedora Project
libdrm-2.4.134-1.fc44 Fedora Project
libdrm-2.4.134-1.fc44 Fedora Project
mesa-dri-drivers-26.2.5-1.fc44 Fedora Project
mesa-dri-drivers-26.2.5-1.fc44 Fedora Project

Expected: ffmpeg and ffmpeg-libs from RPM Fusion. Two lines for one package are its x86_64 and i686 builds (the format string prints no arch). If ffmpeg is not installed and Fedora's ffmpeg-free is, sudo dnf swap ffmpeg-free ffmpeg --allowerasing replaces it (that is how this box got it, in July); why that matters for players is in Two libavcodecs behind one soname.

The RPM Fusion free repository is configured:
```
$ rpm -q rpmfusion-free-release
rpmfusion-free-release-44-3.noarch
```
Expected: an rpmfusion-free-release package for your Fedora release. The freeworld driver comes from rpmfusion-free-updates (step 9).
ffmpeg can encode the test clips:
```
$ rpm -q --requires ffmpeg-libs | grep -E 'libx265|libSvtAv1Enc'
libSvtAv1Enc.so.3()(64bit)
libx265.so.215()(64bit)
```
Expected: both libraries. Step 4 encodes with libx265 and libsvtav1. Fedora's ffmpeg-free was not tried for this.

The render node belongs to the amdgpu kernel driver:

$ readlink /sys/class/drm/renderD128/device/driver
../../../../bus/pci/drivers/amdgpu

Expected: a path ending in amdgpu.

The render node exists and your user can open it:
```
$ ls -l /dev/dri/renderD128
crw-rw-rw-. 1 root render 226, 128 Oct 20 18:56 /dev/dri/renderD128
```
Expected: a character device. Mode crw-rw-rw- here, so no group membership is needed. Every command below uses /dev/dri/renderD128, the only render node on this box. With two GPUs, find the AMD node and change the path in both scripts and in the ffmpeg commands; for mpv's vaapi-copy the mpv manual names --vaapi-device [UNVERIFIED: single-GPU box].
Placeholders: none.
Backups: none needed. The package adds its VA drivers and its own libgallium under /usr/lib64/dri-freeworld/, one file in /etc/ld.so.conf.d/, and license and metainfo files; its install scriptlet runs ldconfig, which rebuilds the linker cache. Fedora's Mesa packages stay installed (steps 7 and 10).

Steps#

Save the two scripts in an empty directory and work there.

mkdir -p ~/vaapi-test && cd ~/vaapi-test

Download amdgpu_video_caps.py and va_profiles.py from this page, or copy them from here. The first asks the amdgpu kernel driver through libdrm, the second asks libva.

amdgpu_video_caps.py:

# What the amdgpu kernel driver says the video block can do (AMDGPU_INFO_VIDEO_CAPS).
import ctypes, os
from ctypes import POINTER, byref, c_uint32, c_void_p, sizeof

class CodecInfo(ctypes.Structure):
    _fields_ = [(f, c_uint32) for f in
                ("valid", "max_width", "max_height", "max_pixels_per_frame", "max_level", "pad")]

class VideoCaps(ctypes.Structure):
    _fields_ = [("codec_info", CodecInfo * 8)]

CODECS = ["MPEG2", "MPEG4", "VC1", "H264", "HEVC", "JPEG", "VP9", "AV1"]
lib = ctypes.CDLL("libdrm_amdgpu.so.1")
lib.amdgpu_device_initialize.argtypes = [ctypes.c_int, POINTER(c_uint32), POINTER(c_uint32), POINTER(c_void_p)]
lib.amdgpu_query_video_caps_info.argtypes = [c_void_p, ctypes.c_uint, ctypes.c_uint, c_void_p]

fd = os.open("/dev/dri/renderD128", os.O_RDWR)
major, minor, dev = c_uint32(), c_uint32(), c_void_p()
assert lib.amdgpu_device_initialize(fd, byref(major), byref(minor), byref(dev)) == 0

for kind, cap_type in (("decode", 0), ("encode", 1)):
    caps = VideoCaps()
    assert lib.amdgpu_query_video_caps_info(dev, cap_type, sizeof(caps), byref(caps)) == 0
    print(f"{kind}:")
    for name, c in zip(CODECS, caps.codec_info):
        if c.valid:
            print(f"  {name:5} {c.max_width}x{c.max_height} level {c.max_level}")

va_profiles.py:

# What the VA-API driver that libva actually loads offers, per profile.
import ctypes, os
from ctypes import POINTER, byref, c_char_p, c_int, c_void_p

va = ctypes.CDLL("libva.so.2")
va_drm = ctypes.CDLL("libva-drm.so.2")
va_drm.vaGetDisplayDRM.restype = c_void_p
va_drm.vaGetDisplayDRM.argtypes = [c_int]
va.vaInitialize.argtypes = [c_void_p, POINTER(c_int), POINTER(c_int)]
va.vaQueryVendorString.restype = c_char_p
va.vaQueryVendorString.argtypes = [c_void_p]
va.vaMaxNumProfiles.argtypes = [c_void_p]
va.vaMaxNumEntrypoints.argtypes = [c_void_p]
va.vaQueryConfigProfiles.argtypes = [c_void_p, POINTER(c_int), POINTER(c_int)]
va.vaQueryConfigEntrypoints.argtypes = [c_void_p, c_int, POINTER(c_int), POINTER(c_int)]
va.vaProfileStr.restype = c_char_p
va.vaProfileStr.argtypes = [c_int]
va.vaEntrypointStr.restype = c_char_p
va.vaEntrypointStr.argtypes = [c_int]

dpy = va_drm.vaGetDisplayDRM(os.open("/dev/dri/renderD128", os.O_RDWR))
major, minor = c_int(), c_int()
assert va.vaInitialize(dpy, byref(major), byref(minor)) == 0
print(va.vaQueryVendorString(dpy).decode())

profiles, n = (c_int * va.vaMaxNumProfiles(dpy))(), c_int()
va.vaQueryConfigProfiles(dpy, profiles, byref(n))
for p in profiles[:n.value]:
    eps, m = (c_int * va.vaMaxNumEntrypoints(dpy))(), c_int()
    va.vaQueryConfigEntrypoints(dpy, p, eps, byref(m))
    names = [va.vaEntrypointStr(e).decode().removeprefix("VAEntrypoint") for e in eps[:m.value]]
    print(f"  {va.vaProfileStr(p).decode().removeprefix('VAProfile'):26} {' '.join(names)}")

Neither writes anything. Both open /dev/dri/renderD128 and print what comes back, using libdrm_amdgpu.so.1 (package libdrm) and libva.so.2 plus libva-drm.so.2 (package libva) through Python's ctypes. vainfo from libva-utils is the usual tool for the second list. It is not installed on this box, so its output is not shown here.

Ask the kernel which codecs the video block decodes.
```
$ python3 amdgpu_video_caps.py
decode:
  H264  4096x4096 level 52
  HEVC  8192x4352 level 186
  JPEG  16384x16384 level 0
  VP9   8192x4352 level 0
  AV1   8192x4352 level 0
encode:
  H264  4096x4096 level 0
  HEVC  8192x4352 level 0
  AV1   8192x4352 level 0
```
Expected: an HEVC line under decode:. This is the kernel's AMDGPU_INFO_VIDEO_CAPS answer, read with libdrm's amdgpu_query_video_caps_info(): the 780M decodes H.264 up to 4096x4096 and HEVC up to 8192x4352. The answer has no profile field, so it can't tell Main from Main 10; the driver's list in step 3 can. If there is no HEVC line under decode:, this manual doesn't apply to your GPU.
List what Fedora's own VA driver offers.
```
$ LIBVA_DRIVERS_PATH=/usr/lib64/dri python3 va_profiles.py
libva info: VA-API version 1.23.0
libva info: Trying to open /usr/lib64/dri/radeonsi_drv_video.so
libva info: Found init function __vaDriverInit_1_23
libva info: va_openDriver() returns 0
Mesa Gallium driver 26.2.5 for AMD Radeon 780M Graphics (radeonsi, phoenix, ACO, DRM 3.64, 7.2.10-200.fc44.x86_64)
  JPEGBaseline               VLD
  VP9Profile0                VLD
  VP9Profile2                VLD
  AV1Profile0                VLD EncSlice
  None                       VideoProc
```
Expected: no H264… line and no HEVC… line. Fedora's driver decodes JPEG, VP9 and AV1 (VLD) and encodes AV1 (EncSlice). The GPU has HEVC (step 2), the driver build doesn't offer it. Fedora's mesa.spec passes no -Dvideo-codecs, so Mesa's default all_free applies, which Mesa's build options describe as enabling the codecs that aren't patent-encumbered.

LIBVA_DRIVERS_PATH replaces libva's driver search list (colon-separated). Fedora builds libva to search /usr/lib64/dri-nonfree, then /usr/lib64/dri-freeworld, then /usr/lib64/dri. On a box without freeworld, plain python3 va_profiles.py tries the first two and loads the same Fedora file. With the variable set to /usr/lib64/dri, the command lists Fedora's driver even after step 8, which is how this page's "before" transcripts were made (Field notes).

Generate three 2-second test clips.

ffmpeg -f lavfi -i testsrc2=size=1920x1080:rate=30 -t 2 -c:v libx265 -pix_fmt yuv420p10le main10.mkv
ffmpeg -f lavfi -i testsrc2=size=1920x1080:rate=30 -t 2 -c:v libx265 -pix_fmt yuv420p main8.mkv
ffmpeg -f lavfi -i testsrc2=size=1920x1080:rate=30 -t 2 -c:v libsvtav1 -pix_fmt yuv420p av1.mkv

$ ls -l main10.mkv main8.mkv av1.mkv
-rw-r--r--. 1 user user 1497381 Oct 25 16:24 av1.mkv
-rw-r--r--. 1 user user 1215321 Oct 25 16:24 main10.mkv
-rw-r--r--. 1 user user 1205903 Oct 25 16:24 main8.mkv

Expected: three files of 1.2 to 1.5 MB here: HEVC Main 10, HEVC Main (8-bit), and AV1 as the control. libx265 and libsvtav1 are software encoders, so this step doesn't depend on the VA driver, and no sample downloads are needed. ffmpeg's decode log names each clip's codec and profile (the Stream #0:0: Video: line in step 5).

Decode the Main 10 clip through VA-API with Fedora's driver.

$ LIBVA_DRIVERS_PATH=/usr/lib64/dri ffmpeg -hide_banner -v verbose -hwaccel vaapi -hwaccel_device /dev/dri/renderD128 -hwaccel_output_format vaapi -i main10.mkv -f null -
[…]
  Stream #0:0: Video: hevc (Main 10), 1 reference frame, yuv420p10le(tv, progressive, left), 1920x1080 [SAR 1:1 DAR 16:9], 30 fps, 30 tbr, 1k tbn
[…]
[VAAPI @ 0x5604256d4140] libva: Trying to open /usr/lib64/dri/radeonsi_drv_video.so
[…]
[VAAPI @ 0x5604256d4140] VAAPI driver: Mesa Gallium driver 26.2.5 for AMD Radeon 780M Graphics (radeonsi, phoenix, ACO, DRM 3.64, 7.2.10-200.fc44.x86_64).
[…]
[hevc @ 0x5604257bec40] No support for codec hevc profile 2.
[hevc @ 0x5604257bec40] Failed setup for format vaapi: hwaccel initialisation returned error.
[graph -1 input from stream 0:0 @ 0x7fb718004e80] w:1920 h:1080 pixfmt:yuv420p10le tb:1/1000 fr:30/1 sar:1/1 csp:unknown range:tv alpha:unspecified
[…]
[in#0/matroska,webm @ 0x5604256cc580]   Input stream #0:0 (video): 60 packets read (1211848 bytes); 60 frames decoded; 0 decode errors;
[…]
Exiting with exit code 0

Expected with Fedora's driver: No support for codec hevc profile 2., then Failed setup for format vaapi: hwaccel initialisation returned error. Profile 2 is libavcodec's number for HEVC Main 10, profile 1 is Main: main8.mkv fails the same way with profile 1 (Failure modes, row 2). ffmpeg then decodes all 60 frames in software. The filter graph gets pixfmt:yuv420p10le, a CPU pixel format.

Gotchaffmpeg exits 0 on the software fallback

A failed hwaccel setup doesn't fail the ffmpeg run. ffmpeg drops VA-API, decodes in software, and ends with 0 decode errors and Exiting with exit code 0, the same as the working run in step 12. An exit-code test passes on both. Look for the Failed setup line, and, with -hwaccel_output_format vaapi as here, for pixfmt:vaapi on the graph -1 input line.

Decode the AV1 control clip with the same driver.

$ LIBVA_DRIVERS_PATH=/usr/lib64/dri ffmpeg -hide_banner -v verbose -hwaccel vaapi -hwaccel_device /dev/dri/renderD128 -hwaccel_output_format vaapi -i av1.mkv -f null -
[…]
[VAAPI @ 0x555fc65982c0] libva: Trying to open /usr/lib64/dri/radeonsi_drv_video.so
[…]
[graph -1 input from stream 0:0 @ 0x7f2d10004ec0] w:1920 h:1080 pixfmt:vaapi tb:1/1000 fr:30/1 sar:1/1 csp:unknown range:tv alpha:unspecified
[…]
[in#0/matroska,webm @ 0x555fc6585580]   Input stream #0:0 (video): 60 packets read (1496364 bytes); 60 frames decoded; 0 decode errors;
[…]

Expected: no Failed setup line, and pixfmt:vaapi: the frames come out of the GPU as VA surfaces. The render node, libva and Fedora's driver work. Only the codec list is short.

Dry-run the install.

sudo dnf install --assumeno mesa-va-drivers-freeworld

Expected: one package to install, mesa-va-drivers-freeworld, and nothing to remove or downgrade. --assumeno answers no at the prompt, so nothing changes. On this box dnf's own log (/var/log/dnf5.log) names the run dnf install --assumeno mesa-va-drivers-freeworld. The terminal output, with the repository loading cut:

[…]
Repositories loaded.
Package                    Arch   Version         Repository                  Size
Installing:
 mesa-va-drivers-freeworld x86_64 0:26.2.5-1.fc44 rpmfusion-free-updates  53.0 MiB

Transaction Summary:
 Installing:         1 package

Total size of inbound packages is 14 MiB. Need to download 14 MiB.
After this operation, 53 MiB extra will be used (install 53 MiB, remove 0 B).
Operation aborted by the user.

Install it.

sudo dnf install mesa-va-drivers-freeworld

Expected: the one-package transaction from step 7, then Complete!. Here dnf's log names the install dnf install -y mesa-va-drivers-freeworld, so there was no confirmation prompt. The terminal output:

[…]
Package                    Arch   Version         Repository                  Size
Installing:
 mesa-va-drivers-freeworld x86_64 0:26.2.5-1.fc44 rpmfusion-free-updates  53.0 MiB
[…]
Running transaction
[1/3] Verify package files              100% |  21.0   B/s |   1.0   B |  00m00s
[2/3] Prepare transaction               100% |   1.0   B/s |   1.0   B |  00m01s
[3/3] Installing mesa-va-drivers-freewo 100% |  33.7 MiB/s |  53.0 MiB |  00m02s
Complete!

The package is RPM Fusion's build of the same Mesa version with -Dvideo-codecs=h264dec,h264enc,h265dec,h265enc,vc1dec,av1dec,av1enc,vp9dec, installed into /usr/lib64/dri-freeworld/, the directory libva tries before Fedora's.

Check the installed package.

$ rpm -qi mesa-va-drivers-freeworld | grep -E "^(Version|Release|Install Date|Size|Vendor)"
Version     : 26.2.5
Release     : 1.fc44
Install Date: Sun 25 Oct 2026 04:01:19 PM EET
Size        : 55577925
Vendor      : RPM Fusion

$ dnf repoquery --installed --qf "%{name} %{from_repo}\n" mesa-va-drivers-freeworld
mesa-va-drivers-freeworld rpmfusion-free-updates

Expected: vendor RPM Fusion, the same version as mesa-dri-drivers (26.2.5 in Before you start), and an RPM Fusion repo. Size is in bytes: 55577925 is the 53 MiB from step 7.

Check that both drivers are on disk.
```
$ rpm -qf /usr/lib64/dri/radeonsi_drv_video.so /usr/lib64/dri-freeworld/radeonsi_drv_video.so
mesa-dri-drivers-26.2.5-1.fc44.x86_64
mesa-va-drivers-freeworld-26.2.5-1.fc44.x86_64
```
Expected: Fedora's file still belongs to mesa-dri-drivers, the new one to mesa-va-drivers-freeworld. Nothing of Fedora's was replaced. libva finds the freeworld file first.

List the profiles libva loads now.

$ python3 va_profiles.py
libva info: VA-API version 1.23.0
libva info: Trying to open /usr/lib64/dri-nonfree/radeonsi_drv_video.so
libva info: Trying to open /usr/lib64/dri-freeworld/radeonsi_drv_video.so
libva info: Found init function __vaDriverInit_1_23
libva info: va_openDriver() returns 0
Mesa Gallium driver 26.2.5 for AMD Radeon 780M Graphics (radeonsi, phoenix, ACO, DRM 3.64, 7.2.10-200.fc44.x86_64)
  H264ConstrainedBaseline    VLD EncSlice
  H264Main                   VLD EncSlice
  H264High                   VLD EncSlice
  HEVCMain                   VLD EncSlice
  HEVCMain10                 VLD EncSlice
  VP9Profile0                VLD
  VP9Profile2                VLD
  AV1Profile0                VLD EncSlice
  None                       VideoProc

Expected: libva stops at /usr/lib64/dri-freeworld/, and the list now has H264ConstrainedBaseline, H264Main, H264High, HEVCMain and HEVCMain10, each with VLD (decode) and EncSlice (encode). JPEGBaseline is gone: the freeworld build lists no JPEG decode profile (Notes).

Decode the HEVC clips again, without the variable.

$ ffmpeg -hide_banner -v verbose -hwaccel vaapi -hwaccel_device /dev/dri/renderD128 -hwaccel_output_format vaapi -i main10.mkv -f null -
[…]
[VAAPI @ 0x55bc56360140] libva: Trying to open /usr/lib64/dri-nonfree/radeonsi_drv_video.so
[VAAPI @ 0x55bc56360140] libva: Trying to open /usr/lib64/dri-freeworld/radeonsi_drv_video.so
[VAAPI @ 0x55bc56360140] libva: Found init function __vaDriverInit_1_23
[VAAPI @ 0x55bc56360140] libva: va_openDriver() returns 0
[VAAPI @ 0x55bc56360140] Initialised VAAPI connection: version 1.23
[VAAPI @ 0x55bc56360140] VAAPI driver: Mesa Gallium driver 26.2.5 for AMD Radeon 780M Graphics (radeonsi, phoenix, ACO, DRM 3.64, 7.2.10-200.fc44.x86_64).
[…]
[graph -1 input from stream 0:0 @ 0x7f5fa4004ec0] w:1920 h:1080 pixfmt:vaapi tb:1/1000 fr:30/1 sar:1/1 csp:unknown range:tv alpha:unspecified
[…]
[in#0/matroska,webm @ 0x55bc56358580]   Input stream #0:0 (video): 60 packets read (1211848 bytes); 60 frames decoded; 0 decode errors;
[…]
Exiting with exit code 0

Expected: libva opens the freeworld driver, there is no No support or Failed setup line, and the graph input is pixfmt:vaapi: the GPU decoded the 60 frames. The 8-bit clip:

$ ffmpeg -hide_banner -v verbose -hwaccel vaapi -hwaccel_device /dev/dri/renderD128 -hwaccel_output_format vaapi -i main8.mkv -f null -
[…]
[graph -1 input from stream 0:0 @ 0x7f9718004ec0] w:1920 h:1080 pixfmt:vaapi tb:1/1000 fr:30/1 sar:1/1 csp:unknown range:tv alpha:unspecified
[…]
[in#0/matroska,webm @ 0x56516b88e580]   Input stream #0:0 (video): 60 packets read (1202435 bytes); 60 frames decoded; 0 decode errors;
[…]

Expected: pixfmt:vaapi again.

Make Konsole follow Plasma's light/dark color scheme

Sun, 25 Oct 2026 00:00:00 +0000

Make Konsole switch its windows between a light and a dark profile whenever Plasma's color scheme changes, open windows included, using the profile sync that Konsole 26.08 ships switched off.

Tested on: Fedora 44 desktop, KDE Plasma 6.7.5 on X11, Konsole 26.08.1, kf6-kconfig 6.31.0, Qt 6.11.2 (2026-10-25).
Not verified: Plasma's own scheduled switch (AutomaticLookAndFeel) driving Konsole; I only watched scheme changes I triggered with step 5's commands. A new window opened while Plasma is light, and new tabs: the light-mode windows I tested that day all predate the light profile (Field notes). Starting the test in light mode. The settings-dialog route (Notes). A bundled light scheme such as SolarizedLight; I used my own. Whether a Konsole process that was already running picks up step 3. Wayland, other distributions, Konsole 26.08.0. The rollback on the live desktop (run on copies of the files only).
Needs: Konsole 26.08.0 or newer; a Plasma 6 session; kwriteconfig6 and kreadconfig6 (Fedora package kf6-kconfig); plasma-apply-colorscheme (Fedora package plasma-workspace) for the test; a dark Konsole profile whose file has a ColorScheme= line; a light Konsole color scheme. Optional: strings (binutils) to list Konsole's bundled schemes; xdotool and ImageMagick to screenshot the test window.
Time: 15 min.
Risk: low. The setup is per user: konsolerc gains one group of three keys and one profile file is added. With the sync on, Konsole puts the light or dark profile on every tab of that Konsole process whenever a window opens and at each switch (step 3). The test in step 5 changes Plasma's color scheme for the whole session and leaves an extra ColorScheme= line in ~/.config/kdeglobals; step 1 copies that file and step 6 puts it back. Plasma also rewrote its GTK and Qt theme files under ~/.config/ during my round trip (gtk-3.0/, gtk-4.0/, gtkrc, gtkrc-2.0, xsettingsd/, dconf/user, Trolltech.conf, all written at the second command); I didn't compare them before and after. Undo: delete the three keys and move the light profile out (Undo / rollback).

Before you start#

Konsole is 26.08.0 or newer. That is the first stable release with the setting.
```
$ rpm -q konsole
konsole-26.08.1-1.fc44.x86_64
```
Expected: 26.08.0 or later. On other distributions, ask the package manager.
The sync is still off, and you know which profile Konsole uses now:
```
$ kreadconfig6 --file konsolerc --group LightDarkTheme --key SyncProfileWithSystemTheme

$ kreadconfig6 --file konsolerc --group 'Desktop Entry' --key DefaultProfile
user-default.profile
$ kreadconfig6 --file kdeglobals --group KDE --key AutomaticLookAndFeel
true
```
Expected: an empty line for SyncProfileWithSystemTheme (unset, and off by default). DefaultProfile is the profile file new windows get today; mine is the dark one. AutomaticLookAndFeel is Plasma's own automatic light/dark switching. It was on here; Konsole reacts only to the color scheme, so the manual works without it by the source (not tried with it off).
Your dark profile has a ColorScheme= line, and you have a light scheme:
```
$ cd ~/.local/share/konsole
$ grep -H -e '^Name=' -e '^ColorScheme=' *.profile
user-default.profile:ColorScheme=islands-dark
user-default.profile:Name=user-default
$ ls -1 *.colorscheme
islands-dark.colorscheme
islands-light.colorscheme
```
Expected: the dark profile with its Name= and ColorScheme=. Step 2 assumes the file is named after the profile (<Name>.profile), as mine is. A scheme's name is its .colorscheme file name without the extension. A profile without a ColorScheme= line is not covered here.
If you have no light scheme of your own: Konsole 26.08.1 builds its bundled schemes into its library (in the Fedora package konsole-part), and this lists them:
```
$ strings -e b /usr/lib64/libkonsoleprivate.so.* | grep '\.colorscheme$'
*.colorscheme
RedOnBlack.colorscheme
BlueOnBlack.colorscheme
Breeze.colorscheme
GreenOnBlack.colorscheme
Solarized.colorscheme
SolarizedLight.colorscheme
BlackOnWhite.colorscheme
Campbell.colorscheme
DarkPastels.colorscheme
Linux.colorscheme
BlackOnLightYellow.colorscheme
WhiteOnBlack.colorscheme
BlackOnRandomLight.colorscheme
```
Expected: the bundled scheme names. The first line, *.colorscheme, is a file-name filter from Konsole's code, not a scheme. Going by their names, the light ones are SolarizedLight, BlackOnWhite, BlackOnLightYellow and BlackOnRandomLight. Konsole looks for <name>.colorscheme under ~/.local/share/konsole/ and the system data directories first, then in this bundle (source: ColorSchemeManager.cpp). Mine is islands-light, made from the light variant of my editor theme (Field notes); I haven't put a bundled one in a profile.
Variables instead of placeholders: step 2 sets DARK (your dark profile's Name=), LIGHT (a name for the new light profile) and LIGHT_SCHEME (the light scheme's name). Steps 2 and 3, Verify and the undo use them; in a new shell, set them again. Step 5's screenshot method names <PID>, <WINDOW_ID> and <FILE>.

Steps#

Back up konsolerc, kdeglobals and your profiles.

$ mkdir -p ~/konsole-backup
$ cp -p ~/.config/konsolerc ~/.config/kdeglobals ~/.local/share/konsole/*.profile ~/konsole-backup/
$ ls -1 ~/konsole-backup
kdeglobals
konsolerc
user-default.profile

Expected: the two config files and every .profile file. kdeglobals is in the list because step 5 writes to it.

Make a light twin of the dark profile. Put your names in the second line (mine are shown), then copy the dark profile under the new name with the light scheme:

$ cd ~/.local/share/konsole
$ DARK=user-default LIGHT=user-light LIGHT_SCHEME=islands-light
$ sed -e "s/^Name=.*/Name=$LIGHT/" -e "s/^ColorScheme=.*/ColorScheme=$LIGHT_SCHEME/" "$DARK.profile" > "$LIGHT.profile"
$ diff "$DARK.profile" "$LIGHT.profile"
2c2
< ColorScheme=islands-dark
---
> ColorScheme=islands-light
7c7
< Name=user-default
---
> Name=user-light

Expected: exactly two lines differ, ColorScheme= and Name=. If diff shows only the Name= line, both profiles use the same scheme: Failure modes, row 2.

Turn on the sync and name the two profiles.
```
$ kwriteconfig6 --file konsolerc --group LightDarkTheme --key SyncProfileWithSystemTheme true
$ kwriteconfig6 --file konsolerc --group LightDarkTheme --key LightThemeProfile "$LIGHT"
$ kwriteconfig6 --file konsolerc --group LightDarkTheme --key DarkThemeProfile "$DARK"
$ kreadconfig6 --file konsolerc --group LightDarkTheme --key SyncProfileWithSystemTheme
true
$ kreadconfig6 --file konsolerc --group LightDarkTheme --key LightThemeProfile
user-light
$ kreadconfig6 --file konsolerc --group LightDarkTheme --key DarkThemeProfile
user-default
```
Expected: true, then the light and the dark name, spelled exactly as the profiles' Name= lines. Konsole looks the profiles up by that name; a name that matches no profile gets Konsole's built-in profile instead, without a message (source: ProfileManager.cpp; not tried).

NoteEvery tab gets the pair

Whenever a window opens and on each switch, Konsole sets the light or the dark profile on every session of that Konsole process, so a tab you opened with another profile changes to the pair too (source: applyThemeProfile() in MainWindow.cpp; not tried).
Open a test window in a new Konsole process.
```
konsole --separate &
```
Don't pass --profile: the sync has to choose the profile. --separate starts a new process, which reads konsolerc when it starts, even where Konsole is set to run all windows in one process (source: main.cpp; that option, UseSingleInstance, is off by default). To see the ANSI palette as well as the background, you can run this loop in the test window:
```
for i in 0 1 2 3 4 5 6 7; do printf '\e[3%sm normal%s \e[9%sm bright%s \e[2;3%sm faint%s\e[0m\n' $i $i $i $i $i $i; done
```
It comes from the script I used for one of that afternoon's light-mode screenshots (13:49). The live-switch window in Verify printed a single color0–color7 row instead, with a command I didn't record.

Expected: the colors of the profile for Plasma's current mode. Plasma was dark here and the window came up dark, background pixel 24,25,27.
Switch Plasma to the other scheme and back while the test window is open. First, the scheme the session is on:
```
$ kreadconfig6 --file kdeglobals --group General --key ColorScheme
BreezeDark
```
Expected: the current scheme's name. Here ~/.config/kdeglobals itself has no ColorScheme= line; the value comes from ~/.config/kdedefaults/kdeglobals, which is first in XDG_CONFIG_DIRS in my session. Switch to the other scheme first: by its source, plasma-apply-colorscheme given the scheme that is already set only reports that and changes nothing (not tried). Mine was BreezeDark, so:
```
plasma-apply-colorscheme BreezeLight
```
Wait about 4 s and look at the test window, then switch back:
```
plasma-apply-colorscheme BreezeDark
```
By its source (plasma-workspace 6.7.5), each successful call prints Successfully applied the color scheme <name> to your current Plasma session. Expected: the open window turns light, then dark again.

Screenshots, for the screen half of Verify (optional): save the test window before the first command and about 4 s after each, as ~/konsole-test/1-dark-start.png, 2-after-light.png and 3-after-dark.png (names for a start in dark mode; mkdir -p ~/konsole-test first). I found the window with xdotool search --pid <PID> --onlyvisible, where <PID> is the konsole --separate process ($! right after step 4), and saved it with ImageMagick's import -window <WINDOW_ID> <FILE>. The exact command lines weren't recorded, and my files went to a different directory; I copied them into ~/konsole-test/ for the re-run in Field notes.

Run both directions. On my box a window that comes up dark proves little: DefaultProfile is my dark profile, so with the sync off a new window is dark in dark mode too. The switch to light shows that the sync works. The switch back shows that the dark profile is still dark; if both profiles carry the light scheme (Failure modes, row 2), a window in light mode looks right either way.

These two scheme names are the only ones I tried. My session was dark, on the Breeze Dark global theme (LookAndFeelPackage=org.kde.breezedark.desktop), so the round trip ended in dark mode, where it started. If you start in light mode or on another scheme, end on the one you started from [UNVERIFIED: not tried].

Gotchaplasma-apply-colorscheme writes to kdeglobals

After the round trip, ~/.config/kdeglobals had its own ColorScheme=BreezeDark line under [General] (step 6). A key in that file takes precedence over the kdedefaults value, so the scheme was now set in ~/.config/kdeglobals itself. I put the copy back so the file is as it was. Whether the extra line would block Plasma's automatic switching, I didn't check.
Put kdeglobals back.
```
$ diff ~/konsole-backup/kdeglobals ~/.config/kdeglobals
135a136
> ColorScheme=BreezeDark
$ cp -p ~/konsole-backup/kdeglobals ~/.config/kdeglobals
$ diff ~/konsole-backup/kdeglobals ~/.config/kdeglobals
```
Expected: the first diff shows what the test added (one line here). After the copy, diff prints nothing. The copy brings back the whole file as it was at step 1: if the first diff shows more than the ColorScheme= line, delete that one line in an editor instead (not tried). Don't remove it with kwriteconfig6 --delete: that leaves a ColorScheme[$d] marker behind (Failure modes, row 4). I didn't check what copying the file back does to a running session, so finish step 5 on the scheme you want to keep.
Close the test window and restart Konsole. By its source, Konsole applies the sync when a window is created and when its settings change from inside Konsole (MainWindow.cpp), and I didn't check whether a running Konsole notices an outside edit of konsolerc. A new Konsole process has it, as the test window did.

Measure real btrfs disk use without sudo

Sun, 25 Oct 2026 00:00:00 +0000

Run the host's own compsize as root in a throwaway Docker container to get the real on-disk size of a path on btrfs, with compression and reflinked copies counted correctly, when you are in the docker group but have no sudo.

Tested on: Fedora 44 workstation, kernel 7.2.10-200.fc44, btrfs /home mounted with compress=zstd:1, compsize 1.5^git20250123.d79eacf-15.fc44, coreutils 9.10, Docker CE 29.9.1 (rootful), alpine image 3.24.2 (2026-10-25, on test files). Used on real data on the same workstation on 2026-10-23 or 2026-10-24 (tool versions not recorded).
Not verified: a Docker daemon with SELinux support enabled (selinux in docker info security options); rootless Docker or Podman themselves (only the user-namespace mechanism they rely on, Failure modes row 2); the All empty or still-delalloced files. message compsize prints for data not yet written out.
Needs: a btrfs filesystem; compsize installed on the host as /usr/bin/compsize; access to a rootful Docker daemon, usually through the docker group; the alpine image, or network access to pull it. No sudo.
Time: 5 min.
Risk: nothing on disk changes (except a root-owned ro-test file if the read-only check in Before you start fails), but this is not a low-privilege method. The docker group grants root-level privileges (Docker's own docs). The container runs as root with CAP_SYS_ADMIN, and -v /:/host:ro guards against your own mistakes, not against hostile code in the image. Run it only with an image you trust. The image provides only chroot; the compsize binary and its libraries come from the host. Nothing to undo afterwards.

Before you start#

Optional: a test directory with known content, to check the numbers before you trust them. Every transcript in this manual ran in one scratch directory on the same btrfs /home; the measurements use these three 64 MiB files:
```
$ head -c 64M /dev/urandom > random.bin
$ cp random.bin random-copy.bin
$ yes 'compsize demo: the quick brown fox jumps over the lazy dog' | head -c 64M > text.txt
```
compsize fails as your user, on any file on the btrfs filesystem (here text.txt from the test directory). This is the error the manual works around:
```
$ compsize text.txt
text.txt: SEARCH_V2: Operation not permitted
```

The path is on btrfs, and compression is on:

$ findmnt -no FSTYPE,OPTIONS -T .
btrfs rw,relatime,seclabel,compress=zstd:1,ssd,discard=async,space_cache=v2,subvolid=257,subvol=/home

Expected: btrfs and a compress= option. Use -T <path> for a path that is not the current directory.

compsize is installed on the host, at the path the container will call:
```
$ rpm -q compsize
compsize-1.5^git20250123.d79eacf-15.fc44.x86_64
$ command -v compsize
/usr/bin/compsize
```
Without it the chroot has nothing to run, and installing it needs root.
The Docker daemon is rootful:
```
$ docker info --format '{{.SecurityOptions}}'
[name=seccomp,profile=builtin name=cgroupns]
```
Expected: no rootless entry. A rootless daemon runs containers in a user namespace, where compsize fails the same way as for your user (Failure modes, row 2; rootless Docker itself not tested).
The read-only mount reaches the filesystem that holds your path. /home can be a separate mount under /; on this box it is (subvol=/home above). Docker makes the submounts of a read-only bind read-only too only as a best effort, on kernel 5.12 or newer:
```
$ docker run --rm -v /:/host:ro -w "/host$PWD" alpine touch ro-test
touch: ro-test: Read-only file system
```
Expected: Read-only file system. If touch succeeds instead, the guard does not cover your path, and a root-owned ro-test file is left behind. Remove it through a container, for example docker run --rm -v "$PWD":/w alpine rm /w/ro-test [UNVERIFIED: not exercised, the touch failed here].
The alpine image is present, or docker run pulls it on first use:
```
$ docker run --rm alpine cat /etc/alpine-release
3.24.2
```
Expected: an Alpine version. The measurement uses only its chroot.
Placeholders: <path> is the file or directory to measure, as an absolute path ("$PWD/<name>" or ~/…; a relative path prints No files., Failure modes row 3). <name> is a file or directory in the current directory. <dir> is your test directory.
Backups: none needed. Nothing is written.

Steps#

Flush pending writes.
```
sync
```
Expected: no output. compsize counts only data that already has extents on disk; its man page says recently written files can show as taking no space until they are synced or written out, typically within about 30 seconds.

Run the host's compsize through the container. This is the command as used on real data:

docker run --rm --cap-add SYS_ADMIN -v /:/host:ro alpine chroot /host /usr/bin/compsize -x <path>

On the test directory:

$ docker run --rm --cap-add SYS_ADMIN -v /:/host:ro alpine chroot /host /usr/bin/compsize -x "$PWD"
Processed 3 files, 513 regular extents (514 refs), 0 inline, 325 fragments.
Type       Perc     Disk Usage   Uncompressed Referenced  
TOTAL       51%       66M         128M         192M       
none       100%       64M          64M         128M       
zstd         3%      2.0M          64M          64M

Expected: a Processed N files line, a TOTAL row, and one row per compression type. --cap-add SYS_ADMIN grants the capability that btrfs checks for the search ioctl compsize uses. -v /:/host:ro shows the host's root read-only. chroot /host makes /usr/bin/compsize the host's binary. -x stops at filesystem boundaries, and to compsize a nested btrfs subvolume is one (Failure modes, row 5).

Read the TOTAL row against du.
```
$ du -h random.bin random-copy.bin text.txt
64M	random.bin
64M	random-copy.bin
64M	text.txt
$ du -sh .
192M	.
```
Expected: du matches Referenced (192M), not Disk Usage (66M). From the compsize man page and README: Disk Usage is what the files cost on disk, and every referenced extent is counted once; Uncompressed is the same extents before compression; Referenced is the apparent size of every file, so each reflinked copy counts again. A none row is data btrfs stored uncompressed.

Price duplicates as a set: all copies, then one.

$ docker run --rm --cap-add SYS_ADMIN -v /:/host:ro alpine chroot /host /usr/bin/compsize -x "$PWD/random.bin" "$PWD/random-copy.bin"
Processed 2 files, 1 regular extents (2 refs), 0 inline, 2 fragments.
Type       Perc     Disk Usage   Uncompressed Referenced  
TOTAL      100%       64M          64M         128M       
none       100%       64M          64M         128M       
$ docker run --rm --cap-add SYS_ADMIN -v /:/host:ro alpine chroot /host /usr/bin/compsize -x "$PWD/random.bin"
Processed 1 file, 1 regular extents (1 refs), 0 inline, 1 fragments.
Type       Perc     Disk Usage   Uncompressed Referenced  
TOTAL      100%       64M          64M          64M       
none       100%       64M          64M          64M

Expected: Disk Usage of all copies minus Disk Usage of one copy is what the extra copies really cost. Here it is 64M − 64M = 0, because cp made a reflink: coreutils 9.0 and later default to --reflink=auto, and this box has 9.10. A duplicate finder that adds up file sizes would report 64M wasted.

Verify#

A file with known content gives the expected cost. 64 MiB of repeated text takes 2.0M on disk:

$ docker run --rm --cap-add SYS_ADMIN -v /:/host:ro alpine chroot /host /usr/bin/compsize -x "$PWD/text.txt"
Processed 1 file, 512 regular extents (512 refs), 0 inline, 323 fragments.
Type       Perc     Disk Usage   Uncompressed Referenced  
TOTAL        3%      2.0M          64M          64M       
zstd         3%      2.0M          64M          64M

64 MiB of random data takes 64M, type none (step 4, second command).

Undo / rollback#

Nothing on the filesystem changes: compsize only reads, and the host root is mounted read-only (checked in Before you start).

--rm removes the container when it exits. Checked with a named run:

$ docker run --rm --name compsize-manual-rmcheck-20261025 --cap-add SYS_ADMIN -v /:/host:ro alpine chroot /host /usr/bin/compsize -x "$PWD/text.txt" > /dev/null; docker ps -a --filter name=compsize-manual-rmcheck-20261025 --format '{{.Names}}' | wc -l
0

If docker run pulled alpine only for this, docker image rm alpine removes it [UNVERIFIED: not exercised, the image was already present].
Remove the test directory with rm -r <dir> if you made one [UNVERIFIED: not exercised, the test files are kept as evidence].

Failure modes#

Symptom (exact message)	Cause	Fix
`text.txt: SEARCH_V2: Operation not permitted` (compsize run as your user; the file name comes first)	The btrfs `TREE_SEARCH_V2` ioctl returns EPERM without CAP_SYS_ADMIN (kernel 7.2.10 `fs/btrfs/ioctl.c`).	Step 2.
The same message from root in a user namespace: `unshare -Ur` shows `CapEff: 000001ffffffffff` and compsize still fails	The kernel checks the capability in the initial user namespace. Rootless Docker runs the daemon and its containers inside a user namespace (Docker docs); tested here with `unshare -Ur` only.	A rootful daemon, or an admin who runs compsize.
`No files.`	A relative `<path>`. After `chroot /host` the working directory is `/` (checked with `pwd`), and compsize skips paths that do not exist without an error.	Pass an absolute path: `"$PWD/<name>"` or `~/…`. A relative path given together with absolute ones is skipped the same way, so the total is partial with no error.
`du: cannot read directory './locked': Permission denied` and a total that is too small	`du` runs as your user and skips directories it cannot read, such as a container's database directory with mode 700.	Use the container total: root in the container reads them. On the test directory, a 16 MiB file in a `chmod 000` directory was missing from `du -sh .` (192M) and counted by compsize (Disk Usage 66M → 82M).
No message, but files in a nested subvolume are missing: `Processed 4 files` instead of 5	`-x` skips anything whose device number differs from its parent's, and every btrfs subvolume has its own.	Drop `-x` when the path holds subvolumes you want counted. On the test directory a 16 MiB file in a subvolume made 82M (with `-x`) into 98M (without). Without `-x` compsize also enters other mounts below the path, and per its source it stops at a non-btrfs one with `Not btrfs (or SEARCH_V2 unsupported).` (not exercised).

Field notes#

2026-10-25, workstation: Fedora 44, kernel 7.2.10-200.fc44, btrfs compress=zstd:1 (/home); compsize 1.5^git20250123.d79eacf-15.fc44; Docker CE 29.9.1 (rootful), alpine 3.24.2; coreutils 9.10, overlayfs storage, SELinux enforcing: Every block in this manual was run on test files in a scratch directory on the same /home, not on real data. As the normal user, compsize failed with the file name in front of the error: text.txt: SEARCH_V2: Operation not permitted. The container run worked first time. du said 192M for the directory, compsize said 66M on disk. The 64 MiB cp copy cost nothing (one extent, two references). A compsize run started within a second of writing 64 MiB of text was expected to show the unflushed-data message, but all 512 extents were already counted, so the sync in step 1 is a precaution from the man page, not an observed fix. A touch through the read-only mount failed, so the read-only flag reached the /home submount on this kernel. Root in a user namespace (unshare -Ur, all capabilities) still got EPERM. A relative path printed No files. A directory with mode 000 hid 16 MiB from du but not from the container, and -x silently left out a nested test subvolume. The daemon has no SELinux support enabled, so this run says nothing about one that has.
2026-10-23 or 2026-10-24 (the day was not recorded), same workstation and /home filesystem, tool versions not recorded: On the real disk, compsize ran without sudo, through the rootful Docker daemon (docker group), and each destructive step of the housekeeping waited for my approval. du reported uncompressed sizes. compsize run as my normal user failed on SEARCH_V2 with Operation not permitted, and the container command in step 2 worked. Result: 144 GB of data in 94 GB of disk. 78 GB of it was stored uncompressed: zips, ROMs, maps and model weights, data that btrfs's compression heuristic skips. A Postgres data directory owned by a container's uid (mode 700) made du print Permission denied and undercount by 15.8 GB. A duplicate finder listed 268 sets of identical files of at least 5 MB, 12.4 GB of apparent waste. compsize per set (all copies, then one) put the real figure at 3.4 GB, because cp had already made reflinks: a 2.9 GB speech model and its copy took 2.8 GB together. Recompressing with btrfs filesystem defragment -czstd -L 9 worked without root but gained about 5%, so it was dropped. A live SQLite database had the m (no-compress) attribute on purpose.

Notes#

Without Docker: btrfs filesystem du -s <path> runs as a normal user and separates Exclusive from Set shared, so it does see reflinked copies. It reports uncompressed sizes, though: on the test directory it gave text.txt 64.00MiB, against compsize's 2.0M.
Why chroot into the host instead of a compsize image: no package install inside a root container, and the binary is the host's own. Docker keeps the SYS_CHROOT capability by default.
~/… paths work for <path> because the host shell expands them before docker runs (checked); relative paths do not (Failure modes, row 3).
Higher zstd level: about 5% on the original box, which was put down to btrfs compressing each 128 KiB chunk on its own (the chunk size is in the btrfs docs). btrfs-filesystem(8) warns that defragmenting breaks up reflinks on kernels 3.14-rc2 and later, so do not defragment files whose copies share extents.
The story behind the numbers in the field notes, and why du misled: the btrfs duplicates that weren't.

Sources#

compsize source, compsize.c: the %s: SEARCH_V2: %m error, -x as a device-number comparison, missing paths skipped silently, No files.. Fedora's package is built from commit d79eacf, byte-identical to master when fetched.
compsize man page, compsize.8: meaning of Disk Usage, Uncompressed and Referenced; -x; the caveat about unsynced files; "The ioctls used by this program require root."
compsize README: "every referenced extent is counted whole, exactly once"; the ioctl requires root.
Linux 7.2.10 fs/btrfs/ioctl.c: btrfs_ioctl_tree_search_v2() returns -EPERM unless capable(CAP_SYS_ADMIN).
GNU coreutils NEWS, release 9.0: "cp now uses --reflink=auto mode by default."
Docker: Linux post-installation steps: "The docker group grants root-level privileges to the user."
Docker: security: the daemon needs root unless in rootless mode; only trusted users should control it.
Docker: bind mounts: read-only binds make submounts read-only as a best effort, on kernel 5.12 or newer.
Docker: running containers: default capabilities (DAC_OVERRIDE and SYS_CHROOT kept, SYS_ADMIN only through --cap-add).
Docker: rootless mode: a rootless daemon lists rootless under Security Options in docker info.
btrfs documentation: compression: data is split into 128 KiB chunks before compression; if the first portion compressed does not shrink, compression is disabled for the whole file.
btrfs-filesystem(8) from btrfs-progs 7.1 (man btrfs-filesystem): the defragment warning about breaking up reflinks.

Prune a stale synced copy with an rsync checksum dry run

Sun, 25 Oct 2026 00:00:00 +0000

Compare an old one-way copy of another machine's tree with that machine by checksum, without moving any file contents, delete locally only the top-level entries whose files all exist on the source with the same checksum (git's .git/index and FETCH_HEAD aside), and revoke the temporary SSH key.

Tested on: Fedora 44 (kernel 7.2.10), rsync 3.5.1 protocol 33, GNU findutils 4.10.0, GNU Awk 5.3.2, against a loopback remote shell on synthetic trees (2026-10-25). Original run: a Fedora workstation against an older laptop over SSH (2026-10-23 or 2026-10-24, the day was not recorded); the rsync versions and the laptop's OS were not recorded.
Not verified: steps 1, 10 and 11 against a real SSH server, and step 2 over ssh (it ran through the loopback shell). No second machine was reachable for this manual; the key-removal command ran only against a fake authorized_keys through the loopback shell, and step 11's identity check only as ssh -G.
Needs: bash, rsync on both machines, an SSH login on the source, and the source owner's permission to add a temporary key and remove it again. GNU find and xargs, awk and coreutils on this machine.
Time: about 30 min of hands-on steps (an estimate; the original run was not timed), plus one checksum pass over both trees.
Risk: step 8 deletes local entries for good. Every file in them matched the source by checksum at the step 7 re-check, except .git/index and .git/FETCH_HEAD in git-noise entries: Undo brings back the source's versions of those two, so the copy's own index, and anything staged in it, cannot be restored. Undo needs access to the source again. On the source, step 1 adds one key and step 10 removes it; the dry runs write nothing there, but they make it read every file that has the same size as its local counterpart.

Before you start#

Placeholders used below:
- <ABSOLUTE_PATH_OF_COPY>: root of the stale copy on this machine.
- <USER>@<HOST>: the SSH login on the source machine.
- <PATH_ON_SOURCE>: the tree the copy was made from, relative to that login's home or absolute.
- <KEY>: file name for the temporary key, for example tmp-compare.
- <ENTRY>: one top-level entry name (Undo only).
- <ABSOLUTE_PATH_OF_SHIM>: where you saved the test shim (Notes only).
Set them once, in the bash shell you use for every step (the commands rely on bash splitting an unquoted $RSYNC_RSH into words):
```
LOCAL=<ABSOLUTE_PATH_OF_COPY>
SRC=<USER>@<HOST>
REMOTE=<PATH_ON_SOURCE>
```
Work from a directory outside $LOCAL, for example mkdir -p ~/copy-compare && cd ~/copy-compare. The steps write dry.txt, verdicts.tsv and similar files to the current directory; inside the copy they would turn up in the comparison.

rsync, GNU find, awk, and a UTF-8 character set (in the C locale rsync escapes non-ASCII names; see Failure modes):

$ rsync --version | head -1; find --version | head -1; awk --version | head -1; locale charmap
rsync  version 3.5.1-g315819c5  protocol version 33
find (GNU findutils) 4.10.0
GNU Awk 5.3.2, API 4.0, PMA Avon 8-g1, (GNU MPFR 4.2.2, GNU MP 6.3.0)
UTF-8

Expected: the last line is UTF-8.

Nothing under $LOCAL is unreadable to you:
```
$ find "$LOCAL" $ ! -type l ! -readable -o -type d ! -executable $ -prune -printf '%U %m %P\n'
```
Expected: no output. Each line it prints is an owner uid, a mode and a path that rsync cannot read or enter either. On a test tree with a mode-000 file and a mode-444 directory:
```
$ find "$LOCAL" $ ! -type l ! -readable -o -type d ! -executable $ -prune -printf '%U %m %P\n'
1000 0 both-locked/secret.bin
1000 444 noexec-dir
```
Both kinds can make an entry look identical. rsync prints no itemize line for the contents of a directory it cannot open, which shows up in step 3 as an error. A file it cannot read gets no error at all: when the source's copy of it is unreadable too and has the same size, rsync prints nothing for it (Failure modes, rows 2 and 3). Make the listed paths readable, or move them out of $LOCAL and decide on them separately, before step 3. ! -readable alone misses the mode-444 directory, hence the -executable test. ! -type l leaves symlinks out: rsync compares a symlink's target as text, so one that dangles on this machine is fine, and without that test the check listed a dangling symlink in the same test tree. The original copy held an unreadable directory, a Postgres data directory written by a container: owned by the container's uid, mode 700, and unreadable to du as well.
Backups: none. Nothing is deleted before step 8, and step 8 deletes only entries that step 7 has just re-checked against the source.

Steps#

Create a temporary key and install it on the source.
```
ssh-keygen -t ed25519 -N '' -C tmp-compare -f ~/.ssh/<KEY>
ssh-copy-id -i ~/.ssh/<KEY>.pub "$SRC"
export RSYNC_RSH="ssh -i $HOME/.ssh/<KEY> -o IdentitiesOnly=yes"
```
ssh-copy-id appends the public key to ~/.ssh/authorized_keys on the source, creating the file if needed; it logs in with the account's password (or a key that already works) to do so. RSYNC_RSH is the remote shell rsync uses when no -e is given, so every rsync command below goes through this ssh command. rsync splits the value into separate arguments: a logging shim set as RSYNC_RSH received -i, the key path, -o and IdentitiesOnly=yes as four arguments, followed by the host and rsync. IdentitiesOnly=yes keeps keys held by ssh-agent out of the login; IdentityFile lines from ~/.ssh/config still apply, which is why step 11 tests the key with -F /dev/null. Expected: ssh-copy-id reports one key added. [UNVERIFIED: steps 1 and 2 not run against an SSH server for this manual. The original run used a temporary key; its setup commands were not recorded.]
Check the path and rsync on the source without listing anything. The loopback run (its "source" is a second directory on the same machine, so it reports the local rsync):
```
$ $RSYNC_RSH "$SRC" "test -d $REMOTE && echo dir-ok; command -v rsync && rsync --version | head -1"; echo "rc=$?"
dir-ok
/usr/bin/rsync
rsync  version 3.5.1-g315819c5  protocol version 33
rc=0
```
Expected: three lines, dir-ok, the path of rsync on the source and its version. No dir-ok line: $REMOTE is not a directory there (in the loopback run, a path that does not exist printed only the two rsync lines). No path and version: rsync is not installed there, or not in the remote shell's PATH. The final rc comes from the last command and says nothing about the directory.
Run the checksum dry run, from the copy to the source. The command from the original run, with LOCAL, host and REMOTE as its placeholders: rsync --dry-run -rlc --itemize-changes --out-format='%i %n' LOCAL/ host:REMOTE/ The same command with the variables from Before you start, saving both output streams:
```
$ rsync --dry-run -rlc --itemize-changes --out-format='%i %n' "$LOCAL"/ "$SRC":"$REMOTE"/ > dry.txt 2> dry.err; echo "rc=$?"
rc=0
```
Expected: rc=0 and an empty dry.err (step 4 shows its line count). Anything else: find the cause under Failure modes before going on; step 5 refuses to classify while dry.err has a line.
- --dry-run: rsync works out what it would send and reports it; no file contents are sent and nothing is written on the source. The copy's file list, with names, sizes and checksums, does go to the source (Notes). In the loopback runs, a listing of the source tree with sizes, mtimes and ctimes was the same before and after seven dry runs.
- -c: decide by checksum, not by size and modification time. The local side checksums its files while it builds the file list; the source checksums each of its files that has the same size as the local one, and a file whose size differs is reported without one. The algorithm is negotiated between the two ends (xxh128 between the two rsync 3.5.1 ends of the loopback run), so "identical" below means the same checksum. Without -c, the loopback run missed a same-size edit with an unchanged mtime and flagged a file whose bytes matched but whose mtime did not (Notes).
- -r -l: recurse, and compare symlinks as links instead of following them. Not -a: its -t -p -o -g add attribute-only lines, such as .f..t...... notes/touched.txt for a file with identical bytes, and those would turn an identical entry into differs.
- --itemize-changes --out-format='%i %n': one line per item that would change, made of an 11-character change code, a space and the path relative to $LOCAL. The explicit format leaves out the -> target that --itemize-changes alone appends to symlinks, so every line splits the same way.
- "$LOCAL"/ with the trailing slash: compare the contents of the copy with the contents of $REMOTE. The form without the slash is Failure modes, row 4.
- No --delete: it would itemize files that exist only on the source, and without --dry-run it would delete them there.

Read the itemized lines.

$ cat dry.txt; wc -l dry.txt dry.err
<fcsT...... edited/changed-size.txt
<fc.T...... edited/same-size.txt
cd+++++++++ gone-there/
<f+++++++++ gone-there/NOTES
cd+++++++++ gone-there/src/
<f+++++++++ gone-there/src/main.c
<f+++++++++ grown/new-here.txt
<fcsT...... repo-index/.git/FETCH_HEAD
<fc.T...... repo-index/.git/index
  9 dry.txt
  0 dry.err
  9 total

In this direction the local side is the sender, so every file line starts with <, sent to the remote host. On the loopback trees, notes/, repo-same/, top-file.txt and .dotfile print nothing: every file in them matched by checksum, including one whose mtime differs on the source, and the symlink in notes/ points at the same target on both sides.

Line	Meaning here
no line	the item exists on the source with the same checksum (a symlink: the same target)
`<f+++++++++ path`	file missing on the source
`cd+++++++++ dir/`	directory missing on the source; everything under it follows as new
`cL+++++++++ link`	symlink missing on the source
`<fcsT...... path`	content (`c`) and size (`s`) differ
`<fc.T...... path`	same size, different content

A leading c means the receiver would create the item, a directory or symlink here. The T only says the receiver would set the transfer time as mtime, because times are not preserved; it carries no information here. Line codes by kind:

$ cut -c1-11 dry.txt | sort | uniq -c
      2 cd+++++++++
      3 <f+++++++++
      2 <fcsT......
      2 <fc.T......

GotchaCount <f, not >f

> marks an item received by the local side, which happens in a pull. In the original run my first classifier looked for > and counted zero.

$ grep -c '^>f' dry.txt
0
$ grep -c '^<f' dry.txt
7

Give each top-level entry a verdict. Save this as classify.awk in the working directory:

# classify.awk: one verdict per top-level entry of LOCAL, from a push-direction
#   rsync --dry-run -rlc --itemize-changes --out-format='%i %n' LOCAL/ host:REMOTE/ > dry.txt 2> dry.err
# usage: awk -f classify.awk entries.txt dry.txt dry.err > verdicts.tsv
#   identical   no line: every file under it exists on the source with the same checksum
#   git-noise   only .git/index or .git/FETCH_HEAD differ
#   only-local  the entry itself is missing on the source
#   differs     anything else (new or changed files inside)
# Any line in dry.err, or any line of dry.txt it cannot map to an entry,
# aborts with exit 2 and no verdicts: an unreadable directory prints no line.
FILENAME == ARGV[1] { order[++n] = $0; v[$0] = "identical"; next }
FILENAME == ARGV[3] { print "rsync stderr: " $0 > "/dev/stderr"; bad = 1; next }
{
    code = substr($0, 1, 11); path = substr($0, 13); sub(/\/$/, "", path)
    top = path; sub(/\/.*/, "", top)
    if (substr($0, 12, 1) != " " || !(top in v)) {
        print "unmapped line: " $0 > "/dev/stderr"; bad = 1; next
    }
    new = (substr(code, 3) == "+++++++++")
    if (path == top && new) v[top] = "only-local"
    else if (v[top] == "only-local") next
    else if (!new && path ~ /\/\.git\/(index|FETCH_HEAD)$/) {
        if (v[top] == "identical") v[top] = "git-noise"
    }
    else v[top] = "differs"
}
END {
    if (bad) exit 2
    for (i = 1; i <= n; i++) printf "%s\t%s\n", v[order[i]], order[i]
}

List the entries, then classify:

$ find "$LOCAL" -mindepth 1 -maxdepth 1 -printf '%f\n' | sort > entries.txt; cat entries.txt
.dotfile
edited
gone-there
grown
notes
repo-index
repo-same
top-file.txt
$ awk -f classify.awk entries.txt dry.txt dry.err > verdicts.tsv; echo "rc=$?"; cat verdicts.tsv
rc=0
identical	.dotfile
differs	edited
only-local	gone-there
differs	grown
identical	notes
git-noise	repo-index
identical	repo-same
identical	top-file.txt

Expected: rc=0 and one verdict per entry. rc=2 with rsync stderr: or unmapped line: messages and an empty verdicts.tsv: see Failure modes.

identical: no line under the entry; every file in it exists on the source with the same checksum, and every symlink with the same target.
git-noise: the only differing files are .git/index and .git/FETCH_HEAD, and every object, ref and work-tree file matched by checksum. The index caches each tracked file's stat data, which differs between two machines even for identical files, and git status rewrites it when it refreshes that data; FETCH_HEAD records the last git fetch. On the loopback tree, one git status on the source side and a fetch there from a second URL produced exactly this. The index is also git's staging area, so whatever the copy had staged goes with it; the objects it names are on the source, because no file under .git/objects differed. Any other differing file under .git leaves the entry as differs.
only-local: the entry itself is missing on the source; the copy is the only one.
differs: new or changed files inside; either side may hold the newer version.

List the deletion candidates and look at what stays.

$ awk -F'\t' '$1 == "identical" || $1 == "git-noise" { print $2 }' verdicts.tsv | sort > planned.txt; cat planned.txt
.dotfile
notes
repo-index
repo-same
top-file.txt
$ awk -F'\t' '$1 == "only-local" || $1 == "differs"' verdicts.tsv
differs	edited
only-local	gone-there
differs	grown

Expected: planned.txt holds only identical and git-noise entries. Remove from it anything you want to keep anyway. The other entries stay: an only-local entry exists nowhere else, and a differs entry may hold the newer copy of a file.

Re-run the dry run right before deleting, and keep only entries that still qualify. The source can change between step 3 and the deletion:

rsync --dry-run -rlc --itemize-changes --out-format='%i %n' "$LOCAL"/ "$SRC":"$REMOTE"/ > dry2.txt 2> dry2.err; echo "rc=$?"; cat dry2.err
awk -f classify.awk entries.txt dry2.txt dry2.err > verdicts2.tsv; echo "rc=$?"
awk -F'\t' '$1 == "identical" || $1 == "git-noise" { print $2 }' verdicts2.tsv | sort | comm -12 planned.txt - > delete.txt
comm -23 planned.txt delete.txt | sed 's/^/dropped: /'; cat delete.txt

In the loopback run, a line was appended to notes/b.txt on the source between the two dry runs (a harness step, to show what a change does):

$ rsync --dry-run -rlc --itemize-changes --out-format='%i %n' "$LOCAL"/ "$SRC":"$REMOTE"/ > dry2.txt 2> dry2.err; echo "rc=$?"; cat dry2.err
rc=0
$ awk -f classify.awk entries.txt dry2.txt dry2.err > verdicts2.tsv; echo "rc=$?"
awk -F'\t' '$1 == "identical" || $1 == "git-noise" { print $2 }' verdicts2.tsv | sort | comm -12 planned.txt - > delete.txt
comm -23 planned.txt delete.txt | sed 's/^/dropped: /'; cat delete.txt
rc=0
dropped: notes
.dotfile
repo-index
repo-same
top-file.txt

Expected: rc=0 twice, and delete.txt lists the planned entries that are still identical or git-noise; dropped: lines name those that are not. When the classifier refuses (exit 2), verdicts2.tsv is left empty (0 bytes in the slashless test), so delete.txt comes out empty.

Delete the entries in delete.txt from the copy.

WarningThis step is irreversible on this machine

The entries are gone from the copy. Their files matched the source by checksum at step 7, apart from .git/index and FETCH_HEAD in git-noise entries, whose versions in the copy cannot be brought back. Undo pulls everything else back from the source while the source keeps it.

Size first:

$ (cd "$LOCAL" && xargs -d '\n' du -shc --) < delete.txt
4.0K	.dotfile
132K	repo-index
128K	repo-same
4.0K	top-file.txt
268K	total

Then delete:

while IFS= read -r e; do
  if [ -z "$e" ] || [ "$e" = . ] || [ "$e" = .. ] || [ "${e#*/}" != "$e" ]; then echo "skip: $e" >&2; continue; fi
  rm -rf -- "${LOCAL:?}/$e" && printf 'removed\t%s\n' "$e"
done < delete.txt | tee -a removed.log

$ while IFS= read -r e; do
  if [ -z "$e" ] || [ "$e" = . ] || [ "$e" = .. ] || [ "${e#*/}" != "$e" ]; then echo "skip: $e" >&2; continue; fi
  rm -rf -- "${LOCAL:?}/$e" && printf 'removed\t%s\n' "$e"
done < delete.txt | tee -a removed.log
removed	.dotfile
removed	repo-index
removed	repo-same
removed	top-file.txt

Expected: one removed line per entry in delete.txt and no skip: line. The loop refuses empty names, ., .. and anything containing /, and ${LOCAL:?} makes the shell refuse the rm when $LOCAL is empty or unset instead of running it against /<entry>.

Re-check the copy against the source while you still have access.

$ find "$LOCAL" -mindepth 1 -maxdepth 1 -printf '%f\n' | sort > entries-after.txt
rsync --dry-run -rlc --itemize-changes --out-format='%i %n' "$LOCAL"/ "$SRC":"$REMOTE"/ > dry3.txt 2> dry3.err; echo "rc=$?"
awk -f classify.awk entries-after.txt dry3.txt dry3.err
rc=0
differs	edited
only-local	gone-there
differs	grown
differs	notes

Expected: rc=0, and only only-local and differs verdicts, plus any entry you took out of planned.txt on purpose. notes is differs here because of the source-side edit from step 7.

Remove the temporary key from the source. This is the one change on the source after step 1; ask its owner first.
```
BLOB=$(cut -d' ' -f2 ~/.ssh/<KEY>.pub)
$RSYNC_RSH "$SRC" "cd ~/.ssh && cp -p authorized_keys authorized_keys.tmpkey-bak && { grep -vF '$BLOB' authorized_keys.tmpkey-bak > authorized_keys; [ \$? -le 1 ]; } && rm authorized_keys.tmpkey-bak; grep -cF '$BLOB' authorized_keys"
```
Expected: 0, the number of lines still holding the key (the command exits 1 because that last grep matched nothing). This edits authorized_keys only, the file ssh-copy-id appended to; sshd also reads authorized_keys2 by default, which step 1 did not touch. > rewrites the file in place, so it keeps its mode; the backup is deleted only after the filter succeeded. If grep reports an error instead, authorized_keys may be cut short and the backup is still there: cp -p ~/.ssh/authorized_keys.tmpkey-bak ~/.ssh/authorized_keys on the source puts it back (not run). The same command, run through the loopback shell against a fake home, left a file that had held two other keys plus this one with exactly the two others, and a file that had held only this key empty (0 bytes); both kept mode 600, and the backup was gone both times. It needs a POSIX-style login shell on the source and was tested with /bin/sh only. [UNVERIFIED: not run against a real sshd.]
Close any shared connection and check that the key no longer logs in.
```
ssh -O exit "$SRC"
ssh -G -F /dev/null -i ~/.ssh/<KEY> -o IdentitiesOnly=yes -o BatchMode=yes -o ControlPath=none "$SRC" true | grep -E '^(identityfile|identitiesonly|batchmode|controlpath) '
ssh -F /dev/null -i ~/.ssh/<KEY> -o IdentitiesOnly=yes -o BatchMode=yes -o ControlPath=none "$SRC" true; echo "rc=$?"
```
ssh -O exit closes a master connection if one exists. Without one it fails harmlessly; with a control path that has no master behind it, a local test printed:
```
$ ssh -F /dev/null -o ControlPath=/nonexistent/master.sock -O exit "$SRC"; echo "rc=$?"
Control socket connect(/nonexistent/master.sock): No such file or directory
rc=255
```
ssh -G prints the configuration the test login will use and exits without connecting. With -F /dev/null, ssh reads no ~/.ssh/config and no system-wide config, so the temporary key is the only identity:
```
$ ssh -G -F /dev/null -i keytest/tmp-key -o IdentitiesOnly=yes -o BatchMode=yes -o ControlPath=none "$SRC" true | grep -E '^(identityfile|identitiesonly|batchmode|controlpath) '
batchmode yes
identitiesonly yes
identityfile keytest/tmp-key
```
Without -F /dev/null, an IdentityFile line in a config still joins the list, even with IdentitiesOnly=yes:
```
$ cat keytest/ssh_config; ssh -G -F keytest/ssh_config -i keytest/tmp-key -o IdentitiesOnly=yes "$SRC" true | grep '^identityfile '
Host *
    IdentityFile keytest/other-key
identityfile keytest/tmp-key
identityfile keytest/other-key
```
Expected: the test login fails with a Permission denied message and rc=255. Any other error (Could not resolve hostname, Connection refused) means the test never reached authentication; if the source needs settings from ~/.ssh/config, such as Port or ProxyJump, add them as -o options and test again. Only after a Permission denied, delete the local key files: rm ~/.ssh/<KEY> ~/.ssh/<KEY>.pub; unset RSYNC_RSH.

GotchaAn open master connection logs in without the key

With ControlMaster and ControlPersist in ~/.ssh/config, a master connection stays open in the background after the rsync runs, and later sessions reuse its network connection instead of opening a new one. A test login over it reuses a connection that was authenticated before the key was removed, so it says nothing about the key. -O exit closes the master, ControlPath=none keeps the test off any master, and BatchMode=yes stops ssh from falling back to a password prompt.

[UNVERIFIED: the test login was not run against a real sshd. In the original run the multiplexed connection was closed and a fresh login was checked to fail.]

Restart a Go server under systemd without dropping requests

Sun, 25 Oct 2026 00:00:00 +0000

A .socket unit keeps the port open across restarts, the Go server takes that socket from systemd and drains running requests on SIGTERM, and KillMode=mixed leaves the processes those requests wait on alone, so systemctl --user restart refuses no connection and cuts no stream that ends within the drain budget (2 min here).

Tested on: GEEKOM AE8 mini PC, Fedora Linux 44 (kernel 7.2.10), systemd 259 (259.9-1.fc44) user manager with linger on, Go 1.26.0, curl 8.18.0, iproute2 6.17.0 (2026-10-25). The demo service is tsvdemo-drain on 127.0.0.1:18490 (18491 after step 10).
Not verified: system (root) units; IPv6 and Unix-socket ListenStream= addresses (more than one ListenStream= the server refuses, Failure modes); Accept=yes; TLS and HTTP/2; WebSockets and other hijacked connections; a start at boot from the enabled units (I used the runtime unit directory and enable --runtime, no reboot); FreeBind= for a LAN address.
Needs: a working systemctl --user; Go (1.26.0 here); curl; ss; ports 18490 and 18491 free on 127.0.0.1.
Time: 20 min.
Risk: low for the demo: two units on 127.0.0.1 in a unit directory that a reboot empties. On your own service, a change of the socket unit refuses or resets new connections for as long as the drain runs (step 10), and a TimeoutStopSec= below the drain aborts the stop. Every change here is undone in Undo / rollback.

Before you start#

Versions and linger:

$ systemctl --version | head -1; go version; loginctl show-user "$USER" -p Linger
systemd 259 (259.9-1.fc44)
go version go1.26.0 linux/amd64
Linger=yes

The user manager's default stop timeout. It is 45 s here; the systemd 259 man page says 90 s. Fedora lowered it to 45 s in Fedora 38 (the "Shorter Shutdown Timer" change), and /usr/lib/systemd/user.conf lists #DefaultTimeoutStopSec=45s. A drain longer than this default needs its own TimeoutStopSec= (step 4):
```
$ systemctl --user show -p DefaultTimeoutStopUSec
DefaultTimeoutStopUSec=45s
```

Nothing listens on the demo ports, 18490 and 18491 (header line only):

$ ss -ltn '( sport = :18490 or sport = :18491 )'
State Recv-Q Send-Q Local Address:Port Peer Address:Port

Make a directory for the demo and run every command below from it. UNITDIR is where install-units.sh (step 5) puts the units. I used the runtime unit directory, which systemd reads like ~/.config/systemd/user and which lives on tmpfs (/run/user/<UID>), so a reboot removes the trial. For a permanent install leave UNITDIR unset: the script then writes to ~/.config/systemd/user. Export it again in every new shell: without it install-units.sh installs to ~/.config/systemd/user, and the drop-in and Undo commands below lose their directory.
```
mkdir tsvdemo-drain && cd tsvdemo-drain
export UNITDIR=$XDG_RUNTIME_DIR/systemd/user
```
To apply this to your own service later, copy its unit file first (cp ~/.config/systemd/user/<APP>.service ~/<APP>.service.orig, where <APP> is your unit's name). The demo itself replaces nothing.

Steps#

Write the server. Save it as main.go. listenerFrom takes the socket systemd passes (fd 3, LISTEN_PID = this process, LISTEN_FDS = 1) or binds -listen itself; main unsets the four LISTEN_* variables before any child process starts; the first SIGTERM or SIGINT starts the drain and a second one exits at once; serveUntil waits for Shutdown and calls Close when the drain budget runs out; /stream?n=N sends N events one second apart, and &wait=S first runs sleep S as a child process.

// tsvdemo-drain: an SSE demo that takes its listening socket from systemd and drains on stop.
package main

import (
	"context"
	"errors"
	"flag"
	"fmt"
	"log"
	"net"
	"net/http"
	"os"
	"os/exec"
	"os/signal"
	"strconv"
	"syscall"
	"time"
)

func main() {
	listen := flag.String("listen", "127.0.0.1:18490", "address to bind when not socket-activated")
	drain := flag.Duration("drain", 2*time.Minute, "on stop, how long running requests may finish")
	flag.Parse()

	// The listener first, and the LISTEN_* variables gone, before any child process starts.
	ln, inherited, err := listenerFrom(*listen)
	if err != nil {
		log.Fatal(err)
	}
	for _, k := range []string{"LISTEN_PID", "LISTEN_FDS", "LISTEN_FDNAMES", "LISTEN_PIDFDID"} {
		os.Unsetenv(k)
	}

	// First SIGTERM/SIGINT: drain. A second one: exit at once.
	ctx, cancel := context.WithCancel(context.Background())
	sigs := make(chan os.Signal, 1)
	signal.Notify(sigs, os.Interrupt, syscall.SIGTERM)
	go func() {
		<-sigs
		cancel()
		<-sigs
		log.Print("shutdown: second signal, exiting now")
		os.Exit(1)
	}()

	mux := http.NewServeMux()
	mux.HandleFunc("GET /stream", stream)
	srv := &http.Server{Handler: mux, ReadHeaderTimeout: 10 * time.Second}
	log.Printf("pid %d serving on %s (inherited=%t)", os.Getpid(), ln.Addr(), inherited)
	if err := serveUntil(ctx, srv, ln, *drain); err != nil {
		log.Fatal(err)
	}
	log.Print("exit")
}

// listenerFrom returns the socket systemd passed (fd 3, LISTEN_PID = this process,
// LISTEN_FDS = 1) or, without socket activation, binds addr itself.
func listenerFrom(addr string) (net.Listener, bool, error) {
	if os.Getenv("LISTEN_PID") != strconv.Itoa(os.Getpid()) {
		ln, err := net.Listen("tcp", addr)
		return ln, false, err
	}
	if n := os.Getenv("LISTEN_FDS"); n != "1" {
		return nil, false, fmt.Errorf("systemd passed %q sockets, want 1 (one ListenStream= line)", n)
	}
	f := os.NewFile(3, "systemd-socket")
	ln, err := net.FileListener(f) // a dup; close fd 3 itself so children don't inherit it
	f.Close()
	return ln, true, err
}

// serveUntil serves on ln until ctx ends, lets running requests finish for up to drain, then
// closes what is left. It returns only after that: Serve returns ErrServerClosed as soon as
// Shutdown starts, and a main that returned then would cut every running request.
func serveUntil(ctx context.Context, srv *http.Server, ln net.Listener, drain time.Duration) error {
	done := make(chan struct{})
	go func() {
		defer close(done)
		<-ctx.Done()
		log.Printf("shutdown: draining for up to %s", drain)
		sctx, stop := context.WithTimeout(context.Background(), drain)
		defer stop()
		if err := srv.Shutdown(sctx); err != nil {
			log.Printf("shutdown: drain time over (%v), closing", err)
			srv.Close()
			return
		}
		log.Print("shutdown: all requests finished")
	}()
	err := srv.Serve(ln)
	if errors.Is(err, http.ErrServerClosed) {
		<-done
		return nil
	}
	return err
}

// stream sends n events, one per second. With wait=S it first runs `sleep S` as a child
// process: a stand-in for an ssh call or a helper the request waits on.
func stream(w http.ResponseWriter, r *http.Request) {
	n, _ := strconv.Atoi(r.URL.Query().Get("n"))
	if s := r.URL.Query().Get("wait"); s != "" {
		if err := exec.CommandContext(r.Context(), "sleep", s).Run(); err != nil {
			log.Printf("stream: child failed: %v", err)
			http.Error(w, "child failed: "+err.Error(), http.StatusBadGateway)
			return
		}
	}
	w.Header().Set("Content-Type", "text/event-stream")
	rc := http.NewResponseController(w)
	for i := 1; i <= n; i++ {
		fmt.Fprintf(w, "data: pid=%d event=%d/%d\n\n", os.Getpid(), i, n)
		if err := rc.Flush(); err != nil {
			log.Printf("stream: client gone after %d/%d events", i, n)
			return
		}
		if i < n {
			select {
			case <-r.Context().Done():
				log.Printf("stream: cut after %d/%d events", i, n)
				return
			case <-time.After(time.Second):
			}
		}
	}
	log.Printf("stream: %d events sent", n)
}

Create the module and build it:

$ go mod init tsvdemo-drain
go: creating new go.mod: module tsvdemo-drain
go: to add module requirements and sums:
	go mod tidy
$ go vet ./... && go build -o tsvdemo-drain . && ./tsvdemo-drain -h
Usage of ./tsvdemo-drain:
  -drain duration
    	on stop, how long running requests may finish (default 2m0s)
  -listen string
    	address to bind when not socket-activated (default "127.0.0.1:18490")

Expected: no output from go vet, then the two flags.

Check the fallback without systemd. Started by hand, the server binds the address itself; SIGINT drains and exits 0:

$ ./tsvdemo-drain & sleep 0.5; curl -sN 'http://127.0.0.1:18490/stream?n=3'; kill -INT $!; wait $!; echo "exit status $?"
2026/10/25 14:20:56 pid 2187190 serving on 127.0.0.1:18490 (inherited=false)
data: pid=2187190 event=1/3

data: pid=2187190 event=2/3

data: pid=2187190 event=3/3

2026/10/25 14:20:59 stream: 3 events sent
2026/10/25 14:20:59 shutdown: draining for up to 2m0s
2026/10/25 14:20:59 shutdown: all requests finished
2026/10/25 14:20:59 exit
exit status 0

Expected: inherited=false, three events, shutdown: all requests finished, exit status 0. The log lines go to stderr, so they interleave with curl's output. Pasted into an interactive bash, the same line also prints the job lines [1] <PID> before the first log line and [1]+ Done … ./tsvdemo-drain before exit status 0.

Write the socket unit. Save it as tsvdemo-drain.socket:
```
[Unit]
Description=tsvdemo-drain socket: held across restarts, so connections wait while the old process drains

[Socket]
ListenStream=127.0.0.1:18490

[Install]
WantedBy=sockets.target
```
- One ListenStream= line: the server refuses any LISTEN_FDS other than 1 (Failure modes).
- An IP literal with a port: systemd-analyze refuses Go's :18490 and localhost:18490 forms (Failure modes).
- Accept= stays at its default, no: the listening socket itself goes to one service process.
Write the service unit. Save it as tsvdemo-drain.service; install-units.sh replaces @DEMO@ with the demo directory.
```
[Unit]
Description=tsvdemo-drain: SSE demo that drains running requests on stop
# Wants, not Requires: if the socket cannot bind, the service tries to bind the address
# itself and Restart= retries.
Wants=tsvdemo-drain.socket
After=tsvdemo-drain.socket

[Service]
ExecStart=@DEMO@/tsvdemo-drain -listen 127.0.0.1:18490 -drain 2m
Restart=on-failure
RestartSec=5
# SIGTERM to the main process only: children it waits on keep running during the drain.
# Whatever is left in the cgroup gets SIGKILL after the main process exits.
KillMode=mixed
# Above -drain: when the stop times out, systemd ends the drain.
TimeoutStopSec=150

[Install]
WantedBy=default.target
```
- Wants= and After= the socket: starting the service starts the socket first. With Requires=, a socket that cannot bind fails the service as a dependency and nothing retries; with Wants= the server tries to bind by itself, Restart=on-failure retries every 5 s, and the first retry after the port is free gets the socket again (Failure modes).
- KillMode=mixed: the default, control-group, sends SIGTERM to every process in the unit when the stop begins, so a child process a request waits on dies at once (step 8).
- TimeoutStopSec=150, above -drain 2m: when the stop timeout runs out, systemd ends the drain (Failure modes).
- -listen repeats the socket's address. The server uses it only without the socket; change both together.

Write the install script. Save it as install-units.sh. It checks both units with systemd-analyze before it stops anything. A new or changed socket file means stop of socket and service in one call, then start of both: with the service stopped alone, a client that connects during the drain starts it again through the socket, and the socket then refuses to restart while its service runs (Failure modes). An unchanged socket means stop of the service only, while new connections queue on the open socket, then start of both.

#!/bin/bash
# Install or update the tsvdemo-drain units and (re)start them without refusing connections.
set -euo pipefail
cd "$(dirname "$0")"
UNITDIR=${UNITDIR:-$HOME/.config/systemd/user}
mkdir -p "$UNITDIR" build
sed "s|@DEMO@|$PWD|" tsvdemo-drain.service > build/tsvdemo-drain.service
cp tsvdemo-drain.socket build/
systemd-analyze --user verify build/tsvdemo-drain.socket build/tsvdemo-drain.service
if cmp -s build/tsvdemo-drain.socket "$UNITDIR/tsvdemo-drain.socket"; then moved=; else moved=1; fi
install -m644 build/tsvdemo-drain.socket build/tsvdemo-drain.service "$UNITDIR/"
systemctl --user daemon-reload
if [ -n "$moved" ]; then
  # New or changed socket: stop both in one call, so no client re-activates the service in between.
  echo "socket file changed: stopping socket and service, then starting both"
  systemctl --user stop tsvdemo-drain.socket tsvdemo-drain.service
  systemctl --user start tsvdemo-drain.socket tsvdemo-drain.service
else
  # Same socket: stop the service behind it (new connections queue while it drains), start both.
  echo "socket file unchanged: restarting the service behind the open socket"
  systemctl --user stop tsvdemo-drain.service
  systemctl --user start tsvdemo-drain.socket tsvdemo-drain.service
fi

Make it executable:

$ chmod +x install-units.sh

Install, enable and start the units. For a permanent install, leave out --runtime.

$ echo "UNITDIR=$UNITDIR"; ./install-units.sh
UNITDIR=/run/user/1000/systemd/user
socket file changed: stopping socket and service, then starting both
$ systemctl --user enable --runtime tsvdemo-drain.socket tsvdemo-drain.service
Created symlink '/run/user/1000/systemd/user/sockets.target.wants/tsvdemo-drain.socket' → '/run/user/1000/systemd/user/tsvdemo-drain.socket'.
Created symlink '/run/user/1000/systemd/user/default.target.wants/tsvdemo-drain.service' → '/run/user/1000/systemd/user/tsvdemo-drain.service'.

Check that the service got the socket:

$ systemctl --user is-active tsvdemo-drain.socket tsvdemo-drain.service; ss -ltnp 'sport = :18490'
active
active
State  Recv-Q Send-Q Local Address:Port  Peer Address:PortProcess                                    
LISTEN 0      4096       127.0.0.1:18490      0.0.0.0:*    users:(("tsvdemo-drain",pid=2187490,fd=5))
$ journalctl --user -u tsvdemo-drain.service -g serving -n 1 -o cat; tr "\0" "\n" < /proc/$(systemctl --user show -p MainPID --value tsvdemo-drain.service)/environ | grep ^LISTEN_
2026/10/25 14:21:00 pid 2187490 serving on 127.0.0.1:18490 (inherited=true)
LISTEN_PID=2187490
LISTEN_PIDFDID=14783253
LISTEN_FDS=1
LISTEN_FDNAMES=tsvdemo-drain.socket

Expected: both units active; one LISTEN line on 127.0.0.1:18490; inherited=true in the log. /proc/<PID>/environ shows the environment systemd set at exec, including LISTEN_PIDFDID, which systemd 259 adds; the server's os.Unsetenv doesn't change that file, it changes what children get (step 8). If the log says inherited=false, see Failure modes.

Restart while a stream runs. Save restart-test.sh. Stream A asks for 15 events; the restart starts after 3.5 s; request B is made 2 s into the drain; ss shows the listening socket 1 s later. A second argument replaces the restart command (step 10).

#!/bin/bash
# Restart tsvdemo-drain while stream A (15 events) runs; request B is made during the drain.
# usage: restart-test.sh [PORT [COMMAND...]]; COMMAND defaults to systemctl --user restart.
P=${1:-18490}
U=http://127.0.0.1:$P
shift
[ $# -gt 0 ] || set -- systemctl --user restart tsvdemo-drain.service
ts() { date +%T.%3N; }
stamp() { while IFS= read -r l; do [ -n "$l" ] && echo "$(ts) $1 $l"; done; }
{ curl -sSN "$U/stream?n=15" -w 'http=%{http_code}\n' 2>&1; echo "curl rc=$?"; } | stamp A &
sleep 3.5
echo "$(ts) restart begins"
("$@"; echo "$(ts) restart returned rc=$?") &
sleep 2
echo "$(ts) B starts"
{ curl -sSN "$U/stream?n=1" -w 'http=%{http_code} connect=%{time_connect}s total=%{time_total}s\n' 2>&1; echo "curl rc=$?"; } | stamp B &
sleep 1
ss -Hltnp "sport = :$P" | stamp ss
wait

$ chmod +x restart-test.sh
$ ./restart-test.sh
14:21:00.774 A data: pid=2187490 event=1/15
14:21:01.775 A data: pid=2187490 event=2/15
14:21:02.776 A data: pid=2187490 event=3/15
14:21:03.777 A data: pid=2187490 event=4/15
14:21:04.271 restart begins
14:21:04.778 A data: pid=2187490 event=5/15
14:21:05.778 A data: pid=2187490 event=6/15
14:21:06.274 B starts
14:21:06.778 A data: pid=2187490 event=7/15
14:21:07.317 ss LISTEN 1      4096   127.0.0.1:18490 0.0.0.0:*
14:21:07.780 A data: pid=2187490 event=8/15
14:21:08.780 A data: pid=2187490 event=9/15
14:21:09.781 A data: pid=2187490 event=10/15
14:21:10.781 A data: pid=2187490 event=11/15
14:21:11.783 A data: pid=2187490 event=12/15
14:21:12.784 A data: pid=2187490 event=13/15
14:21:13.785 A data: pid=2187490 event=14/15
14:21:14.785 A data: pid=2187490 event=15/15
14:21:14.787 A http=200
14:21:14.789 A curl rc=0
14:21:15.293 restart returned rc=0
14:21:15.306 B data: pid=2188843 event=1/1
14:21:15.307 B http=200 connect=0.000108s total=9.024878s
14:21:15.307 B curl rc=0

Expected: A gets 15 of 15 events from the old PID and curl rc=0. B's connect completes in 0.11 ms, before the new process exists, and B gets its event from the new PID once the drain ends (9.0 s later here). During the drain the old process has already closed its listener (Shutdown closes the listeners first), yet ss shows the port listening, with Recv-Q at 1 while B waits and no process listed: systemd keeps its own copy of the socket. systemctl restart returns when the drain is over (11.0 s here). The journal for the same restart:

$ journalctl --user -u tsvdemo-drain.service --since -30s -o short-precise
Oct 25 14:21:00.455060 host systemd[1397]: Started tsvdemo-drain.service - tsvdemo-drain: SSE demo that drains running requests on stop.
Oct 25 14:21:00.466518 host tsvdemo-drain[2187490]: 2026/10/25 14:21:00 pid 2187490 serving on 127.0.0.1:18490 (inherited=true)
Oct 25 14:21:04.276149 host tsvdemo-drain[2187490]: 2026/10/25 14:21:04 shutdown: draining for up to 2m0s
Oct 25 14:21:04.276225 host systemd[1397]: Stopping tsvdemo-drain.service - tsvdemo-drain: SSE demo that drains running requests on stop...
Oct 25 14:21:14.784301 host tsvdemo-drain[2187490]: 2026/10/25 14:21:14 stream: 15 events sent
Oct 25 14:21:15.288520 host tsvdemo-drain[2187490]: 2026/10/25 14:21:15 shutdown: all requests finished
Oct 25 14:21:15.288520 host tsvdemo-drain[2187490]: 2026/10/25 14:21:15 exit
Oct 25 14:21:15.289782 host systemd[1397]: Stopped tsvdemo-drain.service - tsvdemo-drain: SSE demo that drains running requests on stop.
Oct 25 14:21:15.291662 host systemd[1397]: Started tsvdemo-drain.service - tsvdemo-drain: SSE demo that drains running requests on stop.
Oct 25 14:21:15.304665 host tsvdemo-drain[2188843]: 2026/10/25 14:21:15 pid 2188843 serving on 127.0.0.1:18490 (inherited=true)
Oct 25 14:21:15.305812 host tsvdemo-drain[2188843]: 2026/10/25 14:21:15 stream: 1 events sent

Restart while a request waits on a child process. Save child-test.sh. Request A runs sleep 10 as a child of the server, then streams 3 events; the restart starts 2 s in. The script also prints the child's file descriptors and how many LISTEN_* variables it inherited.

#!/bin/bash
# Restart tsvdemo-drain while request A waits on a child process (sleep 10) before it streams 3 events.
U=http://127.0.0.1:${1:-18490}
ts() { date +%T.%3N; }
stamp() { while IFS= read -r l; do [ -n "$l" ] && echo "$(ts) $1 $l"; done; }
{ curl -sSN "$U/stream?n=3&wait=10" -w 'http=%{http_code}\n' 2>&1; echo "curl rc=$?"; } | stamp A &
sleep 2
main=$(systemctl --user show -p MainPID --value tsvdemo-drain.service)
child=$(pgrep -P "$main" -x sleep)
echo "$(ts) child: pid $child, fds: $(ls /proc/$child/fd | tr '\n' ' ')LISTEN_ variables: $(tr '\0' '\n' < /proc/$child/environ | grep -c '^LISTEN_')"
echo "$(ts) restart begins"
systemctl --user restart tsvdemo-drain.service
echo "$(ts) restart returned rc=$?"
wait

$ chmod +x child-test.sh
$ ./child-test.sh
14:21:17.873 child: pid 2188987, fds: 0 1 2 LISTEN_ variables: 0
14:21:17.878 restart begins
14:21:25.841 A data: pid=2188843 event=1/3
14:21:26.842 A data: pid=2188843 event=2/3
14:21:27.843 A data: pid=2188843 event=3/3
14:21:27.845 A http=200
14:21:27.846 A curl rc=0
14:21:27.988 restart returned rc=0

Expected: the child has only fds 0, 1 and 2 and no LISTEN_* variable; it keeps running through the drain, A gets 3 of 3 events, and the restart returns after them (10.1 s here).

GotchaThe default KillMode kills the child the request waits on

With KillMode=control-group, the SIGTERM of the stop reaches the child too: the request fails with 502 within 6 ms of the restart, and the drain has nothing left to wait for. The same test with a drop-in, then the drop-in removed:

$ mkdir -p "$UNITDIR/tsvdemo-drain.service.d" && printf "[Service]\nKillMode=control-group\n" > "$UNITDIR/tsvdemo-drain.service.d/killmode.conf" && systemctl --user daemon-reload && systemctl --user show -p KillMode tsvdemo-drain.service
KillMode=control-group
$ ./child-test.sh
14:21:30.796 child: pid 2189923, fds: 0 1 2 LISTEN_ variables: 0
14:21:30.801 restart begins
14:21:30.807 A child failed: signal: terminated
14:21:30.808 A http=502
14:21:30.809 A curl rc=0
14:21:30.811 restart returned rc=0
$ rm "$UNITDIR/tsvdemo-drain.service.d/killmode.conf" && rmdir "$UNITDIR/tsvdemo-drain.service.d" && systemctl --user daemon-reload && systemctl --user show -p KillMode tsvdemo-drain.service
KillMode=mixed

End a drain early (optional). A second SIGTERM to the main process makes the server exit at once; a restart then goes on with the new process. The command is systemctl --user kill --kill-whom=main --signal=SIGTERM tsvdemo-drain.service. Save abort-test.sh to see it during a 60-event stream:

#!/bin/bash
# Restart tsvdemo-drain during a 60-event stream, then end the drain early with a second SIGTERM.
U=http://127.0.0.1:${1:-18490}
ts() { date +%T.%3N; }
stamp() { while IFS= read -r l; do [ -n "$l" ] && echo "$(ts) $1 $l"; done; }
{ curl -sSN "$U/stream?n=60" -w 'http=%{http_code}\n' 2>&1; echo "curl rc=$?"; } | stamp A &
sleep 2.5
echo "$(ts) restart begins"
(systemctl --user restart tsvdemo-drain.service; echo "$(ts) restart returned rc=$?") &
sleep 3
echo "$(ts) second SIGTERM to the main process"
systemctl --user kill --kill-whom=main --signal=SIGTERM tsvdemo-drain.service
wait

$ chmod +x abort-test.sh
$ ./abort-test.sh
14:21:31.564 A data: pid=2190293 event=1/60
14:21:32.565 A data: pid=2190293 event=2/60
14:21:33.566 A data: pid=2190293 event=3/60
14:21:34.059 restart begins
14:21:34.566 A data: pid=2190293 event=4/60
14:21:35.566 A data: pid=2190293 event=5/60
14:21:36.567 A data: pid=2190293 event=6/60
14:21:37.062 second SIGTERM to the main process
14:21:37.069 A curl: (18) transfer closed with outstanding read data remaining
14:21:37.070 A http=200
14:21:37.071 A curl rc=18
14:21:37.072 restart returned rc=0

Expected: A is cut (curl: (18)) 3.0 s into the drain, and the restart returns 10 ms after the second signal. The journal records exit status 1 as Failed with result 'exit-code', then starts the new process on the socket:

$ journalctl --user -u tsvdemo-drain.service --since -15s -o short-precise
[…]
Oct 25 14:21:34.065330 host systemd[1397]: Stopping tsvdemo-drain.service - tsvdemo-drain: SSE demo that drains running requests on stop...
Oct 25 14:21:34.065848 host tsvdemo-drain[2190293]: 2026/10/25 14:21:34 shutdown: draining for up to 2m0s
Oct 25 14:21:37.067622 host systemd[1397]: tsvdemo-drain.service: Sent signal SIGTERM to main process 2190293 (tsvdemo-drain) on client request.
Oct 25 14:21:37.068169 host tsvdemo-drain[2190293]: 2026/10/25 14:21:37 shutdown: second signal, exiting now
Oct 25 14:21:37.068962 host systemd[1397]: tsvdemo-drain.service: Main process exited, code=exited, status=1/FAILURE
Oct 25 14:21:37.069055 host systemd[1397]: tsvdemo-drain.service: Failed with result 'exit-code'.
Oct 25 14:21:37.069645 host systemd[1397]: Stopped tsvdemo-drain.service - tsvdemo-drain: SSE demo that drains running requests on stop.
Oct 25 14:21:37.071006 host systemd[1397]: Started tsvdemo-drain.service - tsvdemo-drain: SSE demo that drains running requests on stop.
Oct 25 14:21:37.088652 host tsvdemo-drain[2190806]: 2026/10/25 14:21:37 pid 2190806 serving on 127.0.0.1:18490 (inherited=true)

Apply later changes with install-units.sh. After an edit to the service file only (here its Description=), the socket file is unchanged: the script stops the service behind the open socket and then starts both, so a request made meanwhile queues as in step 7:

$ sed -i 's/^Description=tsvdemo-drain:/Description=tsvdemo-drain (edited):/' tsvdemo-drain.service && ./restart-test.sh 18490 ./install-units.sh
14:21:37.604 A data: pid=2190806 event=1/15
14:21:38.605 A data: pid=2190806 event=2/15
14:21:39.605 A data: pid=2190806 event=3/15
14:21:40.606 A data: pid=2190806 event=4/15
14:21:41.098 restart begins
socket file unchanged: restarting the service behind the open socket
14:21:41.606 A data: pid=2190806 event=5/15
14:21:42.608 A data: pid=2190806 event=6/15
14:21:43.101 B starts
14:21:43.609 A data: pid=2190806 event=7/15
14:21:44.149 ss LISTEN 1      4096   127.0.0.1:18490 0.0.0.0:*
14:21:44.610 A data: pid=2190806 event=8/15
14:21:45.610 A data: pid=2190806 event=9/15
14:21:46.610 A data: pid=2190806 event=10/15
14:21:47.611 A data: pid=2190806 event=11/15
14:21:48.613 A data: pid=2190806 event=12/15
14:21:49.614 A data: pid=2190806 event=13/15
14:21:50.614 A data: pid=2190806 event=14/15
14:21:51.615 A data: pid=2190806 event=15/15
14:21:51.616 A http=200
14:21:51.617 A curl rc=0
Stopping 'tsvdemo-drain.service', but its triggering units are still active:
tsvdemo-drain.socket
14:21:51.727 restart returned rc=0
14:21:51.737 B data: pid=2192112 event=1/1
14:21:51.738 B http=200 connect=0.000108s total=8.627194s
14:21:51.739 B curl rc=0

Expected: socket file unchanged: …, systemd's warning that the socket is still active (that is the point here), B queued and answered by the new PID.

After an edit to the socket file (here the address, in both files), the script stops socket and service in one call before it starts both:

$ sed -i 's/127.0.0.1:18490/127.0.0.1:18491/' tsvdemo-drain.socket tsvdemo-drain.service && ./install-units.sh
socket file changed: stopping socket and service, then starting both
$ ss -ltnp '( sport = :18490 or sport = :18491 )'; journalctl --user -u tsvdemo-drain.service -g serving -n 1 -o cat
State  Recv-Q Send-Q Local Address:Port  Peer Address:PortProcess                                    
LISTEN 0      4096       127.0.0.1:18491      0.0.0.0:*    users:(("tsvdemo-drain",pid=2192375,fd=5))
2026/10/25 14:21:52 pid 2192375 serving on 127.0.0.1:18491 (inherited=true)

Expected: socket file changed: …, one LISTEN line on 18491, and inherited=true on 18491.

NoteA socket change refuses or resets new connections until the drain ends

In a separate run of the same move (18490 to 18491) with a stream running, two requests made during the drain, one to each port, both failed at once with curl: (7) … Could not connect to server, while the stream on the old port finished 8 of 8. With the address unchanged and another line of the socket file edited, a request made during the drain connected, waited, and got curl: (56) Recv failure: Connection reset by peer when the socket closed after the service. A plain restart (steps 7–9) has neither problem.

Stop docker compose from orphaning anonymous volumes

Sun, 25 Oct 2026 00:00:00 +0000

Tear a script's compose stack down with docker compose rm -fsv, then docker compose down, in one EXIT trap, so each run's anonymous volumes are deleted with their containers and the named volumes stay.

Tested on: a Fedora 44 workstation (x86_64), Docker Engine 29.9.1 with the containerd image store, Docker Compose v5.6.0, GNU bash 5.3.9, GNU coreutils 9.10 for timeout (2026-10-25), against a throwaway test stack.
Not verified: Docker Desktop, rootless Docker, Podman, other Compose versions, one-off containers from docker compose run, moving data out of an anonymous volume.
Needs: Docker Engine with the Compose plugin and permission to run docker; the script that brings your stack up and down; network access to pull alpine:3.24.2 for the test stack.
Time: 15 min.
Risk: rm -v deletes the anonymous volumes of the containers it removes, and there is no undo for that. Anything you want to keep must sit in a named volume or a bind mount before you change the teardown (checked in Before you start). Named volumes and bind mounts are not touched.

Before you start#

Docker, Compose and bash versions, and whether the test image tag is already on the box (0 = no; Undo removes the tag only in that case):

$ docker version --format '{{.Server.Version}}'
29.9.1
$ docker compose version
Docker Compose version v5.6.0
$ bash --version | head -1
GNU bash, version 5.3.9(1)-release (x86_64-redhat-linux-gnu)
$ docker image ls --filter 'reference=alpine:3.24.2' --format '{{.Repository}}:{{.Tag}}' | wc -l
0

Placeholders used below:
- <SCRIPT> — the script that runs your stack (benchmark, test run).
- <PROJECT> — the Compose project name it uses: the -p value; without -p, Compose takes COMPOSE_PROJECT_NAME, then a top-level name: in the compose file, then the name of the directory holding the compose file.
- <CONTAINER> — one container of that stack, as listed by docker compose -p <PROJECT> ps.
- <VOLUME> — the name of one anonymous volume (64 hex characters).
Back up the script: cp <SCRIPT> <SCRIPT>.bak. Edit <SCRIPT> only while no run of it is in progress: bash reads a script as it executes it.
With your stack up, run this for each container listed by docker compose -p <PROJECT> ps. Every volume row with a 64-character hex name is anonymous, and the new teardown deletes it:
```
docker inspect -f '{{.Name}}{{range .Mounts}}{{println}}  {{.Type}} {{.Name}} -> {{.Destination}}{{end}}' <CONTAINER>
```
Output for a stand-in image that declares MongoDB's two VOLUME paths, run with a named volume on /data/db only (how it was built: Field notes):
```
$ docker inspect -f '{{.Name}}{{range .Mounts}}{{println}}  {{.Type}} {{.Name}} -> {{.Destination}}{{end}}' anonvol2-db-1
/anonvol2-db-1
  volume 5f8dc2fb359c192091a7e14bd087a2251ed275b05247a9d3289028cfe992a54a -> /data/configdb
  volume anonvol2_dbdata -> /data/db
```
Anonymous volumes come from two places: a Compose volumes: entry with only a container path (- /anon), and every VOLUME path in the image that nothing is mounted onto. Current official images declare, for example: mongo VOLUME /data/db /data/configdb (7.0 to 9.0); postgres VOLUME /var/lib/postgresql/data (16, 17) and VOLUME /var/lib/postgresql (18); mysql and mariadb VOLUME /var/lib/mysql.

If a row you need is anonymous, stop here. Pointing that path at a new named volume does not move the data: in a probe on the same box (a - /data entry, and an image VOLUME path), the recreated container saw an empty directory both times, and in the - /data case the old data was still in the previous anonymous volume, now attached to nothing, which is the kind of volume docker volume prune deletes. Copy the data into a named volume first; that procedure is not covered here.