Knowledge base
cluster-addresscriticalWritten by the HubdirectiveAMQP address of the broker over which nodes announce themselves and tell each other to re-read settings; defaults to the same broker that carries the mail.database-addresscriticalWritten by the HubdirectiveConnection string for the database that holds every runtime setting of the cluster — throttles, DKIM keys, pools, pauses, suppressions, rewrite rules and response patterns.licensecriticalWritten by the HubdirectivePath to the licence file, without which the engine does not run.rabbitmq-addresscriticalWritten by the HubdirectiveAMQP address of the broker that carries the mail: host, credentials and virtual host in one string.rabbitmq-failurecriticaldirectiveRouting key under which a message that has finally failed is published, with its full attempt history.rabbitmq-outboxcriticalWritten by the HubdirectiveRouting key used when a message is published for sending — and, on a stock configuration, also the name of the queue the engine reads.rabbitmq-persistentcriticalWritten by the HubdirectiveWhether messages are stored on disk by the broker, so that mail in the queue survives a broker crash — off by default, and deliberately so.rabbitmq-queuecriticalWritten by the HubdirectiveName of the queue MailerQ reads messages from; when it is not set, the engine falls back to the queue named by rabbitmq-outbox.rabbitmq-successcriticaldirectiveRouting key under which the result of every successful delivery is published.send-logcriticaldirectiveText log of every delivery attempt — the only record of intermediate attempts, which never reach the result queues.smtp-authcriticalWritten by the HubdirectiveWhere submitted credentials are checked; naming any scheme here makes a login mandatory for every client.smtp-default-ipscriticalWritten by the HubdirectiveList of addresses submitted mail is sent from — and, when set, it replaces the intake mapping rather than backing it up.smtp-extractcriticalWritten by the HubdirectiveWhether x-mq-* headers in a submitted message are turned into delivery instructions and stripped before sending.smtp-ipcriticalWritten by the HubdirectiveSemicolon-separated list of local addresses on which mail is accepted — and, by that act, the addresses it will be sent from.smtp-mappable-ipscriticalWritten by the HubdirectiveRanges of local addresses for which mail submitted on an address is also sent from that address.smtp-rangecriticalWritten by the HubdirectiveAddress ranges permitted to open an SMTP session; a hard gate applied before anything else in the conversation.www-authcriticalWritten by the HubdirectiveWhere console logins are checked; like the SMTP side, it accepts seven schemes, and like it, the shipped value is a password everyone knows.www-ipcriticalWritten by the HubdirectiveLocal addresses the console is served on; the shipped value is every address the machine has.application-logimportantdirectiveWhere the engine reports its own state: start-up, database and broker connections, configuration reloads, crashes.cluster-exchangeimportantWritten by the HubdirectiveName of the fanout exchange over which nodes announce themselves and control messages travel.database-ttlimportantWritten by the HubdirectiveSeconds between re-reads of the settings database; within that window the engine works entirely from memory and never queries the database per message.dns-attemptsimportantWritten by the HubdirectiveHow many times a query is retried before the domain counts as unresolvable.dns-nameserverimportantWritten by the HubdirectiveName servers the engine queries, overriding whatever the system's resolver configuration says.download-blacklistimportantWritten by the HubdirectiveAddress ranges the engine refuses to download resources from — the guard against a message template reaching into the local network.max-attemptsimportantWritten by the HubdirectiveHow many delivery attempts a message may consume before it is given up on.max-delivertimeimportantWritten by the HubdirectiveSeconds from acceptance after which a message is abandoned, however many attempts remain.rabbitmq-consumersimportantWritten by the HubdirectiveHow many threads read from the consumed queue in parallel.rabbitmq-declareimportantWritten by the HubdirectiveWhether MailerQ declares the queues and exchanges it needs at start-up, or expects them to exist already.rabbitmq-durableimportantWritten by the HubdirectiveWhether queues and exchanges declared by the engine are durable, meaning the broker recreates them after a restart.rabbitmq-exchangeimportantWritten by the HubdirectiveExchange every published message goes to; empty means RabbitMQ's default exchange, where the routing key is simply the queue name.rabbitmq-inboximportantWritten by the HubdirectiveWhere a message accepted by the built-in SMTP server is published; ships pointing at the sending queue, so accepted mail goes straight out.rabbitmq-qosimportantWritten by the HubdirectiveHow many messages one consumer thread may hold unacknowledged at a time.render-enabledimportantWritten by the HubdirectiveWhether the console may display fully rendered messages taken from the live stream.retry-intervalimportantWritten by the HubdirectiveComma-separated list of waits between attempts: ten minutes twice, half an hour twice, an hour twice, then two hours.send-log-formatimportantWritten by the HubdirectiveTemplate for each delivery line, with access to any field of the message and of the result, plus conditionals.server-idimportantWritten by the HubdirectiveNumber identifying this node, used to keep generated message identifiers unique across a cluster.smtp-certificateimportantWritten by the HubdirectiveCertificate presented for STARTTLS on the intake; without it, neither TLS nor AUTH is offered.smtp-connections-outimportantWritten by the HubdirectiveHow many connections to receiving servers the engine may hold open at once, across all domains.smtp-portimportantWritten by the HubdirectivePort or ports on which mail is accepted, with STARTTLS available if a certificate is configured.smtp-privatekeyimportantWritten by the HubdirectivePrivate key matching the intake certificate.www-certificateimportantWritten by the HubdirectiveCertificate presented on the console's TLS port.www-portimportantWritten by the HubdirectiveTCP port the management console is served on, without encryption.www-privatekeyimportantWritten by the HubdirectivePrivate key matching the console certificate.www-secure-portimportantWritten by the HubdirectivePort on which the console is served over HTTPS instead of plain HTTP.delayed-durabledirectiveWhether the delay-step queues are declared durable.delayed-queuesdirectiveNumber of delay steps declared at start-up; each step waits twice as long as the one before, so the count decides the longest single wait.dns-capacityWritten by the HubdirectiveHow many DNS operations may be outstanding at once.dns-intervalWritten by the HubdirectiveSeconds before an unanswered query is sent again.dns-min-ttlWritten by the HubdirectiveLower bound on cached lifetime: records with a shorter TTL are still kept this long, so that domains publishing very short TTLs cannot force a lookup per message.dns-rotateWritten by the HubdirectiveWhether queries are distributed across the configured name servers instead of always preferring the first.dns-timeoutWritten by the HubdirectiveSeconds the resolver waits for a reply after its last attempt before giving up.heartbeat-enableddirectiveWhether the engine periodically reports usage to the vendor; documented as on and as something paid licences may switch off.lockWritten by the HubdirectiveFile holding the process id, used to keep two engines from running at once.plugin-directorydirectiveDirectory of shared objects the engine loads at start-up, giving custom C code a place inside the delivery path.rabbitmq-lazyWritten by the HubdirectiveDeclares queues as lazy, so the broker moves messages to disk as they arrive instead of holding them in memory.rabbitmq-localWritten by the HubdirectiveWhere incoming mail addressed to an address listed as local is published, instead of being sent onward.rabbitmq-maxpriorityWritten by the HubdirectiveHow many priority levels the consumed queue supports; zero means priorities are not used at all.rabbitmq-publishersWritten by the HubdirectiveHow many threads publish results back to the broker.rabbitmq-reportsWritten by the HubdirectiveWhere incoming messages recognised as reports — bounce notifications, DMARC reports — are published.rabbitmq-retriesdirectiveRouting key under which a message that failed temporarily is published to wait for its next attempt.received-logdirectiveText log of messages accepted by the built-in SMTP server.render-useragentdirectiveRestricts the preview module to browsers sending a particular user-agent string, so casual viewing cannot pollute campaign statistics.smarthostdirectiveHostname of a server every message is handed to, instead of being delivered to the recipient's own mail server.smtp-checkWritten by the HubdirectiveWhich validations are run on accepted mail — SPF, DKIM, DMARC and spam scoring.smtp-connectionsWritten by the HubdirectiveUpper limit on all SMTP connections the engine holds, incoming and outgoing together.smtp-connections-inWritten by the HubdirectiveHow many clients may be connected to the intake at once.smtp-hostnameWritten by the HubdirectiveHostname the SMTP server presents in its banner, overriding the system hostname.smtp-passworddirectiveAccepted by the binary; the partner of smtp-username, superseded by smtp-auth.smtp-protectiondirectiveWhether the intake blocks addresses that behave abusively, such as repeated failed logins.smtp-sink-addressdirectiveRedirects the TCP connection of every delivery to one address, while the rest of the engine behaves as though the mail were going to its real destination.smtp-threadsWritten by the HubdirectiveHow many threads handle incoming SMTP traffic; each binds its own socket per address.smtp-unmappable-ipsWritten by the HubdirectiveRanges taken back out of the mappable set — loopback and private addresses by default.smtp-usernamedirectiveAccepted by the binary; the pre-5.x way of requiring a login, superseded by smtp-auth.smtp-validate-addressesdirectiveHow strictly submitted envelope and recipient addresses are checked against the standard.spool-directorydirectiveDirectory the engine watches for message files, reading each one and publishing it as a job.storage-addressdirectiveConnection string for an external store holding message bodies, so that jobs travelling through the broker carry only a key.storage-ttldirectiveSeconds a body is kept in the store before it expires.strict-email-addressesdirectiveWhether addresses must conform strictly to the standard; the 5.16 replacement for the documented validate-envelope and validate-recipient.temporary-expiresdirectiveTime to live on a temporary queue: after it expires, mail held there because of throttling or a pause goes back to the sending queue.userWritten by the HubdirectiveSystem account the engine switches to after binding privileged ports.www-logdirectiveText log of requests to the management console, including who was logged in.www-passworddirectiveAccepted by the binary, printed nowhere, absent from the stock config.www-samesitedirectiveSameSite policy applied to the console's session cookie.www-urlWritten by the HubdirectiveFull URL other cluster members use to link to this node's console; absent from –help but present in the stock config.cluster-timeoutdirectiveHow long a node waits for other nodes to answer its announcement before it proceeds.cluster-verifydirectiveWhether the broker's TLS certificate is verified when the cluster address uses amqps; turning it off is how self-signed certificates are accepted.database-validatedirectiveWhether the engine verifies that the database schema matches the version it expects before it starts working.delayed-declaredirectiveWhether the delay-step queues are declared by the engine at start-up.delayed-exchangedirectiveExchange used when publishing a message into a delay step; defaults to the main result exchange.delayed-lazydirectiveDeclares the delay steps as lazy queues, so waiting messages are written to disk.delayed-replytodirectiveExchange a delayed message is sent back to when its wait is over.delayed-routingkeydirectiveRouting key used when a message is published into the ladder.delayed-typedirectiveWhether the delay steps are declared as classic or quorum queues.dns-buffersizeWritten by the HubdirectiveSize of the socket buffer used for DNS traffic.dns-socketsWritten by the HubdirectiveHow many sockets the resolver spreads its queries across.download-bin-logdirectiveCompact machine-readable copy of the download log.download-cacheWritten by the HubdirectiveStore for downloaded resources, so the same image is not fetched for every message.download-logdirectiveText log of resources the engine fetched from the internet while building messages.download-log-formatdirectiveTemplate for download lines; ships as a timestamp and the URL.download-proxydirectiveProxy used specifically when fetching resources, separate from the engine's general proxy.download-ttlWritten by the HubdirectiveSeconds a downloaded resource is served from the cache before being fetched again.download-user-agentdirectiveThe user-agent string the engine presents when downloading resources.download-whitelistdirectiveAddress ranges resources may be fetched from, to the exclusion of everything else; empty, so no such restriction applies.dsn-advertiseWritten by the HubdirectiveWhether the built-in SMTP server advertises the DSN extension, letting submitting clients request notifications per message.dsn-notifyWritten by the HubdirectiveDefault events that produce a delivery status notification: never, on failure, on success, on delay — or a combination.dsn-retWritten by the HubdirectiveWhether a notification carries the whole original message or only its headers.envelopedirectiveSets the return address for a message published from the command line.extract-recipientsdirectiveWhen the binary is used as a command-line utility, take the recipients from the message's own headers instead of the command line.ignore-dotdirectiveTreat end of input, rather than a lone dot, as the end of a message read from standard input.message-tracingdirectiveTurns on detailed tracing of what happens to individual messages.proxy-serverdirectiveHTTP or SOCKS proxy used for the engine's own network calls — not for delivering mail.rabbitmq-dsndirectiveWhere MailerQ publishes the bounce notifications it generates itself.rabbitmq-encodingWritten by the HubdirectiveWhether messages the engine publishes are compressed, and with what.rabbitmq-flushdirectiveHow many messages are loaded at once while the engine is draining a queue.rabbitmq-minqosdirectiveThe smallest window the engine will shrink to when it reduces prefetch under pressure.rabbitmq-refuseddirectiveWhere messages the SMTP server refused are published, if they are to be kept at all.rabbitmq-throttledirectiveHow many messages may be written to the broker socket at the same time.rabbitmq-unroutabledirectiveWhere a published message goes when the exchange has nowhere to route it.rabbitmq-verifydirectiveWhether the broker's TLS certificate is verified when the address uses amqps.received-bin-logdirectiveCompact machine-readable copy of the intake log.received-log-formatdirectiveTemplate for intake lines, addressing the incoming message JSON directly and guarding the message id with a conditional.send-bin-logdirectiveCompact machine-readable copy of the delivery log.smarthost-passworddirectivePassword offered to the smarthost.smarthost-portdirectivePort used when connecting to the smarthost; falls back to the standard SMTP port.smarthost-usernamedirectiveUsername offered to the smarthost when it requires authentication.smtp-auth-resultsWritten by the HubdirectiveWhether the verdicts from smtp-check are recorded in an Authentication-Results header, and for which recipients.smtp-ciphersdirectiveOpenSSL cipher specification for the intake, shipped with a conservative list already in place.smtp-defaultipdirectiveAccepted by the binary; singular variant, undocumented and absent from the stock config.smtp-defaultipsdirectiveAccepted by the binary; neither printed by –help nor present in the stock config.smtp-keydirectiveAccepted by the binary; the vendor's documentation uses this name for what –help calls smtp-privatekey.smtp-maxsizeWritten by the HubdirectiveMaximum size of a message the intake will accept, announced to clients in the SMTP greeting.smtp-proxydirectiveAddress ranges whose connections begin with a PROXY header carrying the real client address.smtp-secure-portdirectivePort where the connection is encrypted from the start, without a STARTTLS upgrade.smtp-sink-ipdirectiveAccepted by the binary; printed nowhere and absent from the stock config.smtp-sink-passworddirectivePassword offered to the sink.smtp-sink-portdirectivePort used when connecting to the sink; documented as 25 when unset.smtp-sink-usernamedirectiveUsername offered to the sink when it demands authentication.smtp-timeoutdirectiveSeconds the intake waits for a client to say something before closing the session.smtp-validate-addressdirectiveAccepted by the binary; the vendor documents this spelling while the help output prints the plural.spamassassin-hostdirectiveAddress of a SpamAssassin daemon used to score incoming mail; empty, so no scoring happens.spamassassin-portdirectivePort of the SpamAssassin daemon; ships with the standard 783.spool-delaydirectiveSeconds a file must sit untouched before it is read, so half-written files are not published.spool-extractdirectiveWhether x-mq-* headers in a spooled file are turned into delivery instructions.spool-fail-directorydirectiveDirectory that receives spooled files the engine could not parse.spool-open-filesdirectiveHow many spooled files the engine holds open simultaneously.spool-removedirectiveWhether a spooled file is deleted once it has been published.spool-threadsdirectiveHow many threads read and publish spooled files in parallel.storage-policydirectiveWhether outgoing, incoming, all or no message bodies are placed in the external store.storage-rescheduledirectiveSeconds before a message whose body could not be fetched is tried again.storage-threadsdirectiveHow many connections to the store the engine keeps for fetching and writing bodies.storage-timeoutdirectiveSeconds to wait for the store to return a body before treating the fetch as failed.temporary-declaredirectiveWhether the exchange for temporary queues is declared at start-up.temporary-durabledirectiveWhether the exchange for temporary queues is declared durable.temporary-exchangedirectiveExchange the engine binds each temporary queue to when it creates one.temporary-typedirectiveWhether temporary queues are declared classic or quorum.validate-envelopedirectiveAccepted by the binary and documented with a default of strict, but superseded in this build by strict-email-addresses.validate-recipientdirectiveThe recipient-side twin of validate-envelope, in the same superseded state.www-bin-logdirectiveCompact machine-readable copy of the console access log.www-cache-controldirectiveValue sent in the Cache-Control header for the console's static files.www-ciphersdirectiveOpenSSL cipher specification used on the console's TLS port.www-connectionsWritten by the HubdirectiveHow many HTTP connections the console will hold at once.www-dirdirectiveDirectory the console's HTML, JavaScript and translations are served from.www-hostdirectiveHostname this node publishes for cluster console links, when a full URL is not given.www-log-formatdirectiveTemplate for console access lines: client address, timestamp, the account that was authenticated, and the request.www-management-onlydirectiveAccepted by the engine, printed nowhere, and with no effect we could observe — recorded as a finding rather than as a setting.What the console exposes, and how it is protectedcriticalWritten by the HubmechanismThe console can pause sending, rewrite messages, read message bodies and change every limit — and by default it is reachable from anywhere, unencrypted, behind a password it displays to whoever is already inside.Why mail leaves from the address it arrived oncriticalWritten by the HubmechanismMail handed to the built-in SMTP server goes out from the address it was handed to — unless a default address list is configured, which replaces the rule entirely.How a setting reaches a running nodecriticalWritten by the HubmechanismA MailerQ setting lives in the database and reaches a node one of two ways: quietly, when the node's cache expires, or at once, when someone publishes a reload message to the cluster exchange.How MailerQ waits between attemptsimportantmechanismRetry waiting is done by the broker, not the engine: a message is published into a queue whose messages expire after a fixed time and whose expiry routes them back to the sending queue.Why the resolver is a delivery concern, not an infrastructure detailimportantWritten by the HubmechanismA failed lookup is a permanently failed message, so the resolver a node uses is part of its deliverability, not part of its plumbing.The template language the log formats shareimportantWritten by the HubmechanismLog lines are rendered from templates with access to whole objects by path and with conditionals — so a log can carry anything a message or a result contains, including our own fields.The three limits that end an undelivered messageimportantWritten by the HubmechanismA message stops being retried when the retry list is exhausted, the attempt count is reached, or the deadline passes — and the shipped values for the three do not line up.Where queue names come from, and what inherits themimportantWritten by the HubmechanismThe consumed queue takes its name from rabbitmq-queue, or from rabbitmq-outbox when that is absent — and the entire delay ladder is named after it.Where held-back mail goes, and why their names matterimportantmechanismMail held back by a rate limit, a flood pattern, a pause or greylisting is moved into a queue created on the spot and named after what is holding it.Traffic a MailerQ node generates that is not mailmechanismBesides mail, a node reports usage to the vendor, may send crash reports, and fetches resources referenced by messages — three outbound channels a customer may ask about.Three places a message body can be, and what each costsmechanismA body travels inside the job through the broker, or sits in an external store addressed by a key, or arrives as a file in a watched directory — and each choice moves the bottleneck somewhere else.purge-databasecriticalstartup flagEmpties the cluster database and rebuilds an empty schema — every throttle, DKIM key, pool, pause and suppression is gone.repair-databasecriticalWritten by the Hubstartup flagCreates missing tables and brings an existing schema up to the version the binary expects, then exits.list-ipsstartup flagPrints the local addresses available for sending, then exits.pausedstartup flagStarts the engine in a paused state — connected and configured, but delivering nothing.config-filestartup flagReads settings from the named file instead of /etc/mailerq/config.txt.daemonstartup flagDetaches the process from the terminal.disable-crash-poststartup flagStops crash reports from being sent to the vendor, while still producing them locally.disable-crash-reportstartup flagStops the engine from producing a crash report when it dies unexpectedly.fetch-licensestartup flagFetches a licence file from the vendor using an identifier, then exits.