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.
| Chapter | What it covers |
|---|---|
| 1. Concepts | The daemon, the state store, clients, DNS, health states, and what happens when something fails |
| 2. Installation | Building, install prefixes, systemd, FreeBSD, and the client libraries |
| 3. Configuration | Every table and key of emfor.toml, validation, and what a reload can change |
| 4. Health checks | tcp, http, exec, plugins and emfor-check; rise, fall, scheduling and reasons |
| 5. Choosing a backend | The balance methods, on_all_down, and a stale store |
| 6. Client libraries | Looking up a backend from Rust, C, Go, Python, Perl and PHP |
| 7. DNS | The DNS server, its answers, SRV records, forwarding from the host resolver, and caching |
| 7b. DNS recipes | nginx, HAProxy, Caddy, Prometheus and pf on emfor’s DNS answers, and clients that ask for SRV records themselves |
| 8. Operations | Commands, signals and reload, emfor status, emfor lookup, metrics, logs, exit codes, the store on disk, upgrading |
| 9. Troubleshooting | Symptoms, their causes, and what to do |
| 10. Moving from HAProxy or Consul | What 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.