跳到主內容

【PowerDNS】Lua Records

這是一份 PowerDNS 官方文件的完整中文翻譯。
它說明了 LUA Record（Lua 動態記錄） 的用途、語法、應用範例、進階用法與安全注意事項。
我保留了原文段落結構與技術名詞，方便你比對。

🧩 PowerDNS — Lua Records 中文說明文件

一、概述

為了提供動態行為（例如全球負載平衡 Global Server Load Balancing），
PowerDNS Authoritative Server 自 4.2 版起 支援 動態 DNS 記錄（LUA Records）。

這些記錄中包含了小段設定程式（Lua 程式碼），
可根據「查詢者 IP」、「EDNS Client Subnet」、「伺服器可用性」等因素，
動態決定要回應哪個 IP 或 CNAME。

功能範圍從簡單到複雜，
可實現多池（multi-pool）地理與權重負載平衡（Geo & Weighted Load Balancing）。

雖然使用者不必了解內部原理，
但 PowerDNS 的動態記錄本質上是 嵌入在 DNS 內的小型 Lua 腳本。

💡 注意：
這是 PowerDNS 專屬功能，目前尚未成為 IETF 或其他標準機構的標準。
PowerDNS 官方承諾會致力於互通性，並希望最終能成為被廣泛支持的標準。

要啟用此功能，可在設定檔中加入：

enable-lua-records=yes

或對單一 zone 設定 metadata：

ENABLE-LUA-RECORDS=1

若要使用地理位置功能，請確認 launch 設定中包含：

launch=gpgsql,geoip

⚠️ 警告：
使用 AXFR 傳輸包含長 Lua 記錄的 zone 時，請確保每筆記錄內容（TXT 型態傳輸）
不超過 255 bytes。超過時會被分割成多段，導致次伺服器解析錯誤。

二、範例說明

1️⃣ ifportup()

www IN LUA A "ifportup(443, {'192.0.2.1', '192.0.2.2'})"

這會讓 www 這個名稱隨機回應 192.0.2.1 或 192.0.2.2，
前提是這些 IP 的 TCP 443 port 是開放的。

若其中一個 IP 不再回應 443，則僅回傳另一個。
若全部都不通，則全部地址會被回傳。

多組 IP 可分優先層級，例如：

www IN LUA A "ifportup(443, {{'192.0.2.1', '192.0.2.2'}, {'192.0.3.1'}})"

這表示：

  • 若第一組中的任一 IP 可用 → 回第一組；

  • 否則 → 試第二組。

因為 DNS 查詢要求極快回應，PowerDNS 不會即時檢查連線狀態，
而是由背景程序定期檢測這些 IP 是否可用。

2️⃣ pickclosest()

www IN LUA A "pickclosest({'192.0.2.1','192.0.2.2','198.51.100.1'})"

這會根據查詢者的地理位置（GeoIP），
選擇最靠近使用者的 IP 回覆。

也可以與 ifportup() 結合：

www IN LUA A ("ifportup(443, {'192.0.2.1', '192.0.2.2', '198.51.100.1'}, {selector='pickclosest'})")

這會在可用的 IP 中挑出距離使用者最近的一個。

3️⃣ 複雜 Lua 程式碼範例

www IN LUA A ";if country('US') then return {'192.0.2.1','192.0.2.2','198.51.100.1'} else return '192.0.2.2' end"

可同時回傳單一字串或多筆字串（array）。

4️⃣ 使用 qname 的例子

*.example.net 10 IN LUA TXT "; return 'Got a TXT query for ' .. qname:toString() .. '; First label is: ' .. qname:getRawLabels()[1]"

注意：qtype 無法從 Lua 內直接取得（它是固定的）。
可使用預設變數（Preset Variables）取得其他查詢相關資訊。

三、在 SQL 後端使用 Lua Records

LUA Records 可與一般的 gmysql / gpgsql 通用 SQL 後端一起使用。

由於內容同時包含單引號與雙引號，
在 INSERT 或 UPDATE 時需特別轉義。

範例如下：

-- 建立 zone
INSERT INTO domains (id, name, type) VALUES (1, 'example.com', 'NATIVE');

-- 啟用 Lua 記錄功能
INSERT INTO domainmetadata (domain_id, kind, content)
VALUES (1, 'ENABLE-LUA-RECORDS', 1);

-- 建立 pickclosest() 記錄
INSERT INTO records (domain_id, name, type, content, ttl)
VALUES (
  1,
  'www.example.com',
  'LUA',
  'A "pickclosest({''192.0.2.1'',''192.0.2.2'',''198.51.100.1''})"',
  600
);

這三筆 SQL：

  • 建立 example.com zone，

  • 啟用 Lua Records，

  • 新增一筆 www.example.com 的動態 A 記錄。

四、LUA Record 格式

💡 名稱由來：
“Lua” 在葡萄牙文中意為「月亮」，不是縮寫。
但 DNS 慣例記錄類型一律大寫，因此用 LUA。

一筆 LUA Record 結構如下：

LUA <query_type> <Lua 程式>

例如：

www IN LUA A "pickclosest({'1.1.1.1','8.8.8.8'})"

  • 可設定 TTL，PowerDNS 會照常套用；

  • 可被 DNSSEC 簽章（需在同一伺服器即時簽署）。

五、更強大的範例

west IN LUA A ("ifurlup('https://www.lua.org/', {{'192.0.2.1', '192.0.2.2'}, {'198.51.100.1'}}, {stringmatch='Programming in Lua'})")

這會：

  • 嘗試對 www.lua.org 發出 HTTPS；

  • 若回應內容包含 Programming in Lua，則視為可用；

  • 第一組 IP 可用 → 回第一組；否則 → 回第二組。

與地理導向結合：

www IN LUA CNAME (";if(continent('EU')) then return 'west.powerdns.org' else return 'usa.powerdns.org' end")

對應的 usa 名稱配置如下：

usa IN LUA A ("ifurlup('https://www.lua.org/', {{'198.51.100.1'}, {'192.0.2.1', '192.0.2.2'}}, {stringmatch='Programming in Lua'})")

歐洲以外的訪客會優先使用 198.51.100.1，
若失效則回到 192.0.2.1 / 192.0.2.2。

六、進階主題

(1) 語法模式

若記錄內容未以 ; 開頭，PDNS 會自動加上 return。
若要撰寫完整 Lua 腳本，請以分號 ; 開頭。

(2) 可引用其他記錄的設定

可用 include() 引用共用設定：

config IN LUA LUA ("settings={stringmatch='Programming in Lua'} EUips={'192.0.2.1','192.0.2.2'} USAips={'198.51.100.1'}")

usa IN LUA A (";include('config') return ifurlup('https://www.lua.org/', {USAips, EUips}, settings)")
west IN LUA A (";include('config') return ifurlup('https://www.lua.org/', {EUips, USAips}, settings)")

七、安全與同步機制

  • LUA Record 是查詢時即時生成；

  • 可透過 AXFR 同步至其他 PDNS 伺服器；

  • 但無法直接查詢（防止外部洩露負載邏輯）。

⚠️ 警告：

  • 絕對不要從不信任的來源匯入含 LUA Record 的 zone！
    惡意 Lua 可能導致伺服器崩潰甚至被接管。

  • 即使是可信來源也請使用 TSIG 保護 AXFR 傳輸。

若有 DNSSEC 簽章需求，
LUA Record 必須由主伺服器即時簽署（無法預先簽署 zone）。

八、共享 Lua 狀態模式（shared mode）

預設情況下，PDNS 每次查詢都會建立新的 Lua 執行環境。
這樣每筆 LUA Record 彼此獨立，不會污染變數。
但建立 Lua state 很耗時。

可啟用共用模式：

enable-lua-records=shared

  • 每個執行緒建立一個 Lua 狀態並重複使用；

  • 約可提升 QPS 10 倍；

  • 各執行緒 Lua 環境獨立（UDP 為多實例，TCP 共用一個）。

九、Reference（函式與物件類別）

PowerDNS 提供的 Lua 內建 API 包含：

預設變數（Preset Variables）

  • qname, qtype, remoteip, ednssubnet 等

可用函式

  • getdns(), ifportup(), pickclosest(), country(), continent()

  • ifurlup(), include(), pdnslog(), 等

物件類別

  • DNSName, ComboAddress, DNSResourceRecord, DNSHeader, QType

  • Netmask, ComboAddressSet, DNSRecord, 及輔助函式群組

（這些內容在官方文件的「LUA Reference」章節中詳細列出）

🔚 總結

功能 說明
LUA Record PowerDNS 內建的動態 DNS 回覆機制
語言 Lua
用途 智能選址、健康檢查、地理導向、服務偵測
啟用方式 enable-lua-records=yes 或 ENABLE-LUA-RECORDS=1
安全性 僅限信任 zone；建議使用 TSIG
效能優化 enable-lua-records=shared 可大幅提高 QPS

是否要我幫你把這篇翻譯版整理成 可直接放進公司內部 Wiki 的 Markdown 版（含語法高亮與範例區塊）？
我可以自動加上標題層級、代碼框、注意區塊與翻譯對照欄位。

回到頂端