主機維護的實作紀錄 on Tarragon

多台主機維護清單的實作紀錄：在容器上安裝 ansible-core 與 Terraform、由 Terraform 產生 inventory、用 Ansible 的範本部署每台的清單、以 sudo 與 systemd-run 執行檢查腳本，以及清理

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

事件說明：2026-10-26，在一台 Apple Silicon 的 macOS 開發機上，用 OrbStack 提供的 Docker Engine 29.8.2（核心 7.2.12-orbstack，arm64，cgroup（控制群組） v2）建立可拋棄的容器，把多台主機的維護清單從 Terraform 產生 inventory、用 Ansible 部署到兩台主機並執行檢查腳本。受管主機（managed node，Ansible 連過去執行任務的主機）是兩個 Oracle Linux 10.2 容器（systemd 257 當 PID 1，OpenSSH 9.9p1、Python 3.12.15、sudo 1.9.17、dnf-automatic 4.20.0），以 --privileged --cgroupns=private 執行。控制端（control node，執行 ansible 與 Terraform 指令的機器）是一個 python:3.12-slim 容器（Debian 13，OpenSSH 用戶端 10.0p2），裝 ansible-core 2.17.7（Jinja2 3.1.6）與 Terraform 1.9.8，Terraform 的 hashicorp/local provider（Terraform 操作某一類資源的外掛）是 2.5.2。檢查腳本是 host-check.py 在 2026-10-26 的版本（作者私有專案的 commit 3fc41c0），原樣複製一份來用，它的原始碼在只讀檢查腳本 host-check.py 的原始碼與逐段說明：選項的切分與各工具的白名單規則、清單的載入與驗證、指令的執行、各項檢查、路徑與時間的量測、結果檔與命令列，以及這一版的已知限制。

這篇把多台主機的維護清單：值的分層與合併的位置、用 Ansible 的 inventory 與範本產生每台的清單、由 Terraform 的輸出產生 inventory、跨主機執行的 exit code，以及單台清單的適用範圍的做法在兩台可拋棄的受管主機上從安裝走到清理，一台只當 web、另一台同時是 web 與 db。各節依序是：

受管主機與控制端的容器怎麼建、裝了哪些套件。
控制端經由 SSH 登入受管主機用的金鑰、known_hosts 與 sudo。
Terraform 由主機清單寫出 inventory（Ansible 讀的主機清冊，見 Configuration Management（組態管理）），以及 local_file 的預設檔案權限。
變數檔與範本照檢查腳本實際要求的欄位寫，兼任兩種角色的主機怎麼取得兩個角色的入口。
用 playbook（依序執行多個任務的 YAML 檔）部署檢查腳本與每台的清單：validate 改用檢查腳本自己的載入函式、在寫出之前就驗出欄位錯誤，以及 --check 的預覽與實際執行結果不同的那一次。
以 -b 與 systemd-run 對所有主機執行檢查腳本，每台的輸出與 ansible 指令的 exit code。
刻意讓一台的門檻變成 WARN、讓一台的清單格式錯、讓一台連不上時，ansible 的 exit code 與每台的 rc 各是什麼。
容器跟真主機不同的地方，以及在真主機上要另外確認的項目。
清理。

值為什麼分成每台相同、依角色不同、每台不同三類，合併為什麼放在部署時，exit code 2 與 4 的意思，這些判斷依據寫在那篇概念文章，這裡只寫套在這次環境上的操作與結果。清單的格式、檢查腳本的白名單與 systemd-run 各屬性的效果在主機維護清單寫成 TOML：JSON、YAML、TOML 的取捨、TOML 1.0 與 1.1 的版本差異、清單的欄位設計與只讀檢查腳本。這次沒有碰雲端：主機是容器，雲端防火牆那一層的檢查在清單裡寫成要到主控台確認的項目，terraform plan 對雲端資源的比對也沒有量。

前置條件：開發機的資源、檔案配置與檢查腳本

開發機的記憶體：這次三個容器同時在跑時，docker stats 量到受管主機各用 36 MiB 與 52 MiB、控制端 5 MiB（檢查腳本執行時，systemd 回報那一次執行的記憶體高峰是 70 MiB 到 79 MiB）。這些值依映像檔與正在跑的服務而變；開發機上已經有別的容器在跑時，建容器之前先看 swap 已用多少（macOS 是 sysctl vm.swapusage）與 OrbStack 分到的記憶體上限（在 OrbStack 的設定裡）。
主機的數量：兩台受管主機加一個控制端是這次需要的最小組合：一台只當 web、一台兼任 web 與 db，才看得到依角色取聯集的結果；控制端一個就夠。

一個工作目錄：控制端容器把它掛在 /work，Terraform 的設定、Ansible 的變數檔、範本、產生出來的 inventory 與 Terraform 的 State（IaC 狀態檔）都放在這裡；容器刪掉之後 State 仍在開發機上，清理時才查得到 Terraform 建過什麼。這次的配置：

 1.
 2├── host-image/Containerfile       # 受管主機的映像檔
 3├── ctl-image/Containerfile        # 控制端的映像檔
 4└── work/
 5    ├── tf/main.tf                 # Terraform：主機清單與寫出 inventory 的 local_file
 6    └── ansible/
 7        ├── inventory.yml          # 由 Terraform 寫出，不手改
 8        ├── group_vars/all.yml     # 每台相同的值
 9        ├── group_vars/web.yml     # web 角色的值
10        ├── group_vars/db.yml      # db 角色的值
11        ├── host_vars/mh-web1.yml  # 只有 mh-web1 不同的值
12        ├── host.toml.j2           # 清單的範本
13        ├── files/host-check.py    # 檢查腳本（由原始碼那一篇的區塊接成）
14        ├── deploy.yml             # 部署腳本與清單的 playbook
15        └── check.sh               # 對每台執行檢查的 ad-hoc 指令（不寫 playbook、直接執行單一模組）

下面各節程式碼區塊第一行的註解寫著檔名，照那個路徑在開發機上建檔，路徑的起點依檔案分三種：

host-image/…、ctl-image/…：從 work/ 的上一層起算。兩個映像檔的建置目錄不必掛進控制端，所以不放進 work/。
tf/main.tf：從工作目錄 work/ 起算。
其餘的（group_vars/…、host.toml.j2、deploy.yml、check.sh）：從 work/ansible/ 起算。

ansible/ 與 tf/ 目錄要在起控制端容器之前建好。inventory.yml 跟 group_vars/、host_vars/ 放在同一個目錄，是 Ansible 載入這兩個目錄的條件：Ansible 從 inventory 檔所在的目錄（以及 playbook 所在的目錄）找 group_vars/ 與 host_vars/。

檢查腳本：host-check.py 的原始碼在只讀檢查腳本 host-check.py 的原始碼與逐段說明：選項的切分與各工具的白名單規則、清單的載入與驗證、指令的執行、各項檢查、路徑與時間的量測、結果檔與命令列，以及這一版的已知限制，把那一篇的 python 區塊照它開頭寫的接法接起來，存成 files/host-check.py。換成自己的檢查腳本時，這篇的步驟用到的腳本行為有下面這幾項，替代的腳本要全部滿足，或照它的行為改寫對應的步驟：
- 有一個只載入與驗證清單、不執行檢查的函式或模式，清單格式錯時以非零結束（host-check.py 是 load_manifest()，格式錯時丟出例外）；部署時的 validate 用它。
- exit code 0 代表沒有 WARN、1 代表至少一項 WARN、2 代表清單格式錯；跨主機的輸出靠每台的 rc 分出這三種情形（rc 是 Ansible 回報的、那台主機上指令的 return code，執行檢查時就是檢查腳本的 exit code）。
- 結尾一定印一行 summary:；腳本沒有開始或沒有跑完時，靠這一行分辨。
- 接受 --manifest <路徑> 指定清單的位置。
- --no-state 不讀也不寫結果檔。
- 結果檔放在 /var/lib/host-check/，由 systemd-run 的 StateDirectory=host-check 建立。
- 在沙箱底下跑得完：ProtectSystem=strict、只有 ReadWritePaths 列的 /var/log 與 /var/cache/dnf 兩個目錄（加上 StateDirectory）可寫、IPAddressDeny=any 擋掉所有網路連線。
- 給 runpy 載入時：模組層級沒有副作用、__name__ 不是 __main__ 時不執行主程式、載入函式以丟出例外表達格式錯；主機的 Python 是 3.11 以上（tomllib）。
- 清單的欄位：〈變數檔與範本：檢查腳本實際要求的欄位、兼任兩種角色的主機〉那一節列的欄位與允許值是 host-check.py 自己的規格，換腳本時範本換成那支腳本要求的欄位。
換成自己的腳本時，正文的預期輸出（PASS、WARN、MANUAL 的行格式、since: 與 DELTA、manifest error: 的訊息、[vars] 的替換）以那支腳本自己的輸出為準。
容器、network 與映像檔的名稱一律 mh- 開頭：清理時 docker ps -a --filter name=mh- 這一類查詢列得出這次建的全部資源，開發機上其他專案的容器不會被誤刪。
把這個 lab 固定成自動化測試時：可用的工具是 molecule 的 docker driver，它拿容器當受管主機，依序建立容器、套用 playbook（converge）、執行驗證。這次沒有用 molecule，每一步都手動執行。

受管主機與控制端的容器：Oracle Linux 10 加 systemd 與 sshd、python:3.12-slim 加 ansible-core 與 Terraform

受管主機的映像檔以 oraclelinux:10 為底，裝 sshd、sudo、Python 與檢查腳本會查的 dnf-automatic，建一個 ops 帳號當 Ansible 登入的帳號：

 1# host-image/Containerfile：受管主機
 2FROM oraclelinux:10
 3RUN dnf -y install systemd procps-ng iproute openssh-server sudo python3 dnf-automatic dnf-plugins-core \
 4    && dnf clean all \
 5    && systemctl mask systemd-logind.service getty.target console-getty.service \
 6    && systemctl enable sshd.service \
 7    && useradd -m ops \
 8    && echo 'ops ALL=(ALL) NOPASSWD: ALL' > /etc/sudoers.d/ops && chmod 0440 /etc/sudoers.d/ops
 9STOPSIGNAL SIGRTMIN+3
10CMD ["/usr/sbin/init"]

 1# ctl-image/Containerfile：控制端
 2FROM python:3.12-slim
 3ARG TF_VERSION=1.9.8
 4# TARGETARCH 由 docker build 依開發機的架構填入（這台是 arm64），Terraform 的壓縮檔名照它選
 5ARG TARGETARCH
 6RUN apt-get update && apt-get install -y --no-install-recommends openssh-client curl unzip \
 7    && rm -rf /var/lib/apt/lists/* \
 8    && pip install --no-cache-dir ansible-core==2.17.7 \
 9    && curl -fsSLo /tmp/tf.zip https://releases.hashicorp.com/terraform/${TF_VERSION}/terraform_${TF_VERSION}_linux_${TARGETARCH}.zip \
10    && unzip /tmp/tf.zip terraform -d /usr/local/bin && rm /tmp/tf.zip
11WORKDIR /work

1# 開發機上，在 work/ 的上一層執行；-f 指定檔名，因為檔名是 Containerfile 而 docker build 預設找 Dockerfile
2docker build -f host-image/Containerfile -t mh-host:ol10 host-image
3docker build -f ctl-image/Containerfile -t mh-ctl:1 ctl-image
4docker run --rm mh-ctl:1 sh -c 'ansible --version | head -1; terraform version | head -1'

最後一條印出 ansible [core 2.17.7] 與 Terraform v1.9.8。這台開發機上 oraclelinux:10 已經在本機，受管主機的映像檔建了 23 秒；控制端要下載 pip 套件與 Terraform 的壓縮檔，建了 101 秒。兩個時間依網路與本機的快取而變。

受管主機的 Containerfile 最後兩行讓 systemd 當容器的 PID 1：CMD ["/usr/sbin/init"] 啟動 systemd，STOPSIGNAL SIGRTMIN+3 讓 docker stop 送出 systemd 認得的關機訊號。systemd 收到 SIGRTMIN+3 才照正常的關機流程停下各個 unit；Docker 預設送的是 SIGTERM，systemd 不把它當成關機，docker stop 會等到逾時再強制結束容器（依 systemd 文件對訊號的說明推論，沒有實跑拿掉這一行的結果）。

這次遇到的錯誤：第一次建受管主機的映像檔時套件名寫成 'dnf-command(needs-restarting)'，dnf 回 Unable to find a match，在 Oracle Linux 10 上，檢查腳本用的 dnf needs-restarting 子命令由 dnf-plugins-core 提供（外掛檔案在它依賴的 python3-dnf-plugins-core 裡），oraclelinux:10 的映像檔已經裝了它；另一個獨立的 /usr/bin/needs-restarting 指令屬於 yum-utils（2026-10-27 在 oraclelinux:10 容器裡用 rpm -qf 查到，Oracle Linux 10.2）。Containerfile 仍把 dnf-plugins-core 寫進安裝清單，讓檢查腳本依賴的套件明示在這一行：換成沒有預裝它的底層映像檔時，建映像檔那一步會裝上它，不會漏掉。

換成 VM 或別的發行版、不開特權、sudo 要密碼、改用別的安裝方式時的結果，在〈這一節的其他做法：容器或 VM、作業系統、遮蔽的 unit、privileged、sudo 密碼、安裝版本與雜湊、金鑰密碼〉。

兩台受管主機與控制端接在同一個 Docker network 上，控制端用容器名就連得到受管主機：

1docker network create mh-net
2docker run -d --name mh-web1  --hostname mh-web1  --network mh-net --privileged --cgroupns=private mh-host:ol10
3docker run -d --name mh-both1 --hostname mh-both1 --network mh-net --privileged --cgroupns=private mh-host:ol10
4docker exec mh-web1 systemctl is-system-running --wait    # 等 systemd 啟動完成，印 running
5docker exec mh-both1 systemctl is-system-running --wait

docker network create 另建一個 network，因為 Docker 預設的 bridge network 不提供容器名的 DNS 解析，接在上面的容器只能用 IP 互連；自建的 bridge network 由 Docker 內建的 DNS 把容器名解析成位址（依 Docker 文件〈Bridge network driver〉，沒有在預設的 bridge 上實跑）。

--privileged --cgroupns=private 讓容器裡的 systemd 管得到自己的 cgroup，systemd-run 才建得出暫時的 unit（transient unit：執行時由 systemd-run 建立、不寫成 unit 檔的 unit）。Docker 在 cgroup v2 的主機上，cgroup namespace 的預設就是 private，所以 systemd 能否當 PID 1 啟動，取決於 --privileged，--cgroupns=private 只是把預設寫明（依 docker run 參考文件推論）。拿掉 --privileged 時，容器裡的 systemd 管不到自己的 cgroup，PID 1 起不來，或 systemd-run 建不出暫時的 unit（從 systemd 文件〈The Container Interface〉對 cgroup 階層的要求推論，沒有實跑）。主機維護清單寫成 TOML：JSON、YAML、TOML 的取捨、TOML 1.0 與 1.1 的版本差異、清單的欄位設計與只讀檢查腳本在同一種容器裡量沙箱的效果時用的就是這組參數。--privileged 的代價與不開特權的做法，在〈這一節的其他做法：容器或 VM、作業系統、遮蔽的 unit、privileged、sudo 密碼、安裝版本與雜湊、金鑰密碼〉。

systemctl is-system-running --wait 等到 systemd 的啟動結束才印出狀態：running 代表啟動完成、沒有失敗的 unit，degraded 代表有 unit 失敗，用 systemctl --failed 查是哪一個。不加 --wait、緊接在 docker run 之後執行時，這次印的是 initializing、exit code 1，systemd 還在啟動，sshd 可能還沒開始接聽。

兩台各再做三件事，這三件在真主機上分別由建立主機時的設定與服務自己的部署負責，這裡用 docker exec 代替：

 1# 開發機上執行；<暫存目錄> 換成工作目錄以外的一個暫存目錄，金鑰的用法在〈控制端連到受管主機的 SSH：金鑰、known_hosts 與 sudo〉
 2mkdir -p <暫存目錄>/keys    # ssh-keygen 不建上層目錄
 3ssh-keygen -q -t ed25519 -N '' -C mh-walkthrough -f <暫存目錄>/keys/id_ed25519
 4for h in mh-web1 mh-both1; do
 5  docker exec $h install -d -m 0700 -o ops -g ops /home/ops/.ssh
 6  docker cp <暫存目錄>/keys/id_ed25519.pub $h:/home/ops/.ssh/authorized_keys
 7  docker exec $h sh -c 'chown ops:ops /home/ops/.ssh/authorized_keys && chmod 0600 /home/ops/.ssh/authorized_keys'
 8  docker exec $h systemctl enable --now dnf-automatic.timer
 9  docker exec $h systemd-run --unit=stand-in-http python3 -m http.server 80
10done
11docker exec mh-both1 systemd-run --unit=stand-in-postgres python3 -m http.server 5432
12docker exec mh-both1 ss -H -l -n -t

公鑰：ssh-keygen 在暫存目錄產生一把新的金鑰。暫存目錄要在工作目錄以外：工作目錄整個掛進控制端容器，私鑰放在裡面的話會跟著掛進去，而控制端只需要唯讀掛載的那一份金鑰目錄。keys 目錄不存在時它以 Saving key … failed: No such file or directory 失敗，所以先 mkdir -p。-N '' 讓私鑰不設密碼，控制端執行 Ansible 時才不必輸入。雲端主機在建立時由 cloud-init 把公鑰放進預設帳號，這裡用 docker cp 手動放。
dnf-automatic 的 timer：清單要求它 enabled 而且 active，真主機上由部署腳本啟用。
代替服務的接聽程式：web 角色的入口是 80，db 角色是 5432，檢查腳本確認那個連接埠有程序在聽。這次沒有裝 nginx 與 PostgreSQL，用 python3 -m http.server 在兩個連接埠上接聽；systemd-run --unit= 建的是暫時的 unit，容器重啟之後就不在，〈一台變成 WARN、一台清單格式錯、一台連不上：ansible 的 exit code 與每台的 rc〉那一節正好用到這個性質。

最後一條在 mh-both1 上列出 0.0.0.0:22、[::]:22、0.0.0.0:80 與 0.0.0.0:5432，另有 Docker 內建 DNS 在 127.0.0.11 上的一個 TCP 連接埠（它的另一個連接埠是 UDP，不在 -t 的輸出裡）；Docker 內建 DNS 的位址在 loopback 上，檢查腳本的 listen_audit 只比對 loopback 以外的位址，所以 DNS 的連接埠不算多開的連接埠。

這一節的其他做法：容器或 VM、作業系統、遮蔽的 unit、privileged、sudo 密碼、安裝版本與雜湊、金鑰密碼

受管主機用容器：容器建得快、刪得乾淨，代價是沙箱、SELinux、logind 這幾項跟真主機不同（〈容器跟真主機不同的地方，以及在真主機上要另外確認的項目〉）。換成完整的 VM（Lima、UTM、multipass）或雲端主機時，那一節列的 SELinux、logind 的 session 與持久的 journal 這幾項就量得到，代價是建立與清理都比較慢、雲端主機要計費（推論，這次沒有用 VM 跑）。
受管主機的作業系統：檢查腳本的 [updates] 段讀的是 dnf-automatic 的設定檔（INI 格式的 [commands] 段），reboot_check 用 dnf needs-restarting -r，所以選 Oracle Linux；同為 dnf 系的 Rocky Linux、AlmaLinux 同樣適用（推論，沒有實跑）。換成 debian:12 這類 Debian 系的映像檔可以少下載一些，代價是 Debian 上沒有 dnf-automatic 的設定檔、timer 與 dnf 指令，[updates] 那幾項（timer、config、reboot）都不會是 PASS，[updates] 段要照 unattended-upgrades 的設定改寫，檢查腳本也要跟著改（從腳本的程式碼推的，沒有實跑）。
systemd 當 PID 1 與遮蔽的 unit：檢查要用 systemd-run 套沙箱，[updates] 也要查 systemd timer 的狀態，所以容器裡要有 systemd。systemctl mask 那幾個 unit 是容器裡用不到的登入與終端機服務；遮蔽 systemd-logind 的副作用寫在〈容器跟真主機不同的地方，以及在真主機上要另外確認的項目〉。不遮蔽時，logind 會替每次 SSH 登入建一個 session scope，Ansible 模組的紀錄落在那個 scope 底下，log/sshd 的最新一筆就不再是 Ansible 的紀錄（推論，這次沒有實跑不遮蔽的版本）。
--privileged 的代價與不開特權的做法：--privileged 的代價在 Linux 開發機上最明顯：這種容器拿得到主機上所有的裝置與 Linux capability，約等於主機上的 root（Privileged Container（特權容器）；Docker 的 --privileged 跟卡上寫的 securityContext.privileged 是同一種權限）。這次的 Docker Engine 跑在 OrbStack 的 Linux VM 裡，拿到的是那台 VM 的權限，不是 macOS 本身。不想開特權時，Podman 的 --systemd=always 不需要 privileged 也能讓 systemd 當 PID 1（依 Podman 文件，沒有實跑）。
ops 帳號的 sudo 不要密碼：Ansible 的 become（-b，讓 Ansible 登入之後經由 sudo 切成 root）因此不必另外給密碼。sudo 要密碼的主機，ansible 與 ansible-playbook 要加 -K（--ask-become-pass）在執行時輸入，或把密碼放進 Ansible Vault（Ansible 內建的加密功能，把變數檔加密存放、執行時用密碼解開）加密的變數；不給的話 become 那一步失敗（依 Ansible 文件〈Understanding privilege escalation: become〉，沒有實跑）。由排程執行時沒有人輸入，-K 用不了；改用 Vault 時，解開 Vault 的密碼檔要放在控制端上，控制端被入侵時密碼檔與私鑰一起被拿走，風險的範圍沒有變小（推論）。
ansible-core 與 Terraform 固定版本：ansible-core 用 pip install ansible-core==2.17.7，Terraform 下載 1.9.8 的壓縮檔。改用 apt、pipx 或 HashiCorp 的套件庫安裝時拿到的版本可能不同，版本不同時 ansible 與 terraform 印出的格式與本文的輸出不保證相同（從版本差異推論，沒有實跑其他版本）。
Terraform 的壓縮檔沒有驗證雜湊：HashiCorp 在同一個目錄放了 terraform_<版本>_SHA256SUMS 與它的簽章，下載之後用 sha256sum -c 比對，可以確認下載到的檔案沒有被換掉；這次沒有做這一步（依 HashiCorp 的下載頁，沒有實跑）。
金鑰不設密碼：替代做法是設密碼，在控制端起 ssh-agent 並 ssh-add 解鎖一次：私鑰檔外洩時多一層密碼保護，代價是每次開一個新的 shell 都要先解鎖（推論，沒有實跑）。

控制端連到受管主機的 SSH：金鑰、known_hosts 與 sudo

控制端用的金鑰是〈受管主機與控制端的容器：Oracle Linux 10 加 systemd 與 sshd、python:3.12-slim 加 ansible-core 與 Terraform〉那一節在暫存目錄產生的那一把，開發機上自己的金鑰沒有拿來用：這把金鑰只授權給這兩個可拋棄的容器，清理時連同容器一起刪掉。

1# 開發機上；<工作目錄> 是〈前置條件：開發機的資源、檔案配置與檢查腳本〉的工作目錄，<暫存目錄> 是產生金鑰時用的那一個
2docker run -d --name mh-ctl --network mh-net -v <工作目錄>:/work -v <暫存目錄>/keys:/keys:ro mh-ctl:1 sleep infinity
3docker exec mh-ctl sh -c 'mkdir -p ~/.ssh && cp /keys/id_ed25519 ~/.ssh/ && chmod 600 ~/.ssh/id_ed25519
4  for h in mh-web1 mh-both1; do ssh-keyscan -t ed25519 $h; done > ~/.ssh/known_hosts
5  for h in mh-web1 mh-both1; do ssh ops@$h "id; sudo -n id -u"; done'

-v <工作目錄>:/work 把開發機上的工作目錄掛進控制端；金鑰的目錄唯讀掛載，再複製一份進容器改權限，因為 ssh 拒絕權限比 0600 寬的私鑰，而掛載進來的檔案權限照開發機那一份。私鑰複製到 ~/.ssh/id_ed25519，是 ssh 沒有指定金鑰時預設會試的路徑之一，Ansible 經由 ssh 連線時也就用這一把，inventory 不必另外寫 ansible_ssh_private_key_file。最後那個迴圈在 mh-web1 上印出 uid=1000(ops) 與 0：ops 登入成功，sudo -n（不問密碼，要密碼就直接失敗）切成了 root。這次實跑時這一條只連了 mh-web1，mh-both1 的登入與 sudo 由後面的 ansible -b 指令確認。

ssh-keyscan 把兩台主機出示的 host key 直接寫進 known_hosts，等於第一次連線時不比對指紋就信任（SSH Host Key 與 known_hosts（主機金鑰）卡寫了首次信任的風險）。在一個只有這三個容器的 Docker network 裡，連線的另一端只可能是這次建的容器，所以這次接受這個風險。改用自己的金鑰、或改用別的方式寫入 known_hosts 時的結果，在〈這一節的其他做法：自己的金鑰與寫入 known_hosts 的方式〉。

之後的 Terraform 與 Ansible 指令都在控制端容器裡的 shell 執行，從開發機進入那個 shell：

1# 開發機上；-w 把 shell 的工作目錄設在 /work/ansible
2docker exec -it -w /work/ansible mh-ctl bash

下文寫「控制端容器裡」的指令都在這個 shell 執行，工作目錄是 /work/ansible；Terraform 那幾條在 /work/tf，區塊裡先 cd /work/tf。

這一節的其他做法：自己的金鑰與寫入 known_hosts 的方式

用自己的金鑰：用自己的金鑰也連得上，代價是要把自己的私鑰掛進控制端容器，控制端容器裡的任何程式都讀得到它。
ssh-keyscan 寫進 known_hosts（這次的做法）：之後的連線都會比對 host key，主機重建、host key 換了時 ssh 拒絕連線。
不寫 known_hosts：Ansible 預設檢查 host key，第一次連到沒有紀錄的主機時沒有人回答確認的提問，那一台失敗；在 ansible.cfg 設 host_key_checking = False 可以跳過，代價是之後每次連線都不比對，連到被冒充的主機也不會發現（依 Ansible 文件〈Connection methods and details〉的〈Managing host key checking〉，沒有實跑）。
StrictHostKeyChecking=accept-new（OpenSSH 7.6 起）：第一次連到沒有紀錄的主機時自動把 host key 記進 known_hosts，之後 host key 變了照樣拒絕連線；首次連線同樣不比對指紋，跟 ssh-keyscan 承擔的是同一個風險，差別是不必先跑一次掃描（依 ssh_config 的文件，沒有實跑）。
比對主控台或序列主控台印出的指紋再寫入：真主機建立時，業者的主控台或序列主控台的開機輸出印得出 host key 的指紋，比對過 ssh-keyscan 取回的 host key 再寫進 known_hosts，第一次連線也不必無條件信任。代價是每建一台主機都要人工比對一次（這次沒有真主機，沒有實跑）。
SSH 憑證：只寫 CA 公鑰：用 SSH Certificate（SSH 憑證）簽主機金鑰的環境，known_hosts 只要寫一行 CA 的公鑰，新建的主機不必逐台加紀錄；代價是要先建好簽發主機憑證的 CA 與流程（從機制推論，沒有實跑）。

由 Terraform 產生 inventory：init、plan、apply 與 local_file 的檔案權限

Terraform 的設定（HCL 寫成）照多台主機的維護清單：值的分層與合併的位置、用 Ansible 的 inventory 與範本產生每台的清單、由 Terraform 的輸出產生 inventory、跨主機執行的 exit code，以及單台清單的適用範圍〈主機由 Terraform 建立時由它的輸出產生 inventory〉的寫法，主機改成這次的兩個容器，all 群組（Ansible 內建、包含 inventory 裡每一台主機的群組）加上 Ansible 登入用的帳號。跟概念文章那份設定不同的兩處：每台主機的鍵名 public_ip 改成 address，因為這次填的是容器名、不是 IP；filename 指向 ansible/ 目錄，inventory 寫在 Ansible 的變數檔旁邊。

 1# tf/main.tf
 2terraform {
 3  required_providers {
 4    local = { source = "hashicorp/local", version = "2.5.2" }
 5  }
 6}
 7
 8# 實際的設定裡，address 來自主機資源的屬性（例如 public_ip）；這裡用容器名代替
 9locals {
10  hosts = {
11    "mh-web1"  = { roles = ["web"], address = "mh-web1" }
12    "mh-both1" = { roles = ["web", "db"], address = "mh-both1" }
13  }
14}
15
16resource "local_file" "inventory" {
17  filename        = "${path.module}/../ansible/inventory.yml"
18  file_permission = "0644"
19  content = yamlencode({
20    all = {
21      vars = { ansible_user = "ops" }
22      children = {
23        for role in distinct(flatten([for h in values(local.hosts) : h.roles])) :
24        role => { hosts = { for name, h in local.hosts : name => { ansible_host = h.address } if contains(h.roles, role) } }
25      }
26    }
27  })
28}
29
30output "hosts" { value = local.hosts }

1# 控制端容器裡
2cd /work/tf
3terraform init
4terraform plan
5terraform apply -auto-approve
6ansible-inventory -i ../ansible/inventory.yml --graph
7terraform output -json hosts

required_providers 宣告這份設定要用的 provider（Terraform 操作某一類資源的外掛，hashicorp/local 管本機的檔案），terraform init 依它下載 provider；${path.module} 是 main.tf 所在的目錄，filename 因此指到 tf/ 旁邊的 ansible/。children 那兩層 for 把「每台主機有哪些角色」反轉成「每個角色有哪些主機」：外層取出不重複的角色，每個角色成為一個群組，內層把角色串列含有這個角色的主機收進那個群組。apply 的 -auto-approve 跳過執行前的確認提問，這裡用它是因為剛跑過 plan 看過內容。

terraform init 印出 Installed hashicorp/local v2.5.2 (signed by HashiCorp)，花了 8.8 秒（下載 provider 的時間，依網路而變）；plan 印 local_file.inventory will be created 與 Plan: 1 to add；apply 之後，--graph 列出 db 群組裡有 mh-both1、web 群組裡有 mh-both1 與 mh-web1，mh-both1 同時在兩個群組裡。產生出來的 inventory.yml（以同一份設定在 hashicorp/terraform:1.9.8 容器裡另外重跑 apply 之後 cat 的輸出；yamlencode 依鍵名排序，字串一律加引號）：

 1"all":
 2  "children":
 3    "db":
 4      "hosts":
 5        "mh-both1":
 6          "ansible_host": "mh-both1"
 7    "web":
 8      "hosts":
 9        "mh-both1":
10          "ansible_host": "mh-both1"
11        "mh-web1":
12          "ansible_host": "mh-web1"
13  "vars":
14    "ansible_user": "ops"

address 填的是容器名，Docker network 的內建 DNS 把它解析成容器的位址；真主機上填 <主機資源>.public_ip 這類屬性，或主機在私有網路時的私有位址，看控制端從哪一條網路連進去。

terraform output -json hosts 印出同一份主機清單的 JSON：{"mh-both1":{"address":"mh-both1","roles":["web","db"]},"mh-web1":{"address":"mh-web1","roles":["web"]}}，給 Ansible 以外的工具讀。

local_file 的 file_permission 預設值是 "0777"，實際的檔案權限是它扣掉建立檔案那個程序的 umask。照上面寫了 file_permission = "0644" 的設定做時，inventory.yml 的權限是 644；明寫 0644 讓權限不依賴執行環境的 umask，固定讓其他帳號改不了這份檔案。

這一行是這次第一次 apply 之後才加的。這個控制端容器的 umask 是 0000，所以沒有寫 file_permission 時，stat -c %a ../ansible/inventory.yml 印 777，同一台機器上的任何帳號都改得了 inventory，也就改得了 Ansible 要以 root 連去的主機清單；另一次在 umask 0022 的容器裡重跑是 755。

加上 file_permission = "0644" 之後，plan 印 local_file.inventory must be replaced 與 file_permission = "0777" -> "0644" # forces replacement，apply 之後權限是 644。

產生出來的檔案不手改。下面這個實驗是可以略過的驗證，用來確認手改會被蓋掉：在 inventory.yml 末端加一行 # 手加的一行 之後，plan 回報 local_file.inventory will be created，apply 之後那一行消失（grep -c 印 0），跟概念文章寫的結果相同。plan 寫的是重新建立，原因是 local_file 讀取時發現檔案內容跟 State 記的不同，就把這個資源當成不存在（從 plan 的訊息推論的機制）。

手寫 inventory、動態 inventory、直接讀 State 的 inventory plugin 這幾種做法的結果，在〈這一節的其他做法：產生 inventory 的方式〉。

這一節的其他做法：產生 inventory 的方式

產生 inventory 的方式與這次的環境下各自的結果：

Terraform 的 local_file（這次的做法）：主機清冊只有 locals（真實環境是主機資源）這一個來源，增刪主機時 inventory 跟著改。
手寫 inventory：不需要 Terraform；主機由 Terraform 建立時，增刪主機要在 Terraform 與 inventory 兩邊各改一次，判斷依據在概念文章〈主機由 Terraform 建立時由它的輸出產生 inventory〉。這次沒有實跑手寫的版本。
Ansible 的動態 inventory（雲端業者的 inventory plugin 直接查業者的 API）：主機由 autoscaling 這類服務建立、不在 State 裡時也列得出來，代價是控制端要有讀業者 API 的憑證，分組要依主機的標籤（依 Ansible 文件〈Working with dynamic inventory〉與各業者 plugin 的文件，沒有實跑）。
Ansible 的 cloud.terraform collection：它的 inventory plugin 直接讀 Terraform 的 State 列出主機，不寫 inventory.yml 這份檔案，也就沒有 local_file 的檔案權限與手改被蓋掉這兩件事（依 collection 的文件推論，沒有實跑）。讀 State 與寫檔案兩種做法的判斷依據在概念文章〈主機由 Terraform 建立時由它的輸出產生 inventory〉。

變數檔與範本：檢查腳本實際要求的欄位、兼任兩種角色的主機

變數檔照多台主機的維護清單：值的分層與合併的位置、用 Ansible 的 inventory 與範本產生每台的清單、由 Terraform 的輸出產生 inventory、跨主機執行的 exit code，以及單台清單的適用範圍〈用 Ansible 的 inventory、群組變數與範本產生每台的清單〉的分層：每台相同的寫在 group_vars/all.yml，依角色不同的寫在角色的檔案，每台不同的寫在 host_vars。

1# group_vars/all.yml：每台相同的預設值
2host_provider: container
3host_region: local
4min_free_bytes: 1073741824       # 根檔案系統至少留 1 GiB
5journal_limit_bytes: 1073741824
6update_timer: dnf-automatic.timer
7manifest_path: /etc/host-check/host.toml
8checker_path: /opt/host-check/host-check.py
9ansible_python_interpreter: /usr/bin/python3

1# group_vars/web.yml：web 角色；依角色不同的串列用帶角色名的變數名
2web_entrypoints:
3  - { name: http, port: 80, exposure: cdn-only }

1# group_vars/db.yml：db 角色
2db_entrypoints:
3  - { name: postgres, port: 5432, exposure: admin-only }

1# host_vars/mh-web1.yml：只有 mh-web1 不同的值
2min_free_bytes: 2147483648       # 這台的根檔案系統至少留 2 GiB

web.yml 與 db.yml 的入口串列用 web_entrypoints、db_entrypoints 兩個不同的變數名。兩個群組用同一個變數名時，同層的群組依名稱排序合併、後合併的蓋過先合併的，mh-both1 少掉一個角色的入口；合併規則與聯集的寫法在概念文章〈用 Ansible 的 inventory、群組變數與範本產生每台的清單〉。

ansible_python_interpreter 指定受管主機上的 Python。沒有指定時 Ansible 自己找，每次執行都印一段 [WARNING]: Platform linux on host mh-web1 is using the discovered Python interpreter at /usr/bin/python3.12，執行結果相同；指定之後警告消失。manifest_path 與 checker_path 是清單與腳本在受管主機上的固定位置，playbook 與執行檢查的指令都用這兩個值。清單放在 /etc/host-check/，因為 /etc 是 FHS 規定放設定檔的位置，主機備份設定檔時會一起收進去。host_provider 與 host_region 寫進清單 [host] 段的 provider 與 region，這次填 container 與 local，真主機填業者與區域的名稱；主機分在幾家業者或幾個區域時，這兩個值就從每台相同改成依群組或每台不同。

檢查腳本載入清單時逐欄比對型別與允許的值，所以範本照腳本要求的欄位寫。host-check.py 要求的欄位：

[host] 要有 name、provider、region、role 四個字串：role 只收一個字串，兼任兩種角色的主機寫成 group_names | join(',')，mh-both1 得到 "db,web"。group_names 是 Ansible 替每台主機算出的所屬群組清單（不含 all），依群組名排序；name 用的 inventory_hostname 是那台主機在 inventory 裡的名字（mh-web1、mh-both1）。
[listen_audit] 是 protocols 與 allow：允許接聽的連接埠由兩處合起來，where = "host" 的每一筆 [[entrypoint]] 自動算進去，allow 只寫入口以外、刻意允許的連接埠（每一筆是 { port, protocol, reason }）。所以入口的串列取聯集之後，listen_audit 就跟著有了兩個角色的連接埠，allow 這次是空的。
[[filesystem]] 的門檻是 min_free_bytes：剩餘空間的位元組數下限。
exposure 只能是 public、cdn-only、admin-only、loopback：寫了清單外的值（例如 private）時，檢查腳本把清單判成格式錯（exit code 2），〈一台變成 WARN、一台清單格式錯、一台連不上：ansible 的 exit code 與每台的 rc〉實測過。
[[entrypoint]] 要有 protocol、where、enforced_by，每一層防護至少一筆 [[entrypoint.verify]]：enforced_by 列出這個入口靠哪幾種防護限制來源（雲端防火牆、主機防火牆這類），每一種是一「層」，每一層至少寫一筆 [[entrypoint.verify]] 說明怎麼確認那一層（同一層寫兩筆也可以，這次每層寫一筆）。where 寫在哪裡要確認：host 是檢查腳本在主機上自己確認，console 是要人到業者主控台確認。這次每個入口寫一層 cloud-firewall，where = "console"，執行時印成要到主控台確認的 MANUAL。
[[log]]、[[accumulation]]、[updates]、[[suspend]]、[[resume]] 都是必填：少了任何一段，腳本判成格式錯。這次各寫一筆最小的內容。[[suspend]] 與 [[resume]] 的每一步要寫出主機停下來時還計不計費（billed_when_stopped 這幾個欄位）；容器沒有計費，填 unknown，欄位的意思在主機維護清單寫成 TOML：JSON、YAML、TOML 的取捨、TOML 1.0 與 1.1 的版本差異、清單的欄位設計與只讀檢查腳本〈清單欄位的設計：檢查腳本要讀的與人要讀的〉。

跟概念文章那份範本對照：概念文章的範本是示範值怎麼代入的節錄，鍵名有幾個是那篇自己取的，例如它的 [[filesystem]] 用 warn_percent（使用率的百分比），檢查腳本不認得這個鍵。

下面是 ansible/host.toml.j2 的全文。字串值一律經過 to_json 輸出，引號與反斜線由它跳脫，含中文的值加 ensure_ascii=False 讓中文原樣寫出；直接輸出時會發生什麼，在概念文章〈值寫進 TOML 的方式：直接輸出、to_json 與 ensure_ascii〉。

 1# 由 Ansible 依 host.toml.j2 產生，不在主機上手改。TOML 1.0。
 2[vars]
 3journal_dir = "/var/log/journal"
 4
 5[host]
 6name = {{ inventory_hostname | to_json(ensure_ascii=False) }}
 7provider = {{ host_provider | to_json(ensure_ascii=False) }}
 8region = {{ host_region | to_json(ensure_ascii=False) }}
 9role = {{ group_names | join(',') | to_json(ensure_ascii=False) }}
10
11[listen_audit]
12protocols = ["tcp"]
13allow = []
14
15{% set eps = [{'name': 'ssh', 'port': 22, 'exposure': 'admin-only'}]
16   + (web_entrypoints if 'web' in group_names else [])
17   + (db_entrypoints if 'db' in group_names else []) %}
18{% for ep in eps %}
19[[entrypoint]]
20name = {{ ep.name | to_json(ensure_ascii=False) }}
21port = {{ ep.port }}
22protocol = "tcp"
23exposure = {{ ep.exposure | to_json(ensure_ascii=False) }}
24where = "host"
25enforced_by = ["cloud-firewall"]
26
27  [[entrypoint.verify]]
28  layer = "cloud-firewall"
29  where = "console"
30  console_path = "業者主控台 → 網路 → 防火牆規則"
31  expect = {{ ("TCP " ~ ep.port ~ " 的規則只對 " ~ ep.exposure ~ " 的來源開放") | to_json(ensure_ascii=False) }}
32
33{% endfor %}
34[[log]]
35name = "sshd"
36source = "journal:sshd.service"
37look_for = "登入失敗與不認得的帳號"
38interval_days = 7
39manual_command = "journalctl -u sshd --since -7d"
40
41[[accumulation]]
42name = "journal"
43path = ["{% raw %}{{journal_dir}}{% endraw %}"]
44missing_ok = true
45limit_bytes = {{ journal_limit_bytes }}
46purge_command = "journalctl --vacuum-size=500M"
47
48[[filesystem]]
49name = "root"
50mount = "/"
51min_free_bytes = {{ min_free_bytes }}
52
53[updates]
54mode = "download-only"
55timer = {{ update_timer | to_json(ensure_ascii=False) }}
56config_files = ["/etc/dnf/automatic.conf"]
57expect = { download_updates = "yes", apply_updates = "no" }
58reboot_check = "dnf needs-restarting -r"
59
60[[suspend]]
61step = 1
62resource = "主機"
63billed_when_stopped = "unknown"
64billed_when_stopped_beyond_free = "unknown"
65billing_basis = "依業者的計費文件"
66where = "console"
67console_path = "業者主控台 → 主機 → 停止"
68verify = "主機的狀態是已停止"
69
70[[resume]]
71step = 1
72resource = "主機"
73billed_when_stopped = "unknown"
74billed_when_stopped_beyond_free = "unknown"
75billing_basis = "依業者的計費文件"
76where = "console"
77console_path = "業者主控台 → 主機 → 啟動"
78verify = "主機的狀態是執行中"

範本裡每台相同的值（ssh 的入口、log、累積的資料、更新的設定、暫停與恢復的步驟）直接寫在範本本身：這些值在所有主機都相同、也不隨角色變，放進 group_vars/all.yml 只多一層間接；它開始依群組或主機而變時，才換成變數。依角色不同的入口由 eps 那一行依 group_names 取聯集，每台不同的只有主機名與 min_free_bytes。[[accumulation]] 的 path 用檢查腳本自己的替換語法 {{journal_dir}}，包在 {% raw %} 與 {% endraw %} 之間，Jinja2 原樣輸出，留給檢查腳本換成 [vars] 的值；理由在概念文章〈範本的 {{ }} 與清單自己的替換語法同形〉。

部署到主機之前，先在控制端用 -c local 產生一份到 out/ 看內容：

 1# 控制端容器裡，在 /work/ansible 執行；out/ 要先存在
 2mkdir -p out
 3ansible all -i inventory.yml -c local -e ansible_python_interpreter=/usr/local/bin/python3 \
 4  -m template -a "src=host.toml.j2 dest=out/{{ inventory_hostname }}.toml" -o
 5python3 -c '
 6import sys, tomllib
 7for f in sys.argv[1:]:
 8    d = tomllib.load(open(f, "rb"))
 9    print(f, d["host"]["role"], [(e["name"], e["port"]) for e in d["entrypoint"]], d["filesystem"][0]["min_free_bytes"], d["accumulation"][0]["path"])
10' out/*.toml

ansible 這一條兩台都印 CHANGED，exit code 0。-m 指定要執行的模組（這裡是 template），-a 是給那個模組的參數，-o 把每台的結果擠成一行印出。-c local 讓 Ansible 在控制端自己身上執行模組，這時「受管主機」就是控制端，而 group_vars/all.yml 的 ansible_python_interpreter（/usr/bin/python3）照樣套用；python:3.12-slim 沒有 /usr/bin/python3，Python 裝在 /usr/local/bin/python3，所以用 -e 換成控制端的路徑，不換的話這一條以 exit code 2 失敗。python3 那一段用 tomllib 讀回兩份清單，印出：

1out/mh-both1.toml db,web [('ssh', 22), ('http', 80), ('postgres', 5432)] 1073741824 ['{{journal_dir}}']
2out/mh-web1.toml web [('ssh', 22), ('http', 80)] 2147483648 ['{{journal_dir}}']

mh-both1 有兩個角色的入口，門檻沿用 all 的 1 GiB；mh-web1 只有 web 的入口，門檻是 host_vars 的 2 GiB；兩份的 path 都留著 {{journal_dir}}。tomllib 讀得懂只代表語法正確；要確認欄位是否符合檢查腳本的規格，得讓檢查腳本自己載入一次，〈部署清單：建目錄、copy 與 template、validate 改用檢查腳本的載入函式、–check 的預覽〉裡 template 任務的 validate 做的就是這件事。out/ 的檔案在這個 umask 0000 的控制端上寫成 0666；它們只用來預覽，看完刪掉即可。省略這一步時的結果，在〈這一節的其他做法：省略本機的預覽〉。

這一節的其他做法：省略本機的預覽

這一步可以省略，直接部署也會寫出同樣的內容；先在本機產生一份的好處是不連任何主機就看得到每台的清單，改範本時可以先比對 out/ 裡新舊兩份的差異。

部署清單：建目錄、copy 與 template、validate 改用檢查腳本的載入函式、–check 的預覽

部署有三個任務：建放腳本與清單的目錄、把檢查腳本複製過去、依範本寫出每台的清單。三個任務都要以 root 寫進 /opt 與 /etc，所以整個 play 設 become: true，Ansible 以 ops 登入後經由 sudo 切成 root。

 1# deploy.yml
 2- hosts: all
 3  become: true
 4  tasks:
 5    - name: 放腳本與清單的目錄
 6      ansible.builtin.file:
 7        path: "{{ item }}"
 8        state: directory
 9        owner: root
10        group: root
11        mode: "0755"
12      loop:
13        - "{{ checker_path | dirname }}"
14        - "{{ manifest_path | dirname }}"
15    - name: 檢查腳本
16      ansible.builtin.copy:
17        src: files/host-check.py
18        dest: "{{ checker_path }}"
19        owner: root
20        group: root
21        mode: "0755"
22    - name: 每台的清單（寫出之前用檢查腳本自己的載入函式驗證）
23      ansible.builtin.template:
24        src: host.toml.j2
25        dest: "{{ manifest_path }}"
26        owner: root
27        group: root
28        mode: "0644"
29        validate: >-
30          python3 -I -c 'import runpy, sys;
31          runpy.run_path(sys.argv[1], run_name="hc")["load_manifest"](sys.argv[2])'
32          {{ checker_path }} %s

建目錄的任務用 loop 對串列裡的每一項各執行一次，每一次的值放在 item；dirname 過濾器取路徑的上層目錄，/opt/host-check/host-check.py 得到 /opt/host-check。validate: >- 是 YAML 的折疊寫法：底下幾行接成一行、行與行之間換成空白、結尾不留換行，長指令可以分行寫。

1# 控制端容器裡
2ansible-playbook -i inventory.yml deploy.yml --check --diff   # 預覽，不寫任何檔案
3ansible-playbook -i inventory.yml deploy.yml

加上 file 任務之後，第一次執行三個任務都是 changed，再執行一次 changed=0，花 1.9 秒（兩台，控制端與主機在同一台開發機上，真主機要加上網路來回的時間）。

這次遇到的錯誤：建目錄的任務是第一次實跑失敗之後加的。最初的 playbook 只有 copy 與 template 兩個任務，--check --diff 預覽時兩台都回報 changed=2、failed=0；實際執行時兩台都在 copy 那一步失敗，訊息是 Destination directory /opt/host-check does not exist，exit code 2。copy 與 template 都不建上層目錄（template 單獨執行時同樣以 Destination directory … does not exist 失敗，另外單獨實跑過一次確認），而 check 模式沒有實際寫檔，碰不到這個錯誤，所以預覽的 failed=0 不代表實際執行會成功。

validate 用的是檢查腳本自己的載入函式。多台主機的維護清單：值的分層與合併的位置、用 Ansible 的 inventory 與範本產生每台的清單、由 Terraform 的輸出產生 inventory、跨主機執行的 exit code，以及單台清單的適用範圍〈產生時驗證清單與比對主機上的清單〉的 validate 範例只用 tomllib 解析，驗得到語法、驗不到欄位。host-check.py 的 load_manifest() 讀清單並逐欄驗證（逐欄驗證的程式在原始碼那一篇〈清單的載入與驗證：Probe、_Validator、load_manifest 與 validate〉），格式錯時丟出 ManifestError，不執行任何檢查，所以 validate 用 runpy.run_path 載入腳本、只呼叫這個函式：函式丟出例外時 Python 以 exit 1 結束，Ansible 判成驗證失敗，那一台的清單維持原樣。

用 runpy.run_path 載入腳本：腳本開頭有 from __future__ import annotations，dataclass 要從 sys.modules 找到這個模組。runpy.run_path 執行期間會把它登記進去，run_name="hc" 讓腳本結尾的 if __name__ == "__main__" 不成立，main() 不會跑。
%s 與 {{ checker_path }}：%s 由 Ansible 換成暫存檔的路徑，{{ checker_path }} 換成上一個任務放好的腳本。validate 在受管主機上執行，用的是主機上的 Python 與主機上那一份腳本，所以 copy 的任務要排在 template 之前，主機上的 Python 也要是 3.11 以上（tomllib）。
-I：Python 的隔離模式，忽略所有 PYTHON* 環境變數，不把目前目錄與使用者的 site-packages 加進模組的搜尋路徑；執行 validate 時的工作目錄裡放了 json.py 這類跟標準函式庫同名的檔案，也不會取代標準函式庫被載入。

這次遇到的錯誤：寫進 validate 之前，先在控制端拿 out/ 的兩份清單試載入；最初用 importlib.util.spec_from_file_location 載入，在腳本的 @dataclass 那一行丟出 AttributeError: 'NoneType' object has no attribute '__dict__'，因為那樣載入的模組沒有登記進 sys.modules。

check 模式不執行 validate：另外在一個裝 ansible-core 2.17.7 的容器裡，以 -c local 對一個 template 任務設 validate 指向一條一定 exit 1、執行時會留下紀錄的指令，--check --diff 回報 changed、exit code 0，紀錄檔沒有出現；拿掉 --check 實際執行時以 failed to validate 失敗、exit code 2，紀錄檔有那一行。所以會被 validate 擋下的清單，--check 的預覽照樣顯示成功。

--check --diff 對 copy 任務會印出整份腳本的差異（這次一千多行），清單的差異埋在後面；只想看清單時，用〈一台變成 WARN、一台清單格式錯、一台連不上：ansible 的 exit code 與每台的 rc〉那一節的 ad-hoc 指令，只對 template 模組跑 --check --diff。

validate 的其他寫法、逐台驗證造成的部分部署、copy 任務的替代，在〈這一節的其他做法：validate 的寫法、部分部署與 copy 的替代〉。

這一節的其他做法：validate 的寫法、部分部署與 copy 的替代

這個 validate 擋得下的範圍在下面〈一台變成 WARN、一台清單格式錯、一台連不上：ansible 的 exit code 與每台的 rc〉實測過一次：db 角色寫了 exposure: private 時，只有 mh-both1 驗證失敗、維持舊的清單，mh-web1 照常部署。三種寫法的差別：

檢查腳本的載入函式（這次的做法）：型別、允許的值、必填欄位、白名單都在寫出之前驗過，主機上不會出現一份腳本拒絕載入的清單。需要腳本有這樣的函式，而且 validate 依賴腳本內部的函式名，腳本改名時這一行要跟著改。
只用 tomllib：只要求主機上有 Python 3.11 以上，不依賴腳本的內部；exposure = "private" 這種語法正確、值不允許的寫法會被寫到主機上，等下一次執行檢查時腳本以 exit code 2 結束（exposure = "private" 是合法的 TOML，所以 tomllib 照常解析，這一點是從 TOML 的語法推的，沒有另外實跑）。
不寫 validate：寫壞的清單直接上主機。〈一台變成 WARN、一台清單格式錯、一台連不上：ansible 的 exit code 與每台的 rc〉那一節在主機上手改清單的實驗就是這個結果：那台主機在修好之前一項檢查都沒有跑。

validate 逐台執行，一台驗證失敗時其他台照常寫出新版，結果是部分部署：這次 exposure: private 那一輪，mh-web1 照常部署、mh-both1 留在舊版；範本的改動同時涉及兩台時，兩台就會停在不同的版本。要全部主機一起成功或一起不動時，有兩種替代：先在控制端用 -c local 產生全部主機的清單，用同一個載入函式驗完再部署；或在 play 設 any_errors_fatal: true，有一台失敗就停下整個 play（兩種都是推論，沒有實跑；any_errors_fatal 停的是之後的任務，失敗那一刻之前已經寫出的主機不會退回）。

copy 那一個任務另有兩種做法：把檢查腳本放進主機的映像檔，或打包成套件由套件管理員安裝。兩種都讓腳本的版本跟著映像檔或套件的版本走，代價是改腳本要重建映像檔或重新打包；打包成 rpm 時，另外換到 rpm -V 查得出主機上那一份腳本有沒有被改過。這次腳本與清單一起由 Ansible 部署，改腳本與改範本是同一個步驟。這一點是從部署的流程推的，沒有實作另外兩種。

以 -b 與 systemd-run 執行檢查腳本：每台的輸出與 ansible 的 exit code

執行檢查之前，先確認 systemd-run 的限制在這次的容器裡有沒有套上：主機維護清單寫成 TOML：JSON、YAML、TOML 的取捨、TOML 1.0 與 1.1 的版本差異、清單的欄位設計與只讀檢查腳本記錄過 OrbStack 的 LXC 機器會讓限制靜默無效。

1# 控制端容器裡
2ansible all -i inventory.yml -b -m command -a "systemd-detect-virt" -o
3ansible mh-web1 -i inventory.yml -b -m command -a "systemd-run --wait --pipe --collect -p ProtectSystem=strict touch /var/x"

systemd-detect-virt 兩台都印 docker（Docker 容器；LXC 環境印的是 lxc）；touch /var/x 那一條在 mh-web1 上以 rc=1 失敗，輸出 /bin/touch: cannot touch '/var/x': Read-only file system，ProtectSystem=strict 套上了。印的是 lxc、或 touch 成功時，這個環境量不到沙箱的效果，真主機上的確認方式在〈容器跟真主機不同的地方，以及在真主機上要另外確認的項目〉。這一條的 ansible 指令本身以 exit code 2 結束，是預期的結果：rc=1 正是要看到的失敗（整批的 exit code 怎麼讀，在多台主機的維護清單：值的分層與合併的位置、用 Ansible 的 inventory 與範本產生每台的清單、由 Terraform 的輸出產生 inventory、跨主機執行的 exit code，以及單台清單的適用範圍〈用 Ansible 對多台主機執行檢查腳本：整批的 exit code、每台的 rc 與執行身分的代價〉）。

執行檢查的指令寫成一支小腳本，屬性照 TOML 那一篇〈只讀檢查腳本的白名單、輸出、exit code 與結果檔〉的 systemd-run 寫法。這次量輸出時 check.sh 寫的是固定路徑 /opt/host-check/host-check.py 與 /etc/host-check/host.toml，跟下面用變數的版本代入之後的值相同：

1#!/bin/bash
2# check.sh：對 inventory 的每台主機以 root、在 systemd 沙箱裡執行檢查腳本；"$@" 接其他 ansible 參數（例如 --limit）
3ansible all -i inventory.yml -b -m command -o -a "systemd-run --wait --pipe --collect \
4  -p ProtectSystem=strict -p 'ReadWritePaths=/var/log /var/cache/dnf' \
5  -p StateDirectory=host-check -p StateDirectoryMode=0700 \
6  -p NoNewPrivileges=yes -p PrivateTmp=yes -p IPAddressDeny=any \
7  python3 {{ checker_path }} --manifest {{ manifest_path }}" "$@"

check.sh 建在控制端的 /work/ansible（開發機上是工作目錄的 ansible/），建好之後在控制端容器裡加上執行權限，下文以 ./check.sh 執行：

1chmod +x check.sh

要依環境換的位置只有 all（要檢查的主機範圍）。腳本與清單的路徑寫成 {{ checker_path }} 與 {{ manifest_path }}，Ansible 執行時用每台主機的變數代入，跟部署時用的是同一組值；寫死路徑的話，group_vars 改了位置而 check.sh 沒改時，檢查會安靜地讀舊路徑上過期的清單。command 模組用 shlex 切參數、不經過 shell，所以 'ReadWritePaths=/var/log /var/cache/dnf' 的單引號讓兩個路徑留在同一個參數裡。變數代入與引號的切法另外在一個裝 ansible-core 2.17.7 的容器裡，以 -c local 對設了這兩個變數的 localhost 實跑過一次：{{ checker_path }} 與 {{ manifest_path }} 換成了變數的值，'ReadWritePaths=/var/log /var/cache/dnf' 留在同一個參數裡。不加 --manifest 時，腳本讀它自己所在目錄的 host.toml，這次清單放在 /etc/host-check/，所以要寫。

讀下面的輸出之前，先把兩個 exit code 分開：ansible 指令本身的 exit code 是整批的結果，每台的 rc 是那台主機上檢查腳本的 exit code。

`ansible` 指令的 exit code（整批）	代表
0	每台的任務都成功
2	至少一台主機的任務失敗（標成 `FAILED!`）
4	有主機連不上（標成 `UNREACHABLE!`）

每台的 `rc`（檢查腳本的 exit code）	代表
0	沒有 `WARN`
1	至少一項 `WARN`
2	清單格式錯，或命令列參數錯（stderr 印用法說明而不是 `manifest error:`）

讀的順序：先看整批的值決定要不要告警，再看每台的 rc 決定處置；rc 是 1 時另看輸出裡有沒有 summary: 那一行。

./check.sh 第一次執行，ansible 的 exit code 是 0，花 0.9 秒。兩台都印 CHANGED | rc=0；command 模組不論指令做了什麼一律回報 changed，所以這個 CHANGED 只代表指令執行了，不代表檢查改動了主機。-o 把每台的報告印成一行、換行寫成 \n；要看分行的報告時，拿掉 -o 再跑一次（ansible all -i inventory.yml -b -m command -a "…"，指令照 check.sh），每台的 stdout 會分行印出。mh-both1 的報告：

 1PASS   entrypoint/ssh:22/tcp  有程序在聽（0.0.0.0, [::]），exposure=admin-only
 2MANUAL entrypoint/ssh:22/tcp/cloud-firewall  [主控台] 業者主控台 → 網路 → 防火牆規則 → 預期：TCP 22 的規則只對 admin-only 的來源開放
 3PASS   entrypoint/http:80/tcp  有程序在聽（0.0.0.0），exposure=cdn-only
 4MANUAL entrypoint/http:80/tcp/cloud-firewall  [主控台] 業者主控台 → 網路 → 防火牆規則 → 預期：TCP 80 的規則只對 cdn-only 的來源開放
 5PASS   entrypoint/postgres:5432/tcp  有程序在聽（0.0.0.0），exposure=admin-only
 6MANUAL entrypoint/postgres:5432/tcp/cloud-firewall  [主控台] 業者主控台 → 網路 → 防火牆規則 → 預期：TCP 5432 的規則只對 admin-only 的來源開放
 7PASS   listen-audit  loopback 以外只有清單列出的連接埠在聽（tcp）
 8PASS   log/sshd  最新一筆：2026-10-26T13:44:47+00:00 mh-both1 python3[1904]: ansible-ansible.legacy.command Invoked …；每 7 天讀一次：journalctl -u sshd --since -7d
 9PASS   accumulation/journal  路徑不存在，算 0 bytes（/var/log/journal）
10PASS   filesystem/root  / 剩 77.7 GiB／共 117.6 GiB（下限 1.0 GiB）
11PASS   updates/dnf-automatic.timer/is-enabled  enabled（預期 enabled）
12PASS   updates/dnf-automatic.timer/is-active  active（預期 active）
13PASS   updates/config  download_updates = yes, apply_updates = no（mode download-only，讀了 /etc/dnf/automatic.conf）
14PASS   updates/reboot  不需要重開機
15since: 沒有前一次的結果（/var/lib/host-check/last.json）
16summary: 11 PASS, 0 WARN, 3 MANUAL（phase maintain，/etc/host-check/host.toml）

mh-web1 少了 postgres 的兩行，結果是 10 PASS, 0 WARN, 2 MANUAL，filesystem/root 的下限印成 2.0 GiB。summary: 裡的 phase maintain 是這次跑的檢查階段：檢查腳本分維護（maintain，預設）、暫停（suspend）與恢復（resume）三種階段，這次跑的是維護。報告之後的 stderr 是 systemd-run 印的那一次執行的資料：Finished with result: success、Service runtime: 378ms、Memory peak: 79M。三個值得讀的位置：

accumulation/journal 判成 PASS 而路徑不存在：[[accumulation]] 寫了 missing_ok = true，這個容器的 journald（systemd-journald）只把 journal 存在記憶體裡（/run/log/journal），/var/log/journal 沒有建出來。path 那一格印出 /var/log/journal，代表檢查腳本把 {{journal_dir}} 換成了 [vars] 的值。
log/sshd 的最新一筆是 Ansible 自己留下的：ansible-ansible.legacy.command Invoked 是這次執行檢查時 Ansible 的模組寫進 journal 的紀錄，而它被算在 sshd.service 底下，所以「journal 裡有 sshd 的紀錄」這一項由檢查的執行本身滿足。成因寫在〈容器跟真主機不同的地方，以及在真主機上要另外確認的項目〉。
結果檔：/var/lib/host-check 是 700、last.json 是 600，擁有者都是 root，StateDirectoryMode=0700 生效了。第二次執行時 since: 那一行印出上一次的時間，量到的值都跟前一次相同時接著印 ，與前一次相同（since: <上一次的時間>，與前一次相同），後面沒有其他行；DELTA <項目> 舊值 → 新值（差） 這種行只在量到的值變了時出現，例如〈一台變成 WARN、一台清單格式錯、一台連不上：ansible 的 exit code 與每台的 rc〉把門檻改成 1 TiB 的那一輪。

不加 -b、不經過 systemd-run、改由每台的 timer 執行、接上排程時讀結果的方式，以及沙箱屬性寫在 check.sh 的代價，在〈這一節的其他做法：-b、systemd-run、執行的位置、排程讀結果與屬性的住址〉。

這一節的其他做法：-b、systemd-run、執行的位置、排程讀結果與屬性的住址

執行檢查這一步，在 -b、systemd-run 與執行的位置上各有替代。「不加 -b」與「不加 -b、也不經過 systemd-run」只對 mh-web1 跑過，指令是：

1# 控制端容器裡；不加 -b：check.sh 那一條拿掉 -b，只對 mh-web1
2ansible mh-web1 -i inventory.yml -m command -o -a "systemd-run --wait --pipe --collect \
3  -p ProtectSystem=strict -p 'ReadWritePaths=/var/log /var/cache/dnf' \
4  -p StateDirectory=host-check -p StateDirectoryMode=0700 \
5  -p NoNewPrivileges=yes -p PrivateTmp=yes -p IPAddressDeny=any \
6  python3 /opt/host-check/host-check.py --manifest /etc/host-check/host.toml"
7# 不加 -b、也不經過 systemd-run：以 ops 直接執行檢查腳本
8ansible mh-web1 -i inventory.yml -m command -o -a "python3 /opt/host-check/host-check.py --manifest /etc/host-check/host.toml --no-state"

不加 -b：systemd-run 以 ops 執行，ansible 把 mh-web1 標成 FAILED!、rc 是 1，stderr 是 Failed to start transient service unit: Access denied，檢查腳本沒有執行，ansible 的 exit code 是 2。這個 rc 跟檢查腳本「至少一項 WARN」的 exit code 1 相同，只看 rc 分不開，要看輸出裡有沒有 summary: 那一行：腳本跑完一定印它，沒有這一行代表腳本沒有跑完或沒有開始。
不加 -b、也不經過 systemd-run（以 ops 直接執行檢查腳本；--no-state 不讀也不寫結果檔，這次的測試因此不改到 root 那份 last.json）：腳本照常跑完，stderr 印 note: 不是 root，journal、audit.log 與 collector 的目錄可能讀不到（會印成 WARN），結果是 9 PASS, 1 WARN, 2 MANUAL，多出來的 WARN 是 log/sshd（ops 讀不到 journal）。這次的清單只有少數幾項需要 root；TOML 那一篇的完整清單在專用帳號（加了 systemd-journal 與 adm 兩個群組的非 root 帳號）下，從 37 項 PASS 掉到 29 項。
以 root 執行而不套 systemd-run：這次沒有跑。結果依 TOML 那一篇的量測：檢查照常，dnf 的 log 與 sqlite 的 -shm 這類工具自己的寫入不再被擋下，檢查過程會在主機上留下寫入，只讀的保證沒有了。
Ansible 集中執行，或每台用自己的 timer 執行：這次用的是 Ansible 集中執行。多台主機的維護清單：值的分層與合併的位置、用 Ansible 的 inventory 與範本產生每台的清單、由 Terraform 的輸出產生 inventory、跨主機執行的 exit code，以及單台清單的適用範圍〈用 Ansible 對多台主機執行檢查腳本：整批的 exit code、每台的 rc 與執行身分的代價〉寫了集中執行的代價：控制端握有能 SSH 登入每台、再切成 root 的憑證。這次的 ops 帳號是 NOPASSWD: ALL，控制端的這把私鑰就等於兩台的 root。
接上排程時讀結果的方式：-o 的一行輸出要用 grep 分出每台的 rc。設 ANSIBLE_STDOUT_CALLBACK=json 時，ansible 改印一份 JSON，每台的 rc 與 stdout 是其中的欄位，排程的腳本可以直接取值，代價是輸出不再適合人直接讀；改寫成 playbook，在任務上設 failed_when: result.rc not in [0, 1]（result 是 register 存下的結果），WARN 的 rc=1 就不算失敗，整批的 exit code 只在清單格式錯或腳本沒跑起來時變成 2，代價是 WARN 要另外從輸出裡讀（兩種都是推論，沒有實跑）。

沙箱的屬性寫在 check.sh 裡有一個代價：同一組屬性在主機自己的 timer unit 裡還有一份，收緊其中一份時漏改另一份，沒有任何訊號。替代做法是把屬性放在主機上的一支包裝腳本或一個靜態的 service unit 裡，check.sh 與 timer 都呼叫它，屬性只有一份（推論，沒有實跑）。

一台變成 WARN、一台清單格式錯、一台連不上：ansible 的 exit code 與每台的 rc

這一節依序製造門檻造成的 WARN、清單格式錯（被 validate 擋下的與在主機上手改的）、連不上的主機，每一種情形看 ansible 指令本身的 exit code，以及每台的標記與 rc。

門檻讓 mh-web1 變成 WARN。把 host_vars/mh-web1.yml 的 min_free_bytes 改成 1 TiB（1099511627776），行尾的註解 # 這台的根檔案系統至少留 2 GiB 一起改成 1 TiB，之後讀這個檔的人才不會被舊的註解誤導。部署之前先只對 template 預覽：

1# 控制端容器裡
2ansible all -i inventory.yml -b -m template -a "src=host.toml.j2 dest=/etc/host-check/host.toml" --check --diff

mh-both1 印 SUCCESS、"changed": false；mh-web1 印 --- before: /etc/host-check/host.toml 與 +++ after: 兩邊的差異，只有一行從 -min_free_bytes = 2147483648 換成 +min_free_bytes = 1099511627776，標成 CHANGED。這條指令的 exit code 是 0，有主機標成 CHANGED 時也是 0，所以拿它定期比對主機上的清單時，要讀輸出裡有沒有 CHANGED，只看 exit code 看不出哪一台的清單跟範本不同；判斷依據在多台主機的維護清單：值的分層與合併的位置、用 Ansible 的 inventory 與範本產生每台的清單、由 Terraform 的輸出產生 inventory、跨主機執行的 exit code，以及單台清單的適用範圍〈產生時驗證清單與比對主機上的清單〉。以 ansible-playbook -i inventory.yml deploy.yml 部署之後，再跑 ./check.sh：

1mh-both1 | CHANGED | rc=0 | (stdout) …summary: 11 PASS, 0 WARN, 3 MANUAL…
2mh-web1 | FAILED! => {"changed": true, … "rc": 1, … "msg": "non-zero return code", …}

ansible 的 exit code 是 2。mh-web1 的報告裡是 WARN filesystem/root / 剩 77.7 GiB／共 117.6 GiB（下限 1024.0 GiB）、CHANGED filesystem/root PASS→WARN 與 summary: 9 PASS, 1 WARN, 2 MANUAL。-o 對成功的主機印一行 CHANGED | rc=0 | (stdout) …，對失敗的主機把整份結果印成一行 JSON，rc 是 JSON 裡的一個欄位，所以用 grep 分出每台的 rc 時，兩種形式都要比對。

db 角色的 exposure 寫成 private，被 validate 擋下。把 group_vars/db.yml 的 admin-only 改成 private 再跑 ansible-playbook -i inventory.yml deploy.yml：exit code 2，mh-both1 在 template 那一步失敗，"msg": "failed to validate"，stderr 的最後一行是 hc.ManifestError: entrypoint[postgres]: exposure 要是 ['public', 'cdn-only', 'admin-only', 'loopback'] 之一，實際是 'private'；mh-web1 不在 db 群組，failed=0。mh-both1 上的 /etc/host-check/host.toml 仍是上一版，三個 exposure 都沒有 private。把 group_vars/db.yml 改回 admin-only；主機上的清單沒有被改到，這裡不必重新部署。

在主機上手改清單，檢查腳本以 exit code 2 結束。validate 擋下的是 Ansible 寫出的那一份；有人在主機上直接改檔，或另一條部署路徑沒有 validate 時，壞掉的清單照樣在主機上。用 sed 把 mh-both1 清單裡的 exposure = "admin-only" 改成 exposure = "private"，ssh 與 postgres 兩個入口都改到：

1# 開發機上執行：在 mh-both1 上直接改清單
2docker exec mh-both1 sed -i 's/exposure = "admin-only"/exposure = "private"/' /etc/host-check/host.toml

mh-web1 維持 1 TiB 的門檻，再跑 ./check.sh：

主機	`-o` 的標記	`rc`	報告
`mh-both1`	`FAILED!`	2	stderr 兩行 `manifest error: entrypoint[…]: exposure 要是 … 之一，實際是 'private'`，最後一行 `manifest error: 2 項，沒有執行任何檢查`
`mh-web1`	`FAILED!`	1	`summary: 9 PASS, 1 WARN, 2 MANUAL`

ansible 的 exit code 是 2。兩台都標成 FAILED!，rc 分別是 2 與 1：mh-both1 在修好清單之前一項檢查都沒有跑，mh-web1 跑完了檢查、有一項 WARN（這次是門檻寫錯）。整批的 exit code 與每台的 rc 各自用來決定什麼，判斷依據在概念文章〈用 Ansible 對多台主機執行檢查腳本：整批的 exit code、每台的 rc 與執行身分的代價〉。接著依序做四件事，把兩台帶回全部 PASS：

比對主機上的清單：用門檻那一段只對 template 跑的 --check --diff 指令。mh-both1 標成 CHANGED，差異是兩行 -exposure = "private" 換成 +exposure = "admin-only"；mh-web1 是 SUCCESS，範本與主機上的門檻都是 1 TiB。exit code 0。
門檻改回 2 GiB：host_vars/mh-web1.yml 的 min_free_bytes 與註解改回 2147483648 與 2 GiB。
重新部署：ansible-playbook -i inventory.yml deploy.yml。這一步同時照範本把 mh-both1 的清單寫回 admin-only。不重新部署、只在主機上改回時，替代做法是在開發機上跑反向的 sed：docker exec mh-both1 sed -i 's/exposure = "private"/exposure = "admin-only"/' /etc/host-check/host.toml；已經重新部署的話不必跑。
再跑 ./check.sh：exit code 回到 0，mh-web1 的報告多一行 CHANGED filesystem/root WARN→PASS。

mh-web1 連不上。在開發機上 docker stop mh-web1 之後跑 ./check.sh：exit code 4，花 0.6 秒；mh-web1 印 UNREACHABLE!: Failed to connect to the host via ssh: ssh: Could not resolve hostname mh-web1: Name or service not known，沒有 rc；mh-both1 照常 CHANGED | rc=0。停掉的容器從 Docker network 的 DNS 消失，所以錯誤是解析不到主機名；真主機關機或網路斷了時，錯誤多半是連線逾時或被拒，exit code 同樣是 4（依 ansible-core 2.17.7 的原始碼 lib/ansible/executor/task_queue_manager.py 的 RUN_* 常數與這次的結果推論，真主機的訊息沒有實測）。同一次執行裡一台失敗、一台連不上時，依 ansible-core 2.17.7 的原始碼（plugins/strategy/__init__.py），有主機連不上時優先回 4，沒有才回 2；這次沒有實跑。照本文做不會同時出現兩種情形；排程裡同時有連不上與 FAILED! 時才用得到。

在開發機上 docker start mh-web1，等 systemd 啟動完成、sshd 開始接聽之後（docker exec mh-web1 systemctl is-system-running --wait），再跑一次 ./check.sh：exit code 2，mh-web1 的 rc 是 1，報告是 WARN entrypoint/http:80/tcp 沒有程序在聽這個連接埠，exposure=cdn-only 與 CHANGED entrypoint/http:80/tcp PASS→WARN：代替 nginx 的 stand-in-http 是 systemd-run 建的暫時的 unit，容器重啟之後沒有被拉起來。這跟真主機重開機之後某個服務沒有設成開機啟動是同一種結果，清單裡寫了那個入口，它就被報出來。在開發機上重新起代替的接聽程式之後，./check.sh 回到 exit code 0：

1# 開發機上執行
2docker exec mh-web1 systemd-run --unit=stand-in-http python3 -m http.server 80

這次各情形的整批 exit code 與每台的結果：

情形	`ansible` 的 exit code（整批）	每台的標記與 `rc`（每台）
全部 `PASS` 與 `MANUAL`	0	兩台 `CHANGED`、`rc=0`
一台的門檻造成 `WARN`	2	該台 `FAILED!`、`rc` 1；另一台 `rc=0`
一台清單格式錯、另一台有 `WARN`	2	兩台都 `FAILED!`，`rc` 分別是 2 與 1
一台連不上	4	該台 `UNREACHABLE!`、沒有 `rc`；另一台 `rc=0`
不加 `-b`，`systemd-run` 起不來	2（只對 `mh-web1` 跑）	該台 `FAILED!`、`rc` 1，輸出沒有 `summary:`
`--check --diff` 比對出清單被改過	0	該台 `CHANGED`，輸出有 `--- before` 與 `+++ after`

容器跟真主機不同的地方，以及在真主機上要另外確認的項目

照著在容器上做完不需要這一節；要把同樣的部署搬到真主機時，逐項確認。這次的受管主機是容器，有幾項結果在真主機上會不同，照著做在真主機上時，下面每一項要另外確認一次：

沙箱有沒有套上：這次的容器 systemd-detect-virt 印 docker，ProtectSystem=strict 底下 touch /var/x 回 Read-only file system。在 OrbStack 的 Linux machine 這類 LXC 環境裡同一條 touch 會成功、而且不報錯（主機維護清單寫成 TOML：JSON、YAML、TOML 的取捨、TOML 1.0 與 1.1 的版本差異、清單的欄位設計與只讀檢查腳本〈只讀檢查腳本的白名單、輸出、exit code 與結果檔〉記錄的 OrbStack Linux machine 實測），所以真主機上照樣先跑 systemd-detect-virt 與 touch /var/x 那兩條，再執行檢查。
SELinux：容器裡沒有 SELinux（Mandatory Access Control（強制存取控制）：SELinux 與 AppArmor），getenforce 這類檢查與 SELinux 對 systemd-run 執行的程序的限制都沒有量到。Oracle Linux 與 RHEL 的真主機預設是 enforcing（依 RHEL 文件〈Using SELinux〉，這次沒有在真主機上確認），部署到 /opt/host-check 的腳本由 systemd-run 執行時，SELinux 是否拒絕它的存取，要在真主機上跑一次檢查，再用 ausearch -m avc -ts recent 查有沒有拒絕的紀錄。
log/sshd 被 Ansible 自己的紀錄滿足：容器遮蔽了 systemd-logind，SSH 登入之後的程序留在 sshd.service 的 cgroup 裡，Ansible 模組寫進 journal 的紀錄因此算在 sshd.service 底下。真主機上 logind 會替每個登入建一個 session-<編號>.scope，那些紀錄落在 session 底下（從 logind 的機制推的，沒有在真主機上比對）；在真主機上用 journalctl -u sshd -n 5 看最新幾筆是 sshd 自己的紀錄還是 Ansible 的，確認這一項量的是 sshd。
雲端防火牆：清單裡每個入口的 cloud-firewall 那一層都是 MANUAL，這次沒有任何雲端資源可以比對。主機與規則由 Terraform 建立時，terraform plan 比對得到與比對不到的範圍在多台主機的維護清單：值的分層與合併的位置、用 Ansible 的 inventory 與範本產生每台的清單、由 Terraform 的輸出產生 inventory、跨主機執行的 exit code，以及單台清單的適用範圍〈清單裡要到主控台確認的項目與 terraform plan 的比對範圍〉。
主機防火牆：容器裡沒有 firewalld，清單也沒有寫主機防火牆那一層；真主機的清單在 enforced_by 加上 firewalld，並在那一層的 [[entrypoint.verify]] 寫 where = "host" 與探針（command 欄位寫要執行的 firewall-cmd --query-* 指令，expect_exit 這類欄位寫什麼結果算通過）。
journal 只在記憶體裡：這次的容器與 Oracle Cloud 的 Oracle Linux 10.2 映像檔預設都只把 journal 存在記憶體（長期上線主機的維護項目：會累積的資料、定期讀的 log、對外入口的盤點、安全更新、會到期的設定與檢查間隔的推算〈journald 的紀錄存在記憶體還是磁碟〉），/var/log/journal 不存在，accumulation/journal 以 missing_ok 判成 PASS。開了 Storage=persistent、或發行版預設建了 /var/log/journal 的主機（Debian 系；同一節寫了 Debian 12、13 與 Ubuntu 24.04 的 systemd 套件在安裝時建立這個目錄，以及在 Oracle Cloud 的 Ubuntu 24.04 映像檔上的確認）上，這一項才量得到實際大小，1 GiB 的上限要照那台主機的磁碟與 SystemMaxUse= 重訂。
連線位址與延遲：ansible_host 這次是容器名，部署 1.9 秒、檢查 0.9 秒都沒有經過真正的網路；真主機上 ansible_host 填 IP 或 DNS 名稱，時間會加上每台的 SSH 連線。
sudo 與 host key：這次的 ops 是 NOPASSWD: ALL，known_hosts 由 ssh-keyscan 直接寫入，兩者在真主機上都要重新決定；host key 的做法在〈這一節的其他做法：自己的金鑰與寫入 known_hosts 的方式〉，sudo 要密碼時的做法在〈這一節的其他做法：容器或 VM、作業系統、遮蔽的 unit、privileged、sudo 密碼、安裝版本與雜湊、金鑰密碼〉。

清理：terraform destroy、容器、network、映像檔與金鑰

清理的順序是先 terraform destroy、再刪容器：destroy 要在控制端容器裡執行，控制端先刪掉的話 Terraform 不在了，State 留在工作目錄裡沒有人處理。這次 State 只記著一份本機檔案；真環境的 State 記著雲端主機，先 destroy 才不會留下還在計費的資源。

1# 開發機上
2docker exec -w /work/tf mh-ctl terraform destroy -auto-approve   # 印 Destroy complete! Resources: 1 destroyed.
3docker rm -f mh-ctl mh-web1 mh-both1
4docker network rm mh-net
5docker rmi mh-host:ol10 mh-ctl:1
6docker ps -a --filter name=mh- -q; docker network ls --filter name=mh- -q; docker images 'mh-*' -q; docker volume ls --filter name=mh- -q
7rm -rf <工作目錄> <工作目錄的上一層>/host-image <工作目錄的上一層>/ctl-image <暫存目錄>/keys

terraform destroy 刪掉的是 local_file.inventory，之後在開發機上 ls <工作目錄>/ansible/inventory.yml 回 No such file or directory。docker ps -a --filter name=mh- -q 那一行的四條查詢都沒有輸出，代表這次建的容器、network、映像檔與 volume 都清掉了（這次的容器沒有掛 named volume，docker volume ls 那一條是確認沒有遺漏）。docker build 留下的建置快取沒有清：清快取要用 docker builder prune，它不分是哪一次建置留下的，會一起清掉開發機上其他專案的快取，所以這次留著。底層映像檔 oraclelinux:10 與 python:3.12-slim 也留著：開發機上可能有別的專案在用它們，要刪時執行 docker rmi oraclelinux:10 python:3.12-slim。工作目錄裡有 Terraform 的 State 與產生的清單、暫存目錄裡有私鑰，host-image/ 與 ctl-image/ 是兩個映像檔的建置目錄，rm -rf 那一行把它們一起刪掉；<工作目錄>、<工作目錄的上一層> 與 <暫存目錄> 換成這次實際用的路徑，刪之前先 ls 一次確認是這次建的目錄。

只讀檢查腳本 host-check.py 的原始碼與逐段說明：選項的切分與各工具的白名單規則、清單的載入與驗證、指令的執行、各項檢查、路徑與時間的量測、結果檔與命令列，以及這一版的已知限制

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

事件說明：2026-10-26，把作者私有專案裡的檢查腳本 host-check.py 在這一天的版本（commit 3fc41c0）整理成這篇。這一版的單元測試在一台 Apple Silicon 的 macOS 開發機上，用 uv 分別起 Python 3.12 與 Python 3.15 各執行一次；這一版在 Oracle Linux 10 的容器裡執行過；一台 Oracle Linux 10.2 的雲端主機上執行過的，是修正「權限擋下的目錄被判成路徑不存在」之前的版本。

這篇是主機維護清單的只讀檢查腳本 host-check.py 的完整原始碼，依腳本自己的結構分節。每一個 ## 節先寫這一段程式負責什麼、它滿足的是清單或執行環境的哪一項需求，接著是這一段的原始碼，之後說明從程式碼不容易看出來的地方：為什麼這樣判斷、換成另一種寫法會讓哪一種寫入或誤判通過、哪一項單元測試鎖住這個行為。各節依序是：檔頭的說明與共用常數；照 getopt_long 語法切分選項的函式；systemctl、journalctl、firewall-cmd、ss、find、sqlite3、openssl、sshd、needs-restarting、dnf、rpm、ausearch 各自的選項規則，以及不另外比對選項的工具；判定一條指令是否只讀的 readonly_violation 與腳本自己組出來的指令；清單的載入與驗證；執行指令的 Runner 與時鐘；Checker 對入口與接聽中的連接埠、log、會累積的資料、檔案系統、自動更新、暫停與恢復步驟的檢查；路徑的展開與大小的量測；時間字串的解析與組輸出用的小函式；結果檔的讀寫與跟前一次的差異；命令列與 exit code；最後是這一版的已知限制與重現方式，依清單的驗證、指令的執行與 exit code、各項檢查、結果檔分組。

各節的 python 程式碼區塊照順序接起來就是完整的腳本。區塊內的空行照原檔保留；兩個區塊之間夾著說明的位置，原檔是空行，接的時候補回去：下一個區塊以縮排開頭（Checker 類別裡的方法）時補一個空行，其餘補兩個空行。區塊之間補幾個空行只影響跟原檔逐字比對的結果，不影響執行。照這條規則接出來的檔案是 1442 行，sha256 是 22228d77ee7bc0d126401d04fc3a73b37e0a5768566abefa2b2b9dce69a0761d；這是本篇版本（拿掉 # i18n-exempt 標記、換掉兩處票號之後）的值，不是私有專案裡原檔的值。跟原檔相比改了兩處：行尾給私有專案的翻譯檢查工具用的 # i18n-exempt 標記拿掉了；檔頭說明裡兩處專案內部的工作票號，換成不帶票號的寫法。腳本只用 Python 標準函式庫，需要 Python 3.11 以上（解析 TOML 的 tomllib 在 3.11 加入）。單元測試的檔案沒有收進這篇，說明裡提到的測試以測試函式的名字指稱，並寫出它斷言的行為；每一個 ## 節第一次提到時寫成「單元測試 test_…（本篇沒有收錄）」。74 項單元測試在 Python 3.12 與 3.15 都通過；以 root 執行時，test_glob_in_unlistable_dir_is_unreadable、test_unreadable_glob_with_missing_ok_does_not_pass、test_literal_path_under_unreadable_parent_is_unreadable 這三項會失敗：它們靠目錄權限擋住讀取，而 root 不受目錄權限限制，測試裡的前提檢查寫明以 root 執行時這幾項失敗、不跳過（讀碼）。

文中的行為標兩種來源。「實跑」是實際執行過的結果：沒有另外註明環境的，是在一台 Apple Silicon 的 macOS 26.5 開發機上，以 Python 3.15.0 執行這一版的腳本，把它載入成模組、直接呼叫函式或方法，或從命令列跑整支腳本（Python 的版本差異另外用 uv 起 3.10.18、3.11.13、3.12.11）；在別的環境跑的，就地寫出環境。「讀碼」是從程式碼推得、沒有執行過的行為。

清單的格式與欄位、白名單要擋下哪些寫法與理由、輸出與 exit code 的讀法、結果檔，以及 systemd 沙箱各屬性實跑的效果，寫在主機維護清單寫成 TOML：JSON、YAML、TOML 的取捨、TOML 1.0 與 1.1 的版本差異、清單的欄位設計與只讀檢查腳本，這篇不重寫那些理由，各節連到對應的段落。把這支腳本與每台的清單部署到多台主機、以 sudo 與 systemd-run 執行它的步驟與輸出，在多台主機維護清單的實作紀錄：在容器上安裝 ansible-core 與 Terraform、由 Terraform 產生 inventory、用 Ansible 的範本部署每台的清單、以 sudo 與 systemd-run 執行檢查腳本，以及清理。

接起來的腳本要一份清單才跑得起來：它預設讀腳本所在目錄的 host.toml，沒有清單或清單格式錯時以 exit 2 結束、一項檢查都不執行。最小的清單從多台主機維護清單的實作紀錄：在容器上安裝 ansible-core 與 Terraform、由 Terraform 產生 inventory、用 Ansible 的範本部署每台的清單、以 sudo 與 systemd-run 執行檢查腳本，以及清理〈變數檔與範本：檢查腳本實際要求的欄位、兼任兩種角色的主機〉的 host.toml.j2 取得：把裡面的 {{ }} 換成這台主機實際的值，就是一份這支腳本載入得過的清單；哪些段落必填、哪些可以不寫，在本篇〈清單的載入與驗證：Probe、_Validator、load_manifest 與 validate〉。

檔頭的說明、匯入的模組與共用常數

檔頭的 docstring 是寫給維護的人讀的使用說明：用法、輸出的格式、結果檔、systemd 沙箱要加的屬性、exit code 與只讀的保證；這些行為的理由與實跑結果在主機維護清單寫成 TOML：JSON、YAML、TOML 的取捨、TOML 1.0 與 1.1 的版本差異、清單的欄位設計與只讀檢查腳本〈只讀檢查腳本的白名單、輸出、exit code 與結果檔〉。docstring 之後是匯入的模組與整支腳本共用的常數。

 1#!/usr/bin/env python3
 2"""web-demo 主機的只讀維護檢查。
 3
 4在主機上讀同目錄的 host.toml，逐項執行 where = "host" 的只讀檢查，主機外
 5（OCI Console、Cloudflare dashboard、開發機）的項目印成 MANUAL。
 6
 7用法（在主機上，以 root 執行；firewalld 查詢、sshd -T、collector 的資料庫、nginx 的 log 目錄、
 8audit.log 與 journal 一般帳號讀不到，專用帳號的實測見 README〈以專用帳號執行〉）：
 9
10    sudo python3 host-check.py                       # 例行維護：入口、log、累積的資料、更新
11    sudo python3 host-check.py --phase suspend       # 暫停上線前要做的步驟
12    sudo python3 host-check.py --phase resume        # 恢復上線後要做的步驟
13    sudo python3 host-check.py --manifest other.toml --set repo_dir=/opt/monitor
14    sudo python3 host-check.py --state-file PATH     # 結果檔換路徑（預設 /var/lib/host-check/last.json）
15    sudo python3 host-check.py --no-state            # 不讀也不寫結果檔
16
17輸出：每項一行 `PASS` / `WARN` / `MANUAL`、項目名與理由；接著是與前一次的差（`since:` 開頭，
18其後每個差一行：`CHANGED` 狀態改變、`DELTA` 值改變、`NEW` 新出現、`GONE` 消失）；結尾一行
19`summary: N PASS, M WARN, K MANUAL`；沒有印出 summary 代表腳本中途中止。
20
21結果檔：每次執行結束把這次的計數與量到的值（探針值、累積的 bytes、可用 bytes）寫進結果檔
22（JSON，每個 phase 一段，只替換本次的 phase），下一次拿它算差。目錄不存在時以 0700 建立，檔案
230600，用同目錄暫存檔加 os.replace 寫入。目錄已存在時不改它的權限：由 systemd 的 StateDirectory=
24建立的目錄，權限照 StateDirectoryMode=（預設 0755，每次啟動都會把既有目錄改回這個值），沙箱裡
25執行時要設 StateDirectoryMode=0700。讀不到、壞掉或寫不進去只在 stderr 印 `note:`，不改變
26exit code；清單本身只描述要檢查什麼，不存放結果。
27
28systemd 沙箱（在 Oracle Linux 10 容器裡實測）：ProtectSystem=strict 下要加 ReadWritePaths=/var/log /var/cache/dnf
29（dnf needs-restarting 要寫 dnf.log 與 metadata lock），StateDirectory=host-check 加 StateDirectoryMode=0700；
30NoNewPrivileges、PrivateTmp、IPAddressDeny=any 不影響檢查；不開 PrivateNetwork（ss 看不到主機的 socket，
31入口與 listen-audit 的檢查都會失準）。完整設定見 README〈在 systemd 沙箱裡執行〉。
32
33exit code：
34    0  全部 PASS，或只有 PASS 與 MANUAL
35    1  至少一項 WARN
36    2  清單格式錯（缺必填欄位、型別錯、要執行的指令不在只讀白名單裡），一項都沒有執行
37
38只讀的保證：
39    - 指令不經過 shell（shlex 切詞後直接 exec），沒有管線、轉向與命令替換。
40    - 要執行的每一條指令在執行任何一條之前先比對白名單（READONLY_RULES）；
41      不在白名單裡、或帶了會改變狀態的參數（find -delete、
42      firewall-cmd --add-*、sqlite3 沒有同時帶 -init /dev/null、-readonly 與 -safe 這類）時，整份清單判成格式錯。
43    - systemctl、dnf、rpm、journalctl、ss、find 的選項是列允許：依各工具自己的選項語法（getopt_long，
44      吃值的選項會吃掉下一個字，值可黏在選項後）切分，表外的選項一律拒絕，所以工具日後新增的
45      寫入選項預設就是拒絕（例：rpm --pipe/--eval/-D、systemctl -H/-M、dnf -x、journalctl --cursor-file）。
46    - sshd 只接受單獨的 -T；指令的路徑只接受裸名或 /usr/bin、/usr/sbin、/bin、/sbin 下的檔案。
47    - command 一律會被執行（且必須通過白名單）；manual_command、purge_command 是要人執行的動作，
48      一律只印出來。只印的位置（[[log]]、[[suspend]] / [[resume]]、主機外的 [[entrypoint.verify]]）
49      寫舊名 command 判成格式錯。
50    - 寫結果檔之外不改動任何受檢狀態；結果檔是腳本自己唯一會寫的檔案。例外：collector 停止後
51      資料庫的 -shm、-wal 已被收掉，此時 sqlite3 -readonly 會自己建出這兩個檔（擁有者同資料庫）；
52      在唯讀檔案系統（ProtectSystem=strict）上建不出來，sqlite3 exit 14，該項印成 WARN。
53    - 檔案大小與時間用 Python 的 os.lstat 量，不執行 du。
54
55只用標準函式庫，需要 Python 3.11 以上（tomllib）。
56"""
57
58from __future__ import annotations
59
60import argparse
61import configparser
62import datetime as dt
63import glob
64import json
65import os
66import re
67import shlex
68import stat
69import subprocess
70import sys
71import tempfile
72import time
73import tomllib
74from dataclasses import dataclass, field
75from typing import Any, Callable
76
77WHERE_VALUES = ("host", "external", "console")
78EXPOSURE_VALUES = ("public", "cdn-only", "admin-only", "loopback")
79PROTOCOL_VALUES = ("tcp", "udp")
80BILLED_VALUES = ("yes", "no", "unknown", "n/a")
81MEASURE_VALUES = ("lines", "value", "age_days")
82PHASES = ("maintain", "suspend", "resume")
83COMMAND_TIMEOUT_S = 30
84DEFAULT_STATE_FILE = "/var/lib/host-check/last.json"
85STATE_FORMAT = 1
86
87VAR_RE = re.compile(r"\{\{([A-Za-z_][A-Za-z0-9_]*)\}\}")

docstring 裡的 README〈以專用帳號執行〉與 README〈在 systemd 沙箱裡執行〉是私有專案的 README，沒有公開；改用專用帳號執行時哪些檢查讀得到、哪些讀不到，以及沙箱每一個屬性的實跑效果，寫在清單寫成 TOML 的那篇概念文章的〈只讀檢查腳本的白名單、輸出、exit code 與結果檔〉。docstring 裡的 web-demo 是示範清單所描述的那台主機上跑的服務，collector 是那台主機上寫 SQLite 資料庫的程式。

docstring 裡有幾句跟程式實際的行為不一致，程式碼照原檔保留，實際行為以後面的節為準：

「systemctl、dnf、rpm、journalctl、ss、find 的選項是列允許：依各工具自己的選項語法（getopt_long，……）切分」：「列允許」成立，find 也是列允許；而 find 不照 getopt_long 語法切分，它的規則自己逐個參數比對，寫在〈find 的運算式〉。照 getopt_long 語法切分的是 systemctl、journalctl、ss、needs-restarting、dnf、rpm 這六支，寫在〈選項的切分：OptionSpec 與 getopt_long 語法〉。
exit code 2 的「清單格式錯（……），一項都沒有執行」：清單格式錯時成立。exit 2 另有一個出口：清單通過載入時的比對、執行時 Runner 的白名單又拒絕了一條指令，這時在它之前的指令已經執行過，寫在〈命令列與 exit code：main〉。
exit code 1 的「至少一項 WARN」：檢查中途丟出沒有接住的例外時，Python 也以 exit 1 結束，這時 stdout 沒有 summary: 那一行，寫在〈host-check.py（3fc41c0）的已知限制與重現方式〉的〈指令的執行與 exit code：沒有接住的例外〉。
結果檔的「目錄不存在時以 0700 建立」：0700 只套在 os.makedirs 這次新建的最後一層目錄，中間各層用預設的權限，寫在〈結果檔的讀寫與跟前一次的差異〉。
只讀保證的「檔案大小與時間用 Python 的 os.lstat 量」：會累積的資料用 os.lstat；check_logs 確認檔案型的 log 時用 os.stat（會跟隨符號連結），檔案系統的剩餘空間用 os.statvfs，寫在〈定期讀的 log〉與〈檔案系統的剩餘空間〉。

WHERE_VALUES 到 PHASES 是清單欄位允許的值，下面的 validate 拿它們比對每個欄位，PHASES 同時是命令列 --phase 的選項。這幾個常數只是允許值的清單：加一個值之後，validate 就放行它，而用到那個值的分支沒有跟著改時，新的值在執行時出錯或被當成別的值處理。每個常數要一起改的位置：

WHERE_VALUES：_manual_text 用 {"console": "主控台", "external": "主機外"} 查表，新的值在印 MANUAL 時丟出 KeyError（實跑：_manual_text("bastion", …) 丟出 KeyError: 'bastion'）；validate 與 Checker 都只分 where == "host" 與其餘，其餘的值一律走主機外的路徑（讀碼）。
MEASURE_VALUES：Checker.measure 只分 lines 與 value，其餘一律當成時間解析；新的量法沒有在 measure 加分支時，被當成 age_days 算出天數（實跑：measure("bytes", "x=2026-10-26T00:00:00Z") 回傳了一個天數）。
PHASES：Checker.run 把 maintain 以外的值都交給 check_phase、讀 self.m[phase]，而 validate 只為 for phase in ("suspend", "resume") 這兩個建段落；新的階段要同時改這個迴圈，否則執行時丟出 KeyError（實跑：Checker({}).run("drain") 丟出 KeyError: 'drain'）。
PROTOCOL_VALUES（讀碼）：LISTEN_COMMAND 只帶 -t -u，listening_sockets 只收這兩種協定，audit_listening 的提示用協定的第一個字母組 ss -lnp{p[0]}；新的協定要同時改這三處，以及 ss 規則允許的選項。
EXPOSURE_VALUES、BILLED_VALUES（讀碼）：只在 validate 比對、在理由裡原樣印出，加值不必改其他位置。COMMAND_TIMEOUT_S 是 Runner 等一條指令結束的上限，超過時那一項記成 exit 124 並印成 WARN：一條卡住的指令（等網路、等鎖）只讓那一項失敗，其餘檢查照常跑完。DEFAULT_STATE_FILE 與 STATE_FORMAT 是結果檔的預設路徑與格式版本。VAR_RE 比對清單字串裡的 {{名稱}}，名稱只收 ASCII 的英文字母、數字與底線，第一個字元不能是數字；Python 的識別字另外收非 ASCII 的字母，{{主機}} 這種名稱在這裡對不上，原樣留在字串裡。

1class ManifestError(Exception):
2    """清單格式錯；errors 是逐條的原因。"""
3
4    def __init__(self, errors: list[str]):
5        super().__init__("\n".join(errors))
6        self.errors = errors

ManifestError 帶著逐條的錯誤原因。驗證清單的程式把整份清單的錯誤都收齊之後才丟一次這個例外，命令列再逐行印出 manifest error:，所以改清單的人一次看到全部的錯誤，不必改一條、跑一次。用 Ansible 部署時，template 任務的 validate 在受管主機上載入這支腳本、呼叫 load_manifest 驗證剛產生的清單，清單格式錯時這個例外讓那個任務失敗，格式錯的清單不會寫到正式的位置，做法在多台主機維護清單的實作紀錄：在容器上安裝 ansible-core 與 Terraform、由 Terraform 產生 inventory、用 Ansible 的範本部署每台的清單、以 sudo 與 systemd-run 執行檢查腳本，以及清理〈部署清單：建目錄、copy 與 template、validate 改用檢查腳本的載入函式、–check 的預覽〉。

選項的切分：OptionSpec 與 getopt_long 語法

白名單要比對一條指令的選項，得先分出一串參數裡哪些是選項、哪些是選項的值、哪些是位置參數。這一段照 getopt_long（GNU C 函式庫解析命令列選項的函式，多數 Linux 工具照它的規則解析參數）的語法切分，systemctl、journalctl、ss、needs-restarting、dnf、rpm 的規則共用它。這六支裡，systemctl、journalctl、ss 用 getopt_long 解析參數，rpm 用 popt，dnf 與 needs-restarting 用 Python 的 argparse；popt 與 argparse 在短選項合併、值黏在選項後面、--名稱=值 與 -- 這幾點，切法跟 getopt_long 相同，所以共用同一套切分；為什麼要照工具自己的語法切、沒照語法切時放行了哪些寫法，在主機維護清單寫成 TOML：JSON、YAML、TOML 的取捨、TOML 1.0 與 1.1 的版本差異、清單的欄位設計與只讀檢查腳本〈只讀檢查腳本的白名單、輸出、exit code 與結果檔〉。

 1# ── 只讀白名單 ──────────────────────────────────────────────
 2# 每條規則收 argv（argv[0] 已是 basename），回傳 None 代表放行，字串代表拒絕的理由。
 3
 4
 5# 一支工具允許的選項（列允許，表外一律拒絕）；選項名連同開頭的 - 一起寫。
 6@dataclass(frozen=True)
 7class OptionSpec:
 8    flags: frozenset[str] = frozenset()  # 不吃值的旗標
 9    values: frozenset[str] = frozenset()  # 一定吃值的選項
10    optional: frozenset[str] = frozenset()  # 選填值：只吃黏在一起的值，或下一個字是整數時
11
12
13def _spec(flags: str = "", values: str = "", optional: str = "") -> OptionSpec:
14    return OptionSpec(frozenset(flags.split()), frozenset(values.split()), frozenset(optional.split()))
15
16
17def _parse_options(args: list[str], spec: OptionSpec, stop_at_first: bool = False) -> tuple[list[str], set[str], str | None]:
18    # 依 getopt_long 的語法把 args 切成（位置參數, 出現過的選項, 拒絕理由）：
19    # 短選項可合併（-qa），吃值的短選項值黏在後面或在下一個字；長選項 --name[=value]；-- 之後全是位置參數。
20    # stop_at_first 時，第一個位置參數起的全部字都放進位置參數（不再解析選項）。
21    positionals: list[str] = []
22    seen: set[str] = set()
23    i = 0
24    while i < len(args):
25        tok = args[i]
26        i += 1
27        if tok == "--":
28            positionals.extend(args[i:])
29            break
30        if not tok.startswith("-") or tok == "-":
31            positionals.append(tok)
32            if stop_at_first:
33                positionals.extend(args[i:])
34                break
35            continue
36        if tok.startswith("--"):
37            name, eq, _ = tok.partition("=")
38            consumed = _long_option(name, bool(eq), spec, args, i)
39            if isinstance(consumed, str):
40                return positionals, seen, consumed
41            seen.add(name)
42            i += consumed
43            continue
44        for pos in range(1, len(tok)):
45            name = "-" + tok[pos]
46            if name in spec.flags:
47                seen.add(name)
48                continue
49            consumed = _value_option(name, pos + 1 < len(tok), spec, args, i)
50            if isinstance(consumed, str):
51                return positionals, seen, consumed
52            seen.add(name)
53            i += consumed
54            break
55    return positionals, seen, None
56
57
58def _long_option(name: str, has_value: bool, spec: OptionSpec, args: list[str], i: int) -> int | str:
59    # 回傳這個長選項多吃掉幾個後續字；拒絕時回傳理由。
60    if name in spec.flags:
61        return f"選項 {name} 不吃值" if has_value else 0
62    return _value_option(name, has_value, spec, args, i)
63
64
65def _value_option(name: str, has_glued_value: bool, spec: OptionSpec, args: list[str], i: int) -> int | str:
66    if name not in spec.values and name not in spec.optional:
67        return f"選項 {name} 不在允許清單"
68    if has_glued_value:
69        return 0
70    nxt = args[i] if i < len(args) else None
71    if name in spec.optional:
72        return 1 if nxt is not None and nxt.isdigit() else 0
73    return 1 if nxt is not None else f"選項 {name} 缺少值"

OptionSpec 把一支工具允許的選項分成三組，分組決定切分時這個選項是否吃掉下一個參數：flags 不吃值；values 一定吃值，值黏在選項後面（-pX）時吃黏著的那一段，否則吃下一個參數；optional 是值可帶可不帶的選項，值黏在選項後面時吃黏著的那一段，沒有黏著的值時，下一個參數全是數字才吃它，否則不吃。journalctl 的 -n 放在 optional，所以 journalctl -n 20 -u sshd 的 20 被當成 -n 的值，journalctl -n -u sshd 的 -u 照樣被當成選項比對。「全是數字」用 str.isdigit() 判斷：-5、+5 帶著正負號，不算數字，不會被當成值；²、٣ 這類 Unicode 的數字字元，isdigit() 回 True，會被當成值（這幾個字串都在 Python 裡實跑過）。把一個吃值的選項錯放進 flags，它的值會被當成下一個位置參數，子命令的判定就跟工具實際執行的不同。

短選項的那個迴圈從第二個字元起逐字查：查到旗標就看下一個字元（-qa 是 -q 與 -a）；查到吃值的選項，這個字元後面還有字時（-ppid）把剩下的當成值，沒有時吃下一個參數，然後離開這個參數。單獨一個 - 算位置參數：照 getopt 的慣例，它是一個運算元（多半代表標準輸入），不是選項。長選項用 partition("=") 分出名稱與值，旗標帶了 =值 時拒絕（--no-pager=1）。名稱一律整字比對，getopt_long 接受的前綴縮寫（--cursor-fi 當成 --cursor-file）不在表上，所以被拒絕。表外的選項回傳拒絕理由、不往下切，三組都不在表上的選項就是被拒絕的那一類，這是列允許的寫法在程式裡的樣子。

stop_at_first 給 dnf 用：切到第一個位置參數（子命令）就停，子命令之後的參數交給那個子命令自己的規則。單元測試 test_allowed（本篇沒有收錄）放行 systemctl --no-pager -ppid status nginx；test_rejected 拒絕 systemctl -p show stop nginx（-p 吃掉 show，子命令是 stop）、systemctl -pshow stop nginx 與 systemctl --no-pager=1 status nginx。

各工具的選項規則：systemctl、journalctl、firewall-cmd、ss、find、sqlite3、openssl、sshd、needs-restarting、dnf、rpm、ausearch

每支有選項規則的工具一個函式，收切好的參數串列（第一個元素已經換成檔名），放行時回傳 None，拒絕時回傳理由的字串。每支工具允許與排除了哪些選項、排除的理由，在主機維護清單寫成 TOML：JSON、YAML、TOML 的取捨、TOML 1.0 與 1.1 的版本差異、清單的欄位設計與只讀檢查腳本〈只讀檢查腳本的白名單、輸出、exit code 與結果檔〉的各工具清單；這一節寫程式怎麼實現那些規則，以及每一支的語法跟〈選項的切分：OptionSpec 與 getopt_long 語法〉的切分有哪裡不同。

systemctl 的子命令與選項

 1SYSTEMCTL_READ = {"is-active", "is-enabled", "is-failed", "show", "status", "cat", "list-timers", "list-units", "list-unit-files"}
 2SYSTEMCTL_OPTIONS = _spec(
 3    flags="--no-pager --no-legend --plain --value -a --all -l --full -q --quiet --failed",
 4    values="-p --property -P -t --type --state -n --lines -o --output --timestamp",
 5)
 6
 7
 8def _rule_systemctl(argv: list[str]) -> str | None:
 9    # -p、-t 這類選項會吃掉下一個字，所以子命令要先依選項語法切出來，不能取第一個不以 - 開頭的字。
10    # -H/--host 與 -M/--machine 會把操作送到別台主機或容器（-H 以 root 的 SSH 身分連出去），不在允許清單。
11    positionals, _, err = _parse_options(argv[1:], SYSTEMCTL_OPTIONS)
12    if err:
13        return f"systemctl {err}"
14    if not positionals or positionals[0] not in SYSTEMCTL_READ:
15        return f"systemctl 只允許 {sorted(SYSTEMCTL_READ)}"
16    return None

子命令取切分之後的第一個位置參數，查 SYSTEMCTL_READ。只寫 systemctl 而沒有子命令時，positionals 是空的，同樣拒絕：systemctl 沒有子命令時執行的是 list-units，規則要求清單把子命令寫出來，判定才不依賴工具的預設值。-H 與 -M 不在 SYSTEMCTL_OPTIONS 裡，所以黏在一起的 -Ha@b、長選項的 --host=a@b 與分開寫的 --host a@b 都在切分時被拒絕，單元測試 test_rejected（本篇沒有收錄）逐一列了這幾種寫法。

journalctl 的選項與 match 條件

 1# --cursor-file 與 --vacuum-*、--rotate、--flush、-f 都會寫檔或改變 journal，不在允許清單。
 2JOURNALCTL_OPTIONS = _spec(
 3    flags="-q --quiet --no-pager -r --reverse --utc --no-hostname -k --dmesg -a --all --disk-usage --list-boots",
 4    values="-u --unit --since --until -o --output -g --grep -p --priority -t --identifier",
 5    optional="-n --lines",
 6)
 7
 8
 9def _rule_journalctl(argv: list[str]) -> str | None:
10    _, _, err = _parse_options(argv[1:], JOURNALCTL_OPTIONS)
11    return f"journalctl {err}" if err else None

journalctl 的位置參數是篩選紀錄的 match 條件（_SYSTEMD_UNIT=x.service），只用來讀，所以規則只比對選項、不看位置參數。-n 放在 optional，test_rejected 的 journalctl -n --vacuum-size=1G 因此被拒絕：-n 不吃以 - 開頭的下一個參數，--vacuum-size 照樣被當成選項比對，而它不在表上。-f（持續讀新的紀錄、不會結束）也不在表上，它會讓指令一直跑到 COMMAND_TIMEOUT_S 的上限。

firewall-cmd 的參數樣式

1FIREWALL_READ = re.compile(r"^--(permanent|zone=\S+|state|query-\S+|list-\S+|get-\S+|info-\S+)$")
2
3
4def _rule_firewall_cmd(argv: list[str]) -> str | None:
5    for a in argv[1:]:
6        if not FIREWALL_READ.match(a):
7            return f"firewall-cmd 只允許 --query-*、--list-*、--get-*、--info-*、--state、--permanent、--zone=，不允許 {a}"
8    return None

firewall-cmd 的查詢都寫成一個 --名稱 或 --名稱=值 的參數，所以規則逐個參數比對樣式，不切分。每個參數都要對上樣式，位置參數因此一個都不允許：分開寫的 --zone public 裡，public 對不上任何樣式而被拒絕，值要用 = 黏在選項上。改動設定的選項（--add-port=、--remove-*、--reload）對不上 query-、list-、get-、info- 這幾個前綴，test_rejected 列了 firewall-cmd --add-port=8765/tcp 與 firewall-cmd --reload。

ss 的選項與過濾式

 1# -K（kill）、-D（寫檔）、-N（換 netns）、-F（讀過濾檔）、-r（反查 DNS，對外連線）、-E 都不在允許清單。
 2# 位置參數是過濾式（state listening、sport = :443 這類），ss 只讀它。
 3SS_OPTIONS = _spec(
 4    flags=(
 5        "-H --no-header -l --listening -n --numeric -t --tcp -u --udp -a --all -p --processes -4 --ipv4 -6 --ipv6 "
 6        "-x --unix -w --raw -e --extended -i --info -m --memory -s --summary -o --options"
 7    ),
 8    values="-f --family -A --query",
 9)
10
11
12def _rule_ss(argv: list[str]) -> str | None:
13    _, _, err = _parse_options(argv[1:], SS_OPTIONS)
14    return f"ss {err}" if err else None

ss 的位置參數是過濾式，跟 journalctl 一樣只比對選項。合併的短選項逐字查，所以 ss -tlnK 在查到 K 時被拒絕，-K 不必單獨出現；-f 一定吃值，單獨的 ss -f 以「缺少值」拒絕。-E（持續印出 socket 的事件、不會結束）不在表上，理由跟 journalctl -f 相同。

find 的運算式

 1# find 不是 getopt 語法，所以自己走一遍：選項只認下面兩張表（-delete、-exec*、-ok*、-fprint*、-fls、
 2# -D、-files0-from 都不在裡面）；值只吃下一個字；不以 - 開頭的字是路徑或運算子的括號、驚嘆號。
 3FIND_LEADING = frozenset({"-H", "-L", "-P"})
 4FIND_OPERATORS = frozenset({"(", ")", "!", ",", "-not", "-and", "-or", "-a", "-o"})
 5FIND_FLAGS = frozenset(
 6    "-print -print0 -prune -empty -xdev -mount -true -false -readable -writable -executable".split()
 7)
 8FIND_VALUES = frozenset(
 9    (
10        "-name -iname -path -ipath -regex -iregex -type -xtype -mtime -mmin -atime -amin -ctime -cmin "
11        "-newer -size -user -group -uid -gid -perm -links -inum -maxdepth -mindepth -printf"
12    ).split()
13)
14
15
16def _rule_find(argv: list[str]) -> str | None:
17    args = argv[1:]
18    i = 0
19    while i < len(args) and args[i] in FIND_LEADING:
20        i += 1
21    while i < len(args):
22        tok = args[i]
23        i += 1
24        if tok in FIND_FLAGS or tok in FIND_OPERATORS:
25            continue
26        if tok in FIND_VALUES:
27            if i >= len(args):
28                return f"find 的選項 {tok} 缺少值"
29            i += 1
30            continue
31        if tok.startswith("-") and tok != "-":
32            return f"find 的選項 {tok} 不在允許清單"
33    return None

find 的參數是起點路徑加一串運算式，運算式的元素是單一連字號的整字（-name、-mtime），不能照 getopt_long 合併或拆字，所以規則自己逐個參數比對。-H、-L、-P 只在最前面接受，跟 find 自己的語法一致；放在中間的 -L 對不上任何一張表而被拒絕。以 - 開頭而不在表上的參數一律拒絕，-delete、-exec、-fprint 這類動作因此不必逐一列出來擋；-newerXY 這種帶後綴的寫法也不在表上，test_rejected 列了它。-printf 在允許的表上，因為它把格式化的結果印到標準輸出；同類的 -fprintf 寫進檔案，不在表上。

sqlite3 的必帶選項與 dot-command

 1# sqlite3 的長選項是單破折號整字（--x 等同 -x），不是 getopt 語法，所以自己走一遍：先把開頭的 -- 正規化成 -，再整字比對。
 2SQLITE_FLAGS = frozenset(
 3    "-readonly -safe -bail -batch -header -noheader -csv -json -line -list -box -table -markdown -column -quote -tabs -nofollow".split()
 4)
 5SQLITE_VALUES = frozenset("-separator -newline -nullvalue".split())
 6SQLITE_REQUIRED = frozenset({"-readonly", "-safe", "-init"})
 7
 8
 9def _rule_sqlite3(argv: list[str]) -> str | None:
10    # -readonly 只讓資料庫檔唯讀；SQL 函式 writefile()、edit() 與 ATTACH 仍能寫檔案系統。
11    # -safe 擋下這些函式與會寫檔的 dot-command（OL10 的 3.46.1 實測支援）。
12    # -init 檔與 ~/.sqliterc 在 safe mode 生效前就執行（.shell 照跑，實測會建檔），HOME 擋不住
13    # （sqlite3 用 getpwuid 找家目錄）；唯一的擋法是 -init /dev/null 取代 ~/.sqliterc。三個都要帶。
14    args = argv[1:]
15    seen: set[str] = set()
16    positionals: list[str] = []
17    i = 0
18    while i < len(args):
19        tok = args[i]
20        i += 1
21        if not tok.startswith("-"):
22            positionals.append(tok)
23            continue
24        name = tok[1:] if tok.startswith("--") else tok
25        if name in SQLITE_FLAGS:
26            seen.add(name)
27        elif name == "-init":
28            if i >= len(args) or args[i] != "/dev/null":
29                return "sqlite3 的 -init 的值必須是 /dev/null"
30            seen.add(name)
31            i += 1
32        elif name in SQLITE_VALUES:
33            if i >= len(args):
34                return f"sqlite3 的選項 {tok} 缺少值"
35            i += 1
36        else:
37            return f"sqlite3 的選項 {tok} 不在允許清單"
38    if not SQLITE_REQUIRED <= seen:
39        return "sqlite3 要同時帶 -init /dev/null、-readonly 與 -safe（~/.sqliterc 與 writefile() 都會寫檔）"
40    for sql in positionals[1:]:
41        if any(line.lstrip().startswith(".") for line in sql.splitlines()):
42            return "sqlite3 的 dot-command（.backup、.output、.shell 這類）不允許"
43    return None

sqlite3 的選項是單一連字號的整字，雙連字號的寫法（--readonly）跟單一連字號的意思相同，所以規則先把開頭的 -- 換成 - 再比對，test_sqlite_requires_init_devnull 放行 sqlite3 --init /dev/null --readonly --safe -json …。三個必帶的選項用集合的子集比對（SQLITE_REQUIRED <= seen），少任何一個都拒絕；-init 的值只接受 /dev/null，-init -readonly -safe 這種把下一個選項當成值的寫法也被拒絕，因為 -readonly 不等於 /dev/null。為什麼三個都要帶，在清單寫成 TOML 的那篇概念文章的〈只讀檢查腳本的白名單、輸出、exit code 與結果檔〉講 sqlite3 執行 shell 與寫檔途徑的那一段。

位置參數裡，第一個是資料庫檔，之後的每一個是要執行的 SQL。規則把每段 SQL 逐行看，去掉行首空白之後以 . 開頭的行就是 dot-command，一律拒絕，不只靠 -safe 擋。在 SQL 參數之外塞 dot-command 的 -cmd 選項不在表上；-A（操作 SQLite 封存檔）、-interactive、-echo、-vfs 也不在表上，test_sqlite_requires_init_devnull 逐一列了它們。程式碼註解裡的「OL10 的 3.46.1」指 Oracle Linux 10 上的 sqlite 3.46.1。

openssl 與 sshd 的固定寫法

 1OPENSSL_X509_OPTS = {"-noout", "-in", "-checkend", "-enddate", "-startdate", "-dates", "-subject", "-issuer", "-serial", "-fingerprint", "-sha256", "-ext"}
 2
 3
 4def _rule_openssl(argv: list[str]) -> str | None:
 5    if len(argv) < 2 or argv[1] != "x509" or "-noout" not in argv:
 6        return "openssl 只允許 x509 -noout"
 7    for a in argv[2:]:
 8        if a.startswith("-") and a not in OPENSSL_X509_OPTS:
 9            return f"openssl x509 不允許 {a}"
10    return None

openssl 只允許 x509 子命令，而且一定要帶 -noout（不印出憑證本身的編碼內容）；其餘以 - 開頭的參數要在 OPENSSL_X509_OPTS 裡。不以 - 開頭的參數是選項的值（-in 的憑證路徑、-checkend 的秒數），放行。寫出檔案的 -out 不在表上，test_rejected 列了 openssl x509 -noout -in a -out b。

1def _rule_sshd(argv: list[str]) -> str | None:
2    # -E 與 -f 會寫檔或換設定，所以只接受單獨的 -T。
3    return None if argv[1:] == ["-T"] else "sshd 只允許單獨的 -T（印出生效中的設定）"

sshd 的規則把參數串列跟 ["-T"] 整串比對：檢查要的只有「印出生效中的設定」這一種用法，整串比對比列出允許的選項更窄，-T -E <檔案> 與 -E <檔案> -T 兩種順序都被拒絕。

needs-restarting 與 dnf 的子命令

 1NEEDS_RESTARTING_OPTIONS = _spec(flags="-r -s --reboothint --services")
 2
 3
 4def _rule_needs_restarting(argv: list[str]) -> str | None:
 5    positionals, _, err = _parse_options(argv[1:], NEEDS_RESTARTING_OPTIONS)
 6    if err or positionals:
 7        return "needs-restarting 只允許 -r、-s、--reboothint、--services"
 8    return None
 9
10
11DNF_OPTIONS = _spec(flags="-q --quiet -C --cacheonly")
12NO_OPTIONS = _spec()
13
14
15def _rule_dnf(argv: list[str]) -> str | None:
16    # -x、--setopt、-c、--installroot 這類吃值的選項不在允許清單；只允許子命令前的 -q、-C。
17    rest, _, err = _parse_options(argv[1:], DNF_OPTIONS, stop_at_first=True)
18    if err:
19        return f"dnf {err}"
20    if rest[:1] == ["needs-restarting"]:
21        return _rule_needs_restarting(rest)
22    if rest[:2] in (["history", "list"], ["history", "info"]):
23        _, _, err = _parse_options(rest[2:], NO_OPTIONS)
24        return f"dnf {err}" if err else None
25    return "dnf 只允許 needs-restarting 與 history list/info"

dnf 的規則分兩段切：子命令之前用 DNF_OPTIONS 切，切到第一個位置參數就停（stop_at_first）；剩下的參數以子命令開頭，交給子命令的規則。needs-restarting 這個子命令跟單獨呼叫的 needs-restarting 共用同一個規則函式，rest 的第一個元素正好是 needs-restarting，跟單獨呼叫時的參數串列形狀相同。history list 與 history info 之後用沒有任何允許選項的 NO_OPTIONS 切：位置參數（dnf history info 12 的交易編號）放行，任何選項都拒絕，test_rejected 的 dnf history list -y 就是這一種。dnf -x history -x list install foo 在子命令之前那一段就被拒絕，-x 不在 DNF_OPTIONS 裡。

rpm 的查詢模式

 1# --eval、-E、-D/--define 展開巨集，%(...) 會經 shell 執行；--pipe 直接執行指令；
 2# --macros、--rcfile、--dbpath、--root、-p 換設定或資料來源。都不在允許清單。
 3RPM_OPTIONS = _spec(
 4    flags=(
 5        "-q -a -f -i -l -c -d -s -R --query --all --file --info --list --configfiles --docfiles "
 6        "--state --requires --provides --changelog --last --whatprovides --whatrequires"
 7    ),
 8    values="--qf --queryformat",
 9)
10
11
12def _rule_rpm(argv: list[str]) -> str | None:
13    # 第一個選項必須是查詢模式（-q、-qa、-qi 這類或 --query），不讓 -i、-U 這類模式排在前面。
14    if len(argv) < 2 or not (argv[1].startswith("-q") or argv[1] == "--query"):
15        return "rpm 只允許查詢（第一個選項要是 -q 開頭或 --query）"
16    _, seen, err = _parse_options(argv[1:], RPM_OPTIONS)
17    if err:
18        return f"rpm {err}"
19    if not ({"-q", "--query"} & seen):
20        return "rpm 只允許查詢（要帶 -q）"
21    return None

rpm 的 -i 在查詢模式裡是「印出套件資訊」，排在最前面時是「安裝套件」，同一個字母的意思由模式決定。規則因此先要求第一個參數是查詢模式（-q 開頭或 --query），再照選項表切分：RPM_OPTIONS 裡的 -i、-f 只在查詢模式之後才出現得了，test_rpm_first_option_is_query 拒絕的 rpm -i tree.rpm -q、rpm -iq、rpm -U x.rpm -q 都在查第一個參數時被拒絕。切分之後再確認出現過的選項裡有 -q 或 --query：以現在的寫法，通過第一個參數檢查的輸入，切分之後一定帶著 -q 或 --query，這一道擋不下任何多出來的輸入（讀碼）；它是冗餘的防護，日後有人放寬第一個參數的比對時，查詢模式的要求不會跟著消失。-qp（查詢一個 .rpm 檔而不是已安裝的套件）的 -p 不在表上，test_rejected 列了 rpm -qp /tmp/a.rpm。

ausearch 的篩選選項與時間

 1# ausearch 是單破折號多字母選項，整字比對。--checkpoint、-if/--input 這類寫檔或換輸入來源的選項不在允許清單。
 2AUSEARCH_FLAGS = frozenset("-i --interpret -r --raw --just-one".split())
 3AUSEARCH_VALUES = frozenset(
 4    "-m --message -k --key -c --comm -p --pid -ui --uid -x --executable -sc --syscall -sv --success --format".split()
 5)
 6AUSEARCH_TIME = frozenset("-ts --start -te --end".split())
 7AUSEARCH_CLOCK = re.compile(r"^\d{1,2}:\d{2}(:\d{2})?$")
 8
 9
10def _rule_ausearch(argv: list[str]) -> str | None:
11    args = argv[1:]
12    i = 0
13    while i < len(args):
14        tok = args[i]
15        i += 1
16        name, eq, _ = tok.partition("=") if tok.startswith("--") else (tok, "", "")
17        if name in AUSEARCH_FLAGS and not eq:
18            continue
19        if name in AUSEARCH_VALUES or name in AUSEARCH_TIME:
20            if not eq:
21                if i >= len(args):
22                    return f"ausearch 的選項 {tok} 缺少值"
23                i += 1
24                # -ts 後面是日期時，再下一個字可能是時間（-ts 10/26/2026 10:30）
25                if name in AUSEARCH_TIME and i < len(args) and AUSEARCH_CLOCK.match(args[i]):
26                    i += 1
27            continue
28        return f"ausearch 的選項 {tok} 不在允許清單"
29    return None

ausearch 的短選項有多個字母（-ui、-sc），不能照 getopt_long 拆字，所以整字比對；只有雙連字號的長選項接受 =值，單一連字號的 -i=1 整串對不上表而被拒絕。-ts、-te 的值可以是一個詞（today、recent），也可以是日期加時間兩個參數，所以吃掉值之後，下一個參數長得像時刻（10:30 或 10:30:00）時再吃一個。test_ausearch_allow_list 放行 ausearch -ts 10/26/2026 10:30:00 -te 11:00，拒絕 -m 沒有值、--checkpoint、--input 與 -if。

不另外比對選項的工具與規則表

 1def _allow(argv: list[str]) -> str | None:
 2    return None
 3
 4
 5READONLY_RULES: dict[str, Callable[[list[str]], str | None]] = {
 6    "ss": _rule_ss,
 7    "systemctl": _rule_systemctl,
 8    "journalctl": _rule_journalctl,
 9    "firewall-cmd": _rule_firewall_cmd,
10    "find": _rule_find,
11    "sqlite3": _rule_sqlite3,
12    "openssl": _rule_openssl,
13    "sshd": _rule_sshd,
14    "needs-restarting": _rule_needs_restarting,
15    "dnf": _rule_dnf,
16    "rpm": _rule_rpm,
17    "ausearch": _rule_ausearch,
18    "grep": _allow,
19    "wc": _allow,
20    "stat": _allow,
21    "du": _allow,
22    "df": _allow,
23    "test": _allow,
24    "id": _allow,
25    "uname": _allow,
26    "getenforce": _allow,
27    "sestatus": _allow,
28    "getsebool": _allow,
29}

READONLY_RULES 是白名單本身：鍵是執行檔的檔名，值是那支工具的規則函式；不在這張表上的工具在 readonly_violation 裡被拒絕。其餘對到 _allow 的工具，任何參數都放行，因為它們沒有寫檔或執行其他程式的選項，判斷的依據在清單寫成 TOML 的那篇概念文章的〈只讀檢查腳本的白名單、輸出、exit code 與結果檔〉白名單三層比對（執行檔的路徑、工具、工具的選項）裡的「工具」那一層。白名單要加一支工具時，在這張表加一列；那支工具有會寫檔或執行其他程式的選項時，同時寫一個規則函式，對到 _allow 等於宣告它的每一個選項都只讀。

指令的只讀判定：readonly_violation 與 Checker 自己組的指令

readonly_violation 把一條指令字串判定成放行或拒絕：先用 shlex 切詞，再依序做白名單的三層比對。執行檔的路徑那一層在這個函式裡比對；工具那一層依檔名查 READONLY_RULES，查不到就拒絕；工具的選項那一層交給查到的規則函式，寫在〈各工具的選項規則：systemctl、journalctl、firewall-cmd、ss、find、sqlite3、openssl、sshd、needs-restarting、dnf、rpm、ausearch〉。程式碼裡排在 readonly_violation 之前的，是腳本自己用清單的值組出來的指令（LISTEN_COMMAND、timer_command、journal_command），載入清單時與執行時用的是同一批函式，比對過的字串就是執行的字串。三層比對的理由，以及裸工具名依 PATH 找檔案而要經由 sudo 或 systemd 執行的條件，在主機維護清單寫成 TOML：JSON、YAML、TOML 的取捨、TOML 1.0 與 1.1 的版本差異、清單的欄位設計與只讀檢查腳本〈只讀檢查腳本的白名單、輸出、exit code 與結果檔〉。

 1# Checker 實際會拼出來的指令；validate 載入時用同一批函式先比對白名單，兩邊不會不一致。
 2LISTEN_COMMAND = "ss -H -l -n -t -u"
 3UPDATE_TIMER_VERBS = (("is-enabled", "enabled"), ("is-active", "active"))
 4# needs-restarting -r 判定要重開機時印的句子（dnf 4 與 dnf 5 相同，Runner 以 LC_ALL=C 執行）。
 5# exit 1 也是 dnf 自己出錯時的 exit（ProtectSystem=strict 下寫不了 /var/log/dnf.log），只看 exit 分不開。
 6REBOOT_REQUIRED_TEXT = "Reboot is required"
 7
 8
 9def timer_command(verb: str, timer: str) -> str:
10    return f"systemctl {verb} {shlex.quote(timer)}"
11
12
13def journal_command(unit: str) -> str:
14    return f"journalctl -u {shlex.quote(unit)} -n 1 -q --no-pager -o short-iso"
15
16
17TRUSTED_BIN_DIRS = frozenset({"/usr/bin", "/usr/sbin", "/bin", "/sbin"})
18
19
20def readonly_violation(command: str) -> str | None:
21    """command 不在只讀白名單時回傳理由。"""
22    try:
23        argv = shlex.split(command)
24    except ValueError as e:
25        return f"指令切詞失敗：{e}"
26    if not argv:
27        return "指令是空的"
28    if "/" in argv[0] and os.path.dirname(argv[0]) not in TRUSTED_BIN_DIRS:
29        return f"{argv[0]} 的路徑不在 {', '.join(sorted(TRUSTED_BIN_DIRS))} 之下（只接受裸名或系統目錄）"
30    name = os.path.basename(argv[0])
31    rule = READONLY_RULES.get(name)
32    if rule is None:
33        return f"{name} 不在只讀白名單（{', '.join(sorted(READONLY_RULES))}）"
34    return rule([name] + argv[1:])

timer_command 與 journal_command 把清單裡的 systemd timer 名稱與 unit 名稱嵌進指令。shlex.quote 讓名稱裡的空白與引號在切詞之後仍是一個參數，名稱塞不進第二個參數；而名稱本身寫成選項的樣子時，shlex.quote 不改它，要靠白名單擋。單元測試 test_evil_timer_rejected_at_load（本篇沒有收錄）把清單的 timer 寫成 --host=evil，組出來的 systemctl is-enabled --host=evil 在載入時被 systemctl 的規則拒絕，腳本以 exit 2 結束，假的執行器一條指令都沒有收到。REBOOT_REQUIRED_TEXT 給自動更新那一項判斷要不要重開機，它跟 exit code 一起用的理由寫在註解裡，判定的程式在下面〈自動更新的排程、設定與重開機〉。註解寫這一句「dnf 4 與 dnf 5 相同」，原始碼與測試裡沒有 dnf 5 的輸出可以對照：單元測試用的是 dnf 4 格式的輸出，dnf 5 印的句子這次未實跑。

執行檔路徑那一層比對的是字串：os.path.dirname 取出的目錄要逐字等於四個系統目錄之一，沒有先正規化路徑。./grep 的目錄是 .、/usr/local/bin/grep 的目錄是 /usr/local/bin，都不在表上；/usr/bin/../../tmp/grep 的目錄是 /usr/bin/../../tmp，同樣不等於 /usr/bin，.. 因此繞不過這一層。規則函式收到的第一個元素換成了檔名，/usr/bin/grep 與 grep 走同一個規則。shlex.split 遇到沒有收尾的引號時丟出 ValueError，這一條指令判成拒絕，不讓整支腳本中止。

白名單是擋得住「請 PID 1 這類別的程序代做」這種改動的那一層。systemd 沙箱的檔案系統與網路限制管的是腳本自己的程序，而 systemctl stop 經由 D-Bus 請 systemd（PID 1）去停服務，停服務的是不受這些限制的 systemd。在 Ubuntu 24.04（systemd 255）上實跑：systemd-run --wait --pipe -p ProtectSystem=strict -p IPAddressDeny=any systemctl stop 回 rc=0，unit 被停掉，加上 PrivateNetwork=yes 也一樣停得掉；只有用 RestrictAddressFamilies="AF_INET AF_INET6" 拿掉 AF_UNIX 時，回 rc=1（Failed to connect to bus: Address family not supported by protocol）。所以 systemctl 的規則只放行查詢的子命令；白名單與沙箱怎麼分工，在清單寫成 TOML 的那篇概念文章的〈只讀檢查腳本的白名單、輸出、exit code 與結果檔〉。

清單的載入與驗證：Probe、_Validator、load_manifest 與 validate

這一段把 TOML 讀成 Python 的 dict 之後逐段驗證並正規化：每個欄位查存在、型別與允許值，字串裡的 {{名稱}} 換成 [vars] 的值，要執行的指令比對白名單；整份清單的錯誤收齊之後一次丟出 ManifestError，這時一條指令都還沒有執行。欄位怎麼依檢查腳本與人的需要設計，在主機維護清單寫成 TOML：JSON、YAML、TOML 的取捨、TOML 1.0 與 1.1 的版本差異、清單的欄位設計與只讀檢查腳本〈清單欄位的設計：檢查腳本要讀的與人要讀的〉；照這段驗證實際要求的欄位寫成範本，在多台主機維護清單的實作紀錄：在容器上安裝 ansible-core 與 Terraform、由 Terraform 產生 inventory、用 Ansible 的範本部署每台的清單、以 sudo 與 systemd-run 執行檢查腳本，以及清理〈變數檔與範本：檢查腳本實際要求的欄位、兼任兩種角色的主機〉。

  1# ── 清單解析與驗證 ─────────────────────────────────────────
  2
  3
  4@dataclass
  5class Probe:
  6    command: str
  7    expect_exit: int | None = None
  8    ok_exit: list[int] = field(default_factory=lambda: [0])
  9    expect_stdout: str | None = None
 10    expect_contains: str | None = None
 11    expect_not_contains: str | None = None
 12    measure: str | None = None
 13    warn_above: float | None = None
 14
 15
 16class _Validator:
 17    def __init__(self, variables: dict[str, str]):
 18        self.errors: list[str] = []
 19        self.vars = variables
 20
 21    def err(self, where: str, msg: str) -> None:
 22        self.errors.append(f"{where}: {msg}")
 23
 24    def subst(self, where: str, value: str) -> str:
 25        def repl(m: re.Match[str]) -> str:
 26            name = m.group(1)
 27            if name not in self.vars:
 28                self.err(where, f"{{{{{name}}}}} 沒有定義在 [vars]")
 29                return m.group(0)
 30            return self.vars[name]
 31
 32        return VAR_RE.sub(repl, value)
 33
 34    def get(self, tbl: dict[str, Any], key: str, typ: type | tuple[type, ...], where: str, required: bool = True, enum: tuple[str, ...] | None = None) -> Any:
 35        if key not in tbl:
 36            if required:
 37                self.err(where, f"缺少必填欄位 {key}")
 38            return None
 39        v = tbl[key]
 40        # bool 是 int 的子類別，數字欄位不收 true/false。
 41        if not isinstance(v, typ) or (isinstance(v, bool) and bool not in (typ if isinstance(typ, tuple) else (typ,))):
 42            self.err(where, f"{key} 的型別要是 {_typename(typ)}，實際是 {type(v).__name__}")
 43            return None
 44        if enum is not None and v not in enum:
 45            self.err(where, f"{key} 要是 {list(enum)} 之一，實際是 {v!r}")
 46            return None
 47        if isinstance(v, str):
 48            return self.subst(f"{where}.{key}", v)
 49        return v
 50
 51    def reject_old_command_name(self, tbl: dict[str, Any], where: str) -> None:
 52        # command 一律會被執行；只印不執行的欄位叫 manual_command，舊名出現在只印的位置判成格式錯。
 53        if "command" in tbl:
 54            self.err(where, "只印不執行的指令改用 manual_command（command 一律會被執行並過白名單）")
 55
 56    def str_list(self, tbl: dict[str, Any], key: str, where: str, required: bool = True) -> list[str] | None:
 57        v = self.get(tbl, key, list, where, required)
 58        if v is None:
 59            return None
 60        if not all(isinstance(x, str) for x in v):
 61            self.err(where, f"{key} 的每一項都要是字串")
 62            return None
 63        return [self.subst(f"{where}.{key}", x) for x in v]
 64
 65    def table_list(self, data: dict[str, Any], key: str, required: bool = True) -> list[dict[str, Any]]:
 66        v = data.get(key)
 67        if v is None:
 68            if required:
 69                self.err(key, f"缺少 [[{key}]]")
 70            return []
 71        if not isinstance(v, list) or not all(isinstance(x, dict) for x in v):
 72            self.err(key, f"{key} 要是 [[{key}]] 表格陣列")
 73            return []
 74        return v
 75
 76    def probe(self, tbl: dict[str, Any], where: str, allow_measure: bool = False) -> Probe | None:
 77        command = self.get(tbl, "command", str, where)
 78        if command is None:
 79            return None
 80        reason = readonly_violation(command)
 81        if reason:
 82            self.err(where, f"command 不是只讀指令：{reason}（{command}）")
 83        p = Probe(command=command)
 84        p.expect_exit = self.get(tbl, "expect_exit", int, where, required=False)
 85        ok_exit = tbl.get("ok_exit", [0])
 86        if not isinstance(ok_exit, list) or not all(isinstance(x, int) and not isinstance(x, bool) for x in ok_exit):
 87            self.err(where, "ok_exit 要是整數陣列")
 88        else:
 89            p.ok_exit = ok_exit
 90        p.expect_stdout = self.get(tbl, "expect_stdout", str, where, required=False)
 91        p.expect_contains = self.get(tbl, "expect_contains", str, where, required=False)
 92        p.expect_not_contains = self.get(tbl, "expect_not_contains", str, where, required=False)
 93        if allow_measure:
 94            p.measure = self.get(tbl, "measure", str, where, required=False, enum=MEASURE_VALUES)
 95            p.warn_above = self.get(tbl, "warn_above", (int, float), where, required=p.measure is not None)
 96        has_expect = any(x is not None for x in (p.expect_exit, p.expect_stdout, p.expect_contains, p.expect_not_contains, p.measure))
 97        if not has_expect and "ok_exit" not in tbl:
 98            self.err(where, "探針至少要有一個預期值（expect_exit、ok_exit、expect_stdout、expect_contains、expect_not_contains 或 measure）")
 99        return p
100
101
102def _typename(typ: type | tuple[type, ...]) -> str:
103    if isinstance(typ, tuple):
104        return " 或 ".join(t.__name__ for t in typ)
105    return typ.__name__

Probe 是一個探針：要執行的一條指令，加上怎樣算正常的預期值。_Validator 把驗證時共用的動作收在一起，每個方法查到錯誤時記一條、回傳 None 或空的結果（table_list 回空串列），不丟例外，所以一個欄位錯了之後，其他欄位照樣往下驗。

get 的型別比對多了一個布林的判斷：Python 的 bool 是 int 的子類別，只用 isinstance(v, int) 的話，port = true 會被當成整數 1 收下。get 先比對型別與允許值，再換掉字串裡的 {{名稱}}：有允許值的欄位（exposure、where、protocol 這類）寫成 {{名稱}} 時，比對的是 {{名稱}} 這串字本身，判成格式錯，所以這些欄位不能用 [vars] 填。之後比對白名單的是換過的字串，所以命令列 --set 傳進來的值跟清單裡寫死的值走同一道白名單。[vars] 沒有的名稱記一條錯誤，原文的 {{名稱}} 留在字串裡。

reject_old_command_name 管的是欄位名稱的意思：清單裡的 command 一律會被執行，只印給人看的指令寫在 manual_command。只印的位置（[[log]]、暫停與恢復的步驟、主機外的確認）出現 command 時判成格式錯，讀清單的人看到 command 就知道那一條會被執行，單元測試 test_log_old_name_rejected、test_resume_old_name_rejected 與 test_external_verify_old_name_rejected（本篇沒有收錄）各測一個位置。

probe 要求探針至少寫出一個預期值，或明寫 ok_exit：ok_exit 的預設 [0] 不算宣告，清單的讀者要看得到這一項怎樣算正常。measure 與 warn_above 只在 allow_measure 為真時讀，也就是 log 的計數門檻（[[log.alert]]）；寫了 measure 就一定要有 warn_above，量到的值才有門檻可比。

  1def load_manifest(path: str, overrides: dict[str, str] | None = None) -> dict[str, Any]:
  2    """讀取並驗證清單，回傳正規化後的結構；格式錯時丟 ManifestError。"""
  3    try:
  4        with open(path, "rb") as f:
  5            data = tomllib.load(f)
  6    except OSError as e:
  7        raise ManifestError([f"讀不到清單 {path}：{e}"]) from e
  8    except tomllib.TOMLDecodeError as e:
  9        raise ManifestError([f"{path} 不是合法的 TOML 1.0：{e}"]) from e
 10    return validate(data, overrides or {})
 11
 12
 13def validate(data: dict[str, Any], overrides: dict[str, str]) -> dict[str, Any]:
 14    raw_vars = data.get("vars", {})
 15    errors: list[str] = []
 16    if not isinstance(raw_vars, dict) or not all(isinstance(v, str) for v in raw_vars.values()):
 17        errors.append("vars: [vars] 的每個值都要是字串")
 18        raw_vars = {}
 19    variables = dict(raw_vars)
 20    for k in overrides:
 21        if k not in variables:
 22            errors.append(f"--set {k}: [vars] 沒有這個名稱")
 23    variables.update(overrides)
 24    v = _Validator(variables)
 25    v.errors.extend(errors)
 26    out: dict[str, Any] = {"vars": variables}
 27
 28    host = data.get("host")
 29    if not isinstance(host, dict):
 30        v.err("host", "缺少 [host]")
 31        host = {}
 32    out["host"] = {k: v.get(host, k, str, "host") for k in ("name", "provider", "region", "role")}
 33
 34    la = data.get("listen_audit", {"protocols": ["tcp"], "allow": []})
 35    if not isinstance(la, dict):
 36        v.err("listen_audit", "要是表格")
 37        la = {}
 38    protocols = v.str_list(la, "protocols", "listen_audit") or []
 39    for p in protocols:
 40        if p not in PROTOCOL_VALUES:
 41            v.err("listen_audit", f"protocols 只能是 {list(PROTOCOL_VALUES)}，實際有 {p!r}")
 42    allow_out = []
 43    allow = la.get("allow", [])
 44    if not isinstance(allow, list):
 45        v.err("listen_audit", "allow 要是陣列")
 46        allow = []
 47    for i, a in enumerate(allow):
 48        w = f"listen_audit.allow[{i}]"
 49        if not isinstance(a, dict):
 50            v.err(w, "要是 { port = ..., protocol = ..., reason = ... }")
 51            continue
 52        allow_out.append({"port": v.get(a, "port", int, w), "protocol": v.get(a, "protocol", str, w, enum=PROTOCOL_VALUES), "reason": v.get(a, "reason", str, w)})
 53    out["listen_audit"] = {"protocols": protocols, "allow": allow_out}
 54
 55    eps = []
 56    for i, ep in enumerate(v.table_list(data, "entrypoint")):
 57        w = f"entrypoint[{i}]"
 58        name = v.get(ep, "name", str, w)
 59        w = f"entrypoint[{name or i}]"
 60        e = {
 61            "name": name,
 62            "port": v.get(ep, "port", int, w),
 63            "protocol": v.get(ep, "protocol", str, w, enum=PROTOCOL_VALUES),
 64            "exposure": v.get(ep, "exposure", str, w, enum=EXPOSURE_VALUES),
 65            "where": v.get(ep, "where", str, w, enum=WHERE_VALUES),
 66            "enforced_by": v.str_list(ep, "enforced_by", w) or [],
 67            "verify": [],
 68        }
 69        verifies = ep.get("verify", [])
 70        if not isinstance(verifies, list) or not all(isinstance(x, dict) for x in verifies):
 71            v.err(w, "verify 要是 [[entrypoint.verify]] 表格陣列")
 72            verifies = []
 73        layers_seen = set()
 74        for j, vf in enumerate(verifies):
 75            vw = f"{w}.verify[{j}]"
 76            layer = v.get(vf, "layer", str, vw)
 77            where = v.get(vf, "where", str, vw, enum=WHERE_VALUES)
 78            layers_seen.add(layer)
 79            item: dict[str, Any] = {"layer": layer, "where": where}
 80            if where == "host":
 81                item["probe"] = v.probe(vf, vw)
 82            elif where is not None:
 83                item["console_path"] = v.get(vf, "console_path", str, vw, required=False)
 84                v.reject_old_command_name(vf, vw)
 85                item["manual_command"] = v.get(vf, "manual_command", str, vw, required=False)
 86                if item["console_path"] is None and item["manual_command"] is None:
 87                    v.err(vw, "主機外的確認要有 console_path 或 manual_command")
 88                item["expect"] = v.get(vf, "expect", str, vw)
 89            e["verify"].append(item)
 90        for layer in e["enforced_by"]:
 91            if layer not in layers_seen:
 92                v.err(w, f"enforced_by 的 {layer!r} 沒有對應的 [[entrypoint.verify]]（layer = {layer!r}）")
 93        for layer in layers_seen - set(e["enforced_by"]) - {None}:
 94            v.err(w, f"[[entrypoint.verify]] 的 layer {layer!r} 不在 enforced_by 裡")
 95        eps.append(e)
 96    out["entrypoint"] = eps
 97
 98    logs = []
 99    for i, lg in enumerate(v.table_list(data, "log")):
100        name = v.get(lg, "name", str, f"log[{i}]")
101        w = f"log[{name or i}]"
102        v.reject_old_command_name(lg, w)
103        source = v.get(lg, "source", str, w)
104        if source is not None and not re.match(r"^(file|journal):.+", source):
105            v.err(w, f"source 要寫成 file:<路徑> 或 journal:，實際是 {source!r}")
106        item = {
107            "name": name,
108            "source": source,
109            "look_for": v.get(lg, "look_for", str, w),
110            "interval_days": v.get(lg, "interval_days", int, w),
111            "manual_command": v.get(lg, "manual_command", str, w),
112            "alerts": [],
113        }
114        alerts = lg.get("alert", [])
115        if not isinstance(alerts, list) or not all(isinstance(x, dict) for x in alerts):
116            v.err(w, "alert 要是 [[log.alert]] 表格陣列")
117            alerts = []
118        for j, al in enumerate(alerts):
119            aw = f"{w}.alert[{j}]"
120            aname = v.get(al, "name", str, aw)
121            item["alerts"].append({"name": aname, "probe": v.probe(al, f"{w}.alert[{aname or j}]", allow_measure=True)})
122        logs.append(item)
123    out["log"] = logs
124
125    accs = []
126    for i, ac in enumerate(v.table_list(data, "accumulation")):
127        name = v.get(ac, "name", str, f"accumulation[{i}]")
128        w = f"accumulation[{name or i}]"
129        paths = ac.get("path")
130        if isinstance(paths, str):
131            paths = [paths]
132            ac = dict(ac, path=paths)
133        item = {
134            "name": name,
135            "paths": v.str_list(ac, "path", w) or [],
136            "missing_ok": v.get(ac, "missing_ok", bool, w, required=False) or False,
137            "limit_bytes": v.get(ac, "limit_bytes", int, w, required=False),
138            "retention_days": v.get(ac, "retention_days", int, w, required=False),
139            "purge_command": v.get(ac, "purge_command", str, w),
140            "oldest_command": None,
141        }
142        if item["limit_bytes"] is None and item["retention_days"] is None:
143            v.err(w, "limit_bytes 與 retention_days 至少要有一個")
144        oc = v.get(ac, "oldest_command", str, w, required=False)
145        if oc is not None:
146            if item["retention_days"] is None:
147                v.err(w, "有 oldest_command 時要有 retention_days")
148            reason = readonly_violation(oc)
149            if reason:
150                v.err(w, f"oldest_command 不是只讀指令：{reason}（{oc}）")
151            item["oldest_command"] = oc
152        accs.append(item)
153    out["accumulation"] = accs
154
155    fss = []
156    for i, fs in enumerate(v.table_list(data, "filesystem", required=False)):
157        name = v.get(fs, "name", str, f"filesystem[{i}]")
158        w = f"filesystem[{name or i}]"
159        fss.append({"name": name, "mount": v.get(fs, "mount", str, w), "min_free_bytes": v.get(fs, "min_free_bytes", int, w)})
160    out["filesystem"] = fss
161
162    up = data.get("updates")
163    if not isinstance(up, dict):
164        v.err("updates", "缺少 [updates]")
165        up = {}
166    expect = up.get("expect", {})
167    if not isinstance(expect, dict) or not all(isinstance(x, str) for x in expect.values()):
168        v.err("updates", "expect 要是值為字串的 inline table")
169        expect = {}
170    reboot = v.get(up, "reboot_check", str, "updates", required=False)
171    if reboot is not None:
172        reason = readonly_violation(reboot)
173        if reason:
174            v.err("updates", f"reboot_check 不是只讀指令：{reason}")
175    out["updates"] = {
176        "mode": v.get(up, "mode", str, "updates"),
177        "timer": v.get(up, "timer", str, "updates"),
178        "config_files": v.str_list(up, "config_files", "updates", required=False) or [],
179        "expect": expect,
180        "reboot_check": reboot,
181    }
182
183    for phase in ("suspend", "resume"):
184        steps = []
185        for i, st in enumerate(v.table_list(data, phase)):
186            w = f"{phase}[{i}]"
187            item = {
188                "step": v.get(st, "step", int, w),
189                "resource": v.get(st, "resource", str, w),
190                "billed_when_stopped": v.get(st, "billed_when_stopped", str, w, enum=BILLED_VALUES),
191                "billed_when_stopped_beyond_free": v.get(st, "billed_when_stopped_beyond_free", str, w, enum=BILLED_VALUES),
192                "billing_basis": v.get(st, "billing_basis", str, w),
193                "where": v.get(st, "where", str, w, enum=WHERE_VALUES),
194                "manual_command": v.get(st, "manual_command", str, w, required=False),
195                "console_path": v.get(st, "console_path", str, w, required=False),
196                "verify": None,
197            }
198            v.reject_old_command_name(st, w)
199            if item["manual_command"] is None and item["console_path"] is None:
200                v.err(w, "manual_command 或 console_path 至少要有一個")
201            vf = st.get("verify")
202            if item["where"] == "host":
203                if not isinstance(vf, dict):
204                    v.err(w, "where = \"host\" 的 verify 要是只讀探針的 inline table")
205                else:
206                    item["verify"] = v.probe(vf, f"{w}.verify")
207            elif item["where"] is not None:
208                if not isinstance(vf, str):
209                    v.err(w, "主機外的 verify 要是一句要看到的結果（字串）")
210                else:
211                    item["verify"] = v.subst(f"{w}.verify", vf)
212            steps.append(item)
213        nums = [s["step"] for s in steps if s["step"] is not None]
214        if len(nums) != len(set(nums)):
215            v.err(phase, "step 有重複的編號")
216        out[phase] = sorted(steps, key=lambda s: s["step"] or 0)
217
218    _check_builtin_commands(v, out)
219    if v.errors:
220        raise ManifestError(v.errors)
221    return out
222
223
224def _check_builtin_commands(v: "_Validator", out: dict[str, Any]) -> None:
225    # Checker 自己拼的指令也含清單的值（timer 名稱、journal unit），載入時一併比對白名單，不合就判成格式錯。
226    cmds = [("listen_audit", LISTEN_COMMAND)]
227    timer = out["updates"]["timer"]
228    if isinstance(timer, str):
229        cmds += [("updates.timer", timer_command(verb, timer)) for verb, _ in UPDATE_TIMER_VERBS]
230    for lg in out["log"]:
231        source = lg["source"]
232        if isinstance(source, str) and source.startswith("journal:"):
233            cmds.append((f"log[{lg['name']}].source", journal_command(source.partition(":")[2])))
234    for where, cmd in cmds:
235        reason = readonly_violation(cmd)
236        if reason:
237            v.err(where, f"自動執行的指令不是只讀指令：{reason}（{cmd}）")

load_manifest 把兩種讀不進來的情形（檔案打不開、內容不是合法的 TOML）都轉成 ManifestError，跟欄位錯走同一個 exit 2。錯誤訊息寫「不是合法的 TOML 1.0」，因為示範清單描述的那台 Oracle Linux 10 主機上，Python 3.12 的 tomllib 只認 TOML 1.0：在開發機上用較新的 Python 驗證過的清單，到了只有 3.12 的主機上，1.1 才有的語法會在這裡失敗；兩個版本的差異與解析器的版本在清單寫成 TOML 的那篇概念文章的〈TOML 1.0 與 1.1 的差異與解析器的版本〉。

validate 先處理 [vars] 與 --set：--set 給的名稱要已經寫在 [vars] 裡，打錯字的名稱算格式錯（test_unknown_set_name_is_format_error），不會被當成一個新的變數收下、而清單裡想覆寫的那個值照舊不變。同一份清單套到多台主機時，每台不同的值在執行時用 --set 覆寫、還是在部署時就寫進每台的清單，以及依角色過濾項目的取捨，在多台主機的維護清單：值的分層與合併的位置、用 Ansible 的 inventory 與範本產生每台的清單、由 Terraform 的輸出產生 inventory、跨主機執行的 exit code，以及單台清單的適用範圍。之後依清單的段落逐段驗：

必填與選填的段落：[host]、[updates]、[[entrypoint]]、[[log]]、[[accumulation]]、[[suspend]]、[[resume]] 缺了都算格式錯；[[filesystem]]（table_list 的 required=False）、[vars]（預設是空表格）與 [listen_audit]（預設寫在 [listen_audit] 那一項）可以不寫。所以一份只想檢查入口的清單，其他段落也要寫出來；這是這支腳本的規格，換成自己的腳本時依需要放寬。
[listen_audit]：整段沒寫時，預設檢查 TCP、沒有額外允許的連接埠，沒寫這一段的清單照樣檢查有沒有多開的 TCP 連接埠；寫了這一段就要寫出 protocols，寫成空陣列等於關掉這項檢查。
錯誤的位置：入口、log、會累積的資料有名稱時，錯誤的位置寫成 entrypoint[https] 這種帶名稱的寫法，名稱缺了才退回索引，改清單的人照名稱找得到那一段。
入口的 enforced_by 與 [[entrypoint.verify]]：enforced_by 的每一層至少要有一筆 [[entrypoint.verify]]，每一筆 verify 的 layer 都要在 enforced_by 裡；比對用的是集合，同一層寫兩筆 verify 是允許的。宣告由某一層擋、卻沒寫那一層怎麼確認，或寫了確認方式、卻沒宣告由那一層擋，兩種都是格式錯（test_enforced_layer_without_verify 測宣告了卻沒有確認的那一種）。理由是清單宣告的防護層，每一層都要有一個確認的動作，欄位這樣設計的推導在清單寫成 TOML 的那篇概念文章的〈清單欄位的設計：檢查腳本要讀的與人要讀的〉。
會累積的資料：path 可以寫一個字串或一個陣列，先統一成陣列；limit_bytes 與 retention_days 至少要有一個，沒有門檻的累積項目只能印出大小、判定不了 WARN；oldest_command 用來從資料庫查最舊一筆的時間，它跟保留天數一起才有意義，也要過白名單。
暫停與恢復的步驟：verify 的型別依 where 而定，在主機上確認的是一個只讀探針，寫成寫在同一行的表格（inline table），在主機外確認的是一句人要看到的結果；步驟編號重複時判成格式錯，之後依編號排序，清單裡的寫出順序不影響執行順序。

最後 _check_builtin_commands 把腳本自己會組的指令（接聽連接埠的查詢、timer 的兩個查詢、journal 的查詢；journal 是 journald（systemd-journald）收下的紀錄）用清單的值組出來比對白名單，載入時就擋下 --host=evil 這種 timer 名稱。全部驗完才看 v.errors，有任何一條就丟出 ManifestError。

執行指令的 Runner 與時鐘

腳本執行外部程式都經過 Runner.run：執行之前再比對一次白名單，以固定的環境變數與逾時執行，找不到指令與逾時都轉成一個結果、不丟例外。單元測試把它換成假的執行器，記錄每一次被呼叫的指令並回傳預先寫好的結果，所以測試不碰主機的狀態；取現在時間的 now_utc 也可以替換，讓跟時間有關的判定在測試裡有固定的答案。

 1# ── 執行環境（測試時替換）─────────────────────────────────
 2
 3
 4@dataclass
 5class Result:
 6    exit: int
 7    stdout: str
 8    stderr: str
 9
10
11class Runner:
12    """執行只讀指令。測試以假的 Runner 替換，記錄被呼叫的指令。"""
13
14    def run(self, command: str) -> Result:
15        # 執行前再比對一次白名單：validate 之後到執行之間沒有別的路徑能塞進指令，這是第二道。
16        reason = readonly_violation(command)
17        if reason:
18            raise RuntimeError(f"拒絕執行非只讀指令：{reason}")
19        argv = shlex.split(command)
20        env = dict(os.environ, LC_ALL="C", LANG="C", SYSTEMD_PAGER="", PAGER="cat")
21        try:
22            p = subprocess.run(argv, capture_output=True, text=True, timeout=COMMAND_TIMEOUT_S, env=env, stdin=subprocess.DEVNULL)
23        except FileNotFoundError:
24            return Result(127, "", f"找不到指令 {argv[0]}")
25        except subprocess.TimeoutExpired:
26            return Result(124, "", f"超過 {COMMAND_TIMEOUT_S} 秒沒有結束")
27        return Result(p.returncode, p.stdout, p.stderr)
28
29
30def now_utc() -> dt.datetime:
31    return dt.datetime.now(dt.timezone.utc)

執行前那一次比對不通過時，Runner 丟出 RuntimeError，命令列把它當成格式錯以 exit 2 結束（單元測試 test_runner_refuses_non_readonly 與 test_runtime_error_becomes_exit_2，本篇沒有收錄）。正常情形下載入清單時已經擋下，這一道防的是之後有人加了一條不經過 validate 就執行指令的程式路徑。

subprocess.run 收的是切好的參數串列，不帶 shell=True，指令不經過 shell。shlex.split 只切詞，不做 shell 會做的展開：* 這類 glob、~、$VAR 都原樣傳給工具。清單寫 du -s /var/log/x/* 時，du 收到的是字面的 /var/log/x/*（實跑：du 以 exit 1 結束，錯誤是 No such file）；要量多個檔案的大小，寫在 [[accumulation]] 的 path，那裡的 glob 由 expand_path 展開。環境變數從呼叫者的環境複製一份再蓋掉四個：LC_ALL=C 與 LANG=C 讓工具印英文，REBOOT_REQUIRED_TEXT 與 enabled、active 這類比對字串才對得上；SYSTEMD_PAGER 設成空字串、PAGER=cat，systemctl 與 journalctl 就不會開分頁程式等人按鍵；stdin 接 /dev/null，要讀輸入的工具立刻讀到結尾。PATH 沿用呼叫者的：裸工具名依 PATH 找檔案，PATH 前面的目錄放了一個同名的檔案時，執行的是那一個、不是系統目錄裡的那一支，白名單的執行檔路徑那一層只看指令字串，擋不住這一種。所以腳本要經由 sudo（它的 secure_path 會重設 PATH）或 systemd 的 unit 執行：systemd 啟動 unit 的程序時不繼承下指令那個 shell 的環境變數，PATH 用 systemd 自己的預設值（systemd.exec(5) 的環境變數一節；本篇未實跑），條件寫在主機維護清單寫成 TOML：JSON、YAML、TOML 的取捨、TOML 1.0 與 1.1 的版本差異、清單的欄位設計與只讀檢查腳本〈只讀檢查腳本的白名單、輸出、exit code 與結果檔〉白名單三層比對裡的「執行檔的路徑」那一層。

找不到指令時回 127、逾時回 124，跟 shell 與 GNU timeout 用的 exit code 相同，錯誤訊息放在 stderr。工具自己也可能以 127 或 124 結束，所以 Checker 的 run_probe 同時看 exit code 與 stderr 是否以 找不到指令 或 超過 開頭，分辨這是 Runner 造出來的結果、還是工具自己的 exit code。

Checker 的各項檢查

Checker 依清單逐項執行檢查，每一項產生一行報告：狀態（PASS、WARN、MANUAL）、項目名稱、理由，有量到數字的項目另外帶著那個數字給結果檔用。維護時跑入口、log、會累積的資料、檔案系統與自動更新五類，暫停與恢復時只跑那個階段的步驟。各類檢查要量什麼、門檻怎麼定，在長期上線主機的維護項目：會累積的資料、定期讀的 log、對外入口的盤點、安全更新、會到期的設定與檢查間隔的推算；輸出與 exit code 的讀法在主機維護清單寫成 TOML：JSON、YAML、TOML 的取捨、TOML 1.0 與 1.1 的版本差異、清單的欄位設計與只讀檢查腳本〈只讀檢查腳本的白名單、輸出、exit code 與結果檔〉。

報告的一行與探針的判定

1# ── 檢查 ───────────────────────────────────────────────────
2
3
4@dataclass
5class Line:
6    status: str  # PASS / WARN / MANUAL
7    item: str
8    reason: str
9    value: float | None = None  # 量到的數字（探針值、累積的 bytes、可用 bytes）；結果檔拿它算與前一次的差

Line 的 item 是結果檔比對前後兩次的鍵（例如 entrypoint/https:443/tcp、accumulation/journald），由清單的名稱與欄位組出來；清單裡改了一個名稱，下一次的差異就印成舊名稱 GONE、新名稱 NEW。

 1class Checker:
 2    def __init__(self, manifest: dict[str, Any], runner: Runner | None = None, clock: Callable[[], dt.datetime] = now_utc):
 3        self.m = manifest
 4        self.runner = runner or Runner()
 5        self.clock = clock
 6        self.lines: list[Line] = []
 7
 8    def emit(self, status: str, item: str, reason: str, value: float | None = None) -> None:
 9        self.lines.append(Line(status, item, reason, value))
10
11    # 探針：回傳 (ok, 理由, 量到的值)
12    def run_probe(self, p: Probe) -> tuple[bool, str, float | None]:
13        r = self.runner.run(p.command)
14        out = r.stdout.strip()
15        if r.exit in (124, 127) and r.stderr.startswith(("找不到指令", "超過")):
16            return False, r.stderr, None
17        if p.expect_exit is not None:
18            if r.exit != p.expect_exit:
19                return False, f"exit {r.exit}（預期 {p.expect_exit}）{_brief(r.stderr or out)}", None
20        elif r.exit not in p.ok_exit:
21            return False, f"exit {r.exit}（可接受 {p.ok_exit}）{_brief(r.stderr or out)}", None
22        if p.expect_stdout is not None and out != p.expect_stdout.strip():
23            return False, f"輸出 {_brief(out) or '（空）'}（預期 {p.expect_stdout!r}）", None
24        if p.expect_contains is not None and p.expect_contains not in r.stdout:
25            return False, f"輸出沒有 {p.expect_contains!r}：{_brief(out)}", None
26        if p.expect_not_contains is not None and p.expect_not_contains in r.stdout:
27            return False, f"輸出含 {p.expect_not_contains!r}：{_brief(out)}", None
28        if p.measure is None:
29            return True, _brief(out) or f"輸出為空，exit {r.exit}", None
30        try:
31            value = self.measure(p.measure, r.stdout)
32        except ValueError as e:
33            return False, str(e), None
34        unit = "天" if p.measure == "age_days" else ""
35        shown = f"{value:.1f}{unit}" if p.measure == "age_days" else f"{value:g}"
36        if p.warn_above is not None and value > p.warn_above:
37            return False, f"量到 {shown}，超過門檻 {p.warn_above:g}{unit}", value
38        return True, f"量到 {shown}（門檻 {p.warn_above:g}{unit}）", value
39
40    def measure(self, kind: str, stdout: str) -> float:
41        if kind == "lines":
42            return float(sum(1 for ln in stdout.splitlines() if ln.strip()))
43        text = stdout.strip()
44        if "=" in text:
45            text = text.rsplit("=", 1)[1].strip()
46        if kind == "value":
47            try:
48                return float(text)
49            except ValueError:
50                raise ValueError(f"輸出不是數字：{_brief(stdout)}") from None
51        if text in ("", "n/a"):
52            # systemctl show 的時間屬性沒有值時印空值或 n/a（timer 從未觸發就是這樣）。
53            raise ValueError(f"沒有時間值（{_brief(stdout) or '空的輸出'}；timer 從未觸發過時就是這樣）")
54        ts = parse_time(text)
55        if ts is None:
56            raise ValueError(f"輸出不是時間值：{_brief(stdout) or '（空）'}")
57        return (self.clock() - ts).total_seconds() / 86400

run_probe 依固定的順序判定一個探針，第一個不符的條件決定那一項的理由：Runner 造出來的找不到指令或逾時；exit code（寫了 expect_exit 就只比它，否則比 ok_exit）；expect_stdout 比對去掉前後空白的整段輸出；expect_contains 與 expect_not_contains 在原始輸出裡找子字串；最後才量數字。exit code 不符時，理由附上 stderr（沒有時附輸出）的開頭，WARN 那一行就帶著工具自己的錯誤訊息。

measure 有三種量法。lines 數非空白的行，用在列出符合條件的紀錄、每筆一行的指令；value 與 age_days 先取最後一個 = 之後的字串，因為 systemctl show -p NRestarts 這類指令印的是 NRestarts=0。age_days 遇到空值或 n/a 時的理由是「沒有時間值」，跟解析失敗的「輸出不是時間值」分開：「沒有時間值」代表 timer 從來沒有觸發過，是主機的狀態；「輸出不是時間值」代表腳本讀不懂這個格式，是腳本要修的地方。單獨的 0 不在「沒有時間值」的條件裡，measure("age_days", "LastTriggerUSec=0") 得到「輸出不是時間值」（實跑）。單元測試 test_alert_age_days_never_triggered（本篇沒有收錄）斷言 timer 從未觸發時的理由裡有「沒有時間值」。門檻的比較是「大於才 WARN」，量到的值等於門檻時是 PASS（test_alert_value_at_threshold_passes），清單裡的 warn_above = 0 因此讀成「出現任何一筆就 WARN」。只有量了數字的探針回傳那個值，其餘回傳 None。

入口與接聽中的連接埠

 1    def check_entrypoints(self) -> None:
 2        listening = None
 3        if any(e["where"] == "host" for e in self.m["entrypoint"]) or self.m["listen_audit"]["protocols"]:
 4            listening = self.listening_sockets()
 5        for e in self.m["entrypoint"]:
 6            item = f"entrypoint/{e['name']}:{e['port']}/{e['protocol']}"
 7            if e["where"] == "host":
 8                if listening is None:
 9                    self.emit("WARN", item, "讀不到監聽中的 socket（ss 失敗）")
10                else:
11                    addrs = sorted({a for (proto, a, port) in listening if proto == e["protocol"] and port == e["port"]})
12                    if addrs:
13                        self.emit("PASS", item, f"有程序在聽（{', '.join(addrs)}），exposure={e['exposure']}")
14                    else:
15                        self.emit("WARN", item, f"沒有程序在聽這個連接埠，exposure={e['exposure']}")
16            else:
17                self.emit("MANUAL", item, f"主機外的入口，exposure={e['exposure']}，逐層確認見下方")
18            for vf in e["verify"]:
19                vitem = f"{item}/{vf['layer']}"
20                if vf["where"] == "host":
21                    ok, reason, value = self.run_probe(vf["probe"])
22                    self.emit("PASS" if ok else "WARN", vitem, reason, value)
23                else:
24                    self.emit("MANUAL", vitem, _manual_text(vf["where"], vf.get("console_path"), vf.get("manual_command"), vf["expect"]))
25        if listening is not None:
26            self.audit_listening(listening)
27
28    def listening_sockets(self) -> set[tuple[str, str, int]] | None:
29        r = self.runner.run(LISTEN_COMMAND)
30        if r.exit != 0:
31            return None
32        socks = set()
33        for line in r.stdout.splitlines():
34            parts = line.split()
35            if len(parts) < 5:
36                continue
37            proto = parts[0]
38            local = parts[4]
39            addr, _, port = local.rpartition(":")
40            if not port.isdigit() or proto not in PROTOCOL_VALUES:
41                continue
42            socks.add((proto, addr, int(port)))
43        return socks
44
45    def audit_listening(self, listening: set[tuple[str, str, int]]) -> None:
46        la = self.m["listen_audit"]
47        if not la["protocols"]:
48            return
49        known = {(e["protocol"], e["port"]) for e in self.m["entrypoint"] if e["where"] == "host"}
50        known |= {(a["protocol"], a["port"]) for a in la["allow"]}
51        if not any(p in la["protocols"] for (p, _, _) in listening):
52            # ss 成功卻一個都沒列出：多半是看不到主機的網路（PrivateNetwork=yes 的沙箱），跟「沒有多開」分不開。
53            self.emit("WARN", "listen-audit", f"ss 沒有列出任何 {', '.join(la['protocols'])} 的監聽 socket，判斷不了有沒有多開的連接埠（在 PrivateNetwork=yes 這類隔離網路的環境裡執行時就是這樣）")
54            return
55        extra = sorted({(p, a, port) for (p, a, port) in listening if p in la["protocols"] and not _is_loopback(a) and (p, port) not in known})
56        if not extra:
57            self.emit("PASS", "listen-audit", f"loopback 以外只有清單列出的連接埠在聽（{', '.join(la['protocols'])}）")
58        for p, a, port in extra:
59            self.emit("WARN", f"listen-audit/{port}/{p}", f"{a}:{port} 在聽，但不在 [[entrypoint]] 或 [listen_audit].allow；用 ss -lnp{p[0]} 查是哪個程序")

ss 在一次維護檢查裡只執行一次，入口的判定與多開連接埠的稽核共用它的結果。listening_sockets 讀 ss -H -l -n -t -u 的每一行：第一欄是協定（tcp、udp），第五欄是本機的位址加連接埠；用 rpartition(":") 從右邊切，[::]:22 與 *:8765 這種含冒號或萬用字元的位址也切得出連接埠。ss 的 exit code 不是 0 時回傳 None，主機上的每個入口都印成「讀不到」的 WARN，不判成沒有程式在接聽。

主機上的入口只要有任何一個位址在接聽那個協定與連接埠，就印 PASS，理由裡列出接聽的位址與清單寫的 exposure。腳本不拿位址去比對 exposure：一個 cdn-only 的入口接聽在 0.0.0.0，對外的範圍由防火牆與雲端規則決定，那幾層的確認寫在 [[entrypoint.verify]]，在主機上的逐層跑探針，在主機外的印成 MANUAL。

audit_listening 找清單沒有列出的連接埠：清單已經列出的連接埠是主機上的入口加 [listen_audit].allow，loopback 位址上的接聽不算多開，其餘每個接聽的位址加連接埠各印一行 WARN，項目名是 listen-audit/<連接埠>/<協定>，理由附上查出是哪個程式的 ss 指令。同一個連接埠同時接聽 0.0.0.0 與 [::] 時印兩行，兩行的項目名相同，結果檔只留後一行（〈host-check.py（3fc41c0）的已知限制與重現方式〉）。ss 成功而一個要稽核的協定的 socket 都沒有時印 WARN：在 PrivateNetwork=yes 的沙箱裡，ss 看不到主機的網路，只看結果分不出「沒有多開」與「什麼都看不到」，實跑的結果在清單寫成 TOML 的那篇概念文章的〈只讀檢查腳本的白名單、輸出、exit code 與結果檔〉systemd 屬性表的 PrivateNetwork=yes 那一列。test_extra_port_warns_and_missing_listener_warns 給一份含 0.0.0.0:3306 與 127.0.0.1:631 的輸出，斷言 3306 印成 WARN、631 不出現，沒有程式接聽的 22 印成 WARN；test_no_socket_listed_warns 給空的輸出，斷言稽核那一行是 WARN。

定期讀的 log

 1    def check_logs(self) -> None:
 2        for lg in self.m["log"]:
 3            item = f"log/{lg['name']}"
 4            kind, _, target = lg["source"].partition(":")
 5            hint = f"每 {lg['interval_days']} 天讀一次：{lg['manual_command']}"
 6            if kind == "file":
 7                try:
 8                    st = os.stat(target)
 9                    with open(target, "rb"):
10                        pass
11                except FileNotFoundError:
12                    self.emit("WARN", item, f"{target} 不存在；{hint}")
13                    continue
14                except PermissionError:
15                    self.emit("WARN", item, f"{target} 讀不到（權限，用 sudo 執行）；{hint}")
16                    continue
17                self.emit("PASS", item, f"{target} {_human(st.st_size)}；{hint}")
18            else:
19                r = self.runner.run(journal_command(target))
20                if r.exit == 127:
21                    self.emit("WARN", item, f"{r.stderr}；{hint}")
22                elif not r.stdout.strip():
23                    self.emit("WARN", item, f"journal 裡沒有 {target} 的紀錄（unit 沒跑過，或沒有權限讀 journal）；{hint}")
24                else:
25                    self.emit("PASS", item, f"最新一筆：{_brief(r.stdout.strip(), 90)}；{hint}")
26            for al in lg["alerts"]:
27                ok, reason, value = self.run_probe(al["probe"])
28                self.emit("PASS" if ok else "WARN", f"{item}/{al['name']}", reason, value)

讀 log 的內容是人的工作，腳本只確認 log 在那裡、讀得到，並在每一行的理由後面附上清單寫的讀取間隔與讀的指令，維護的人照那一行去讀。檔案型的 log 除了 os.stat，還實際開一次檔案：stat 只要求能進入上層目錄，檔案本身的讀取權限要開檔才知道。journal 型的 log 讀最新的一筆；輸出是空的有兩種成因（那個 unit 沒有跑過、執行者沒有讀 journal 的權限），腳本分不開，理由裡兩種都寫出來。這條路徑除了 127 不看 exit code：逾時（124）或 journalctl 以非零結束而沒有輸出時，印的也是同一句理由。log 底下的計數門檻（[[log.alert]]）各自是一個探針，照上面的 run_probe 判定。test_missing_file_log_warns 斷言檔案不存在的 log 印成 WARN。

會累積的資料

這一段檢查清單的 [[accumulation]]，每一筆的欄位是 name、path（一個或多個路徑，可以是 glob 樣式）、missing_ok、limit_bytes、retention_days、oldest_command、purge_command。

 1    def check_accumulations(self) -> None:
 2        for ac in self.m["accumulation"]:
 3            item = f"accumulation/{ac['name']}"
 4            files: list[str] = []
 5            denied: list[str] = []
 6            for pat in ac["paths"]:
 7                found, blocked = expand_path(pat)
 8                files.extend(found)
 9                if blocked and blocked not in denied:
10                    denied.append(blocked)
11            if not files and denied:
12                # 讀不到不等於不存在：missing_ok 只管真的不存在的路徑。
13                self.emit("WARN", item, f"讀不到 {', '.join(denied)}（權限，用 sudo 執行），量不到 {', '.join(ac['paths'])}")
14                continue
15            if not files:
16                if ac["missing_ok"]:
17                    self.emit("PASS", item, f"路徑不存在，算 0 bytes（{', '.join(ac['paths'])}）")
18                else:
19                    self.emit("WARN", item, f"路徑不存在：{', '.join(ac['paths'])}")
20                continue
21            total, oldest, unreadable = measure_paths(sorted(set(files)))
22            problems = []
23            facts = [f"{_human(total)}"]
24            if ac["limit_bytes"] is not None:
25                facts[0] += f"／上限 {_human(ac['limit_bytes'])}"
26                if total > ac["limit_bytes"]:
27                    problems.append(f"大小 {_human(total)} 超過上限 {_human(ac['limit_bytes'])}")
28            if ac["retention_days"] is not None:
29                if ac["oldest_command"]:
30                    r = self.runner.run(ac["oldest_command"])
31                    ts = parse_time(r.stdout.strip()) if r.exit == 0 else None
32                    if r.exit != 0:
33                        problems.append(f"oldest_command exit {r.exit}：{_brief(r.stderr)}")
34                    elif ts is None and r.stdout.strip():
35                        problems.append(f"oldest_command 的輸出不是時間值：{_brief(r.stdout)}")
36                    oldest_ts = ts
37                    label = "最舊一筆"
38                else:
39                    oldest_ts = dt.datetime.fromtimestamp(oldest, dt.timezone.utc) if oldest is not None else None
40                    label = "最舊的檔案"
41                if oldest_ts is not None:
42                    age = (self.clock() - oldest_ts).total_seconds() / 86400
43                    facts.append(f"{label} {age:.1f} 天前／保留 {ac['retention_days']} 天")
44                    if age > ac["retention_days"]:
45                        problems.append(f"{label}是 {age:.1f} 天前，超過保留期 {ac['retention_days']} 天")
46                else:
47                    facts.append(f"{label}：沒有資料")
48            if unreadable:
49                problems.append(f"{unreadable} 個路徑讀不到（權限，用 sudo 執行）")
50            if denied:
51                problems.append(f"讀不到 {', '.join(denied)}（權限，用 sudo 執行），那些路徑沒有算進大小")
52            if problems:
53                self.emit("WARN", item, "；".join(problems) + f"。清理做法（不會自動執行）：{ac['purge_command']}", total)
54            else:
55                self.emit("PASS", item, "，".join(facts), total)

一個累積項目的路徑可能是幾個 glob 樣式，每個樣式交給下面〈路徑的展開與大小的量測：expand_path 與 measure_paths〉的 expand_path 展開；展開時被權限擋下的目錄另外記在 denied。判定先分三種情形：一個檔案都沒找到而有目錄讀不到，印「讀不到」的 WARN；一個檔案都沒找到、也沒有目錄讀不到，才是路徑不存在，這時才看 missing_ok；找到檔案，量大小與時間。missing_ok 只管沒有被權限擋下的路徑（上層目錄列得出內容，或路徑根本不存在），讀不到的目錄即使設了 missing_ok 也印 WARN（test_unreadable_glob_with_missing_ok_does_not_pass）：資料可能就在那個讀不到的目錄裡，判成「不存在、算 0」會讓一個寫滿磁碟的目錄印成 PASS。

保留天數有兩種量法：寫了 oldest_command 時，執行它查資料最舊一筆的時間（例如 SQLite 裡某個時間欄位的最小值），沒有寫時取找到的檔案裡最舊的修改時間。oldest_command 成功而輸出是空的（資料表沒有資料）時，理由寫「沒有資料」，不算問題；輸出是 n/a 或 0 時，parse_time 回 None 而輸出不是空的，記成「oldest_command 的輸出不是時間值」的問題、那一項印 WARN（實跑）。超過上限、超過保留期、讀不到的路徑各記一條問題，任何一條都讓這一項印成 WARN，理由後面附上清單的 purge_command；purge_command 只印不執行，test_accumulation_over_limit_warns 斷言 WARN 那一行印出了清理指令，而要被清理的檔案仍然存在。這一項的 value 是總位元組，下一次執行時印成 DELTA。

檔案系統的剩餘空間

 1    def check_filesystems(self) -> None:
 2        for fs in self.m["filesystem"]:
 3            item = f"filesystem/{fs['name']}"
 4            try:
 5                st = os.statvfs(fs["mount"])
 6            except OSError as e:
 7                self.emit("WARN", item, f"讀不到 {fs['mount']}：{e}")
 8                continue
 9            free = st.f_bavail * st.f_frsize
10            size = st.f_blocks * st.f_frsize
11            text = f"{fs['mount']} 剩 {_human(free)}／共 {_human(size)}（下限 {_human(fs['min_free_bytes'])}）"
12            self.emit("PASS" if free >= fs["min_free_bytes"] else "WARN", item, text, free)

os.statvfs 讀檔案系統的區塊計數，不執行 df。剩餘空間取 f_bavail（一般帳號可用的區塊數），不取 f_bfree（全部空閒的區塊數）：ext4 這類檔案系統預留給 root 的區塊算在 f_bfree 裡，而服務多半以一般帳號寫資料，f_bavail 用完時那些服務就寫不進去。區塊數乘上 f_frsize（區塊的大小）得到位元組。這一項的 value 是可用位元組（傳給 emit 的最後一個參數 free），兩次之間少了多少，差異段印得出來。可用空間幾乎每一次執行都不同，所以這一項幾乎每次都印 DELTA，要讀的是括號裡的差值。test_filesystem_value_is_free_bytes 只斷言結果檔裡這一項的值是數字、而且大於 0。

自動更新的排程、設定與重開機

 1    def check_updates(self) -> None:
 2        up = self.m["updates"]
 3        for verb, want in UPDATE_TIMER_VERBS:
 4            r = self.runner.run(timer_command(verb, up["timer"]))
 5            got = r.stdout.strip() or _brief(r.stderr) or f"exit {r.exit}"
 6            self.emit("PASS" if got == want else "WARN", f"updates/{up['timer']}/{verb}", f"{got}（預期 {want}）")
 7        merged: dict[str, str] = {}
 8        read_files = []
 9        for pat in up["config_files"]:
10            for path in sorted(glob.glob(pat)) if glob.has_magic(pat) else [pat]:
11                if not os.path.isfile(path):
12                    continue
13                cp = configparser.ConfigParser(interpolation=None)
14                try:
15                    cp.read(path, encoding="utf-8")
16                except (configparser.Error, OSError, UnicodeDecodeError) as e:
17                    self.emit("WARN", "updates/config", f"{path} 讀不到或格式錯：{e}")
18                    continue
19                read_files.append(path)
20                if cp.has_section("commands"):
21                    merged.update({k: v.strip() for k, v in cp.items("commands")})
22        if not read_files:
23            self.emit("WARN", "updates/config", f"找不到 dnf-automatic 的設定檔（{', '.join(up['config_files'])}）")
24        else:
25            wrong = {k: merged.get(k) for k, v in up["expect"].items() if merged.get(k) != v}
26            item = "updates/config"
27            if wrong:
28                self.emit("WARN", item, "；".join(f"[commands] {k} = {g!r}（預期 {up['expect'][k]!r}）" for k, g in wrong.items()) + f"，讀了 {', '.join(read_files)}")
29            else:
30                self.emit("PASS", item, ", ".join(f"{k} = {v}" for k, v in up["expect"].items()) + f"（mode {up['mode']}，讀了 {', '.join(read_files)}）")
31        if up["reboot_check"]:
32            r = self.runner.run(up["reboot_check"])
33            item = "updates/reboot"
34            if r.exit == 0:
35                self.emit("PASS", item, "不需要重開機")
36            elif r.exit == 1 and REBOOT_REQUIRED_TEXT in r.stdout + r.stderr:
37                self.emit("WARN", item, f"更新之後需要重開機（{up['reboot_check']}）：{_brief(r.stdout.strip(), 120)}；deploy.sh 不自動重開，排時間 sudo systemctl reboot")
38            elif r.exit == 1:
39                self.emit("WARN", item, f"{up['reboot_check']} exit 1，但輸出沒有 {REBOOT_REQUIRED_TEXT!r}，判斷不了要不要重開機：{_brief(r.stderr or r.stdout) or '（沒有輸出）'}")
40            else:
41                self.emit("WARN", item, f"{up['reboot_check']} exit {r.exit}：{_brief(r.stderr or r.stdout)}")

自動更新分三項檢查。清單的 [updates].mode 不在其中：它只出現在 updates/config 那一行 PASS 的理由裡（mode {up['mode']}），腳本不拿它比對任何設定或輸出。timer 的兩個查詢比對 systemctl 印的整個字串：is-enabled 要印 enabled、is-active 要印 active，輸出是空的時，理由改用 stderr 或 exit code，WARN 那一行看得到 systemctl 回了什麼。

設定檔可以寫成 glob 樣式（主設定檔，加上放在附加目錄裡、依檔名順序蓋過主設定的片段檔，也就是 drop-in；這是 dnf 自己的設定目錄，不改主設定檔、用片段蓋過其中的值這個做法，跟 systemd drop-in（不改原檔的設定疊加）相同），展開之後依檔名排序、依序讀，[commands] 段的值後讀到的蓋過先讀到的。ConfigParser 關掉 interpolation：預設的寫法會把值裡的 % 當成變數替換的語法，設定值含一個不成語法的 % 時，cp.items 取值就丟出例外，而取值的那一行 merged.update({k: v.strip() for k, v in cp.items("commands")}) 不在 try 裡（try 只包住 cp.read），整支腳本會中止。清單的 expect 只列要確認的鍵，設定檔裡其他的鍵不比對；理由裡列出讀了哪些檔案，比對錯了的時候，維護的人知道值是從哪一份讀來的。

reboot_check 的 exit 1 有兩種成因：dnf 判定要重開機，以及 dnf 自己出錯（在唯讀的檔案系統上寫不了 log）。腳本因此同時看輸出裡有沒有 Reboot is required，有才印「需要重開機」，沒有時印「判斷不了」並附上 dnf 的錯誤訊息；兩種成因的實跑結果與沙箱的設定在清單寫成 TOML 的那篇概念文章的〈只讀檢查腳本的白名單、輸出、exit code 與結果檔〉。test_reboot_required_message_warns_reboot、test_reboot_exit1_without_message_is_not_reboot 與 test_reboot_exit0_passes 各給一種輸出，斷言三種理由。理由裡的 deploy.sh 是私有專案部署那台主機的腳本，它裝好自動更新、不自動重開機。

暫停與恢復的步驟，以及依 phase 選檢查

 1    def check_phase(self, phase: str) -> None:
 2        for st in self.m[phase]:
 3            item = f"{phase}/{st['step']}/{st['resource']}"
 4            billing = f"停機計費：額度內 {st['billed_when_stopped']}，超出額度 {st['billed_when_stopped_beyond_free']}（{st['billing_basis']}）"
 5            action = st["manual_command"] or st["console_path"]
 6            if st["where"] == "host":
 7                self.emit("MANUAL", item, f"在主機上做（腳本不執行）：{action}；{billing}")
 8                ok, reason, value = self.run_probe(st["verify"])
 9                self.emit("PASS" if ok else "WARN", f"{item}/verify", reason, value)
10            else:
11                self.emit("MANUAL", item, _manual_text(st["where"], st["console_path"], st["manual_command"], st["verify"]) + f"；{billing}")
12
13    def run(self, phase: str = "maintain") -> list[Line]:
14        if phase == "maintain":
15            self.check_entrypoints()
16            self.check_logs()
17            self.check_accumulations()
18            self.check_filesystems()
19            self.check_updates()
20        else:
21            self.check_phase(phase)
22        return self.lines

暫停與恢復的每一步都印成 MANUAL，理由寫出要做的動作與那項資源停機時的計費；動作由人執行，腳本不執行 manual_command。在主機上的步驟另外執行 verify 的只讀探針，多印一行 PASS 或 WARN：維護的人做完那一步再跑一次腳本，verify 那一行確認那一步是否做成。test_host_step_runs_only_verify 斷言假的執行器只收到 verify 的指令，沒有收到 manual_command。各步驟要做什麼、停機時哪些資源還在計費，在服務暫停與恢復上線：只停服務、停止主機、終止主機到全部刪除各自保留的資源，暫停期間仍計費與仍被指向的資源，恢復前要查的漂移與恢復的順序。

run 依 --phase 選要跑的檢查。維護時五類檢查依固定順序執行，順序只決定報告裡各行的先後；結果檔以項目名稱比對前後兩次，不依賴行的順序。

路徑的展開與大小的量測：expand_path 與 measure_paths

這一段給會累積的資料用：把清單的路徑樣式展開成實際的檔案，分出「不存在」與「讀不到」，再用 os.lstat 量總大小與最舊的修改時間，不執行 du：白名單裡的 du 是給清單的探針用的，腳本自己量大小時不呼叫它。分出讀不到的路徑，是為了讓一般帳號執行時讀不到的目錄印成 WARN，而不是被當成路徑不存在，改用專用帳號實跑時讀不到哪些目錄，在主機維護清單寫成 TOML：JSON、YAML、TOML 的取捨、TOML 1.0 與 1.1 的版本差異、清單的欄位設計與只讀檢查腳本〈只讀檢查腳本的白名單、輸出、exit code 與結果檔〉。

 1# ── 小工具 ─────────────────────────────────────────────────
 2
 3
 4def expand_path(pat: str) -> tuple[list[str], str | None]:
 5    """展開 [[accumulation]] 的一個路徑，回傳 (找到的路徑, 擋住讀取的目錄)。
 6
 7    glob 與 os.path.lexists 遇到沒有權限的目錄都安靜地當成沒有（非 root 讀 0711 的 /var/log/nginx、
 8    0750 的 /var/lib/monitor-collector、0700 的家目錄底下），所以找不到時再查一次：
 9    glob 查萬用字元之前那一層目錄列不列得出來，一般路徑查 lstat 是不是被權限擋下。
10    萬用字元出現在中間一層、而更深一層的目錄讀不到時，這裡查不出來，仍然算成不存在。
11    """
12    if glob.has_magic(pat):
13        found = glob.glob(pat)
14        if found:
15            return found, None
16        parts = pat.split(os.sep)
17        i = next(i for i, part in enumerate(parts) if glob.has_magic(part))
18        base = os.sep.join(parts[:i]) or (os.sep if pat.startswith(os.sep) else os.curdir)
19        try:
20            os.listdir(base)
21        except PermissionError:
22            return [], base
23        except OSError:
24            pass
25        return [], None
26    try:
27        os.lstat(pat)
28    except PermissionError:
29        return [], pat
30    except OSError:
31        return [], None
32    return [pat], None
33
34
35def measure_paths(paths: list[str]) -> tuple[int, float | None, int]:
36    """回傳 (總 bytes, 最舊的 mtime, 讀不到的路徑數)；不跟隨 symlink，同一個 inode 只算一次。"""
37    total = 0
38    oldest: float | None = None
39    unreadable = 0
40    seen: set[tuple[int, int]] = set()
41
42    def visit(p: str) -> None:
43        nonlocal total, oldest, unreadable
44        try:
45            st = os.lstat(p)
46        except OSError:
47            unreadable += 1
48            return
49        key = (st.st_dev, st.st_ino)
50        if key in seen:
51            return
52        seen.add(key)
53        if stat.S_ISREG(st.st_mode):
54            total += st.st_blocks * 512 if st.st_blocks else st.st_size
55            oldest = st.st_mtime if oldest is None else min(oldest, st.st_mtime)
56        elif stat.S_ISDIR(st.st_mode):
57            try:
58                entries = os.listdir(p)
59            except OSError:
60                unreadable += 1
61                return
62            for name in entries:
63                visit(os.path.join(p, name))
64
65    for p in paths:
66        visit(p)
67    return total, oldest, unreadable

glob.glob 遇到列不出內容的目錄時回傳空串列，不丟例外，結果跟「沒有符合的檔案」一樣。expand_path 因此在 glob 找不到時，取樣式裡第一個含萬用字元的那一層之前的目錄，試著列一次內容：被權限擋下就回傳那個目錄，讓呼叫的程式印「讀不到」；列得出來（目錄在、只是沒有符合的檔案）或目錄不存在，才算不存在。不含萬用字元的路徑用 os.lstat 查，上層目錄不讓進入時 lstat 丟出 PermissionError。docstring 寫了這個做法查不出的情形：萬用字元在中間一層、更深一層讀不到時，仍然算成不存在。單元測試 test_glob_in_unlistable_dir_is_unreadable（本篇沒有收錄）用權限 0311（擁有者可以進入、不能列出內容）的目錄重現一般帳號看 0711 的 /var/log/nginx，斷言理由是「讀不到」，同一個目錄擋住兩個樣式時只列一次；test_literal_path_under_unreadable_parent_is_unreadable 用權限 0000 的上層目錄測不含萬用字元的路徑。這幾項測試要以一般帳號執行，以 root 執行時權限擋不住讀取，測試會失敗。

measure_paths 遞迴走過每個路徑，用 lstat 而不用 stat：符號連結本身不算進大小，也不會被跟進去，一個指向 / 的連結不會讓腳本量整個檔案系統。每個檔案以（裝置編號、inode 編號）為鍵只算一次，inode 是檔案系統裡代表一個檔案的節點，硬連結共用同一個 inode，兩個樣式找到同一個檔案時也只算一次。大小取 st_blocks * 512，也就是檔案實際佔用的磁碟區塊（st_blocks 以 512 位元組為單位），跟 du 量的是同一種值：稀疏檔案的長度可能遠大於它佔用的空間，而上限要比的是磁碟用量。量的過程中讀不到的路徑只計數，不中斷，呼叫的程式把計數寫進 WARN 的理由。

st_blocks 是 0 時的退路，跟「上限要比的是磁碟用量」互相衝突。程式在 st_blocks 是 0 時改用檔案的長度 st_size；這個退路是為哪一種情形，原始碼與加入它的 commit 都沒有寫。而整個檔案都是空洞的稀疏檔案，st_blocks 正好是 0，會被算成它的長度，寫在〈host-check.py（3fc41c0）的已知限制與重現方式〉的〈各項檢查：ss 失敗、重複的項目名、loopback、特殊檔案、稀疏檔案與時間值〉。

時間字串的解析與組輸出用的小函式

parse_time 把 log 計數門檻的探針（[[log.alert]] 裡 measure = "age_days" 的那些）與 [[accumulation]] 的 oldest_command 印出的時間字串轉成帶時區的時間，接受 systemd 的格式、Unix 時間戳與 ISO 8601；之後是判斷 loopback 位址、把位元組換成 KiB 與 MiB、把輸出壓成一行、組 MANUAL 理由的小函式。腳本第一次在雲端主機上執行時讀不懂 systemd 印的時間格式，那一次的結果與修正在主機維護清單寫成 TOML：JSON、YAML、TOML 的取捨、TOML 1.0 與 1.1 的版本差異、清單的欄位設計與只讀檢查腳本〈只讀檢查腳本的白名單、輸出、exit code 與結果檔〉裡記錄雲端主機第一次執行結果的那幾段。

 1# systemd 的時間格式：systemctl show 印時間屬性（LastTriggerUSec 這類）時用它，不理
 2# --timestamp=unix。例：'Mon 2026-10-26 07:07:43 GMT'、'Mon 2026-10-26 15:07:43.250000 CST'。
 3# 時區是縮寫：UTC、GMT 直接認；其他縮寫要等於這台主機目前時區的縮寫（time.tzname）才當成本地
 4# 時間，認不得的不猜（回傳 None）。
 5SYSTEMD_TIME_RE = re.compile(r"^(?:[A-Z][a-z]{2} )?(\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}(?:\.\d{1,6})?) ([A-Za-z]{2,6}|[+-]\d{2}:?\d{2})$")
 6
 7
 8def _parse_systemd_time(text: str) -> dt.datetime | None:
 9    m = SYSTEMD_TIME_RE.match(text)
10    if not m:
11        return None
12    clock, zone = m.groups()
13    naive = dt.datetime.fromisoformat(clock)
14    if zone in ("UTC", "GMT", "UCT", "Z"):
15        return naive.replace(tzinfo=dt.timezone.utc)
16    if zone[0] in "+-":
17        return dt.datetime.fromisoformat(f"{clock}{zone[:3]}:{zone[-2:]}")
18    if zone in time.tzname:
19        # 本地時區：naive 的 astimezone() 依這個程序的時區規則換算（含夏令時間）。
20        return naive.astimezone()
21    return None
22
23
24def parse_time(text: str) -> dt.datetime | None:
25    text = text.strip()
26    if not text or text in ("n/a", "0"):
27        return None
28    if re.fullmatch(r"@?\d+(\.\d+)?", text):
29        return dt.datetime.fromtimestamp(float(text.lstrip("@")), dt.timezone.utc)
30    systemd = _parse_systemd_time(text)
31    if systemd is not None:
32        return systemd
33    # 小數秒超過 6 位（Go 的 RFC3339Nano）時截到微秒，fromisoformat 才吃得下。
34    t = re.sub(r"(\.\d{6})\d+", r"\1", text.replace(" ", "T", 1))
35    t = re.sub(r"Z$", "+00:00", t)
36    try:
37        ts = dt.datetime.fromisoformat(t)
38    except ValueError:
39        return None
40    return ts if ts.tzinfo else ts.replace(tzinfo=dt.timezone.utc)

systemd 的時間格式以時區縮寫結尾，而縮寫不唯一對應一個時區：CST 在 Asia/Taipei 是台灣的標準時間，在美國中部是另一個時區。_parse_systemd_time 因此只認 UTC 這一類縮寫，以及等於這台主機目前時區縮寫的那一個（time.tzname），也認 +0800、+08:00 這種數字的時區偏移，其餘回傳 None，讓那一項印成「輸出不是時間值」，不猜一個時區而算出差了幾小時的天數。單元測試 test_alert_age_days_systemd_local_zone（本篇沒有收錄）把時區設成 Asia/Taipei，斷言 CST 換算正確、不認得的 XYZT 判成不是時間值；test_alert_age_days_systemd_format 測 GMT、UTC 與帶小數秒的寫法。

parse_time 接受三種格式：可以有 @ 前綴的 Unix 時間戳（epoch 秒數）、systemd 的格式、ISO 8601。systemd 的格式要另外處理，因為 systemctl show 印時間屬性（LastTriggerUSec 這類）時不理 --timestamp=unix，印的是 systemd 自己的格式；程式碼註解記了這一點，test_alert_age_days_systemd_format 用的就是那種輸出。

單獨的 0 與 n/a，parse_time 回 None，@0 照樣當成 1970-01-01（實跑）。回 None 之後怎麼判由呼叫端決定，兩個呼叫端的判法不同：measure 在呼叫 parse_time 之前，先把空的輸出與 n/a 判成「沒有時間值」，0 不在其中，結果是「輸出不是時間值」；check_accumulations 只把空的輸出當成沒有資料，oldest_command 印 n/a 或 0 時印 WARN「輸出不是時間值」（兩者都實跑）。measure 與 check_accumulations 各自的結果寫在〈host-check.py（3fc41c0）的已知限制與重現方式〉的〈各項檢查：ss 失敗、重複的項目名、loopback、特殊檔案、稀疏檔案與時間值〉。

ISO 8601 的字串截掉超過微秒的小數秒，程式碼註解寫的理由是 datetime.fromisoformat 吃不下 Go 的 RFC3339Nano 印出的奈秒，那是 Python 3.10 以前的行為：實跑 Python 3.10.18 的 fromisoformat 對九位小數丟出 ValueError: Invalid isoformat string，3.11.13、3.12.11、3.15.0 都接受九位小數、自己截到微秒。腳本要求 3.11 以上，所以在它支援的版本上，這一行截斷是冗餘的，結果跟不截斷相同。

沒有時區的 ISO 時間當成 UTC：字串本身沒有時區，腳本沒有別的資訊可以判斷。資料來源寫進去的是不帶時區的本地時間時，算出的天數會差一個時區偏移（台北是 8 小時，約 0.33 天），保留期的判定在門檻附近會早或晚 8 小時翻轉成 WARN。

 1def _is_loopback(addr: str) -> bool:
 2    a = addr.strip("[]").split("%", 1)[0]
 3    return a.startswith("127.") or a == "::1"
 4
 5
 6def _human(n: int | float) -> str:
 7    for unit in ("B", "KiB", "MiB", "GiB"):
 8        if abs(n) < 1024 or unit == "GiB":
 9            return f"{n:.0f} {unit}" if unit == "B" else f"{n:.1f} {unit}"
10        n /= 1024
11    return f"{n:.1f} GiB"
12
13
14def _brief(text: str, limit: int = 160) -> str:
15    one = " ".join(text.split())
16    return one if len(one) <= limit else one[: limit - 1] + "…"
17
18
19def _manual_text(where: str, console_path: str | None, command: str | None, expect: str) -> str:
20    place = {"console": "主控台", "external": "主機外"}[where]
21    how = console_path if console_path else f"執行 {command}"
22    return f"[{place}] {how} → 預期：{expect}"

_is_loopback 先去掉 IPv6 位址外面的方括號與 % 之後的介面名稱（ss 印 [::1]:631 或 127.0.0.53%lo:53 這種寫法），再比對 127. 開頭或 ::1。_human 的單位是 1024 進位的 KiB、MiB、GiB，跟 du -h、df -h 的換算方式相同，報告裡的大小拿去跟這兩支工具的輸出對照時不必換算。_brief 把多行的輸出壓成一行並截到 160 個字元，報告每一項維持一行，用 grep 篩報告時一項就是一行。

結果檔的讀寫與跟前一次的差異

結果檔讓每一次的報告能跟同一個階段的前一次比對（階段就是 --phase 的 maintain、suspend、resume）：讀前一次的紀錄、算出差異、印在報告裡，最後把這一次的紀錄寫回去。寫回的做法是同一個目錄裡的暫存檔、fsync、os.replace，再 fsync 目錄，保證中斷時舊的紀錄仍然完整，說明在程式碼之後。結果檔的格式、印出的差異與預設路徑放在 /var/lib 的理由，在主機維護清單寫成 TOML：JSON、YAML、TOML 的取捨、TOML 1.0 與 1.1 的版本差異、清單的欄位設計與只讀檢查腳本〈只讀檢查腳本的白名單、輸出、exit code 與結果檔〉。

 1# ── 結果檔（與前一次的差）──────────────────────────────────
 2# 腳本自己的結果檔，不是清單的一部分：清單只描述要檢查什麼，量到的值存在這裡。
 3# 唯一會寫的檔案，而且只寫這一個（同目錄暫存檔 + os.replace，結束時目錄裡只有它）。
 4
 5
 6def load_state(path: str) -> tuple[dict[str, Any], str | None]:
 7    # 讀結果檔，回傳 (內容, 要印的 note)。不存在回空內容且不印 note；壞掉或格式不認得當成沒有。
 8    try:
 9        with open(path, encoding="utf-8") as f:
10            data = json.load(f)
11    except FileNotFoundError:
12        return {}, None
13    except (OSError, ValueError) as e:  # JSONDecodeError、UnicodeDecodeError 都是 ValueError
14        return {}, f"結果檔 {path} 讀不到或壞掉（{e}），當成沒有前一次，這次會覆寫"
15    if not isinstance(data, dict) or data.get("format") != STATE_FORMAT or not isinstance(data.get("phases"), dict):
16        return {}, f"結果檔 {path} 的格式不認得，當成沒有前一次，這次會覆寫"
17    return data, None
18
19
20def previous_phase(state: dict[str, Any], phase: str) -> dict[str, Any] | None:
21    prev = state.get("phases", {}).get(phase)
22    if isinstance(prev, dict) and isinstance(prev.get("finished_at"), str) and isinstance(prev.get("items"), dict):
23        return prev
24    return None
25
26
27def build_record(lines: list[Line], counts: dict[str, int], manifest_path: str, finished_at: dt.datetime) -> dict[str, Any]:
28    return {
29        "finished_at": finished_at.astimezone(dt.timezone.utc).isoformat(),
30        "manifest": manifest_path,
31        "counts": counts,
32        "items": {ln.item: {"status": ln.status, "value": ln.value} for ln in lines},
33    }
34
35
36def _num(n: float) -> str:
37    return f"{n:.0f}" if float(n).is_integer() else f"{n:.2f}"
38
39
40def _prev_value(entry: Any) -> tuple[str | None, float | None]:
41    if not isinstance(entry, dict):
42        return None, None
43    value = entry.get("value")
44    ok = isinstance(value, (int, float)) and not isinstance(value, bool)
45    return entry.get("status"), (value if ok else None)
46
47
48def diff_lines(prev: dict[str, Any] | None, lines: list[Line], state_path: str) -> list[str]:
49    # 與前一次的差：第一行 since:，其後每個差一行（CHANGED / DELTA / NEW / GONE）。
50    if prev is None:
51        return [f"since: 沒有前一次的結果（{state_path}）"]
52    out: list[str] = []
53    seen: set[str] = set()
54    for ln in lines:
55        seen.add(ln.item)
56        if ln.item not in prev["items"]:
57            out.append(f"NEW     {ln.item}  {ln.status}")
58            continue
59        old_status, old_value = _prev_value(prev["items"][ln.item])
60        if old_status != ln.status:
61            out.append(f"CHANGED {ln.item}  {old_status}→{ln.status}")
62        if old_value is not None and ln.value is not None and old_value != ln.value:
63            delta = ln.value - old_value
64            out.append(f"DELTA   {ln.item}  {_num(old_value)} → {_num(ln.value)}（{'+' if delta > 0 else '-'}{_num(abs(delta))}）")
65    out.extend(f"GONE    {item}" for item in sorted(set(prev["items"]) - seen))
66    if not out:
67        return [f"since: {prev['finished_at']}，與前一次相同"]
68    return [f"since: {prev['finished_at']}", *out]

讀結果檔的三個函式都把讀到的內容當成不可信的輸入：檔案不存在是第一次執行，不印說明；JSON 壞掉、編碼不對、讀不到，回傳一條 note（由 main 印到 stderr）並當成沒有前一次；最外層不是 format 等於 STATE_FORMAT（1）、帶 phases 的物件時，同樣當成沒有前一次。previous_phase 與 _prev_value 再逐層確認型別，值是布林時不拿來算差。手改過或被別的程式寫壞的結果檔，最多讓差異段印成「沒有前一次的結果」，不會讓腳本中止（單元測試 test_corrupt_state_does_not_abort，本篇沒有收錄）。

diff_lines 以項目名稱比對前後兩次，所以清單改了名稱的項目印成一筆 GONE 加一筆 NEW。同一個項目狀態與數字都變了時，CHANGED 與 DELTA 各印一行；DELTA 只在兩次都有數字時印，value 是 null 的項目只會出現在 CHANGED。GONE 依名稱排序，同樣的兩份紀錄每次印出的差異段順序相同。test_new_and_gone_items 斷言清單加進一個累積項目之後印 NEW accumulation/b PASS，拿掉之後印 GONE accumulation/b；test_second_run_prints_changed_and_delta 斷言一個計數門檻 100 的探針從 42 變成 50 時印 DELTA log/edge/status-429 42 → 50（+8），變成 500 時同時印 CHANGED … PASS→WARN 與 DELTA … 50 → 500（+450），再變成 20 時印 DELTA … 500 → 20（-480）。

 1def _fsync_directory(directory: str) -> None:
 2    # rename 要等目錄項寫進磁碟才耐斷電；Windows 不能開目錄，略過。
 3    if not hasattr(os, "O_DIRECTORY"):
 4        return
 5    fd = os.open(directory, os.O_RDONLY | os.O_DIRECTORY)
 6    try:
 7        os.fsync(fd)
 8    finally:
 9        os.close(fd)
10
11
12def write_state(path: str, state: dict[str, Any]) -> str | None:
13    # 原子地寫結果檔；失敗回傳 note（不改變 exit code）。
14    directory = os.path.dirname(os.path.abspath(path))
15    tmp_path = None
16    try:
17        os.makedirs(directory, mode=0o700, exist_ok=True)
18        fd, tmp_path = tempfile.mkstemp(prefix=".last-", suffix=".tmp", dir=directory)  # mkstemp 建出來就是 0600
19        with os.fdopen(fd, "w", encoding="utf-8") as f:
20            json.dump(state, f, ensure_ascii=False, indent=2, sort_keys=True)
21            f.write("\n")
22            f.flush()
23            os.fsync(f.fileno())
24        os.replace(tmp_path, path)
25        tmp_path = None
26        _fsync_directory(directory)
27    except OSError as e:
28        return f"結果檔 {path} 寫不進去（{e}）；這次的結果沒有存下來，報告與 exit code 不受影響"
29    finally:
30        if tmp_path is not None:
31            try:
32                os.unlink(tmp_path)
33            except OSError:
34                pass  # 暫存檔已不在（沒建成功或已被取代），沒有東西要清
35    return None

write_state 的寫法依序是：在結果檔的同一個目錄用 tempfile.mkstemp 建暫存檔（權限 0600），寫完內容之後 fsync（要求作業系統把檔案內容寫到磁碟），再用 os.replace 換上正式的檔名，最後 fsync 那個目錄。暫存檔要在同一個目錄，因為 os.replace 在同一個檔案系統裡才是一次完成的換名；目錄的 fsync 讓換名這件事本身也寫進磁碟，斷電之後正式的檔名指著的是舊的或新的完整內容，不會是寫到一半的檔案。os.replace 擋的是中斷，擋不住兩次執行同時寫：程式裡沒有檔案鎖（flock 這類），兩次同時跑時，各自讀到的是開始時的結果檔，後換名的那一次蓋掉先換名的那一次寫進的紀錄（讀碼）。test_write_state_fsyncs_file_and_directory 斷言 fsync 至少呼叫兩次（檔案一次、目錄一次）。

os.makedirs 的 mode=0o700 只套在這次新建的最後一層目錄上（中間各層用預設的權限），已經存在的目錄不改權限；exist_ok=True 只讓目錄已經存在時不丟例外。所以由 systemd 的 StateDirectory= 建出的目錄，權限照 StateDirectoryMode= 設定，腳本不跟 systemd 爭這個值。寫入失敗時，finally 刪掉留下的暫存檔，函式回傳一條 note，命令列印到 stderr，exit code 照檢查的結果決定（test_unwritable_state_keeps_exit_code）；成功時目錄裡只剩結果檔（test_first_run_writes_only_last_json）。

命令列與 exit code：main

main 是命令列的入口：解析參數、載入清單、執行檢查、印報告與差異、寫結果檔，最後依報告決定 exit code。exit code 的讀法，以及接上排程時為什麼 exit code 不是 0 就要告警，在主機維護清單寫成 TOML：JSON、YAML、TOML 的取捨、TOML 1.0 與 1.1 的版本差異、清單的欄位設計與只讀檢查腳本〈只讀檢查腳本的白名單、輸出、exit code 與結果檔〉；跨主機執行時每台的 exit code 在多台主機維護清單的實作紀錄：在容器上安裝 ansible-core 與 Terraform、由 Terraform 產生 inventory、用 Ansible 的範本部署每台的清單、以 sudo 與 systemd-run 執行檢查腳本，以及清理〈以 -b 與 systemd-run 執行檢查腳本：每台的輸出與 ansible 的 exit code〉。

 1def main(argv: list[str] | None = None, runner: Runner | None = None, out=None) -> int:
 2    out = out or sys.stdout
 3    ap = argparse.ArgumentParser(description="web-demo 主機的只讀維護檢查")
 4    ap.add_argument("--manifest", default=os.path.join(os.path.dirname(os.path.abspath(__file__)), "host.toml"))
 5    ap.add_argument("--phase", choices=PHASES, default="maintain")
 6    ap.add_argument("--state-file", default=DEFAULT_STATE_FILE, metavar="PATH", help=f"結果檔路徑（預設 {DEFAULT_STATE_FILE}）")
 7    ap.add_argument("--no-state", action="store_true", help="不讀也不寫結果檔")
 8    ap.add_argument("--set", action="append", default=[], metavar="NAME=VALUE", help="覆寫 [vars] 的值")
 9    args = ap.parse_args(argv)
10    overrides = {}
11    for s in args.set:
12        k, sep, val = s.partition("=")
13        if not sep:
14            print(f"manifest error: --set 要寫成 NAME=VALUE：{s}", file=sys.stderr)
15            return 2
16        overrides[k] = val
17    try:
18        manifest = load_manifest(args.manifest, overrides)
19    except ManifestError as e:
20        for msg in e.errors:
21            print(f"manifest error: {msg}", file=sys.stderr)
22        print(f"manifest error: {len(e.errors)} 項，沒有執行任何檢查", file=sys.stderr)
23        return 2
24    if hasattr(os, "geteuid") and os.geteuid() != 0:
25        print("note: 不是 root，journal、audit.log 與 collector 的目錄可能讀不到（會印成 WARN）", file=sys.stderr)
26    try:
27        lines = Checker(manifest, runner).run(args.phase)
28    except RuntimeError as e:
29        # validate 已比對過 Checker 會拼的指令，正常路徑不該走到；保險：當格式錯處理。
30        print(f"manifest error: {e}", file=sys.stderr)
31        return 2
32    counts = {"PASS": 0, "WARN": 0, "MANUAL": 0}
33    for ln in lines:
34        counts[ln.status] += 1
35        print(f"{ln.status:<6} {ln.item}  {ln.reason}", file=out)
36    state: dict[str, Any] = {}
37    if not args.no_state:
38        state, note = load_state(args.state_file)
39        if note:
40            print(f"note: {note}", file=sys.stderr)
41        for text in diff_lines(previous_phase(state, args.phase), lines, args.state_file):
42            print(text, file=out)
43    print(f"summary: {counts['PASS']} PASS, {counts['WARN']} WARN, {counts['MANUAL']} MANUAL（phase {args.phase}，{args.manifest}）", file=out)
44    if not args.no_state:
45        phases = dict(state.get("phases", {}))
46        phases[args.phase] = build_record(lines, counts, args.manifest, now_utc())
47        note = write_state(args.state_file, {"format": STATE_FORMAT, "phases": phases})
48        if note:
49            print(f"note: {note}", file=sys.stderr)
50    return 1 if counts["WARN"] else 0
51
52
53if __name__ == "__main__":
54    sys.exit(main())

main 收 argv、runner 與 out 三個參數，單元測試直接呼叫它，傳入假的執行器並把報告寫進記憶體裡的字串，不必另起一個程序。--manifest 的預設是腳本所在目錄的 host.toml，腳本與清單放在同一個目錄時不用帶這個參數。exit 2 的出口有四個：argparse 遇到不認得的參數或不在 PHASES 裡的 --phase（argparse 自己以 2 結束）、--set 沒有寫成 名稱=值、清單格式錯、執行時白名單拒絕了一條指令；前三個出口在任何檢查執行之前，執行時的拒絕發生時，在它之前的指令已經執行過。走到執行時的拒絕時，RuntimeError 從 Checker(...).run 裡丟出來，run 沒有回傳，lines 沒有被設定，所以已經執行過的那些項目，報告行一行都不會印出，stderr 印一行 manifest error: 加上拒絕的理由。清單格式錯時，每一條錯誤印一行 manifest error:，最後一行寫出錯誤的條數與「沒有執行任何檢查」。-h／--help 由 argparse 印出用法之後以 exit 0 結束，一項檢查都不執行，也沒有 summary: 那一行（實跑）；這支腳本裡，exit 0 而沒有 summary: 的只有這一種（讀碼），跟中途中止的 exit 1 分得開。單元測試 test_cli_format_error_exit_2（本篇沒有收錄）把腳本當成獨立的程序執行一份 name = 1 的清單，斷言 exit code 是 2、stderr 有 manifest error。

不是 root 時，main 在 stderr 印一行 note:，不改變 exit code：哪些項目會讀不到，由那幾項自己印成 WARN。報告的順序是每一項一行、差異段、summary: 一行；結果檔在檢查跑完之後才讀，結果檔壞掉不影響檢查本身，寫結果檔排在印出 summary: 之後，寫入失敗時報告已經完整印出。exit code 只看 WARN 的數量，MANUAL 不影響它。if __name__ == "__main__" 讓這個檔案被當成模組載入時（部署時的 validate 只呼叫 load_manifest）不執行檢查。

照這支腳本的做法替自己的主機寫檢查腳本時，程式裡有幾處字串是寫給示範清單那台主機的，要換成自己的環境：

web-demo：docstring 的第一行與 argparse 的 description，寫的是示範主機上的服務名。
collector、audit.log：docstring 的用法說明與只讀保證，以及 main 不是 root 時印的那一行 note:，寫的是示範主機上讀不到的目錄與檔案。
OCI Console、Cloudflare dashboard：docstring 第二段，寫的是示範主機外的確認位置。
dnf-automatic：check_updates 找不到設定檔時印的理由；自動更新用的是別的工具時，REBOOT_REQUIRED_TEXT 與 config_files 的讀法也要一起換。
deploy.sh 不自動重開，排時間 sudo systemctl reboot：check_updates 判定需要重開機時印的理由，deploy.sh 是私有專案部署那台主機的腳本。
/var/lib/host-check/last.json 與 host.toml：DEFAULT_STATE_FILE 是結果檔的預設路徑，--manifest 的預設是腳本所在目錄的 host.toml；路徑換了時，systemd 沙箱的 StateDirectory= 也要跟著換。

host-check.py（3fc41c0）的已知限制與重現方式

這一版的腳本沒有處理的行為，依腳本的結構分成四組：清單的驗證、指令的執行與 exit code、各項檢查、結果檔。每一條寫出觸發條件與結果，括號裡的「實跑」與「讀碼」照開場的定義讀。

實跑的方式以同一個連接埠在兩個位址接聽那一條為例。在放著 host-check.py 的目錄執行下面這段，假的執行器不管收到哪一條指令都回同一份 ss 的輸出；第一行印出兩筆 ('WARN', 'listen-audit/111/tcp')，第二行印出結果檔的 items 只剩一個 listen-audit/111/tcp：

 1python3 - <<'EOF'
 2import importlib.util
 3
 4spec = importlib.util.spec_from_file_location("host_check", "host-check.py")
 5hc = importlib.util.module_from_spec(spec)
 6spec.loader.exec_module(hc)
 7
 8
 9class FakeRunner(hc.Runner):
10    def run(self, command):
11        out = "tcp LISTEN 0 128 0.0.0.0:111 0.0.0.0:*\ntcp LISTEN 0 128 [::]:111 [::]:*\n"
12        return hc.Result(0, out, "")
13
14
15manifest = {"listen_audit": {"protocols": ["tcp"], "allow": []}, "entrypoint": []}
16checker = hc.Checker(manifest, FakeRunner())
17checker.check_entrypoints()
18print([(ln.status, ln.item) for ln in checker.lines])
19print(list(hc.build_record(checker.lines, {}, "m", hc.now_utc())["items"]))
20EOF

例子裡直接組出 Checker 收的 dict，因為 listen_audit 與空的 entrypoint 在 validate 正規化之後，形狀跟 TOML 的寫法相同。其餘段落正規化之後的形狀不同：[[accumulation]] 的 path 變成 paths（一律是串列），[[log]] 多一個 alerts 串列，每一個探針換成 Probe 物件，[[entrypoint.verify]] 在主機上的確認變成帶 probe 鍵的 dict。照 TOML 的欄位名組 dict 交給 check_accumulations，得到 KeyError: 'paths'（實跑）。所以其餘各條的重現，先寫一份 TOML 清單，用 hc.load_manifest(<清單的路徑>) 取得正規化之後的 dict，再交給 hc.Checker、呼叫對應的方法（check_logs、check_updates、check_accumulations、check_entrypoints）；_Validator.probe、load_state、measure_paths、_is_loopback、parse_time 這些函式可以直接呼叫；〈結果檔：壞掉時的其他階段與兩次同時執行〉的那幾條用 hc.main([..., "--state-file", <路徑>], runner=<假的執行器>) 從頭跑。

清單的驗證：不認得的鍵、同時寫 expect_exit 與 ok_exit、expect 的大寫鍵

[updates].expect 的鍵有大寫字母（實跑）：ConfigParser 預設把設定檔裡的鍵轉成小寫，merged 的鍵因此全是小寫；清單的 expect 寫 Upgrade_Type = "security" 時，查 merged.get("Upgrade_Type") 得到 None，那一項永遠印 WARN。實跑時同一份設定檔，expect 的鍵寫 Upgrade_Type 時印 WARN（理由是 Upgrade_Type = None），寫 upgrade_type 時印 PASS。dnf-automatic 的設定檔裡 [commands] 的鍵寫成小寫（upgrade_type、apply_updates），清單照設定檔的寫法寫小寫就不會碰到。
探針同時寫 expect_exit 與 ok_exit（實跑）：validate 不拒絕這種寫法，run_probe 只比 expect_exit，ok_exit 不起作用。實跑時 expect_exit = 0、ok_exit = [0, 1] 的探針沒有任何格式錯，指令以 exit 1 結束時判成不符（理由 exit 1（預期 0））。
validate 不認得的鍵與只在 [[log.alert]] 生效的 measure（實跑）：validate 只讀它認得的鍵，其餘的鍵不報錯、當成沒寫。打錯字的鍵因此安靜地失效：實跑時一個寫了 expect_exit = 0 與 expect_stdot = "x" 的探針沒有任何格式錯，expect_stdout 讀出來是 None，輸出不會被比對；[[accumulation]] 的 missing_okk 照同一個機制被當成沒寫，missing_ok 取預設的 false（讀碼）。measure 與 warn_above 也屬於這一類：它們只在 log 的計數門檻（[[log.alert]]）讀，入口與暫停、恢復步驟的 verify 探針上寫了這兩個欄位、同一個探針又另外寫了別的預期值時，兩個欄位被略過（實跑：measure 讀出來是 None）；只寫 measure 而沒有其他預期值時，判成「探針至少要有一個預期值」的格式錯（實跑）。

指令的執行與 exit code：沒有接住的例外

check_logs 與 Runner.run 沒有接住的例外：兩處的 try 只接幾種指定的例外，沒有列出的例外一路往上，Python 印出 traceback、以 exit 1 結束，stdout 沒有 summary: 那一行。觸發的情形有三種：
- [[log]] 的 source 寫成 file:<目錄>：os.stat 成功，接著 open() 丟出 IsADirectoryError（實跑，從命令列跑整支腳本：exit 1，stdout 沒有 summary:）。
- source 寫成 file:/etc/hosts/x，把一個檔案當成目錄：os.stat 丟出 NotADirectoryError（實跑，呼叫 check_logs）。check_logs 只接 OSError 底下的 FileNotFoundError 與 PermissionError，IsADirectoryError 與 NotADirectoryError 都不是這兩個子類別。
- PATH 上找到的同名檔案沒有執行權限、而 PATH 上沒有另一個可執行的同名檔案：subprocess.run 丟出 PermissionError，Runner.run 只接 FileNotFoundError 與逾時（實跑：PATH 只放一個權限 0644 的 id，Runner().run("id") 丟出 PermissionError）；經由命令列時的 exit 1 是讀碼。
這個 exit 1 跟「至少一項 WARN」的 exit 1 相同，接上排程或告警的程式只看 exit code 時分不出兩者，要再看 stdout 有沒有 summary: 那一行（docstring 寫的「沒有印出 summary 代表腳本中途中止」）。替代的做法是在 main 外面包一層 try／except，把沒有接住的例外改回一個獨立的 exit code，這一版沒有實作。

各項檢查：ss 失敗、重複的項目名、loopback、特殊檔案、稀疏檔案與時間值

updates/config 的項目名重複（實跑）：config_files 裡有一個檔案讀不到或格式錯時，check_updates 先以 updates/config 印一行 WARN，讀完其餘的檔案之後比對 expect，又以同一個項目名印一行。build_record 以項目名當鍵，結果檔只留後一行。實跑時一個沒有段名的設定檔加一個正確的設定檔：報告印 WARN 與 PASS 兩行 updates/config，結果檔裡這一項是 PASS，讀不到設定檔的那一筆 WARN 不在結果檔裡，下一次的差異段也比不到它。
會累積的資料裡的目錄與特殊檔案（實跑）：measure_paths 只把一般檔案算進大小與最舊的修改時間，目錄本身的修改時間不算；socket 與 FIFO 既不算進大小，也不算成讀不到的路徑。實跑時一個只放了一個 FIFO 的目錄，量到的是總大小 0、沒有最舊的時間、讀不到的路徑 0 個；這種目錄設了 retention_days 時，理由印「最舊的檔案：沒有資料」（讀碼）。
全是空洞的稀疏檔案（實跑）：measure_paths 在 st_blocks 是 0 時改用 st_size，整個檔案都是空洞的稀疏檔案因此被算成它的長度，跟用 st_blocks 量磁碟用量的做法相反。實跑時在 macOS 上用 truncate 建一個 10 MiB 的稀疏檔案，st_blocks 是 0，measure_paths 量到 10485760 位元組；檔案只要有一個資料區塊，st_blocks 就不是 0，量到的是佔用的區塊（讀碼）。這個退路的理由原始碼沒有寫，limit_bytes 因此可能被一個沒有佔用磁碟的檔案觸發 WARN。
ss 以非零結束（實跑）：listening_sockets 回 None，主機上的每個入口印「讀不到監聽中的 socket」的 WARN，listen-audit 那一行整個不印。實跑時清單有一個主機上的入口，報告只有那個入口的 WARN；清單沒有 where = "host" 的入口時，報告裡一行跟 ss 有關的都沒有。前一次的結果有 listen-audit 那一項時，這一次的差異段印 GONE listen-audit（讀碼）。
同一個連接埠在兩個位址接聽（實跑）：audit_listening 依協定、位址、連接埠各印一行，項目名只帶連接埠與協定；0.0.0.0:111 與 [::]:111 同時接聽時印兩行 WARN，項目名都是 listen-audit/111/tcp。build_record 以項目名當鍵，結果檔裡只留後一行，實跑時 items 裡只有一個 listen-audit/111/tcp；下一次的差異比的是留下的那一行。
IPv4 對映的 loopback 位址（實跑）：_is_loopback 只認 127. 開頭與 ::1，[::ffff:127.0.0.1] 回 False。一支程式在 IPv6 的 socket 上綁定 ::ffff:127.0.0.1 時，listen-audit 把它當成 loopback 以外的接聽、印成 WARN（讀碼）。
時間值寫成 0 或 n/a（實跑）：parse_time 對單獨的 0 與 n/a 回 None，兩個呼叫端的判法不同。measure 先把空的輸出與 n/a 判成「沒有時間值」，0 不在其中：measure("age_days", "0") 與 measure("age_days", "LastTriggerUSec=0") 都得到「輸出不是時間值」，那一項的理由指向腳本讀不懂格式。check_accumulations 只把空的輸出當成沒有資料：oldest_command 印 n/a 或 0 時，記一條「oldest_command 的輸出不是時間值」、那一項印 WARN，只有空的輸出印 PASS（「最舊一筆：沒有資料」）。重現時呼叫 hc.Checker({}, <假的執行器>).measure("age_days", "0")，或讓假的執行器對 oldest_command 回 n/a，再呼叫 check_accumulations。

結果檔：壞掉時的其他階段與兩次同時執行

結果檔壞掉時，其他階段的紀錄一起消失（實跑）：load_state 讀到不是合法 JSON 的結果檔時回傳空的內容，main 寫回時只帶這一次的階段。實跑時用 hc.main([..., "--state-file", <路徑>, "--phase", <階段>], runner=<假的執行器>) 依序跑 suspend 與 maintain，結果檔的 phases 是 maintain 與 suspend；把結果檔改成一段沒有收尾的 JSON 之後再跑一次 maintain，stderr 印「讀不到或壞掉」的 note:，寫回之後 phases 只剩 maintain。
兩次執行同時寫結果檔（讀碼）：write_state 沒有檔案鎖，兩次同時跑時各自讀到開始時的結果檔，後換名的那一次蓋掉先換名的那一次；兩次跑的是不同的 --phase 時，先寫完的那個階段的紀錄消失。替代的做法是在腳本外面用 flock 這類工具讓兩次執行排隊，這一版沒有實作。