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_enable | NO | 開機時啟動。 |
emfor_config | /usr/local/etc/emfor/emfor.toml | 設定檔。 |
emfor_user | emfor | daemon 執行時的使用者。需要 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)。 |
| C | cargo 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 的用法。