跳到主內容

【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)管理

# 建立 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)管理

# 新增一筆紀錄
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)與通知

# 設定 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

檢查、調整與匯入/匯出

# 檢查 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 與額外屬性

# 設/查/清除 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(若需要)

# 以「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 <keyid>

# 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)

你已經啟用,重點如下:

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://<host>:8081/api/v1

伺服器 ID 預設是 localhost

/api/v1/servers/localhost/...

範例:列出 Zone

curl -s -H 'X-API-Key: <APIKEY>' \
  http://127.0.0.1:8081/api/v1/servers/localhost/zones

建立 Zone(POST /zones)

curl -s -X POST -H 'X-API-Key: <APIKEY>' -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: REPLACEDELETEname 要以「尾巴有點」的 FQDN。

curl -s -X PATCH -H 'X-API-Key: <APIKEY>' -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})

curl -s -H 'X-API-Key: <APIKEY>' \
  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)

# 例:觸發 NOTIFY
curl -s -X POST -H 'X-API-Key: <APIKEY>' \
  http://127.0.0.1:8081/api/v1/servers/localhost/zones/example.com./notify

統計 & 健康

# 伺服器資訊
curl -s -H 'X-API-Key: <APIKEY>' \
  http://127.0.0.1:8081/api/v1/servers

# 統計值(QPS、響應碼等)
curl -s -H 'X-API-Key: <APIKEY>' \
  http://127.0.0.1:8081/api/v1/servers/localhost/statistics

清快取(Authoritative 有限;常見在 Recursor)

Authoritative 的 cache 能力有限;若啟用 packet/negcache,可用:

curl -s -X PUT -H 'X-API-Key: <APIKEY>' \
  http://127.0.0.1:8081/api/v1/servers/localhost/cache/flush

常見實務小提醒

  • 你把服務綁在 local-port=54,本機測試 dig 要記得 -p 54

  • API 的 namenameserverszone FQDN 都要以 . 結尾(PDNS API 慣例)。

  • webserver-allow-from=0.0.0.0/0 方便測試,但上線環境務必限縮來源段或套防火牆。

  • 改 RRsets 後若 SOA-EDIT-API 有設會自動處理 serial;否則記得用 increase-serial

  • 若搭配 Recursor/外層 dnsdist,有時 Authoritative 的變更需要幾秒才被上層 cache 反映。