mxhop

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.

SignalWhat happens
SIGTERMSIGINTGraceful 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.
SIGHUPRe-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.
SIGKILLNot 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

0check found no problem, health got a 200, or run stopped on a signal as asked
1Problems 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_CONFIGSame as --config
MXHOP_LOGSame as --log
MXHOP_LOG_JSONSame as --log-json
LISTEN_FDSLISTEN_PIDSet 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.