0. Guide to the Manual

This manual is for the people who install emfor, configure it, and write the applications that use it. It explains how the pieces fit together and walks through each task; the documents under docs/deploy/ and the client READMEs hold the full detail and are linked where they apply.

The manual describes emfor 0.5.

ChapterWhat it covers
1. ConceptsThe daemon, the state store, clients, DNS, health states, and what happens when something fails
2. InstallationBuilding, install prefixes, systemd, FreeBSD, and the client libraries
3. ConfigurationEvery table and key of emfor.toml, validation, and what a reload can change
4. Health checkstcp, http, exec, plugins and emfor-check; rise, fall, scheduling and reasons
5. Choosing a backendThe balance methods, on_all_down, and a stale store
6. Client librariesLooking up a backend from Rust, C, Go, Python, Perl and PHP
7. DNSThe DNS server, its answers, SRV records, forwarding from the host resolver, and caching
7b. DNS recipesnginx, HAProxy, Caddy, Prometheus and pf on emfor’s DNS answers, and clients that ask for SRV records themselves
8. OperationsCommands, signals and reload, emfor status, emfor lookup, metrics, logs, exit codes, the store on disk, upgrading
9. TroubleshootingSymptoms, their causes, and what to do
10. Moving from HAProxy or ConsulWhat the same configuration looks like in emfor, what has no equivalent, and how to try emfor next to what you have

New to emfor? Read chapter 1, then follow the quick start in the README, then chapter 3.

Conventions

  • Service names in the examples end in .svc.emfor, the default DNS zone. Any host-name-like name works; only names under the zone resolve over DNS.
  • Paths are the defaults: the config at /etc/emfor/emfor.toml, the store at /var/lib/emfor/state.mdb.
  • $ starts a command you type; lines without it are output.
Built with Hugo
Theme Stack designed by Jimmy