Point dnsmasq at the OpenWrt gateway only while its own process is listening

start_service switched dnsmasq's .fips forwarding to the gateway's port
before the gateway ran. A gateway that then failed, on a config it could
not parse or on a NAT or route error after binding, left every LAN
client's .fips lookups going to a port nothing held, until someone
started the gateway by hand; procd gives up respawning after five
failures and says nothing.

procd now runs the init script's supervise command, which starts the
gateway, switches dnsmasq to its port once the gateway's own process holds
a socket bound there, and switches it back to the daemon's port when the
gateway exits for any reason, passing procd's SIGTERM on so the gateway can
clean up. Ownership is checked by matching a socket inode for the port in
/proc/net/udp{,6} against the gateway's open descriptors, so a port held by
something else, such as an mDNS responder on 5353, is never mistaken for the
gateway. supervise records the gateway's pid in /var/run/fips-gateway.pid,
and an exiting instance skips the swap back only when the gateway named
there, the one procd started in its place, holds the port. Every change to
the dnsmasq entry is made under one lock, so a stopping and a starting
gateway cannot interleave. stop_service still swaps back as before. The
exit status is the gateway's, so procd's respawn behaves as it did.

procd sends SIGTERM to the supervise shell and, five seconds later, SIGKILL
to that shell alone, so a gateway slow to stop would outlive it, holding its
port. supervise kills the gateway three seconds after passing the SIGTERM
on, and stops its watcher as soon as the gateway is gone.

A new scenario runs the command start_service hands procd against stub
gateways that hold their socket themselves and exit before binding, fail
after binding, are stopped by SIGTERM, or ignore it, against a port taken by
another process, and against a swap back with a process other than the
successor holding the port, and checks dnsmasq ends on the daemon's port
each time.

docs/tutorials/deploy-fips-gateway.md

@@ -176,7 +176,10 @@ Behind that single command, the init script
    the LAN's port 53 are forwarded to the gateway's loopback
    listener on port 5365 instead of going straight to the daemon's
    resolver on port 5354. (Dnsmasq still owns 53; the gateway sits
-   in front of the daemon for `.fips` only.)
+   in front of the daemon for `.fips` only.) The switch happens once
+   the gateway is listening, and dnsmasq goes back to port 5354
+   whenever the gateway exits, so a gateway that fails to start
+   leaves `.fips` resolving through the daemon.
 3. **Adds a global-scope IPv6 prefix** to `br-lan`. Without a
    non-ULA address on the local interface, Android and Chrome
    suppress AAAA queries entirely — they assume the LAN has no

packaging/openwrt-ipk/files/etc/init.d/fips-gateway

@@ -12,6 +12,10 @@ USE_PROCD=1
 START=96
 STOP=09
 
+# procd runs "supervise" (below) rather than the gateway itself.
+EXTRA_COMMANDS="supervise"
+EXTRA_HELP="\tsupervise       Run the gateway, pointing dnsmasq at it while it listens (run by procd)\n"
+
 PROG=/usr/bin/fips-gateway
 CONFIG=/etc/fips/fips.yaml
 
@@ -21,6 +25,15 @@ CONFIG=/etc/fips/fips.yaml
 GW_DNS_DEFAULT=5365
 # Port the FIPS daemon DNS listens on.
 DAEMON_DNS_PORT=5354
+# Held while dnsmasq's .fips upstream is changed, so a stopping gateway's swap
+# back to the daemon and a starting gateway's swap to itself cannot interleave.
+DNS_LOCK=/var/lock/fips-gateway-dns.lock
+# The pid of the gateway the current supervise runs, so an exiting instance
+# can tell its successor's socket from anything else holding the port.
+GW_PIDFILE=/var/run/fips-gateway.pid
+# Seconds a stopping gateway gets after SIGTERM before it is killed; under
+# procd's own 5 s, after which procd kills only the supervise shell.
+GW_KILL_AFTER=3
 
 # Global-scope IPv6 prefix assigned to br-lan so Android/Chrome clients
 # believe they have full IPv6 and actually send AAAA queries.
@@ -42,13 +55,6 @@ start_service() {
 	# Load conntrack module for /proc/net/nf_conntrack.
 	modprobe nf_conntrack 2>/dev/null || true
 
-	# Redirect dnsmasq .fips forwarding from the daemon (5354) to the port the
-	# gateway listens on, so LAN clients get virtual IPs instead of raw mesh
-	# addresses. Done early and synchronously so dnsmasq is ready before the
-	# gateway starts accepting DNS queries.
-	dnsmasq_swap_fips_upstream "$(gateway_dns_port)"
-	sleep 1
-
 	# Add a global-scope IPv6 prefix to br-lan so Android/Chrome clients
 	# send AAAA queries (they suppress AAAA when only ULA addresses exist).
 	# Also set ra_default=2 so odhcpd advertises a default route even
@@ -59,8 +65,12 @@ start_service() {
 	# learn a route to the pool automatically.
 	gateway_add_ra_route
 
+	# dnsmasq's .fips forwarding moves to the gateway only once the gateway
+	# holds its DNS port, and back to the daemon (5354) whenever the gateway
+	# exits, so a gateway that fails to start, before or after binding, does
+	# not leave LAN clients' .fips lookups going to a dead port. See supervise.
 	procd_open_instance
-	procd_set_param command "$PROG" --config "$CONFIG"
+	procd_set_param command /etc/init.d/fips-gateway supervise
 	procd_set_param respawn 3600 5 5
 	procd_set_param stdout 1
 	procd_set_param stderr 1
@@ -69,7 +79,7 @@ start_service() {
 
 stop_service() {
 	# Restore dnsmasq .fips forwarding back to the daemon.
-	dnsmasq_swap_fips_upstream "$DAEMON_DNS_PORT"
+	dns_locked dnsmasq_swap_fips_upstream "$DAEMON_DNS_PORT"
 
 	# Remove the RA route for the virtual IP pool.
 	gateway_remove_ra_route
@@ -82,6 +92,119 @@ reload_service() {
 	restart
 }
 
+# Run the gateway as procd's instance. dnsmasq's .fips upstream is pointed at
+# the gateway's DNS port once the gateway itself has that port bound, and back
+# at the daemon's port when the gateway exits for any reason: a config it
+# cannot parse, a port it cannot bind, a failure after binding, a crash, or the
+# SIGTERM procd sends to stop it. That SIGTERM is passed on so the gateway can
+# remove its NAT table and routes, and a gateway still running $GW_KILL_AFTER
+# seconds later is killed, because procd kills only this shell. The exit
+# status is the gateway's, so procd's respawn sees the gateway's failures.
+supervise() {
+	local port pid="" watcher rc stopping="" killer=""
+
+	port="$(gateway_dns_port)"
+	# Set before the gateway starts, so a stop that arrives first still
+	# reaches it.
+	trap 'stopping=1; gateway_stop' TERM INT
+	"$PROG" --config "$CONFIG" &
+	pid=$!
+	mkdir -p "${GW_PIDFILE%/*}" 2>/dev/null
+	echo "$pid" > "$GW_PIDFILE"
+	[ -n "$stopping" ] && gateway_stop
+
+	# Polled from a child of its own so this shell sits in wait and reaps the
+	# gateway the moment it exits; a polling loop here would see an unreaped
+	# gateway as still alive.
+	(
+		while kill -0 "$pid" 2>/dev/null; do
+			dns_locked gateway_dns_claim "$port" "$pid" && exit 0
+			sleep 1
+		done
+		exit 0
+	) &
+	watcher=$!
+
+	# A trapped signal ends wait early, so wait until the gateway is gone.
+	rc=0
+	wait "$pid" || rc=$?
+	while kill -0 "$pid" 2>/dev/null; do
+		rc=0
+		wait "$pid" || rc=$?
+	done
+	[ -n "$killer" ] && kill "$killer" 2>/dev/null
+	# The watcher has nothing left to do, and would otherwise sleep out its
+	# poll; any change it is part way through finishes under the lock first.
+	kill "$watcher" 2>/dev/null
+	wait "$watcher"
+
+	dns_locked gateway_dns_release "$port" "$pid"
+	[ "$(cat "$GW_PIDFILE" 2>/dev/null)" = "$pid" ] && rm -f "$GW_PIDFILE"
+	logger -t fips-gateway "gateway exited with status $rc"
+	return "$rc"
+}
+
+# supervise's stop: SIGTERM to the gateway now, SIGKILL if it is still running
+# $GW_KILL_AFTER seconds later. Reads and sets supervise's pid and killer.
+gateway_stop() {
+	[ -n "$pid" ] || return 0
+	kill -TERM "$pid" 2>/dev/null
+	if [ -z "$killer" ]; then
+		( sleep "$GW_KILL_AFTER"; kill -KILL "$pid" 2>/dev/null ) &
+		killer=$!
+	fi
+	return 0
+}
+
+# Run "$@" holding $DNS_LOCK. The lock is released when the subshell, and
+# every process that inherited its descriptor, has exited.
+dns_locked() {
+	mkdir -p "${DNS_LOCK%/*}" 2>/dev/null
+	(
+		flock 9 || logger -t fips-gateway "could not lock $DNS_LOCK; changing dnsmasq anyway"
+		"$@"
+	) 9>"$DNS_LOCK"
+}
+
+# Succeed when process $2 itself holds a UDP socket bound to port $1, on any
+# address, IPv4 or IPv6: a socket inode from /proc/net/udp{,6} for that port
+# is among the process's open descriptors. Another process holding the port,
+# such as an mDNS responder on 5353, does not count.
+gateway_dns_held_by() {
+	local hex inode fd
+	[ -n "$2" ] || return 1
+	hex="$(printf '%04X' "$1")"
+	for inode in $(cat /proc/net/udp /proc/net/udp6 2>/dev/null |
+		awk -v want=":$hex" 'substr($2, length($2) - 4) == want { print $10 }'); do
+		for fd in /proc/"$2"/fd/*; do
+			[ "$(readlink "$fd" 2>/dev/null)" = "socket:[$inode]" ] && return 0
+		done
+	done
+	return 1
+}
+
+# Point dnsmasq at the gateway's port $1 once gateway $2 holds it. Fails,
+# changing nothing, until then.
+gateway_dns_claim() {
+	gateway_dns_held_by "$1" "$2" || return 1
+	dnsmasq_swap_fips_upstream "$1"
+	logger -t fips-gateway "gateway DNS is listening on port $1; dnsmasq forwards .fips to it"
+	return 0
+}
+
+# Point dnsmasq back at the daemon after gateway $2 on port $1 has exited,
+# unless the gateway procd started in its place (the pid in $GW_PIDFILE) holds
+# the port already; that one claims dnsmasq itself.
+gateway_dns_release() {
+	local next
+	next="$(cat "$GW_PIDFILE" 2>/dev/null)"
+	if [ -n "$next" ] && [ "$next" != "$2" ] && gateway_dns_held_by "$1" "$next"; then
+		return 0
+	fi
+	dnsmasq_swap_fips_upstream "$DAEMON_DNS_PORT"
+	return 0
+}
+
 # Extract the gateway "enabled" flag from fips.yaml.
 # Prints the value indented under the top-level "gateway:" block, or nothing
 # when there is no such block.

testing/openwrt/maintainer-scripts-test.sh

@@ -57,6 +57,7 @@ docker run --rm --network none \
     -e APK_SCRIPTS=/apk \
     -e "POSTINST=${POSTINST:-}" \
     -e "PRERM=${PRERM:-}" \
+    -e "INIT_GATEWAY=${INIT_GATEWAY:-}" \
     "$IMAGE" sh /src/testing/openwrt/scenarios.sh
 rc=$?
 

testing/openwrt/scenarios.sh

@@ -8,9 +8,9 @@
 # exercised is the scripts' behaviour given that contract, not opkg itself.
 # A real `opkg upgrade` on a router image stays uncovered.
 #
-# POSTINST and PRERM may be pointed at other files. That is the seam used to
+# POSTINST, PRERM and INIT_GATEWAY may be pointed at other files. That is the
-# see a scenario red against the previously released scripts, and to re-break
+# seam used to see a scenario red against the previously released scripts, and
-# the fixed ones during a break-check.
+# to re-break the fixed ones during a break-check.
 #
 # APK_SCRIPTS names a directory holding the four scripts the .apk registers
 # (post-install, pre-upgrade, post-upgrade, pre-deinstall), as captured from
@@ -25,7 +25,7 @@ REPO="${REPO:-/src}"
 POSTINST="${POSTINST:-$REPO/packaging/openwrt-ipk/scripts/postinst}"
 PRERM="${PRERM:-$REPO/packaging/openwrt-ipk/scripts/prerm}"
 RELEASED_PRERM="$REPO/testing/openwrt/fixtures/released-prerm"
-INIT_GATEWAY="$REPO/packaging/openwrt-ipk/files/etc/init.d/fips-gateway"
+INIT_GATEWAY="${INIT_GATEWAY:-$REPO/packaging/openwrt-ipk/files/etc/init.d/fips-gateway}"
 APK_SCRIPTS="${APK_SCRIPTS:-}"
 SHIPPED_YAML="$REPO/packaging/openwrt-ipk/files/etc/fips/fips.yaml"
 # The fips.yaml v0.5.0 and v0.5.1 shipped, byte for byte (from the v0.5.1 tag),
@@ -441,41 +441,44 @@ YAML
 # ── 7. start_service refuses to touch dnsmasq for a disabled gateway ────────
 # The init script's helpers are redefined after sourcing it, so start_service
 # runs its own decision against recorded stubs instead of uci, procd and the
-# network.
+# network. Where dnsmasq ends up while the gateway runs is scenario 15's.
+stub_start_service_helpers() {
+    # stub_start_service_helpers [keep-swap]: keep-swap leaves the real
+    # dnsmasq_swap_fips_upstream in place, for a caller with the uci stub.
+    if [ "${1:-}" != "keep-swap" ]; then
+        dnsmasq_swap_fips_upstream() { echo "dnsmasq_swap $1" >> "$CALLS"; return 0; }
+    fi
+    sysctl() { return 0; }
+    modprobe() { return 0; }
+    logger() { return 0; }
+    procd_set_param() {
+        if [ "$1" = "command" ]; then
+            echo "$*" >> "$CALLS"
+        fi
+        return 0
+    }
+    procd_close_instance() { return 0; }
+    gateway_add_global_prefix() { echo "add_global_prefix" >> "$CALLS"; return 0; }
+    gateway_add_ra_route() { echo "add_ra_route" >> "$CALLS"; return 0; }
+    procd_open_instance() { echo "procd_open_instance" >> "$CALLS"; return 0; }
+    return 0
+}
+
 scenario_start_service_guard() {
     note "scenario 7: start_service guard"
 
     # shellcheck source=/dev/null
     . "$INIT_GATEWAY"
-
+    stub_start_service_helpers
-    sysctl() { return 0; }
-    modprobe() { return 0; }
-    logger() { return 0; }
-    sleep() { return 0; }
-    procd_set_param() { return 0; }
-    procd_close_instance() { return 0; }
-    dnsmasq_swap_fips_upstream() { echo "dnsmasq_swap $1" >> "$CALLS"; return 0; }
-    gateway_add_global_prefix() { echo "add_global_prefix" >> "$CALLS"; return 0; }
-    gateway_add_ra_route() { echo "add_ra_route" >> "$CALLS"; return 0; }
-    procd_open_instance() { echo "procd_open_instance" >> "$CALLS"; return 0; }
 
     reset_state
     CONFIG="$SHIPPED_YAML"
     start_service >/dev/null 2>&1
-    assert_called "dnsmasq_swap 5365" "an enabled gateway redirects dnsmasq to the default port"
+    assert_none_called_with_prefix "dnsmasq_swap " \
+        "an enabled gateway does not point dnsmasq at a gateway that is not yet listening"
     assert_called "procd_open_instance" "an enabled gateway still starts the daemon"
-
+    assert_called "command /etc/init.d/fips-gateway supervise" \
-    reset_state
+        "procd runs the gateway through the init script's supervise command"
-    CONFIG="$WORK/explicit-5353.yaml"
-    cat > "$CONFIG" <<'YAML'
-gateway:
-  enabled: true
-  pool: "fd01::/112"
-  dns:
-    listen: "[::1]:5353"
-YAML
-    start_service >/dev/null 2>&1
-    assert_called "dnsmasq_swap 5353" "dnsmasq follows an explicit gateway.dns.listen"
 
     reset_state
     CONFIG="$WORK/disabled.yaml"
@@ -834,6 +837,309 @@ scenario_listen_migration() {
     return 0
 }
 
+# ── 15. dnsmasq points at the gateway only while it listens ───────────────
+# start_service runs against recorded procd stubs, and the command it hands
+# procd is then executed as procd would execute it: the real init script is
+# installed at /etc/init.d/fips-gateway, whose #! line runs a stand-in
+# /etc/rc.common, and /usr/bin/fips-gateway is a stub gateway. A stub that
+# binds does so by becoming nc, so the socket is the stub's own, as the real
+# gateway's is. dnsmasq's loopback .fips forward lives in the uci stub and
+# starts on the daemon's port, as it is while the gateway is stopped. However
+# the gateway exits, it must end there.
+
+GW_STUB=/tmp/fips-gw-stub
+
+install_supervise_env() {
+    # install_supervise_env <gateway DNS listen port>
+    install_uci_stub
+    printf '#!/bin/sh\nexit 0\n' > "$STUB_BIN/logger"
+    chmod 0755 "$STUB_BIN/logger"
+
+    rm -rf "$GW_STUB"
+    mkdir -p "$GW_STUB" /etc/fips /usr/bin
+    rm -f /var/run/fips-gateway.pid
+    echo "$1" > "$GW_STUB/port"
+    cat > /etc/fips/fips.yaml <<YAML
+gateway:
+  enabled: true
+  pool: "fd01::/112"
+  dns:
+    listen: "[::1]:$1"
+YAML
+
+    cp "$INIT_GATEWAY" /etc/init.d/fips-gateway
+    chmod 0755 /etc/init.d/fips-gateway
+
+    cat > /etc/rc.common <<'SHIM'
+#!/bin/sh
+# Stand-in for OpenWrt's rc.common: runs one of the init script's commands.
+initscript="$1"
+action="$2"
+shift 2
+. "$initscript"
+case " ${EXTRA_COMMANDS:-} " in
+*" $action "*) "$action" "$@" ;;
+*) echo "rc.common stand-in: $action is not a command of $initscript" >&2; exit 2 ;;
+esac
+SHIM
+    chmod 0755 /etc/rc.common
+
+    cat > /usr/bin/fips-gateway <<'STUB'
+#!/bin/sh
+# Stub gateway, by $GW_STUB/mode:
+#   parse     exits 1 at once, as on a config it cannot parse;
+#   taken     exits 1 after two seconds without binding, as when another
+#             process holds its port;
+#   bind      becomes nc listening on the port, until signalled;
+#   stubborn  ignores SIGTERM and runs until killed, binding nothing itself.
+d=/tmp/fips-gw-stub
+echo $$ > "$d/pid"
+port="$(cat "$d/port")"
+case "$(cat "$d/mode")" in
+parse) exit 1 ;;
+taken) sleep 2; exit 1 ;;
+stubborn)
+    trap '' TERM
+    while :; do sleep 1; done
+    ;;
+esac
+exec nc -u -l -p "$port" -s ::1 </dev/null >/dev/null 2>&1
+STUB
+    chmod 0755 /usr/bin/fips-gateway
+
+    uci_seed "$DNSMASQ_OPT" "/fips/::1#5354" "/lan/192.168.1.2"
+    return 0
+}
+
+remove_supervise_env() {
+    rm -f /etc/rc.common /usr/bin/fips-gateway /var/run/fips-gateway.pid
+    rm -rf /etc/fips "$GW_STUB" "$STUB_BIN"
+    return 0
+}
+
+fips_upstream() {
+    # The loopback .fips forwards dnsmasq has, sorted, on one line.
+    "$STUB_BIN/uci" -q get "$DNSMASQ_OPT" | tr ' ' '\n' | grep '^/fips/' | sort | tr '\n' ' '
+    return 0
+}
+
+wait_for_upstream() {
+    # wait_for_upstream <port> <tenths of a second>: succeeds once dnsmasq
+    # forwards .fips to ::1#<port> and nowhere else on loopback.
+    n=0
+    while [ "$n" -lt "$2" ]; do
+        [ "$(fips_upstream)" = "/fips/::1#$1 " ] && return 0
+        sleep 0.1
+        n=$((n + 1))
+    done
+    return 1
+}
+
+start_gateway_service() {
+    # Runs start_service and then, in the background, the command it gave
+    # procd, with the uci and logger stubs first on PATH. Sets CMD_PID.
+    (
+        PATH="$STUB_BIN:$PATH"
+        # shellcheck source=/dev/null
+        . "$INIT_GATEWAY"
+        stub_start_service_helpers keep-swap
+        CONFIG=/etc/fips/fips.yaml
+        start_service >/dev/null 2>&1
+    )
+    sed -n 's/^command //p' "$CALLS" > "$WORK/command"
+    # shellcheck disable=SC2046
+    set -- $(cat "$WORK/command")
+    if [ $# -eq 0 ]; then
+        CMD_PID=""
+        bad "start_service gave procd no command: $(calls_oneline)"
+        return 1
+    fi
+    ( PATH="$STUB_BIN:$PATH" exec "$@" ) > "$WORK/command.out" 2>&1 &
+    CMD_PID=$!
+    return 0
+}
+
+wait_command() {
+    # wait_command: waits up to 20 s for the procd command; sets CMD_RC.
+    ( sleep 20; kill -KILL "$CMD_PID" 2>/dev/null ) &
+    dog=$!
+    CMD_RC=0
+    wait "$CMD_PID" || CMD_RC=$?
+    kill "$dog" 2>/dev/null
+    wait "$dog" 2>/dev/null
+    return 0
+}
+
+stub_pid() {
+    # stub_pid: the stub gateway's pid once it has started, else empty.
+    n=0
+    while [ ! -s "$GW_STUB/pid" ] && [ "$n" -lt 100 ]; do sleep 0.1; n=$((n + 1)); done
+    cat "$GW_STUB/pid" 2>/dev/null
+    return 0
+}
+
+assert_gone() {
+    # assert_gone <pid> <what it means>
+    if [ -n "$1" ] && kill -0 "$1" 2>/dev/null; then
+        bad "$2 — pid $1 is still running"
+        kill -KILL "$1" 2>/dev/null
+    else
+        ok "$2"
+    fi
+    return 0
+}
+
+assert_on_daemon() {
+    # assert_on_daemon <what it means>
+    assert_equals "$(fips_upstream)" "/fips/::1#5354 " "$1"
+    return 0
+}
+
+hold_port() {
+    # hold_port <port>: an unrelated process binds the port. Sets HOLDER.
+    nc -u -l -p "$1" -s ::1 </dev/null >/dev/null 2>&1 &
+    HOLDER=$!
+    n=0
+    while ! grep -q ":$(printf '%04X' "$1") " /proc/net/udp6 && [ "$n" -lt 50 ]; do
+        sleep 0.1
+        n=$((n + 1))
+    done
+    return 0
+}
+
+scenario_supervise() {
+    note "scenario 15: dnsmasq follows the gateway's life"
+    unset -f sleep logger sysctl modprobe 2>/dev/null
+
+    # 1. The gateway exits before binding, as on a config it cannot parse.
+    reset_state
+    install_supervise_env 5365
+    echo parse > "$GW_STUB/mode"
+    if start_gateway_service; then
+        wait_command
+        assert_on_daemon "a gateway that exits before binding leaves dnsmasq on the daemon"
+        if [ "$CMD_RC" -ne 0 ]; then
+            ok "the gateway's failure is the exit status procd sees"
+        else
+            bad "the procd command exited 0 although the gateway failed"
+        fi
+    fi
+    remove_supervise_env
+
+    # 2. Another process holds the gateway's port, as an mDNS responder holds
+    #    5353, so the gateway cannot bind it and exits.
+    reset_state
+    install_supervise_env 5365
+    echo taken > "$GW_STUB/mode"
+    hold_port 5365
+    if start_gateway_service; then
+        if wait_for_upstream 5365 15; then
+            bad "dnsmasq was pointed at a port the gateway does not hold"
+        else
+            ok "dnsmasq is not pointed at a port another process holds"
+        fi
+        wait_command
+        assert_on_daemon "a gateway whose port is taken leaves dnsmasq on the daemon"
+    fi
+    kill "$HOLDER" 2>/dev/null
+    wait "$HOLDER" 2>/dev/null
+    remove_supervise_env
+
+    # 3. The gateway binds, then fails, as on a NAT or route setup error.
+    reset_state
+    install_supervise_env 5365
+    echo bind > "$GW_STUB/mode"
+    if start_gateway_service; then
+        if wait_for_upstream 5365 100; then
+            ok "dnsmasq forwards .fips to the gateway once it is listening"
+        else
+            bad "dnsmasq never moved to the listening gateway: $(fips_upstream)"
+        fi
+        kill -USR1 "$(stub_pid)" 2>/dev/null
+        wait_command
+        assert_on_daemon "a gateway that fails after binding hands dnsmasq back to the daemon"
+        assert_equals "$(uci_sorted "$DNSMASQ_OPT")" \
+            "$(sorted_words /lan/192.168.1.2 /fips/::1#5354)" \
+            "the swaps keep dnsmasq's other servers"
+    fi
+    remove_supervise_env
+
+    # 4. procd stops a running gateway with SIGTERM, here on its own (as when
+    #    procd restarts an instance), without stop_service. Port from the config.
+    reset_state
+    install_supervise_env 5400
+    echo bind > "$GW_STUB/mode"
+    if start_gateway_service; then
+        if wait_for_upstream 5400 100; then
+            ok "dnsmasq follows an explicit gateway.dns.listen"
+        else
+            bad "dnsmasq never moved to the gateway's port 5400: $(fips_upstream)"
+        fi
+        gw="$(stub_pid)"
+        kill -TERM "$CMD_PID" 2>/dev/null
+        wait_command
+        assert_equals "$CMD_RC" "143" "procd's SIGTERM reaches the gateway, which exits on it"
+        assert_gone "$gw" "the gateway does not outlive the procd command"
+        assert_on_daemon "a gateway stopped by SIGTERM hands dnsmasq back to the daemon"
+    fi
+    remove_supervise_env
+
+    # 5. A gateway that ignores SIGTERM is killed before procd's own timeout,
+    #    after which procd would kill only the supervise shell.
+    reset_state
+    install_supervise_env 5365
+    echo stubborn > "$GW_STUB/mode"
+    if start_gateway_service; then
+        gw="$(stub_pid)"
+        kill -TERM "$CMD_PID" 2>/dev/null
+        # Tenths of a second until the gateway is gone; the supervise shell
+        # reaps it at once, so kill -0 fails as soon as it dies.
+        tenths=0
+        while [ -n "$gw" ] && kill -0 "$gw" 2>/dev/null && [ "$tenths" -lt 100 ]; do
+            sleep 0.1
+            tenths=$((tenths + 1))
+        done
+        wait_command
+        assert_equals "$CMD_RC" "137" "a gateway that ignores SIGTERM is killed"
+        assert_gone "$gw" "a gateway that ignores SIGTERM does not outlive the procd command"
+        if [ "$tenths" -lt 45 ]; then
+            ok "it is killed inside procd's 5 s stop timeout (after ${tenths} tenths of a second)"
+        else
+            bad "it was killed after ${tenths} tenths of a second, too close to or past procd's 5 s"
+        fi
+        assert_on_daemon "a killed gateway hands dnsmasq back to the daemon"
+    fi
+    remove_supervise_env
+
+    # 6. The swap back after a gateway exits is skipped only when the gateway
+    #    procd started in its place, named in the pid file, holds the port.
+    reset_state
+    install_uci_stub
+    (
+        PATH="$STUB_BIN:$PATH"
+        # shellcheck source=/dev/null
+        . "$INIT_GATEWAY"
+        mkdir -p /var/run
+        hold_port 5365
+        uci_seed "$DNSMASQ_OPT" "/fips/::1#5365"
+        echo "$HOLDER" > "$GW_PIDFILE"
+        gateway_dns_release 5365 99999 >/dev/null 2>&1
+        fips_upstream > "$WORK/successor"
+        echo 99998 > "$GW_PIDFILE"
+        gateway_dns_release 5365 99999 >/dev/null 2>&1
+        fips_upstream > "$WORK/other"
+        kill "$HOLDER"
+        wait "$HOLDER" 2>/dev/null
+        rm -f "$GW_PIDFILE"
+    )
+    assert_file_is "$WORK/successor" "/fips/::1#5365 " \
+        "the swap back is skipped while the successor gateway holds the port"
+    assert_file_is "$WORK/other" "/fips/::1#5354 " \
+        "the swap back happens while only some other process holds the port"
+    rm -rf "$STUB_BIN"
+    return 0
+}
+
 echo "OpenWrt maintainer-script scenarios (shell: $(readlink -f /proc/$$/exe 2>/dev/null || echo sh))"
 echo "  postinst: $POSTINST"
 echo "  prerm:    $PRERM"
@@ -853,6 +1159,7 @@ scenario_dns_port_reader
 scenario_default_port_parity
 scenario_swap_cleanup
 scenario_listen_migration
+scenario_supervise
 
 echo ""
 if [ "$FAILURES" -eq 0 ]; then