Knowledge base
always-allow-relayingGlobalcriticalset by the HubDirectiveThe very reason a node sends mail at all — and the thing that makes it an open relay if granted to the wrong source.http-accessGlobalcriticalset by the HubDirectiveA list of addresses and access levels for the management interface; closed to everyone by default.http-api-keyGlobalcriticalset by the HubDirectiveA key in the X-API-Key header grants administrator rights from any address; the line is repeatable.postmasterGlobalcriticalDirectiveOne of the two settings the engine does not work without: the watchdog sends crash and license expiration reports here, and mail to service addresses is forwarded here as well.process-x-dkim-key<source>criticalDirectiveA permission for the source: with it, the engine takes the private key straight from the X-DKIM-Key header, signs with it and strips the header; without it, the key travels to the recipient.retain-x-dkim-key<source>criticalDirectiveThe only source block directive for which the manual prints its warning in bold: with true, the private key travels to the recipient.run-as-rootGlobalcriticalDirectiveMust be false to run as an unprivileged user; changing it requires a restart.smtp-listenerGlobalcriticalset by the HubDirectiveIf no listener is declared, the node silently brings one up on 0.0.0.0:25.smtp-service<source>criticalset by the HubDirectiveTurning it off closes submission for the source without touching the others.access-token<vault>DirectiveThe Vault authorization token; created manually on the vault side and needed by almost everything that works through the vault.allow-unencrypted-plain-auth<source>set by the HubDirectiveThe PLAIN mechanism transmits the password almost in plain text; the line decides whether to allow it without encryption. The default is not to allow it.allowed-sender-lists<source>DirectiveNames address lists that MAIL FROM and the sender address from the message are checked against; a message that fails is rejected at submission.authentication-method<smtp-user>DirectiveFive methods — a password, your own certificate, a certificate from a trusted authority, a Linux system account and LDAP through the vault; the default is a password.check-spf-inbound<source>DirectiveEnables the check on the way in and adds a header with its result to the message.enable-signalsGlobalDirectiveThe scope of export with three inheritance levels; the subaccount, the tracking domain or the rule list name are appended here too.hashed-address<address-list>DirectiveThe address is lowercased, hashed with SHA256 and encoded as BASE64URL; the engine hashes the address being checked and compares the hashes.http-csrf-protectionGlobalDirectiveForbids changing the node’s state with a GET request and requires a key or a session token on POST; enabled by default.includeGlobalset by the HubDirectiveReads an additional file — by path, by mask or by HTTP address; the contents are processed as if written in this place.password<smtp-user>set by the HubDirectiveSets the password for password login; it is stored in the configuration in plain text, because otherwise not all SASL mechanisms can be supported.privacy-policy<acct-file>DirectiveReplaces the local part of an address with a placeholder or a hash; the default is to leave it as is.privacy-policy<signals>DirectiveReplaces the local part of the recipient address with a one-way SHA-1 hash; by default it is sent as is.require-auth<source>set by the HubDirectiveWith true the engine accepts not a single message from the source until the sender logs in — including submission from the machine itself.require-starttls-before-auth<source>DirectiveWith this line the client must perform STARTTLS before the authentication command; the default is not to require it, and then the password can travel in plain text.smtp-max-auth-failure-rate<source>set by the HubDirectiveAfter the specified number of failed attempts the engine stops accepting logins from the source until the end of the period; the default limits nothing.smtp-server-tls-certificateGlobalset by the HubDirectiveAn X.509 certificate in PEM format — from a file or from a secrets store; the private key password is optional and can also be in the store.source<smtp-listener>DirectiveBinds the listener to a named source block, canceling the usual address-based matching for its connections.tls-certificate<smtp-listener>DirectiveThe certificate and key password for connections to this particular address and port; inherited from the node certificate.use-inbound-proxy<smtp-listener>DirectiveRequires a PROXY header at the start of the connection and takes the real client address from it; off by default.allow-auth<source>DirectiveA switch for the very possibility of logging in: with no the engine neither advertises nor accepts AUTH, and there is no way to log in.await-slot<smtp-listener>DirectiveDecides for one listener whether to wait for a free slot or respond with a refusal; the node-wide line sets the same for all the others.cache-ttl<vault>DirectiveThe time after which a key obtained from Vault is requested again; a missing key is always cached for an hour, regardless of this line.check-arc-inbound<source>DirectiveThe same observational check as for the regular signature; it has no refusals either.check-dkim-inbound<source>DirectiveObservation only: the engine has no refusals based on the signature check result at all.hide-message-source<source>DirectiveRemoves from the added Received header the name and address of whoever submitted the message; the header itself stays.http-extra-headers<include-config>DirectiveNames a file whose lines the node will add as HTTP request headers when loading the configuration.http-redirect-to-httpsGlobalset by the HubDirectiveWith true the monitor accepts only https and redirects plain connections; the default is true since version 5.0.http-tls-min-versionGlobalDirectiveThe oldest protocol version the node’s management interface will negotiate; TLS 1.2 by default.immediate-tls<smtp-listener>DirectiveInstead of STARTTLS the node starts encryption as soon as the connection is accepted; this is a separate submission method, usually on port 465.inbound-proxy-timeout<smtp-listener>DirectiveThe limit for waiting for the PROXY header at the start of a connection; the default is five seconds, and zero means “wait forever.”include<source>DirectiveThe same directive written inside a source block — the included lines become its settings.include<smtp-pattern-list>DirectiveThe same directive written inside an SMTP response parsing list — the included lines become its rules.log-file-world-readableGlobalDirectiveGives all users on the node the right to read the engine’s logs; no by default.server-url<vault>DirectiveThe name or address of the Vault server and, if needed, a port; the scheme is http or https.tls-ca-file<smtp-user>DirectiveOne or more files with chains; any client certificate that chains up to at least one of them will do.tls-certificate<smtp-user>DirectiveThe certificate file the submitter must present; it works with the “certificate” verification method and requires an encrypted connection.tls-certificate<transmissions-api-listener>DirectiveA file with an X.509 certificate and a private key for the HTTP API entry point; it can be taken from the secrets vault.tls-certificate-san-or-cn<smtp-user>DirectiveA fully qualified domain name that the client certificate’s SAN or CN must match; it works on top of chain verification.tls-min-version<smtp-listener>DirectiveThe oldest protocol version accepted on this address and port; the default is TLS 1.2, as for the node.tls-min-version<transmissions-api-listener>DirectiveThe oldest protocol version accepted on this HTTP API entry point; the default is TLS 1.2.use-inbound-proxy<transmissions-api-listener>DirectiveRequires a PROXY header at the start of the connection and takes the real client address from it; off by default.inbound-proxy-timeout<transmissions-api-listener>DirectiveThe limit for waiting for the PROXY header at the start of a connection; the default is five seconds, and zero means “wait forever.”log-inbound-proxy<smtp-listener>DirectiveWrites the received PROXY header to the log; works only with reception of such a header enabled.log-inbound-proxy<transmissions-api-listener>DirectiveWrites the received PROXY header to the log; works only with reception of such a header enabled.tls-ca-file<smtp-listener>DirectiveA list of root certificates for verifying clients on this input; the manual does not promise inheritance from the node’s list.tls-ca-file<transmissions-api-listener>DirectivePath to a PEM file with authority certificates by which the input verifies the submitting client’s certificate.tls-cipher-server-preference<smtp-listener>DirectiveWith this line the cipher is chosen by our order, not by the client’s order; the default is by the client.tls-cipher-server-preference<transmissions-api-listener>DirectiveA switch: take the cipher by the order of the node’s list rather than by the client’s preference; off by default.tls-ciphers<smtp-listener>DirectiveThe list of allowed ciphers in OpenSSL notation for connections on this input; applies up to and including TLS 1.2.tls-ciphers<transmissions-api-listener>DirectiveThe list of allowed ciphers in OpenSSL notation for the HTTP API input; applies up to and including TLS 1.2.tls-max-version<smtp-listener>DirectiveThe newest protocol version accepted on this address and port; unlimited by default.tls-max-version<transmissions-api-listener>DirectiveThe newest protocol version accepted on this HTTP API input; unlimited by default.tls-v1.3-ciphersuites<smtp-listener>DirectiveA separate list for version 1.3 on this input; the default lists five modern suites.tls-v1.3-ciphersuites<transmissions-api-listener>DirectiveThe list of TLS 1.3 suites, colon-separated, for the HTTP API input; all five by default.http-default-max-itemsGlobalDirectiveLength of the “Top Queues”, “Top Domains”, “Top VirtualMTAs” and “Top Jobs” lists; default 10.http-default-sort-orderGlobalDirectiveOrder of lines in the “Top” lists — by recipient count, by name or by volume; by recipients by default.http-log-dataGlobalDirectiveMore detailed logging than the request log; off by default.http-log-requestsGlobalDirectiveA switch for logging calls to the management interface; off by default.http-log-tlsGlobalDirectiveA switch for detailed logging of encryption negotiation in the monitor log; off by default.http-mgmt-sourceGlobaldeprecatedDirectiveReplaced by the http-access directive, which does the same and also distinguishes access levels.http-strict-transport-security-max-ageGlobalDirectiveThe max-age value in the Strict-Transport-Security header of monitor responses; default 0 — that is, do not remember.http-tls-allow-sslv3GlobaldeprecatedDirectivePowerMTA no longer supports SSLv3; the line is kept only for configuration compatibility.http-tls-allow-tlsv1GlobaldeprecatedDirectiveA separate switch for one protocol version on the management interface; deprecated in PowerMTA 5.5 in favor of a pair of bounds.http-tls-allow-tlsv1.1GlobaldeprecatedDirectiveA separate switch for one protocol version on the management interface; deprecated in PowerMTA 5.5 in favor of a pair of bounds.http-tls-allow-tlsv1.2GlobaldeprecatedDirectiveA separate switch for one protocol version on the management interface; deprecated in PowerMTA 5.5 in favor of a pair of bounds.http-tls-allow-tlsv1.3GlobaldeprecatedDirectiveA separate switch for one protocol version on the management interface; deprecated in PowerMTA 5.5 in favor of a pair of bounds.http-tls-ca-fileGlobalDirectivePath to a PEM file with authority certificates by which the monitor verifies the certificate of an incoming client.http-tls-cipher-server-preferenceGlobalDirectiveA switch: take the cipher by the order of the node’s list rather than by the client’s preference; off by default.http-tls-ciphersGlobalDirectiveA list of allowed ciphers in OpenSSL notation for the management interface; applies up to and including TLS 1.2.http-tls-max-versionGlobalDirectiveThe newest protocol version the management interface will negotiate; unlimited by default.http-tls-request-client-certificateGlobalDirectiveA switch for requesting a client certificate in the handshake; on by default.http-tls-v1.3-ciphersuitesGlobalDirectiveA colon-separated list of TLS 1.3 suites for the management interface; all five by default.no-http-mgmt-sourceGlobaldeprecatedDirectiveThe negative half of the former pair; replaced by an http-access line with the none level.upload-url<signals>DirectiveThe event intake endpoint; by default the vendor service’s address.How the node selects a source and combines its settingscriticalMechanismA connection falls under all source blocks whose addresses cover it, and they act merged — the narrow one overrides the wide one; named blocks are attached only by direct reference.How the node decides whether to let an HTTP request incriticalMechanismTwo ways to identify yourself — an access level by address and a key; the key is stronger and works from any address.Who is allowed to submit mail and for whom to accept itcriticalMechanismOut of the box, the node accepts submission only from the machine itself; two different questions — “who can send through us” and “for whose addresses we accept mail” — are answered by different directives.Headers the sender uses to control deliverycriticalMechanismSix control headers let the submitting side choose a stream, tag a message with a job, set signing options and the key, the envelope identifier and the schedule; each is allowed separately and per source.What the submission bindings needMechanismWhat must be in place on the submitting side for the bindings to work: a library, permissions and group membership.Submission logins, plain-text passwords and per-user settingsMechanismA sender logs in with one of three methods; each login is a configuration block with a plain-text password, and that login’s named source overrides what its address would have given.Submission is a network service, and you can log into itMechanismThe submitting application connects to the node by name or address and port — either without login or with a name and password the node is configured to accept.The vendor's analytics — and what leaves the node for itMechanismA paid service that receives the node’s accounting data and returns analytics, a health score and a spam trap report; it is enabled by scope and stays off until its block exists.What protects the web monitor and what that protection is notMechanismThree different protections — an address list, encryption and advice not to expose the monitor to the internet; there is not a single account.Submitting a message by writing a file into a directoryMechanismThe message is placed as a file in a directory, and the envelope is passed in special headers at its start; the engine takes the file into the spool and delivers it.The stream follows the address you connected toMechanismA named source block is attached to a listener and applies to everyone who connected to that address and port — so the sender picks the stream by picking the connection point.The load balancer header at the entranceMechanismThe node reads the PROXY header at the start of an incoming connection and treats the address from it as the source; this works for both kinds of entry point.Secrets in an external vaultMechanismSigning keys can be kept in HashiCorp Vault: the configuration keeps a path, and the engine fetches the key over HTTP and keeps it in memory without writing it to disk.A signing key that came along with the messageMechanismA private key is passed in a message header; the node signs with it and removes the header before sending.The group that grants management rightsMechanismMembership in the pmta group gives an unprivileged user the right to call the node’s commands and use submission.Exposing metrics over SNMPMechanismThe node can expose its metrics over SNMP — a second way of monitoring besides the web monitor.Restrict who can reach the node at allProcedureFive steps of least privilege: the right to hand over mail only for logins, receiving only from a narrow range, the monitor likewise, and running without system administrator rights.Lock down permissions on configuration filesProcedureThe configuration holds passwords, API keys and private signing keys — the manual gives specific commands for them, and included files require the same.Running without root privilegesProcedureMoving the engine to run as a separate user: the line itself, ports above one thousand twenty-four, raised limits on files and processes, and changing the owner of five directories.Enabling FIPS modeProcedureSwitching the node to a validated set of cryptographic algorithms. Some familiar encryption settings become unavailable.<source>criticalConfiguration blockRules for whoever connects to submit: whether relaying is allowed, which control headers to honor, which limits apply and whether authentication is required.show registrationCommandPrints whether the node is registered in the vendor’s console.ConsoleMonitor screenRuns node console commands right from the browser; the page link exists only while the service is running.ConfigurationMonitor screenShows the main and included configuration files and lets you edit them; saving reloads the configuration by itself.The monitor's home pageMonitor screenThe web monitor’s start page: installation information, the top queue domains and links to the other screens.The node's main configuration filecriticalFile/etc/pmta/config is a plain UTF-8 text file, read at startup and on a settings reload; it stores passwords and signing keys in plain text.