# 【PowerDns】pdnsutil 速查表 OK！下面幫你把 **pdnsutil 常用指令** 與 **PowerDNS Authoritative REST API** 的核心用法，整理成一份實用速查表（適用你現在的 SQLite 後端設定）。指令預設在伺服器上執行，API 範例用 `curl`。 --- # pdnsutil 速查表 > 小重點：`pdnsutil` 會用 `/etc/powerdns/pdns.conf` 的後端設定（像你現在的 `gsqlite3-database=/var/lib/powerdns/pdns.db`）。一般情況**不需要**在指令後面再帶資料庫連線字串。 ## 區域（Zone）管理 ```bash # 建立 Zone（會自動產生 SOA/NS） pdnsutil create-zone example.com ns1.example.com # 列出所有 Zone pdnsutil list-all-zones # 查看某個 Zone 內容 pdnsutil list-zone example.com # 刪除 Zone（不可逆） pdnsutil delete-zone example.com # 升版本（序號 +1；SOA serial） pdnsutil increase-serial example.com # 變更 Zone 類型（Native/Master/Slave） pdnsutil set-kind example.com Native pdnsutil set-kind example.com Master pdnsutil set-kind example.com Slave ``` ## 紀錄（RRsets）管理 ```bash # 新增一筆紀錄 pdnsutil add-record example.com www A 300 203.0.113.10 # 取代整個 RRset（同名同型別的多筆紀錄一次重設） pdnsutil replace-rrset example.com www A "300" "203.0.113.10" "203.0.113.11" # 刪除整個 RRset pdnsutil delete-rrset example.com www A # 設定單筆紀錄 TTL（或用 replace-rrset 一次調整） pdnsutil set-ttl example.com www A 600 ``` ## 主從複寫（AXFR）與通知 ```bash # 設定 Master 的來源 IP（Slave/Native 也可設） pdnsutil set-masters example.com 10.0.0.10 10.0.0.11 # 設定通知對象（NOTIFY 將發送給這些 IP） pdnsutil set-notify example.com 10.0.0.20 10.0.0.21 # 手動觸發 NOTIFY pdnsutil notify example.com # 加入 supermaster（供 Slave 自動加入） pdnsutil add-supermaster 10.0.0.10 ns1.example.com accountA pdnsutil list-supermasters pdnsutil delete-supermaster 10.0.0.10 ``` ## 檢查、調整與匯入/匯出 ```bash # 檢查 Zone 合法性（語法/權威性/必要紀錄） pdnsutil check-zone example.com # 調整/整齊化紀錄（例如 DNSSEC/NSEC3 相關或大小寫等） pdnsutil rectify-zone example.com # 從 zonefile 匯入 pdnsutil load-zone example.com /path/to/zonefile # 匯出為 zonefile（BIND 格式） pdnsutil export-zone example.com /tmp/example.com.zone ``` ## Meta 與額外屬性 ```bash # 設/查/清除 Zone meta（AXFR 策略、SOA 編輯模式等） pdnsutil set-meta example.com SOA-EDIT-API INCEPTION-INCREMENT pdnsutil get-meta example.com pdnsutil clear-meta example.com SOA-EDIT-API ``` ## DNSSEC（若需要） ```bash # 以「API 模式」啟用 DNSSEC（變更由 API/工具觸發會自動調整 serial） pdnsutil secure-zone --api example.com # 建/列/刪 key pdnsutil add-zone-key example.com ksk active rsasha256 2048 pdnsutil list-keys example.com pdnsutil remove-zone-key example.com # NSEC3 啟用/調整 pdnsutil set-nsec3 example.com "1 0 10 abcd1234" # 參數: flags optout iterations salt pdnsutil unset-nsec3 example.com # 關閉 DNSSEC（謹慎！） pdnsutil disable-dnssec example.com ``` --- # PowerDNS Authoritative REST API 速查 ## 啟用 API（pdns.conf） 你已經啟用，重點如下： ```ini api=yes api-key=你的長隨機字串 webserver=yes webserver-address=0.0.0.0 webserver-port=8081 webserver-allow-from=0.0.0.0/0 # 建議上線時限縮來源段 ``` > 變更後 `systemctl restart pdns`。呼叫 API 時請加 Header：`X-API-Key: <你的key>` 基底 URL 一般是： ``` http://:8081/api/v1 ``` 伺服器 ID 預設是 `localhost`： ``` /api/v1/servers/localhost/... ``` ## 範例：列出 Zone ```bash curl -s -H 'X-API-Key: ' \ http://127.0.0.1:8081/api/v1/servers/localhost/zones ``` ## 建立 Zone（POST /zones） ```bash curl -s -X POST -H 'X-API-Key: ' -H 'Content-Type: application/json' \ -d '{ "name": "example.com.", "kind": "Native", // 也可 "Master" 或 "Slave" "masters": [], // Slave 時填 Master IP 列表 "nameservers": ["ns1.example.com.", "ns2.example.com."], "soa_edit_api": "INCEPTION-INCREMENT", "rrsets": [ // 可選：同時帶入初始 RRsets { "name": "www.example.com.", "type": "A", "ttl": 300, "changetype": "REPLACE", "records": [ {"content": "203.0.113.10", "disabled": false} ] } ] }' \ http://127.0.0.1:8081/api/v1/servers/localhost/zones ``` ## 修改/新增/刪除 RRsets（PATCH /zones/{zone}） > 用 `changetype: REPLACE` 或 `DELETE`。`name` 要以「**尾巴有點**」的 FQDN。 ```bash curl -s -X PATCH -H 'X-API-Key: ' -H 'Content-Type: application/json' \ -d '{ "rrsets": [ { "name": "www.example.com.", "type": "A", "ttl": 300, "changetype": "REPLACE", "records": [ {"content": "203.0.113.10", "disabled": false}, {"content": "203.0.113.11", "disabled": false} ] }, { "name": "old.example.com.", "type": "A", "changetype": "DELETE", "records": [] } ] }' \ http://127.0.0.1:8081/api/v1/servers/localhost/zones/example.com. ``` ## 讀取 Zone（GET /zones/{zone}） ```bash curl -s -H 'X-API-Key: ' \ http://127.0.0.1:8081/api/v1/servers/localhost/zones/example.com. ``` ## 重新整理/通知 - 重新檢查/AXFR（Slave 取主檔）：`/zones/{zone}/axfr-retrieve`（POST） - 發送 NOTIFY：`/zones/{zone}/notify`（POST） ```bash # 例：觸發 NOTIFY curl -s -X POST -H 'X-API-Key: ' \ http://127.0.0.1:8081/api/v1/servers/localhost/zones/example.com./notify ``` ## 統計 & 健康 ```bash # 伺服器資訊 curl -s -H 'X-API-Key: ' \ http://127.0.0.1:8081/api/v1/servers # 統計值（QPS、響應碼等） curl -s -H 'X-API-Key: ' \ http://127.0.0.1:8081/api/v1/servers/localhost/statistics ``` ## 清快取（Authoritative 有限；常見在 Recursor） Authoritative 的 cache 能力有限；若啟用 packet/negcache，可用： ```bash curl -s -X PUT -H 'X-API-Key: ' \ http://127.0.0.1:8081/api/v1/servers/localhost/cache/flush ``` --- # 常見實務小提醒 - 你把服務綁在 `local-port=54`，本機測試 `dig` 要記得 `-p 54`。 - API 的 `name`、`nameservers`、`zone` **FQDN 都要以 `.` 結尾**（PDNS API 慣例）。 - `webserver-allow-from=0.0.0.0/0` 方便測試，但上線環境務必限縮來源段或套防火牆。 - 改 RRsets 後若 `SOA-EDIT-API` 有設會自動處理 serial；否則記得用 `increase-serial`。 - 若搭配 Recursor/外層 dnsdist，有時 Authoritative 的變更需要幾秒才被上層 cache 反映。 ---