2. 安裝

emfor 用 Cargo 從原始碼建置。Linux 與 FreeBSD 是部署平台;macOS 可用於開發。

什麼東西裝在哪裡

主機安裝
每一台應用程式主機daemon emfor、它的設定檔,以及服務定義(systemd 或 rc.d)。
使用 emfor-check 檢查(redis、MySQL/MariaDB、PostgreSQL、LDAP、DNS、RADIUS、SIP、Diameter、SMTP、AMQP、MongoDB、gRPC、QUIC 或 HTTP/3)的主機另外安裝 emfor-check。
應用程式使用 client 函式庫的主機libemfor,以及應用程式所用語言的包裝。
程式只用 DNS 的主機不需要其他東西;從主機的 resolver 轉送 zone 即可(第 7 章)。

建置 daemon

需要支援 2024 edition 的 Rust 工具鏈(Rust 1.85 或更新)。在 checkout 或解開的原始碼發行版中:

cargo build --release --bin emfor --bin emfor-check
install -m 0755 target/release/emfor /usr/local/bin/emfor
install -m 0755 target/release/emfor-check /usr/local/libexec/emfor-check

emfor-check 是選用的;只有使用它的 plugin 時才需要安裝(第 4 章)。資料庫驅動程式只連結進 emfor-check,不在 daemon 或 client 函式庫裡。

預設設定檔路徑

emfor 讀取 /etc/emfor/emfor.toml,除非 --config 指定其他檔案。預設值在建置時由環境變數 EMFOR_PREFIX 決定:

EMFOR_PREFIX預設設定檔路徑
未設定、空字串或 /usr/etc/emfor/emfor.toml
/usr/local/usr/local/etc/emfor/emfor.toml
/opt/emfor/opt/emfor/etc/emfor/emfor.toml
EMFOR_PREFIX=/usr/local cargo build --release --bin emfor

prefix 必須是絕對路徑,否則建置失敗。emfor --help 會顯示內建的路徑。只有設定檔路徑跟著 prefix 改變:store 仍在設定檔的 [store] path(預設 /var/lib/emfor/state.mdb),這也是 client 預設去找的位置。

使用 cargo install

repository 根目錄是 workspace 而不是 package,所以要指定每個 crate:

EMFOR_PREFIX=/usr/local cargo install --locked --path crates/emfor-daemon --root /usr/local
cargo install --locked --path crates/emfor-check --root /usr/local

--root 只決定執行檔放在哪裡;EMFOR_PREFIX 也要另外設定。

安裝套件

repository 可以建出 deb 與 rpm(packages/;packages/build.sh)。兩者都會把 emfor 與 emfor-check 裝到 /usr/bin、裝上 systemd unit、一份只讀 /etc/emfor/conf.d 的設定檔、把附註解的範例設定放在 /usr/share/doc/emfor/,並建立 emfor 使用者。把服務寫在 /etc/emfor/conf.d/ 的檔案裡(第 3 章),然後:

dpkg -i emfor_0.6.0-1_amd64.deb      # Debian、Ubuntu:同時啟用並啟動
rpm -i emfor-0.6.0-1.x86_64.rpm      # RHEL 與相近的發行版:之後 systemctl enable --now emfor
emfor check-config
systemctl reload emfor

這些套件沒有簽章,由這個 repository 建出,沒有發佈在任何地方;packages/build.sh 會為你的架構建出它們。

在 systemd 下執行

repository 裡有一個加固過的 unit:examples/systemd/emfor.service。它以使用者 emfor 執行 /usr/local/bin/emfor server --config /etc/emfor/emfor.toml:

useradd --system --no-create-home --shell /usr/sbin/nologin emfor
install -m 0644 examples/systemd/emfor.service /etc/systemd/system/emfor.service
install -d /etc/emfor /etc/emfor/conf.d
install -m 0644 examples/emfor.toml /etc/emfor/emfor.toml   # then edit it
emfor check-config
systemctl daemon-reload
systemctl enable --now emfor
emfor status

這個 unit 替你處理的事:

  • StateDirectory=emfor 為 store 建立 /var/lib/emfor,擁有者為 emfor。不要改用 DynamicUser=:它的目錄應用程式無法存取。
  • systemctl reload emfor 會先執行 emfor check-config,設定有效時才送出 SIGHUP。
  • daemon 當掉後會被重新啟動,包括結束代碼 70;但結束代碼 1 或 2 不會,因為重試也無法解決(結束代碼)。
  • log 送進 journal:journalctl -u emfor。
  • LimitNOFILE=65536 把開檔上限從 systemd 預設的 1024 調高;檢查、plugin、DNS 與 metrics 連線都會用到檔案。
  • 除了 /var/lib/emfor,檔案系統都是唯讀。[store] path 放在別處時需要 ReadWritePaths=;DNS 用 53 port 時需要 CAP_NET_BIND_SERVICE(見 docs/deploy/daemon.md)。

建置時不要設定 EMFOR_PREFIX(或設為 /usr),這樣 emfor status 與 emfor check-config 不用 --config 也能找到 /etc/emfor/emfor.toml。

/etc/emfor/conf.d 放 include_dir 用的檔案(第 3 章)。範例設定檔把 include_dir 註解掉;若你設定它,這個目錄必須存在,且不能讓 group 或其他人寫入。

在 FreeBSD 上執行

packages/freebsd/ 是一個範例 port(net-mgmt/emfor),它建置 emfor 與 emfor-check、安裝 rc.d script 與範例設定檔,並建立 emfor 使用者、給 include_dir 用的空目錄 /usr/local/etc/emfor/conf.d 與 /var/db/emfor,它的範例設定檔把 store 放在那裡(應用程式要設定 EMFOR_STORE=/var/db/emfor/state.mdb)。rc.d script 在 daemon(8) 底下執行 daemon;daemon 結束 2 秒後 daemon(8) 會再把它啟動。安裝 port 並編輯 /usr/local/etc/emfor/emfor.toml 之後:

sysrc emfor_enable=YES
service emfor start
emfor status
rc.conf 變數預設值意義
emfor_enableNO開機時啟動。
emfor_config/usr/local/etc/emfor/emfor.toml設定檔。
emfor_useremfordaemon 執行時的使用者。需要 store 所在目錄的寫入權限。

service emfor configtest 檢查設定檔(以 emfor_user 身分);service emfor reload 先檢查再送 SIGHUP;start 拒絕無效的設定。daemon 的 log 以 tag emfor 送進 syslog。

不用 port 時,以 EMFOR_PREFIX=/usr/local 建置 emfor,把 port 的 rc.d script 填好 prefix 後安裝,再建立 emfor 使用者(或設定 emfor_user),它需要 [store] path 所在目錄的寫入權限:

sed 's|%%PREFIX%%|/usr/local|g' packages/freebsd/files/emfor.in > /usr/local/etc/rc.d/emfor
chmod 0555 /usr/local/etc/rc.d/emfor
pw useradd emfor -d /nonexistent -s /usr/sbin/nologin -c "emfor daemon"

使用前請先讀 script 的註解與 port 的 README。兩者都已在 FreeBSD 15.1-RELEASE(arm64,VM)上跑過,port 用的是 make stage check-plist install;尚未用 poudriere、14.x 或 amd64 測試。

安裝 client 函式庫

每個 client 都透過 libemfor 讀取 store,它由 clients/rust 建置而來,內含 daemon 自己的 LMDB build:系統的 liblmdb 無法讀取 store。

client 函式庫必須與 daemon 來自同一個 emfor 發行版,並一起升級。 版本不符時,查詢會以 UNAVAILABLE 失敗,訊息會說明原因。

語言方式
Rust依賴同一發行版的 emfor-client crate(clients/rust)。
Ccargo install cargo-c,然後在 clients/rust 執行 cargo cinstall --release --features capi --prefix /usr/local。這會安裝 libemfor、emfor.h 與 emfor.pc。
Go安裝 libemfor,然後 go get github.com/embark-systems/emfor/clients/[email protected](需要 cgo 與 pkg-config emfor)。
Python安裝 libemfor,然後 pip install clients/python。函式庫不在標準目錄時,設定 EMFOR_LIBRARY。
Perl安裝 libemfor,然後在 clients/perl 執行 perl Makefile.PL && make -f Makefile.xs && make -f Makefile.xs install。
PHP安裝 libemfor,然後用 phpize 建置 extension(見 clients/php),並啟用 extension=emfor。

優先使用 shared library:它只匯出 emfor_* 符號,所以內含的 LMDB 不會與同一行程裡的其他 LMDB 衝突。第 6 章說明各 client 的用法。

使用 Hugo 建立
主題 Stack 由 Jimmy 設計