CLI reference
Three subcommands and three flags.
There is no mxhop start, no mxhop reload, no mxhop queue flush. Starting and stopping belong to your service manager; the queue is files on disk. What is left is the part only the binary can answer.
mxhop --help A headless SMTP forwarder Usage: mxhop [OPTIONS] <COMMAND> Commands: check Read the config, prove every claim in it, print what it means run Accept mail until told to stop health Ask the running process whether it is well Options: -c, --config <CONFIG> [env: MXHOP_CONFIG=] [default: /etc/mxhop/mxhop.toml] --log <LOG> [env: MXHOP_LOG=] --log-json [env: MXHOP_LOG_JSON=] -h, --help Print help -V, --version Print version
Subcommands
mxhop check
Reads the config and proves every claim in it without binding a port: opens the TLS certificate as the user that will run, opens the SRS secret and the ARC private key, resolves every via host in DNS, and walks the alias table for loops and unreachable entries. Prints one line describing what mxhop would do, then exits 0. On failure it prints every problem it found — each with the line number in the file — and exits 1.
Run it before DNS points at the host, and again before every restart. It is the ExecStartPre of the systemd unit for exactly that reason.
mxhop run
Accepts mail until told to stop. Binds listen, or takes the socket systemd hands over when LISTEN_FDS says there is one. Logs a single startup line naming the hostname, the domain and alias counts, the SRS domain, how many messages were already in the spool, and whether authentication is off, stamp only or dmarc. Starts the queue runner, and the metrics endpoint if [observe] is set.
mxhop health
Asks the running process's own /healthz over the [observe] address, prints the body and exits 0 if it answered 200, 1 otherwise — including when it did not answer within five seconds. Suitable as a container HEALTHCHECK or a monitor's check, and it is the image's.
Needs an [observe] block; without one there is no endpoint to ask and it says so.
There is a fourth, send-test, hidden from --help. It delivers one message straight out through the normal outbound path and prints what the far end said, bypassing the listener and the queue. It is for proving a route from this host, not for sending mail; it is hidden because anything that sends mail on request is a thing that gets abused.
Global flags
All three apply to every subcommand, and each has an environment variable, so a container needs no command line at all.
-c, --config <PATH>
The config file. Default /etc/mxhop/mxhop.toml.Env: MXHOP_CONFIG
Every diagnostic is prefixed with this path and, where it knows one, the line — so a problem reads /etc/mxhop/mxhop.toml:14: … and is clickable in an editor.
--log <FILTER>
A tracing filter: a bare level (info, debug, trace), or per-module (info,mxhop::queue=debug). Unset means the default, which is info.Env: MXHOP_LOG
No level prints message content at any verbosity. trace gives you more lines about the same facts, not the mail itself.
--log-json
One JSON object per line instead of human-readable text, for a log shipper. The fields are the same either way.Env: MXHOP_LOG_JSON
-V, --version
Prints mxhop <version> and exits. Worth running after an install: it is the one thing that proves which binary is actually on the PATH.
-h, --help
Prints help and exits. Works per subcommand too: mxhop check --help.
Signals
These are the operational interface. There is no subcommand for any of them, because your service manager already has one.
| Signal | What happens |
|---|---|
| SIGTERMSIGINT | Graceful stop. Stops accepting, lets open sessions finish within 25 seconds, answers anyone waiting mid-command with 421, then exits 0. If the grace period runs out with sessions still open it logs that and exits anyway. |
| SIGHUP | Re-reads the TLS certificate and key and logs the new SHA-256 fingerprint. New connections use it; open ones are untouched. With no [tls] block it logs that there was nothing to reload. This is the certificate-renewal hook — systemctl reload mxhop. |
| SIGKILL | Not graceful, and survivable. A message mid-spool is a .tmp file that never got renamed, so it is ignored on restart; a sender that was waiting for 250 never got one and will try again. Nothing in the spool is ever half a message. |
Exit codes and environment
Exit codes
| 0 | check found no problem, health got a 200, or run stopped on a signal as asked |
| 1 | Problems in the config, something it could not open or resolve, a port it could not bind, or a health endpoint that answered badly or not at all |
Environment it reads
| MXHOP_CONFIG | Same as --config |
| MXHOP_LOG | Same as --log |
| MXHOP_LOG_JSON | Same as --log-json |
| LISTEN_FDSLISTEN_PID | Set by systemd socket activation. When LISTEN_PID matches this process, mxhop uses the socket handed to it instead of binding listen; when it names someone else, it says so and binds normally. |