事件說明：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。

讀的順序：先看整批的值決定要不要告警，再看每台的 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：

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

1. 比對主機上的清單：用門檻那一段只對 template 跑的 --check --diff 指令。mh-both1 標成 CHANGED，差異是兩行 -exposure = "private" 換成 +exposure = "admin-only"；mh-web1 是 SUCCESS，範本與主機上的門檻都是 1 TiB。exit code 0。
2. 門檻改回 2 GiB：host_vars/mh-web1.yml 的 min_free_bytes 與註解改回 2147483648 與 2 GiB。
3. 重新部署：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；已經重新部署的話不必跑。
4. 再跑 ./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 與每台的結果：

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

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

• 沙箱有沒有套上：這次的容器 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 一次確認是這次建的目錄。

延伸閱讀：分層與合併的判斷依據、清單的欄位與檢查腳本、Terraform 與 Ansible 的卡

• 多台主機的維護清單：值的分層與合併的位置、用 Ansible 的 inventory 與範本產生每台的清單、由 Terraform 的輸出產生 inventory、跨主機執行的 exit code，以及單台清單的適用範圍：每台相同、依角色不同、每台不同的分類、合併放在部署時的理由、to_json 的跳脫與 YAML 的隱式型別、exit code 2 與 4 的讀法與集中執行的安全代價
• 主機維護清單寫成 TOML：JSON、YAML、TOML 的取捨、TOML 1.0 與 1.1 的版本差異、清單的欄位設計與只讀檢查腳本：清單每一段的欄位、檢查腳本的白名單、systemd-run 各屬性在 Oracle Linux 10 容器上的實測效果與結果檔
• 只讀檢查腳本 host-check.py 的原始碼與逐段說明：選項的切分與各工具的白名單規則、清單的載入與驗證、指令的執行、各項檢查、路徑與時間的量測、結果檔與命令列，以及這一版的已知限制：這篇部署與執行的那支腳本的完整原始碼，load_manifest 的逐欄驗證、summary: 與各個 exit code 的出口、結果檔的寫法，以及 runpy 載入時不執行主程式的條件
• Configuration Management（組態管理）：inventory、群組變數與主機變數各放什麼；同一個變數在幾層都有值時的合併順序，在概念文章〈用 Ansible 的 inventory、群組變數與範本產生每台的清單〉
• State（IaC 狀態檔）：IaC 工具記錄每個納管資源上一次 apply 之後樣貌的快照，以及它的存放位置、加密與鎖機制
• terraform plan / apply：plan 比對 State、雲端現況與設定檔產出差異報告而不改動任何資源，apply 執行那份差異；手改的 inventory 被 plan 判成重新建立的機制，在概念文章〈主機由 Terraform 建立時由它的輸出產生 inventory〉

範圍是一台主機加上它前面的 CDN 與雲端防火牆（主機有好幾台、要依角色分組時，清單的值怎麼分層、怎麼產生每台的清單，在 多台主機的維護清單：值的分層與合併的位置、用 Ansible 的 inventory 與範本產生每台的清單、由 Terraform 的輸出產生 inventory、跨主機執行的 exit code，以及單台清單的適用範圍），例子取自 Oracle Linux 10.2 上跑 nginx 與一個寫 SQLite 的服務的主機；Debian 系發行版與 Docker 的對照寫在各節。Debian 系的套件預設，是在 Debian 12、Debian 13 與 Ubuntu 24.04 的官方容器映像檔裡裝上同名套件之後讀出來的，再拿 Oracle Cloud 上一台 Ubuntu 24.04 的雲端主機對照（預先裝了哪些套件、journal 的目錄、核心更新前後的重開機判斷）；其他業者的映像檔與 Debian 12 的雲端映像檔預先裝了哪些套件，要在主機上用 dpkg -s <套件名> 查。服務要暫停一段時間時的處理在 服務暫停與恢復上線：只停服務、停止主機、終止主機到全部刪除各自保留的資源，暫停期間仍計費與仍被指向的資源，恢復前要查的漂移與恢復的順序，把本篇的項目寫成機器讀得懂的清單在 主機維護清單寫成 TOML：JSON、YAML、TOML 的取捨、TOML 1.0 與 1.1 的版本差異、清單的欄位設計與只讀檢查腳本。

沒有人操作時主機上會改變的狀態

一台主機上線之後，狀態的改變來自主機上一直在寫入的元件，以及主機內外一直在計時的期限。依改變的來源分成四類：

• 會累積的資料：nginx 每處理一個請求就在 access log 寫一行，journald 收下所有 systemd 服務的輸出，dnf 下載套件時留下中繼資料，應用程式寫自己的資料。寫入的元件一直在跑，而刪除舊資料的元件要另外存在。
• 會老化的軟體：已安裝的軟體版本是固定的，而已知漏洞的清單每天增加。同一個 nginx 版本，上線那天沒有已知漏洞，幾週之後可能有。
• 會漂移的入口：安裝一個新套件可能同時帶進一個開始接聽連接埠的服務；有雲端帳號權限的人可以在主控台單獨修改防火牆規則，主機上看不出這個改動。
• 會到期與會改變的外部設定：憑證、網域註冊、雲端 CLI 的登入有期限；管理者家裡的 IP 會被 ISP 重新分配；CDN 業者會增加自己的位址段；免費方案的業者可能回收閒置的主機。

維護就是定期把每一類狀態量一次，跟允許的範圍比對，超出時處理。允許的範圍以一個警戒值為界：警戒值設在真正出事之前，跟出事之間留著處理要花的時間。磁碟的警戒值設在寫滿之前、離寫滿還夠清出空間或擴充磁碟的剩餘空間，憑證的警戒值設在到期之前、離到期還夠續期的天數。量測值超過警戒值的時候還來得及處理；到了真正出事的那一刻之後，後果依項目而定：有的清掉就恢復（套件快取把磁碟用量推過警戒值，清掉之後就回到警戒值以內），有的收不回來（磁碟完全寫滿的那段時間裡，所有寫入者沒寫進去的紀錄；已經被利用的漏洞）。每一類的警戒值設在哪裡、多久量一次，由那一類狀態改變的速度、處理要花的時間，以及越過出事那一刻之後收不收得回來決定，推算的方法寫在〈檢查間隔與哪些項目改成自動處理的推算〉。

會累積的資料：寫入者、清理機制與磁碟寫滿的後果

會累積的資料各自有一個寫入者，而清理機制有三種情形：套件預設就裝好、要自己設定、或根本不存在。盤點時每一項資料寫出寫入者、清理機制與量測方式；清理機制那一格寫不出來的資料，就是要補上清理機制的那一項。

這張表裡的預設值是一台 Oracle Linux 10.2 主機上查到的，換發行版或版本時會不同。查法是讀 /etc/logrotate.d/ 底下對應的檔案、systemd-analyze cat-config systemd/journald.conf（印出主設定檔與全部 .d 目錄合併後的內容）與套件管理器的設定檔；沒有寫在設定檔裡的值，要讀主機上那個版本自己的 man page（man journald.conf），而不是線上最新版的文件。Docker 的 json-file 驅動預設不輪替，這一點寫在 Docker 的文件裡；daemon.json 改了之後，既有的容器不會套用新的設定，要重新建立容器才生效。服務跑在容器裡時，量測的位置也要跟著換：nginx 在容器裡通常把 log 寫到標準輸出，主機上的 /var/log/nginx 量到的是空目錄，這個零不代表 log 很小。

Debian 系的對應預設在 Debian 12、Debian 13 與 Ubuntu 24.04 上相同（logrotate 3.21 與 3.22）：nginx 套件的 logrotate 設定是每天輪替、保留 14 份、壓縮舊檔，輪替之後執行 invoke-rc.d nginx rotate 讓 nginx 重新開檔；/etc/logrotate.conf 的全域預設是每週輪替、保留 4 份，沒有開 dateext，所以輪替出來的檔名是 .1、.2.gz 這種序號，Oracle Linux 10.2 開了 dateext，檔名帶日期。logrotate 由 logrotate.timer 每天觸發；/etc/cron.daily/logrotate 也在，但這支腳本在 /run/systemd/system 存在（systemd 是 init）時直接結束，所以實際執行的只有 timer 那一份。syslog 檔案那一列要先確認 rsyslog 在不在：這三個容器裝了 systemd、logrotate、nginx、unattended-upgrades 與 needrestart 之後都沒有 rsyslog，/var/log/auth.log、/var/log/syslog 也就不存在。

journald 的紀錄存在記憶體還是磁碟

journald 的紀錄存在磁碟還是記憶體，由 Storage 決定，這個預設值正好是線上文件與主機不一致的例子：systemd 最新版的文件寫的預設是 persistent，而 Oracle Linux 10.2 的 systemd 257 預設是 auto，/var/log/journal 目錄存在時才寫到磁碟。兩種狀態的結果不同：

• /var/log/journal 存在，或設定了 Storage=persistent：紀錄寫在磁碟上，跨得過重開機；上限由 SystemMaxUse（預設檔案系統大小的 10%）與 SystemKeepFree（預設保留 15%）決定。
• 兩者都沒有：紀錄只存在 /run 底下的記憶體裡，每次重開機就清空；上限改由 RuntimeMaxUse 與 RuntimeKeepFree 依 /run 的大小計算。重開機之前的 sshd 失敗登入、自動更新的執行結果，在 journal 裡都查不到，只剩 rsyslog 轉出的 /var/log/secure 與 /var/log/messages。主機重開過機、journalctl --list-boots 卻只列出一次開機，或 /var/log/journal 不存在，就代表主機處在這個狀態；上線之後還沒重開過機的主機，紀錄存在磁碟上時同樣只列出一次開機，所以只看開機次數分不出兩種狀態。

上面兩組上限各自另有 4G 的上限，算出來超過 4G 時以 4G 為準。Oracle Cloud 的 Oracle Linux 10.2 映像檔處在紀錄只存在記憶體的那一種狀態；在 /etc/systemd/journald.conf.d/ 放一個寫了 Storage=persistent 的設定檔並重啟 systemd-journald 之後，那台主機的 journalctl --list-boots 在下一次重開機後列出兩次開機。

Debian 系的預設落在另一種狀態：Debian 12、Debian 13 與 Ubuntu 24.04 的 systemd 套件（252、257、255）在安裝時由套件的 postinst 腳本建立 /var/log/journal，Storage 同樣是預設的 auto，所以紀錄寫在磁碟上、跨得過重開機。雲端映像檔在 Oracle Cloud 的 Ubuntu 24.04 映像檔（2026 年 9 月的版本）上確認過：第一次開機之後 ls -ld /var/log/journal 印出 drwxr-sr-x+ root systemd-journal，目錄與裡面的 journal 檔（-rw-r-----+ root systemd-journal）已經套好群組與 ACL，只屬於 systemd-journal 群組的系統帳號跑 journalctl -n 1 以 exit 0 讀得到，不必另外處理；這個映像檔同時預先裝了 rsyslog，/var/log/syslog 與 /var/log/auth.log 另外有一份。Debian 12 的雲端映像檔沒有確認，ls -ld /var/log/journal 查得到。

磁碟寫滿時各寫入者的反應

磁碟寫滿時，每個寫入者都會寫入失敗，而失敗之後的反應依元件的設計分成三種，外面看得到的程度不同：

• 寫入失敗時繼續服務：nginx 寫不進 log 時照樣回應一般的請求，套件管理器下載更新失敗時，已經在執行的服務照樣跑在舊版本上。從主機外面看不出變化，代價是這段時間的紀錄缺掉、安全更新沒有套用。例外是要寫暫存檔的請求：request body 超過 nginx 的 client_body_buffer_size（預設 8k 或 16k）時，nginx 把 body 寫進暫存檔，上游的回應超過 proxy 的 buffer 時也一樣，這兩種請求在磁碟寫滿時會失敗，外面看得到錯誤。
• 寫入失敗時回錯誤：應用程式寫資料庫失敗時，多半對送資料進來的請求回 5xx。外面看得到錯誤率上升，而那段時間收到的資料遺失。
• 寫入失敗時停止：部分資料庫在交易紀錄寫不進去時會停止服務以保護資料（PostgreSQL 的 WAL 寫入失敗是這一種）。服務整個停掉，外面看得到，恢復要先清出空間再重啟。

繼續服務的那一種，大部分請求在外面沒有徵兆，只有在主機上量磁碟用量才看得到；回錯誤與停止的兩種雖然看得到，看到的時候資料已經遺失或服務已經停了。這是磁碟用量要在寫滿之前定期量、而不是等出錯時才看的原因。

對外寫入端點的增長速度

應用程式的資料是這幾項裡，增長速度最受外部請求影響的一項：access log 每個請求只多一行，而接受外部寫入的端點（收事件、收表單、收上傳），每個請求可以寫進一整個 request body。這一項的允許範圍要用最壞情況算，而最壞情況取決於端點前面有什麼樣的速率限制：

• 有全域的速率限制（整個端點共用一個計數，nginx 以 $server_name 這類固定值當 limit_req_zone 的鍵）：全域速率與 body 上限的乘積就是寫進應用程式資料的上限。例如每秒 20 次、每次最多 64 KB，每秒約 1.3 MB，一天約 110 GB。
• 只有以來源位址為鍵的速率限制（$binary_remote_addr、或 CDN 後面以 CF-Connecting-IP 為鍵）：每個來源各自計數，上限還要乘上來源的數量，而來源的數量由送請求的人控制，所以算不出一個可以拿來跟磁碟比的上限。例如一個收前端事件的端點只依來源 IP 限流，一個爬蟲從上千個雲端位址各送幾個請求時，每個來源都在自己的限額內，access log 裡代表速率限制拒絕的狀態碼一直是零（nginx 預設回 503，示範主機的設定檔用 limit_req_status 429 改成 429），磁碟照樣在增長。以 CF-Connecting-IP 為鍵還有一個前提：源站只接受 CDN 送來的連線，否則這個標頭可以由請求的人自己填，每次換一個值就繞過計數。
• 完全沒有速率限制：跟上一種相同，沒有可以比的上限。
• 只在私有網路裡、來源數量固定（例如只有公司 VPN 內的幾台機器會送）：上限是來源數乘上每個來源的速率，再乘上 body 上限。

算出來的上限只算了 request body；落到磁碟的量還要加上儲存層的放大（資料庫的索引、交易紀錄、應用程式自己的轉換），實際的倍數要用一批真實的請求量一次才知道。拿這個上限跟剩下的磁碟空間比，算得出最壞情況多久會寫滿：剩 15 GB、每秒寫入 1.3 MB 時，只算 body 大約 3 小時，加上放大會更短。這個時間比人的檢查間隔短時，保留期限、配額或容量隔離要由應用程式或作業系統自己執行，或在端點前面加上全域的速率限制，不能靠定期檢查。

全域的速率限制只限制寫進應用程式資料的量，限制不了 log 的量：被拒絕的請求照樣在 access log 寫一行，nginx 的 limit_req 預設在 error 等級替每一次拒絕再記一行（limit_req_log_level 預設 error）。送進來的請求越多，這兩份 log 寫得越快，寫入量由送請求的人決定；每秒上萬個被拒絕的請求，log 的寫入速度可以超過上面算出的資料上限，而 logrotate 一天才輪替一次。所以大量的請求要在 CDN 這一層就擋掉（CDN 的速率限制規則），或把這個端點的拒絕紀錄調低等級、不寫 access log，並另外設一條磁碟剩餘空間的告警。

清理的動作要分開判斷：log 與快取有現成的輪替機制，清掉的是已經過了保留期限的資料；應用程式的資料，以及事後要拿來跟 CDN 的事件紀錄逐筆比對請求來源的 access log（CDN 的每一筆事件帶著請求編號，源站的 access log 記下同一個編號），則可能是之後要查證的材料，保留多久是業務的決定（要回頭查多久以前的事件），磁碟只決定能存多少。所以維護時量測可以每次都做，刪除要依每一項事先定好的保留期限做。

定期讀的 log：每一份要看的欄位與它代表的狀態

自動告警針對的是事先知道的壞狀態（服務沒有回應、錯誤率超過門檻）；定期讀 log 處理的是另外兩件事：確認部署時的假設仍然成立，以及發現還沒有被寫成告警的新模式。一份 log 適合哪一種，看它的欄位在正常狀態下的值能否預測：能預測的，偏離就代表某個假設失效；不能預測的，讀的目的是找出值得寫成告警的模式。

各列的紀錄去哪裡讀：

• sshd：RHEL 系的 unit 是 sshd.service、Debian 系是 ssh.service，名稱用 systemctl list-units '*ssh*' 查；unit 名稱寫錯時 journalctl -u 的輸出也是零，所以零要搭配確認 unit 名稱存在才算數。journal 不保留到重開機之後的主機，讀 rsyslog 寫的 /var/log/secure（RHEL 系）或 /var/log/auth.log（Debian 系，有裝 rsyslog 時才有這個檔案）。
• 強制存取控制：SELinux 用 ausearch -m AVC；Debian 系的 AppArmor 在核心 log 裡找 apparmor="DENIED"。
• 自動更新：journalctl -u dnf-automatic.service 與 dnf history；journal 不保留時讀 /var/log/messages。Debian 系的 unattended-upgrades 寫在 /var/log/unattended-upgrades/。
• 重啟計數：systemctl show -p NRestarts <unit>。

sshd 與強制存取控制這兩列的正常值都是零，偏離零就可以直接寫成告警的條件；access log 的分布要跟前一次比較才看得出變化，所以每一次讀到的數字要存下來，下一次才有比較的基準。這些數字存在哪裡是另一個要決定的事：存在維護的紀錄裡、或讓檢查腳本把每次的計數寫到它自己的結果檔，跟描述「要檢查什麼」的清單分開放。

對外入口：主機上的接聽程式與每一層防火牆的放行範圍

一個入口要從外面連得進來，得同時滿足兩個條件：主機上有程式在接聽那個位址與連接埠，而且請求經過的每一層都放行它。常見的層有雲端的網路安全規則（Oracle Cloud 的 NSG 與 security list、AWS 的 security group，見 Security Group）、主機的防火牆（firewalld、ufw、nftables）、服務自己的限制（只綁 loopback、systemd 的 IPAddressDeny），以及反向代理的路由（只把某些路徑轉給後端）。每一層都可以被單獨修改，所以盤點時兩個方向都要量：

• 從主機裡面量接聽的程式：ss -lntup 列出每一個在接聽的 TCP（-t）與 UDP（-u）位址、連接埠與程序（-p，要 root 才看得到其他使用者的程序）。只寫 -t 的話，UDP 的接聽程式不在輸出裡。拿這份清單跟部署時預期的清單比，多出來的接聽程式，用 ss 印出的程序名找到執行檔路徑，再以 rpm -qf <路徑>（Debian 系是 dpkg -S <路徑>）查是哪個套件帶進來的。例如 Oracle Cloud 的 Oracle Linux 10.2 映像檔預設啟用 rpcbind（RPC 服務的連接埠對應程式，TCP 與 UDP 111）與效能監測套件 PCP（4330、44321），都在所有介面上接聽；停用並遮蔽（systemctl disable --now 加 mask）之後，那台主機上這三個連接埠不再接聽。主機跑 Docker 時，ss 印出的程序是 docker-proxy，查到的套件是 Docker 本身，真正開這個入口的是某一個容器，要用 docker ps 的連接埠欄位對照；Docker 發佈的連接埠繞過 ufw 的規則（Docker 的文件寫明封包在 ufw 的規則套用之前就被轉送），在 firewalld 上也不受一般 zone 的規則約束（Docker 另建 docker zone 與從任何 zone 轉發進來的 policy；Docker 的文件只寫了這組設定，「一般 zone 的規則管不到」是從它推出、在連結那一篇實測過的），封包路徑與限制的寫法見 CDN 後面的源站主機防火牆：只放行 CDN 來源的位置與套用時機、Docker 發佈連接埠的封包路徑、出站 DNS 的限制與地理封鎖〈Docker 發佈的連接埠：封包路徑與限制的寫法〉。
• 從主機外面量連得到的入口：從另一台機器對公開 IP 逐一連線。只從主機裡面量看不到雲端那一層；只從外面量時，結果只代表量測那台機器的來源位址，管理入口只放行管理者 IP 時，從管理者的電腦量連得到是預期的，要換一個不在放行清單裡的來源才量得到別人看到的結果。UDP 沒有連線，nc -u -z 沒有收到拒絕就回報成功，量 UDP 要送一個那個服務會回應的請求（RPC 用 rpcinfo -u <IP> 100000），看有沒有回應。

入口依用途分成四類，各自要收窄到的範圍不同：

• 業務入口（網站的 80、443，API 的連接埠）：它是服務本身，要收窄的是來源與路徑。前面有 CDN 時，只放行 CDN 的位址段（下面這一節寫它的限制）；服務只給私有網路用時（公司 VPN 內的 API），只放行那個網段；反向代理只轉發對外需要的路徑與方法。
• 沒有業務用途的接聽程式：它不服務任何使用者，卻讓那個程式的漏洞多一條從外面利用的路徑，只要某一層防火牆被放寬就會暴露；停用它不影響任何使用者，所以停用並移除。
• 管理入口（SSH、資料庫、管理後台）：它必須存在，而每個能連到它的來源都是一個可以嘗試登入的對象；只放行管理者的來源位址，把能嘗試的對象縮到管理者自己，或改成不開入站連接埠的做法（雲端業者的跳板主機服務 bastion，見 Bastion Host（跳板機）；從主機往外建立的 tunnel，見 Outbound Tunnel），代價是管理者 IP 改變時要更新規則或通道。管理後台跟業務共用同一個連接埠時（WordPress 的 /wp-admin、/wp-login.php 跑在 443 上），443 要對所有訪客開（前面有 CDN 時是對 CDN 的位址段開），雲端防火牆分不出路徑，收窄只能放在反向代理：依路徑只放行管理者 IP，或把後台改成只經 SSH 通道連得到。前面有 CDN 時，反向代理看到的來源位址是 CDN 的位址，依 IP 放行之前要先用 nginx 的 realip 模組從 CF-Connecting-IP 取回訪客的位址，而且 set_real_ip_from 只列 CDN 的位址段，否則這個標頭可以由請求的人自己填（從 realip 的機制推論，沒有實測）。各種做法的取捨與救援入口見 伺服器管理通道的設計：網路可達性、通道授權、主機登入驗證三層的做法與選擇，以及救援入口。
• 只給同一台主機用的入口：應用程式內部的連接埠、查詢與管理用的 API，只有主機上的反向代理需要連它；綁在 loopback、反向代理只轉發對外需要的路徑與方法之後，外面的請求沒有路徑可以到達它。

主機前面有 CDN 時，只放行 CDN 的位址段，確認的是請求經過了那家 CDN，不確認經過的是自己的 CDN 帳號：任何人都可以在自己的 CDN 帳號把網域指到這台主機的 IP，請求同樣從 CDN 的位址段進來，而自己帳號裡的 WAF 與 bot 規則管不到這些請求。維護時讀 access log 的 Host 標頭看得到這類繞過；在連線層擋下它，要讓源站驗證只屬於自己帳號的憑證，或改成源站不開入站連接埠的 tunnel，兩種做法的機制與 Cloudflare 上的設定差異見 CDN 後面的源站主機防火牆：只放行 CDN 來源的位置與套用時機、Docker 發佈連接埠的封包路徑、出站 DNS 的限制與地理封鎖〈限制放在哪一層：雲端防火牆、主機防火牆與 CDN 端的驗證〉。

會老化的軟體：各條更新管道與更新後的重開機

安全更新的維護包含兩件獨立的事：把更新裝上去，以及讓更新後的程式碼實際開始執行。兩件事都要依軟體是從哪一條管道裝上去的來判斷，因為每一條管道由不同的機制更新，主人得知有修補的方式與能不能交給排程也各不相同：

• 發行版套件庫裡的套件（nginx、OpenSSH、核心、函式庫）：修補由發行版發佈，套件管理器讀得到；可以交給排程自動套用，下面寫它的設定。
• 第三方套件庫的套件（nginx.org 的官方套件庫、docker-ce 這類）：一樣由套件管理器更新，但要看那個套件庫有沒有發佈安全公告；只裝安全更新的設定依公告的類型挑套件，沒有發佈公告的套件庫，裡面的套件不會被挑到（從 dnf 依 updateinfo 公告篩選的機制推論，沒有實測）。dnf-automatic 的 upgrade_type 對整台主機生效，沒有逐一套件庫的設定，要對單一套件庫套用全部的更新，就另寫一個 systemd timer 執行 dnf repository-packages <套件庫> upgrade：它只升級那個套件庫的套件，相依的套件仍從全部套件庫取；dnf upgrade --repo=<套件庫> 會停用其他套件庫，新版本多了其他套件庫的相依套件時解析不到。在 Oracle Linux 10.2 的容器（dnf 4.20）用一個自建的本機套件庫實測：主機裝著 demo-1，套件庫裡的 demo-2 多了一個要從發行版套件庫取的相依套件 jq；dnf upgrade --repo=localdemo 以 nothing provides jq needed by demo-2-1.noarch from localdemo 失敗，dnf repository-packages localdemo upgrade 只升級 demo，jq 與它的相依套件從 ol10_baseos_latest 一起裝上。相依套件都已經裝好時（nginx.org 套件庫的 nginx 從 1.30.2 升到 1.30.6），兩條指令的結果相同；Debian 系在 unattended-upgrades 的 Origins-Pattern 加上這個來源。
• 容器映像檔裡的軟體：主機的套件管理器管不到。修補要等上游的映像檔發新版，得知的方式是上游的發佈通知或映像檔的漏洞掃描工具；重新拉取、重新建立容器可以排程，代價是沒有人在場時換了版本，所以多半在維護時段做。
• 應用程式自己的更新機制（WordPress 的核心與外掛這類 CMS）：由應用程式自己的更新功能處理，主機的排程碰不到。看應用程式有沒有自動更新的設定（WordPress 的外掛可以逐個開自動更新）；沒開的，列進維護時段。
• 自己建置的程式（自己編譯的 Go、Rust 程式）：依賴的函式庫或語言的標準函式庫有漏洞時，要重新建置、重新部署才修得到。得知的方式是對依賴跑語言的漏洞掃描工具（Go 的 govulncheck），掃描可以排程，重建與部署多半由人在維護時段做。govulncheck ./... 只回報程式碼實際呼叫得到的漏洞，找到時 exit code 是 3，沒有時是 0（govulncheck 1.1.3 對一個依賴 golang.org/x/text v0.3.5 的程式實測，升到 v0.21.0 之後變成 0），所以排程的 timer 可以直接依 exit code 決定要不要告警。
• 從上游下載的預先建置檔案（官方發佈頁下載的二進位檔、curl | sh 裝的工具）：沒有任何套件管理器記得它裝過，要人去換；得知的方式是訂閱上游的發佈通知，並把它列進清單，否則它會一直停在安裝那天的版本。

容器映像檔的漏洞掃描排程時，要讀的是掃描工具的 exit code，而它的預設跟 govulncheck 不同。以 trivy 0.57.1（官方映像檔 aquasec/trivy:0.57.1）實測：

1trivy image --download-db-only                                     # 只下載漏洞資料庫，獨立成一次執行
2trivy image --skip-db-update --exit-code 7 <映像檔>                # 有漏洞回 7、沒有回 0、掃描失敗回 1
3trivy image --skip-db-update --exit-code 7 --exit-on-eol 5 <映像檔> # 映像檔的發行版已經 EOL 時回 5

• exit code 的讀法：不帶 --exit-code 時，找到漏洞照樣回 0（一個 2023 年 6 月的 Debian 12 映像檔掃出 371 個漏洞，exit 0），所以排程一定要帶這個參數。掃描本身失敗（映像檔名稱打錯、逾時、離線抓不到映像檔、資料庫下載失敗）一律回 1，不受 --exit-code 影響；--exit-code 設成 1 時，「找到漏洞」與「沒有掃成」都是 1，timer 分不開，所以設成 1 以外的值；上面的 7 與 5 是這次挑的值，跟排程裡其他會用到的 exit code 不重複就可以。--severity HIGH,CRITICAL 與 --ignore-unfixed 只縮小計數，篩完還有漏洞時一樣回那個值。
• 已經 EOL 的映像檔：發行版過了支援期限時，資料庫裡不再有它的新漏洞，trivy 掃出 0 個、回 0，只在 stderr 印兩行 WARN：This OS version is no longer supported by the distribution 與 The vulnerability detection may be insufficient because security updates are not provided（alpine 3.15 實測）。exit 0 在這裡看起來跟乾淨一樣，帶 --exit-on-eol <值> 才變成一個看得到的 exit code。
• 資料庫：壓縮檔約 130 MiB，解開後的 trivy.db 約 1.6 GB（1,637,429,248 位元組），放在快取目錄（預設 /root/.cache/trivy）的 db/。--timeout（--help 印出的預設是 5m0s）的倒數包含下載資料庫的時間：快取是空的時，設 30 秒的那一次照樣下載了約 2 分鐘，跑完才以 context deadline exceeded 失敗，下載的內容沒有留下。資料庫已在本機時，一次掃描的時間主要花在從 registry 拉映像檔的 layer 與分析（一個 Debian 映像檔約 40 到 50 秒，layer 已在快取時幾秒）。所以下載資料庫與掃描分成兩次執行，各自有自己的逾時。
• 資料庫的新舊與更新失敗：0.57.1 帶 --skip-db-update、用過期的資料庫掃描時（快取的 metadata.json 把 UpdatedAt 改成一年多前）不印任何警告，結果照常輸出，資料庫的新舊要由排程自己讀 metadata.json 的 UpdatedAt。分成兩次執行之後，掃描仍然會被更新的失敗拖累：離線時 --download-db-only 失敗，trivy 刪掉 metadata.json（trivy.db 留著）；連網而逾時失敗，整個 db/ 目錄都被刪掉。兩種情形之後帶 --skip-db-update 的掃描都以 The first run cannot skip downloading DB 失敗、回 1，跟其他掃描失敗分不開。所以更新那一次的 exit 1 本身要告警；在更新之前備份 metadata.json、失敗後放回去，離線那一種掃描就恢復正常（實測），逾時那一種要整個 db/ 一起備份。另一種寫法是把更新下載到另一個快取目錄（--cache-dir），成功之後才換掉掃描用的那一份，這個寫法沒有實跑。
• 掃本機才有的映像檔：trivy 跑在容器裡時讀不到主機的映像檔，有兩種給法：把主機的 /var/run/docker.sock 掛進去，或在主機上 docker save -o <檔名>.tar <映像檔> 再用 trivy image --input 讀那個檔。兩種掃出的結果相同；掛 docker.sock 等於把主機 Docker daemon 的完整控制權交給這個容器（能啟動特權容器、掛主機的根目錄），docker save 那一種容器只拿到一個以 :ro 掛進去的檔案，代價是每次掃描前要重新匯出一次。

發行版套件庫這一條可以交給排程。Oracle Linux 與 RHEL 系由 dnf-automatic.timer 定期觸發 dnf-automatic，它讀 /etc/dnf/automatic.conf 的兩個鍵：upgrade_type 決定裝哪一類更新（security 只裝安全更新），apply_updates 決定下載之後要不要安裝（預設 no 只下載）。timer 沒有啟用時，設定檔改了也不會執行；systemctl list-timers dnf-automatic.timer 列得出下一次執行的時間，才代表排程在跑。

Debian 系用 unattended-upgrades，排程由兩個 timer 分工：apt-daily.timer（每天 6 點與 18 點，加最多 12 小時的隨機延遲）更新套件清單，apt-daily-upgrade.timer（每天 6 點，加最多 60 分鐘）執行安裝；要不要安裝由 /etc/apt/apt.conf.d/20auto-upgrades 的 APT::Periodic::Unattended-Upgrade 決定，非互動安裝這個套件時，它的值預設是 "1"（套件的 debconf 問題 enable_auto_updates 預設 true）。裝哪些來源的更新寫在 /etc/apt/apt.conf.d/50unattended-upgrades，兩家的預設不同：Debian 12 與 13 的 Origins-Pattern 除了 label=Debian-Security 的兩筆，還有 label=Debian 那一筆，也就是穩定版的點版本更新（point release）同樣自動套用；Ubuntu 24.04 的 Allowed-Origins 是發行時的版本、-security 與兩個 ESM 的安全來源，不含 -updates，自動套用的只有安全更新。以上是三個發行版的容器裡裝上 unattended-upgrades 2.9 到 2.12 之後讀出的值；Oracle Cloud 的 Ubuntu 24.04 映像檔預先裝了 unattended-upgrades 與 needrestart，20auto-upgrades 的兩個值與 Allowed-Origins 的來源跟容器裡讀出的相同，兩個 timer 都是 enabled。

雲端映像檔是某一天建的，主機第一次開機時就已經落後：上面那個映像檔開機之後有 60 個來自 -security 的更新待裝，其中包括核心。手動觸發一次 unattended-upgrade（apt-daily-upgrade.timer 啟動的 apt.systemd.daily install 呼叫的也是它）花了 402 秒，升級了 64 個套件，其中包括新核心；裝完之後還有 18 個可以更新的套件，全部來自 -updates，照預設沒有裝。所以新建的主機在第一次排程執行之前，要先手動跑一次更新並重開機，否則從開機到排程第一次執行之間，映像檔建立之後公開的漏洞都還在。排程裝得到更新的前提是主機連得到套件來源：同一台主機放在只接了 Oracle 服務網路出口（service gateway）的私有子網路時，apt-get update 以 connect (101: Network is unreachable) 與連線逾時失敗；這個子網路加上 NAT gateway、主機放行出站的 80 與 443 之後，同一條指令從 ports.ubuntu.com 取得了套件清單，所以 Ubuntu 的套件來源在 Oracle 的服務網路之外。排程在這種主機上照常觸發而裝不到任何套件（從 apt-get update 的失敗推論，沒有等 timer 觸發實測），讀它的執行紀錄才看得出來。錯誤原文、成因與加出站的指令在 Oracle Cloud 私有子網路 Ubuntu 主機的實測紀錄：套件來源的出站（NAT gateway、路由與 NSG）、序列主控台的連線，以及被回收之後的重建〈只接 service gateway 的私有子網路：apt 連到套件來源時的錯誤原文與成因〉與〈加出站：NAT gateway、路由規則與只掛在這台主機上的 NSG〉。

這裡有兩個獨立的選擇：

• 要不要讓排程自動套用：自動套用時，一個漏洞從修補發佈到這台主機套用，最多隔一個排程的間隔；不自動套用時，這段時間等於兩次人工更新之間的間隔，那段時間裡公開的漏洞在這台主機上都還在。
• 只裝安全更新，還是連一般更新一起裝：安全更新多半是把修補移植回目前的版本，變更的範圍小，改變服務行為的機會比一般更新小，適合在沒有人看著的時候自動套用。只裝安全更新時，一般更新會長期落後，之後整批升級時一次跨過的版本差距大，那一次要安排在有人在場的維護時段做。

套件庫的設定決定自動更新拿得到什麼：有些發行版的套件庫鎖在固定的版本，自動更新只會在那個版本裡更新，拿不到之後發佈的修補。Amazon Linux 2023 預設把套件庫鎖在建立那個 AMI 時的版本，要用 dnf upgrade --releasever=<版本> 才換到新版本的套件庫（AWS 文件〈Deterministic upgrades through versioned repositories on AL2023〉，沒有實測）。發行版本身過了支援期限（EOL）之後，套件庫不再發佈安全更新，排程照常執行而什麼都裝不到；EOL 的判斷與升級的做法見 OS 與基礎軟體更換〈EOL 風險評估〉。確認自動更新實際裝了套件，讀它的執行紀錄（〈定期讀的 log〉表格的自動更新那一列）。

裝上去的更新要等使用它的程序重新啟動才生效：已經在執行的程序把舊版的函式庫留在記憶體裡，核心更新要重開機才換成新核心。needs-restarting（Oracle Linux 10.2 由 yum-utils 套件提供）回報兩件事：-r 回報需不需要重開機，-s 列出用到了已更新函式庫、重啟就能生效的服務。只有函式庫更新時，重啟 -s 列出的服務就夠，不必重開機。核心更新要重開機時，可以交給 dnf-automatic 自己（automatic.conf 的 reboot 鍵：never、when-changed、when-needed），或另寫一個在維護時段執行的 systemd timer，依 needs-restarting -r 的結果決定要不要重開。

Debian 系把這兩件事分給兩個機制：

• 需不需要重開機：看 /var/run/reboot-required 存不存在，需要重開機的套件名寫在 /var/run/reboot-required.pkgs。這個檔案由核心套件安裝後執行的 /etc/kernel/postinst.d/ 底下的腳本建立，在 Debian 12 與 13 上，那支腳本屬於 unattended-upgrades 套件，沒裝這個套件的主機，核心更新之後這個檔案不會出現，它不存在不代表不需要重開；Ubuntu 24.04 的 /etc/kernel/postinst.d/ 底下另有一支 update-notifier，dpkg -S 查得到它與登入訊息（motd）的 /etc/update-motd.d/98-reboot-required 都屬於 update-notifier-common。在 Oracle Cloud 的 Ubuntu 24.04 主機上，unattended-upgrade 裝完新核心之後，/var/run/reboot-required 的內容是 *** System restart required ***，.pkgs 列出新核心的套件與 linux-base，重開機之後兩個檔案都不在了；兩支腳本都裝著，所以這次分不出是哪一支建的，登入訊息也沒有實際看過。
• 哪些服務要重啟：needrestart 套件在每次 apt 安裝之後（/etc/apt/apt.conf.d/99needrestart 的 hook）檢查用到舊函式庫的服務；needrestart -b 用批次格式印出結果，NEEDRESTART-SVC 每行一個要重啟的服務，NEEDRESTART-KSTA 是核心的狀態（依 needrestart 的說明：1 沒有待生效的核心，2 與 3 有新核心等重開機，0 是判斷不出來）。容器裡跑 needrestart -b 時核心屬於宿主，KSTA 印出 0，其他值要在主機上才看得到。在 Oracle Cloud 的 Ubuntu 24.04 主機上量了三個時間點：開機時 1；unattended-upgrade 裝了下一個主要版本的核心之後是 3，NEEDRESTART-KCUR 是執行中的舊核心、NEEDRESTART-KEXP 是新裝的核心，同一次另外印出 dbus.service、systemd-logind.service 與 unattended-upgrades.service 三行 NEEDRESTART-SVC；重開機之後回到 1，KCUR 與 KEXP 相同。2（新核心與執行中的核心 ABI 相容）這次沒有遇到。

unattended-upgrades 自己重開機的設定是 50unattended-upgrades 裡的 Unattended-Upgrade::Automatic-Reboot，預設 "false"；改成 "true" 時，安裝完成而 reboot-required 存在，它就在 Automatic-Reboot-Time 指定的時間重開；這個鍵的預設是 "now"，也就是安裝一完成就立刻重開，設定檔裡被註解掉的 "02:00" 是範例值，要固定在維護時段重開就得自己寫上時間（這是設定檔註解寫的行為，容器裡沒有實際重開機）。

是否讓它自動重開，取決於兩個條件：重開機之後服務會不會自己回來，以及服務沒回來時有沒有人知道。

• 服務會不會自己回來：看服務的 unit 是否 enabled（systemctl is-enabled <unit>）、容器的 restart policy、主機防火牆的規則是不是寫進了永久設定；最可靠的確認是在有人在場的維護時段手動重開一次。例如服務當初是在終端機裡手動啟動、一直沒有寫成 systemd unit，平常主機一直開著所以看不出來，排程在凌晨重開機之後服務就不在了。服務不會自己回來時，先把它改成會自己回來（enable unit、設 restart policy），再看下一個條件。這個條件跟更新無關也成立：主機因為停電或業者的硬體維護重開時，結果相同。
• 服務沒回來時有沒有人知道：要有一個跑在這台主機以外的觀察者（另一台主機上的外部探測、或心跳監看：主機定期送訊號、停送時由外部服務告警），以及告警實際送得到人；跑在同一台主機上的監控，重開機時跟著停掉，報不出這台主機沒回來。外部探測的位置與判讀見 4.28 單台主機的監控盲區與失效域以外的觀察者：主機停機、使用者路徑中斷與告警鏈中斷，心跳監看與外部探測各自回答的問題與位置，以及與內部探測並排的判讀〈頻外訊號：心跳監看與外部探測〉。

兩個條件都成立時，讓它在固定時段自動重開，代價是每次一段可預期的停機，服務沒回來時探測會叫人；新核心開不了機時，修復要從雲端業者的序列主控台進去，停機的長度就不再可預期，自動重開機的時段要選在救援得到的時候。序列主控台要在出事之前準備好三件事：帳號或主機層級已經啟用（部分業者要事先開啟）、有一個能在主控台登入的方式（雲端映像檔的使用者通常只有金鑰、沒有密碼）、開機選單（GRUB）選得回上一版核心；這幾件沒準備好時，救援只剩業者的救援開機，或把磁碟掛到另一台主機上修。三家業者文件寫的預設如下，Oracle Cloud 與 Google Cloud 實際連過，AWS 只取自文件：

• AWS：帳號層級預設不允許使用序列主控台，要在每個區域分別開啟，使用者另外要有 ec2-instance-connect:SendSerialConsoleSSHPublicKey 的 IAM 權限；連得上之後要登入作業系統，主機上得有一個設了密碼的使用者，而 AWS 提供的 AMI 預設沒有，要事先在每台主機用 passwd 設好（AWS 文件〈Configure access to the EC2 Serial Console〉）。
• Google Cloud：互動式的序列埠存取預設關閉，在專案或主機的中繼資料設 serial-port-enable 為 TRUE 才開；連線用 SSH 金鑰驗證，出現登入提示時要本機使用者的密碼，Google 提供的 Linux 映像檔預設不允許密碼登入，要事先用 sudo passwd 或開機腳本設好（Google Cloud 文件〈Troubleshooting using the serial console〉）。在 Debian 12 的 VM 上先建一個設了密碼的救援帳號、再開啟序列埠登入的完整步驟與實測，在 GCP VM 的 SSH 與 RDP 改走 IAP 的實測紀錄：盤點、救援入口、IAP 規則與 IAM、停用舊規則驗證、OS Login 啟用與移除外部 IP〈準備救援入口：Serial Console 與本機救援帳號〉。
• Oracle Cloud：要先替主機建立一個序列主控台連線（instance console connection），上傳一把 RSA 公鑰，經由 SSH 連進去；只看開機輸出不必登入，要登入作業系統時，Oracle Cloud 不替 opc 使用者設預設密碼，要事先替它或另一個使用者設好（Oracle Cloud 文件〈Instance Console Connections〉）。在一台 Ubuntu 24.04 的 A1 主機上實際連過：oci compute instance-console-connection create 帶 RSA 公鑰建立連線，CLI 給的連線字串是一條經由 443 埠跳板的 ssh 指令；連上之後讓主機重開機，看得到 UEFI 韌體的輸出、核心開機訊息，開機後約 27 秒在 ttyAMA0 印出登入提示，所以只看開機過程（核心卡在哪一步）時不必登入。這台主機的 ubuntu 使用者，passwd -S ubuntu 印出的狀態是 L（密碼鎖定），這次也沒有替任何使用者設密碼，所以登入那一步沒有做。金鑰、建立連線的指令與 ProxyJump 的設定檔寫在 Oracle Cloud 私有子網路 Ubuntu 主機的實測紀錄：套件來源的出站（NAT gateway、路由與 NSG）、序列主控台的連線，以及被回收之後的重建〈序列主控台：RSA 金鑰、建立連線、ProxyJump 設定與看到的開機輸出〉。

三家的共同點是登入作業系統要密碼，而雲端映像檔的使用者預設只有金鑰，所以「能登入」這一件要在主機正常時先做；設了密碼的使用者也讓經由 SSH 以外的登入多了一條路，密碼的強度與只在主控台使用的限制（例如 sshd 設成不接受密碼登入）要一起決定。

觀察者還沒有時，先加上它，外部探測與心跳監看都有免費的服務。暫時加不了時，不自動重開機，主機處在「更新已裝、但核心的修補還沒生效」的狀態，直到有人安排重開為止；這段時間要被看見，所以把 needs-restarting -r 的結果寫進人會讀的位置：登入時顯示的訊息（motd），或維護時段讀的檢查報告（例如清單裡的一項 WARN），讓它在下一次登入或維護時被看到。

會到期與會改變的外部設定

這一類狀態的期限多半在主機外面，主機上的檢查量不到，要從持有那個期限的地方查：

• 憑證：公開憑證靠自動續期（ACME 協定，見 ACME Automation），要確認的是續期的排程實際成功，以及續期的時機依效期的比例計算，而不是寫死的天數。效期正在縮短：Let’s Encrypt 公告從 2027 年 2 月 10 日起預設簽發 64 天的憑證、2028 年再縮到 45 天，並建議把寫死「簽發後第 N 天續期」的排程改成在效期約三分之二時續期，或改用支援 ACME Renewal Info（ARI）的客戶端，由 CA 通知續期時間（Let’s Encrypt 的公告）；cron、包裝腳本與操作手冊裡寫死的天數，在效期縮短之後會讓憑證在續期之前就過期。CDN 邊緣的憑證由 CDN 管。
• 源站給 CDN 用的自簽憑證：效期由產生它的人決定；CDN 的 SSL 模式只加密、不驗證源站憑證時（Cloudflare 的 Full），這張自簽憑證過期也不會讓連線失敗，所以它過期了也沒有人會發現。要改成驗證源站憑證的模式（Full (strict)）時，先把這張自簽憑證換成 CDN 驗得過的憑證（公開 CA 簽發的，或 CDN 業者發給源站用的憑證），否則一切換所有請求都會失敗。
• 網域註冊：到期之後網域可能被別人註冊，所有指向它的紀錄跟著失效，而且收不回來；在註冊商那邊開自動續約，另設一條到期前的告警確認續約成功（付款方式過期時，自動續約會失敗）。
• 雲端 CLI 的登入：session token 這類短效期的登入過期之後，維護用的指令全部失敗，主機本身不受影響；它影響的是維護的人能否從開發機執行雲端 CLI 的指令。
• 管理者的 IP：雲端防火牆只放行管理者 IP 時，ISP 重新分配了那個 IP，管理者就連不進來；舊的 IP 被分配給別人時，放行規則變成放行了一個陌生人。換 IP 之後要同時改 SSH 與 bastion 的放行來源。
• CDN 的位址段：源站只放行 CDN 位址段時，CDN 新增的位址段不在放行清單裡，從那些位址回源的請求會連線失敗，訪客看到 CDN 的錯誤頁；CDN 業者公布位址段的清單（Cloudflare 的 ips-v4 與 ips-v6），定期拿它跟防火牆規則比對。取回清單、比對與套用時的陷阱見 CDN 後面的源站主機防火牆：只放行 CDN 來源的位置與套用時機、Docker 發佈連接埠的封包路徑、出站 DNS 的限制與地理封鎖〈只放行 CDN 位址的套用時機、範圍與清單的維護〉。
• 免費額度的閒置回收：免費方案的業者可能回收長期閒置的主機，Oracle Cloud 寫出了判定閒置的使用率門檻，規則的出處與三家業者的比較見 雲端免費額度與小型主機的收費比較：試用金與固定額度、計費單位、區域限制、試用結束後的處置、出站流量與查價項目〈出站流量與閒置回收〉。一台大部分時間沒有流量的實驗機會落在這個條件裡；前面有 CDN 的靜態網站也是，請求多半由 CDN 的快取回應，源站本身的使用率很低。被回收之後是停止還是刪除，官方沒有寫，在容量常常不足的機型上（Oracle Cloud 的 A1），被回收之後不一定建得回來，所以這一項歸在收不回來的那一類：主機上的資料要另外備份到主機以外，並確認照 repo 重建得出同樣的服務。回收在哪一刻發生沒有變化速度可算，備份多久做一次因此不由檢查間隔決定，而由能接受遺失多久的資料決定（RPO）：資料庫用它自己的匯出工具（PostgreSQL 的 pg_dump、SQLite 的 .backup）排程，備份送到主機以外，並定期還原一次確認可用。

這一類裡，到期時間可以預先查到的（憑證、網域、token），適合寫成到期前的自動告警，設計見 4.0.1 監控鏈事前偵測不到的異常：業務結果、資料正確性、到期事件、排程與背景工作、備份、安全、第三方依賴與成本的監看；改變時間無法預知的（管理者 IP、CDN 位址段、業者的回收），要靠定期比對與事先的備份。

檢查間隔與哪些項目改成自動處理的推算

每一類狀態的檢查間隔，從三個量推出來：警戒值（〈沒有人操作時主機上會改變的狀態〉定義的那個界線）設在哪裡、量測值從現在的值變化到警戒值要多久，以及到了真正出事的那一刻之後收不收得回來。

警戒值設在哪裡：從出事的那一刻往回，留出處理期間最壞會增長的量（處理要花的時間乘上最壞的增長速度；清 log 幾分鐘，擴磁碟或搬資料要三天），再加上量測的誤差，警戒值就設在那個位置。處理時間只在設警戒值的時候算一次，之後的間隔推算不再扣它。

到達警戒值的時間：量測值從現在的值變化到警戒值要花的時間，下文寫成 T。用兩次量測的差除以兩次之間的天數得到變化速度，再拿現在的值到警戒值的距離除以速度。有四種情形拿不到穩定的速度：

• 第一次盤點時只有一次量測：現值已經接近或超過警戒值的，當場處理；其餘的隔一小段時間（例如隔天）量第二次，拿到速度再算。
• 有輪替的資料（log）：用量是鋸齒形，兩次量測之間剛好輪替過時差是零或負數。改成比較相鄰兩個輪替週期裡的最高值，差除以週期的長度得到速度；保留份數固定的 log，保留滿之後總量停在份數乘上每份的大小，之後的增長只來自流量變多。
• 增長由外部請求決定（上面的寫入端點）：兩次量測之間的速度不代表下一段時間的速度，改用最壞情況的速度。
• 改變是步階變化：量測值在某一刻一次就從一個值變成另一個值、之後停在新值，中間沒有過渡值（Step Change（步階變化）），相對的是上面幾種逐步累積的變化。例如有人在主控台把 SSH 的放行來源從管理者 IP 改成 0.0.0.0/0，規則在送出的那一刻就從只放行管理者變成對所有人開放；新套件帶進一個在所有介面上接聽的服務、CDN 新增一個位址段、管理者 IP 被 ISP 重新分配，也都是這一種。兩次量測之間看不到任何接近警戒值的過程，到達警戒值的時間是零，下面的公式算不出間隔，處理方式另列在分類裡。同一個量也可能兩種形態都有：磁碟用量平常逐步累積，有人一次複製進一個大檔案時就是步階變化；這一次的增加由下面收不回來那一類的剩餘空間告警發現，不靠檢查間隔。

檢查間隔：間隔為 I 時，漏掉一次檢查，下一次量測落在 2I，要在量測值超過警戒值之前量到，I 要小於 T 的一半。本篇取 T 的三分之一：漏掉一次檢查時，下一次量測落在 T 的三分之二，離到達警戒值還剩三分之一的 T，留給量測的波動與沒預料到的突增；這個比例是作者訂的安全係數，量測的波動大時取得更短。例如剩下 15 GB、log 與資料每天增加 50 MB、擴磁碟要三天：三天的增長只有 150 MB，警戒值取在剩 3 GB 的位置，比三天的增長量大得多，多出來的部分給突增；到達警戒值約 240 天，間隔可以到 80 天，每月量一次就在範圍內。這個間隔管的是這些資料的增長速度；檔案系統完全寫滿屬於收不回來的那一類，剩餘空間另外照下面的分類設一條告警。同一台主機的寫入端點在最壞情況下約 3 小時就寫滿，沒有任何人的檢查間隔來得及。

維護節奏通常是先決定好的（每週或每月一次的維護時段），而不是每一項各自算出來的。每一項算出來的間隔跟這個節奏比：算出的間隔不短於維護節奏的，併進同一次維護；算出的間隔比維護節奏短的，有兩條路：另排一個比節奏短的排程檢查（例如每週執行一次只讀檢查，結果送到下一段說的接收端），或交給機制自動處理。到達警戒值的時間短於任何排程間隔時（寫入端點在最壞情況下約 3 小時就寫滿，到達警戒值還更早），只剩機制這一條路。

這幾條都要有人收到結果，而「收到」包含兩件事，各自的條件不同：

• 主機還在運作時才會發生的狀態（檔案系統的剩餘空間、寫成告警的 log 計數，例如 sshd 的失敗登入、憑證效期；主機開著而某個服務沒有起來也屬於這一種）：告警可以由主機上的程式發出（例如同一台主機上的 Prometheus 與 Alertmanager），條件是送達的管道在主機以外（推播服務、郵件）。
• 主機整台停止、或重開機之後主機本身沒有回來（連不上、作業系統沒有開起來）：主機上的程式跟著停掉，要由跑在主機以外的觀察者發現：外部探測，或心跳監看（主機上的程式定期送訊號，例如 Prometheus 一條一直處在觸發狀態的告警，外部服務在訊號停止時叫人，見 Dead Man’s Switch）。

兩者都沒有時，告警等於沒有寫，這些項目的實際間隔就是人登入主機的間隔；建一個最小的接收端（送達管道在主機以外的推播通知，加上外部的心跳或探測服務）是比這一節任何一項都先做的事。由這幾個量，每一項的處理方式如下：

• 越過之後收不回來（安全漏洞被利用、檔案系統寫滿期間所有寫入者沒寫進去的紀錄、被回收的免費主機、到期被別人註冊的網域）：已經發生的入侵與已經遺失的紀錄沒有辦法收回，所以不等檢查間隔，優先自動化：安全更新依〈會老化的軟體〉的各條管道處理，能排程的交給排程，不能排程的列進維護時段並寫明多久查一次，需要重開機才生效的部分照那一節的條件；檔案系統的剩餘空間是全部寫入者共用的資源，一律寫成告警；網域開自動續約；會被回收的主機，資料依 RPO 定期備份到主機以外。
• 改變是步階變化：比對的間隔不能超過維護的人能接受改變後的狀態持續的最長時間，不由維護節奏決定：每天比對一次，一條被放寬的規則最多開著一天才被發現。這個長度依暴露之後被利用的代價訂，直接把管理入口或資料庫開到外面的，比對要比只會讓部分回源失敗的更密，能在變更發生的當下收到事件（雲端的稽核紀錄、設定變更的通知）就更好。會造成對外暴露的（防火牆規則被放寬、新的接聽程式）與會讓回源失敗的（CDN 新增的位址段），交給定期比對的排程：主機上的接聽清單與暫停前或部署時的清單比、從另一台機器量公開 IP 上連得到的入口、拿 CDN 公布的位址段跟放行規則比，結果送到接收端。管理者 IP 被重新分配時，管理者下一次連線就發現自己連不進去，而舊的 IP 可能已經分給別人、放行規則對陌生人開著 SSH 的連線（登入仍要金鑰），所以發現的那一次就同時把 SSH 與 bastion 的放行來源改成新的 IP；別處有沒有寫死舊 IP（監控的放行來源、維護文件），這一項的確認併進維護時段。
• 到達警戒值的時間比維護節奏短（對外寫入端點造成的資料增長）：維護時段來不及在量測值超過警戒值之前量到，超過的那一刻沒有人在場，所以這一類交給機制自動處理（應用程式的保留期限與配額、容量隔離、全域的速率限制），或另排比節奏短的排程檢查；短於任何排程間隔時只剩機制。維護時段量的是那個機制還在不在運作。
• 期限可以預先查到（憑證、token）：到期日是已知的，等人想起來查才發現就太晚，寫成到期前的告警，維護時段確認告警還設著。
• 算出的間隔不短於維護節奏，而且越過之後收得回來（套件快取、暫存檔、有輪替機制的 log 這些個別的寫入者）：個別的寫入者超過自己的警戒值，只是佔掉較多的空間，清掉就回到警戒值以內；收不回來的是整個檔案系統寫滿，那由全部寫入者一起造成，已經由收不回來那一類的剩餘空間告警處理。所以這一類在維護時段量測與清理，量的目的是找出是誰在長、長多快，交給人判讀的好處是看得到成長的趨勢與原因。

同一個項目同時符合幾種時，照上面的順序取第一個符合的：收不回來優先於步階變化，步階變化優先於到達警戒值比維護節奏快，到達警戒值比維護節奏快優先於期限可預知，期限可預知優先於留給維護時段。哪些項目適合寫成告警、哪些留給人定期讀，在有人值班、每天接班檢查的團隊裡另有一套判斷，見 4.29 值班的例行檢查：接班檢查與每週營運會議讀的訊號、交班紀錄的內容，以及例行檢查項目改寫成告警規則的條件〈例行檢查項目改寫成告警規則的條件〉；本篇的節奏是一個人每週或每月的維護時段，所以留給人的項目只放變化慢的那些。

接手或第一次盤點一台已經上線的主機

接手別人留下的主機、或第一次替自己的主機做盤點時，處理的順序依〈檢查間隔與哪些項目改成自動處理的推算〉的分類，以及每一步要用到的輸入，排成下面的順序：告警的接收端排在最前面，因為後面每一項寫成告警或排程比對的處置，都要靠它把結果送到人手上；接著只讀不改地記下主機的原狀，因為下一步要依這份清單判斷哪些接聽程式該停，而改動之前記下的才是前任留下的原狀；然後處理每多拖一天就多一天收不回的暴露或紀錄；最後量出之後計算變化速度要用的基準值。

• 先建告警的接收端：送達管道在主機以外的推播通知，加上外部的探測或心跳服務。
• 只讀地記下原狀：從主機裡面列出接聽程式與各層的放行範圍（ss -lntup、主機防火牆的規則、雲端規則的匯出，跑 Docker 時加上 docker ps 的連接埠欄位），從另一台機器量公開 IP 上連得到的入口。沒有 repo 時，同一步把設定複製出來收進 repo：docker-compose.yml 與它引用的 .env、/etc/docker/daemon.json、正在跑的映像檔的 tag 或 digest（compose 寫 latest 時，重建會換成另一個版本）、反向代理的設定、systemd unit。之後停錯一個前任的服務時，這一份就是對照還原的依據，重建驗證與恢復時的比對也以它為基準。
• 處理收不回來的暴露與紀錄：依記下原狀時列出的接聽清單與從外面量到的入口（前任開著對外的資料庫或管理後台時，它正是每拖一天就多一天暴露的項目），停用沒有業務用途的接聽程式、把管理入口收窄到管理者；依〈會老化的軟體〉的各條更新管道，列出這台主機上的軟體各自由什麼更新，能排程的排程，不能排程的列進維護時段並寫明多久查一次；journal 改存到磁碟，之後的紀錄才留得下來；設檔案系統剩餘空間的告警；網域開自動續約；資料依 RPO 備份到主機以外。
• 量出基準值：處理完暴露之後，重新列一次接聽程式與各層的放行範圍，記成之後排程比對的基準；會累積的資料各自的大小與清理機制、各份 log 的計數，在接手當天量一次、隔一小段時間再量一次，作為之後計算變化速度與比較的起點。

清單裡每一項要寫出量測的指令與允許的範圍，主機維護清單寫成 TOML：JSON、YAML、TOML 的取捨、TOML 1.0 與 1.1 的版本差異、清單的欄位設計與只讀檢查腳本 用一台實際的主機示範這份清單的欄位設計與只讀的檢查腳本；主機要暫停一段時間時，這些狀態在暫停期間繼續改變，恢復上線時要查哪幾項，寫在 服務暫停與恢復上線：只停服務、停止主機、終止主機到全部刪除各自保留的資源，暫停期間仍計費與仍被指向的資源，恢復前要查的漂移與恢復的順序。

事件說明：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 <unit> 回 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__