emfor is built from source with Cargo. Linux and FreeBSD are the deployment platforms; macOS works for development.
What you install where
| Host | Install |
|---|---|
| Every application host | The daemon emfor, its config, and a service definition (systemd or rc.d). |
Hosts that use a check of emfor-check (redis, MySQL/MariaDB, PostgreSQL, LDAP, DNS, RADIUS, SIP, Diameter, SMTP, AMQP, MongoDB, gRPC, QUIC or HTTP/3) | Also emfor-check. |
| Hosts whose applications use a client library | libemfor, and the wrapper for the application’s language. |
| Hosts whose programs use DNS only | Nothing more; forward the zone from the host resolver (chapter 7). |
Building the daemon
You need a Rust toolchain that supports the 2024 edition (Rust 1.85 or later). From a checkout or an unpacked source release:
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 is optional; install it only if you use its plugins
(chapter 4). The database
drivers are linked into emfor-check only, not into the daemon or the
client library.
The default config path
emfor reads /etc/emfor/emfor.toml unless --config names another
file. The default is fixed when the binary is built, from the environment
variable EMFOR_PREFIX:
EMFOR_PREFIX | Default config path |
|---|---|
not set, empty, or /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
The prefix must be an absolute path, or the build fails. emfor --help
shows the path that was built in. Only the config path follows the prefix:
the store stays at the config’s [store] path (default
/var/lib/emfor/state.mdb), which is also where clients look by default.
With cargo install
The repository root is a workspace, not a package, so name each 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 only decides where the binaries go; set EMFOR_PREFIX as well.
Installing a package
The repository builds a deb and an rpm (packages/;
packages/build.sh). Each installs emfor and emfor-check under
/usr/bin, the systemd unit, a config that only reads /etc/emfor/conf.d,
the commented example config under /usr/share/doc/emfor/, and creates the
emfor user. Put your services in files of /etc/emfor/conf.d/ (chapter
3), then:
dpkg -i emfor_0.6.0-1_amd64.deb # Debian, Ubuntu: also enables and starts it
rpm -i emfor-0.6.0-1.x86_64.rpm # RHEL and relatives: then systemctl enable --now emfor
emfor check-config
systemctl reload emfor
The packages are not signed and are built from this repository, not
published anywhere; packages/build.sh builds them for your architecture.
Running under systemd
The repository has a hardened unit,
examples/systemd/emfor.service. It
runs /usr/local/bin/emfor server --config /etc/emfor/emfor.toml as user
emfor:
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
What the unit does for you:
StateDirectory=emforcreates/var/lib/emforfor the store, owned byemfor. Do not switch toDynamicUser=: its directory is not reachable by applications.systemctl reload emforrunsemfor check-configfirst and sends SIGHUP only when the config is valid.- The daemon is restarted after a crash, including exit status 70, but not after status 1 or 2, which a retry does not fix (exit codes).
- Logs go to the journal:
journalctl -u emfor. LimitNOFILE=65536raises the open-file limit from systemd’s default 1024; checks, plugins and DNS and metrics connections all use files.- The file system is read-only except
/var/lib/emfor. A[store] pathelsewhere needsReadWritePaths=; DNS on port 53 needsCAP_NET_BIND_SERVICE(see docs/deploy/daemon.md).
Build without EMFOR_PREFIX (or with /usr) so that emfor status and
emfor check-config find /etc/emfor/emfor.toml without --config.
/etc/emfor/conf.d is for the files of include_dir
(chapter 3).
The sample config leaves include_dir commented out; if you set it, the
directory must exist and must not be writable by group or others.
Running on FreeBSD
packages/freebsd/ is an example port
(net-mgmt/emfor) that builds emfor and emfor-check, installs an rc.d
script and a sample config, and creates the emfor user, the empty
/usr/local/etc/emfor/conf.d for include_dir and /var/db/emfor, where its sample config puts the store (applications set
EMFOR_STORE=/var/db/emfor/state.mdb). The rc.d script runs the daemon
under daemon(8), which starts it again 2 seconds after it exits. After
installing the port and editing /usr/local/etc/emfor/emfor.toml:
sysrc emfor_enable=YES
service emfor start
emfor status
| rc.conf variable | Default | Meaning |
|---|---|---|
emfor_enable | NO | Start at boot. |
emfor_config | /usr/local/etc/emfor/emfor.toml | Config file. |
emfor_user | emfor | User the daemon runs as. It needs write access to the store’s directory. |
service emfor configtest checks the config (as emfor_user);
service emfor reload checks it and then sends SIGHUP; start refuses an
invalid config. The daemon’s log goes to syslog with the tag emfor.
Without the port, build emfor with EMFOR_PREFIX=/usr/local, install the
port’s rc.d script with its prefix filled in, and create the emfor user
(or set emfor_user), which needs write access to the directory of
[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"
Read the comments in the script and the port’s README before using them.
Both have been run on FreeBSD 15.1-RELEASE (arm64, in a VM), the port with
make stage check-plist install; not with poudriere, on 14.x or on amd64.
Installing the client libraries
Every client reads the store through libemfor, built from
clients/rust. It contains the daemon’s own
LMDB build: a system liblmdb cannot read the store.
Install the client library from the same emfor release as the daemon,
and upgrade both together. A mismatch makes lookups fail with
UNAVAILABLE and a message that says so.
| Language | How |
|---|---|
| Rust | Depend on the emfor-client crate from the same release (clients/rust). |
| C | cargo install cargo-c, then in clients/rust: cargo cinstall --release --features capi --prefix /usr/local. This installs libemfor, emfor.h and emfor.pc. |
| Go | Install libemfor, then go get github.com/embark-systems/emfor/clients/[email protected] (needs cgo and pkg-config emfor). |
| Python | Install libemfor, then pip install clients/python. Set EMFOR_LIBRARY if the library is outside the standard directories. |
| Perl | Install libemfor, then in clients/perl: perl Makefile.PL && make -f Makefile.xs && make -f Makefile.xs install. |
| PHP | Install libemfor, then build the extension with phpize (see clients/php) and enable extension=emfor. |
Prefer the shared library: it exports only emfor_* symbols, so its LMDB
cannot clash with another LMDB in the same process. Chapter 6
shows how to use each client.