Knowledge base
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.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-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-starttls<source>set by the HubDirectivePermission to advertise STARTTLS to this source’s clients; the default is not to allow it, and then submission goes in plain text.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.api-key<transmissions-api>DirectiveThe line declares a key the application passes in the Authorization header; the directive is repeated to create several keys.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.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.openssl-security-levelGlobalDirectiveA number from 0 to 5 below which OpenSSL refuses to work with keys, certificates and protocol versions; 1 by default.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.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<domain>set by the HubDirectiveWith this line the node drops the connection instead of sending in plain text; the default is to send.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.smtp-tls-min-version<domain>DirectiveThe oldest protocol version the node is willing to negotiate when sending; the default is TLS 1.1.tls-certificate<smtp-listener>DirectiveThe certificate and key password for connections to this particular address and port; inherited from the node certificate.use-dane<domain>DirectiveThe node reads the recipient domain’s DANE records, requires encryption if the domain requires it, and checks the certificate against the fingerprint from DNS; the default is off.use-mta-sts<domain>set by the HubDirectiveThe node fetches the recipient domain’s policy and, if it is in enforce mode, delivers only when the MX matches, the connection is encrypted and the certificate is verified; the default is off.use-starttls<domain>set by the HubDirectiveEnables STARTTLS if the receiver offers it; the default is on.api-key<signals>DirectiveExactly forty hexadecimal characters; without it the node will not start at all.auth-password<domain>DirectiveThe second half of the pair; the hash sign is not allowed in it — the engine treats it as the start of a comment.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.hide-message-source<source>DirectiveRemoves from the added Received header the name and address of whoever submitted the message; the header itself stays.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.log-file-world-readableGlobalDirectiveGives all users on the node the right to read the engine’s logs; no by default.require-starttls<source>DirectiveWith this line the client must perform STARTTLS before anything except the greeting and service commands; the default is not to require it.server-url<vault>DirectiveThe name or address of the Vault server and, if needed, a port; the scheme is http or https.smtp-client-certificate<domain>DirectiveThe client certificate the node shows the receiver on an outgoing connection; its password is set as the second word and is optional.smtp-server-tls-min-versionGlobalDirectiveThe oldest protocol version the node is willing to accept from a submitting client; the default is TLS 1.2, stricter than for sending.smtp-tls-ca-file<domain>DirectiveA file with root certificates against which the chain presented by the receiver is verified; by default the list from the distribution is used.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-unencrypted-plain-auth<domain>DirectiveBoth mechanisms transmit the password in the conversation; without encryption it goes over the network in the clear.world-readable<acct-file>DirectiveGives all users of the node the right to read new accounting files; no by default.reuse-ssl-session<domain>set by the HubDirectiveSpeeds up a repeated handshake with the same host; does not work on TLS 1.3 and, according to the manual, is supported by only one known receiver.smtp-server-tls-ca-fileGlobalDirectiveA file with root certificates against which certificates presented by clients on incoming connections are verified.smtp-server-tls-cipher-server-preferenceGlobalDirectiveWith this line the cipher is chosen by the order in our configuration, not by the client’s order; the default is by the client.smtp-server-tls-ciphersGlobalDirectiveThe list of allowed ciphers in OpenSSL notation for incoming connections; applies to versions up to TLS 1.2, 1.3 has its own list.smtp-server-tls-max-versionGlobalDirectiveThe newest protocol version the node is willing to accept from a submitting client; unlimited by default.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.use-https<signals>DirectiveMakes inserted links encrypted; requires your own tracking domain with a certificate; off by default.api-key<inline-seeding>DirectiveExactly forty hexadecimal characters; without it seeding does not work at all.broken-auth-clients<source>deprecatedDirectiveOne of two directives in the catalog about which the manual says nothing except the word “deprecated”.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.log-tls<domain>DirectiveDetails of encryption negotiation with the receiver in the node’s log; the default is not to log.no-http-mgmt-sourceGlobaldeprecatedDirectiveThe negative half of the former pair; replaced by an http-access line with the none level.smtp-server-tls-allow-sslv3GlobaldeprecatedDirectivePowerMTA no longer supports SSLv3; the line is kept only for configuration compatibility.smtp-server-tls-allow-tlsv1GlobaldeprecatedDirectiveA separate switch for one protocol version for receiving; deprecated in PowerMTA 5.5 in favor of a pair of range bounds.smtp-server-tls-allow-tlsv1.1GlobaldeprecatedDirectiveA separate switch for one protocol version for receiving; deprecated in PowerMTA 5.5 in favor of a pair of range bounds.smtp-server-tls-allow-tlsv1.2GlobaldeprecatedDirectiveA separate switch for one protocol version for receiving; deprecated in PowerMTA 5.5 in favor of a pair of range bounds.smtp-server-tls-allow-tlsv1.3GlobaldeprecatedDirectiveA separate switch for one protocol version for receiving; deprecated in PowerMTA 5.5 in favor of a pair of range bounds.smtp-server-tls-v1.3-ciphersuitesGlobalDirectiveA separate list for version 1.3 on incoming connections; the default lists five modern suites.smtp-tls-allow-sslv3<domain>deprecatedDirectivePowerMTA no longer supports SSLv3; the line is kept only for configuration compatibility.smtp-tls-allow-tlsv1<domain>deprecatedDirectiveA separate switch for one protocol version; deprecated in PowerMTA 5.5 in favor of a pair of range bounds.smtp-tls-allow-tlsv1.1<domain>deprecatedDirectiveA separate switch for one protocol version; deprecated in PowerMTA 5.5 in favor of a pair of range bounds.smtp-tls-allow-tlsv1.2<domain>deprecatedDirectiveA separate switch for one protocol version; deprecated in PowerMTA 5.5 in favor of a pair of range bounds.smtp-tls-allow-tlsv1.3<domain>deprecatedDirectiveA separate switch for one protocol version; deprecated in PowerMTA 5.5 in favor of a pair of range bounds.smtp-tls-ciphers<domain>DirectiveA list of allowed ciphers in OpenSSL notation; applies to versions up to TLS 1.2, there is a separate line for 1.3.smtp-tls-max-version<domain>DirectiveThe newest protocol version the node is willing to negotiate when sending; unlimited by default.smtp-tls-v1.3-ciphersuites<domain>DirectiveA separate list for version 1.3 — its suites are structured differently than those of previous versions.tls-allow-sslv3<smtp-listener>deprecatedDirectivePowerMTA no longer supports SSLv3; the line is kept only for configuration compatibility.tls-allow-sslv3<transmissions-api-listener>deprecatedDirectivePowerMTA no longer supports SSLv3; the line is kept only for configuration compatibility.tls-allow-tlsv1<smtp-listener>deprecatedDirectiveA separate switch for one protocol version for the listener; deprecated in PowerMTA 5.5 in favor of a pair of bounds.tls-allow-tlsv1<transmissions-api-listener>deprecatedDirectiveA separate switch for one protocol version for the HTTP API input; deprecated in PowerMTA 5.5 in favor of a pair of bounds.tls-allow-tlsv1.1<smtp-listener>deprecatedDirectiveA separate switch for one protocol version for the listener; deprecated in PowerMTA 5.5 in favor of a pair of bounds.tls-allow-tlsv1.1<transmissions-api-listener>deprecatedDirectiveA separate switch for one protocol version for the HTTP API input; deprecated in PowerMTA 5.5 in favor of a pair of bounds.tls-allow-tlsv1.2<smtp-listener>deprecatedDirectiveA separate switch for one protocol version for the listener; deprecated in PowerMTA 5.5 in favor of a pair of bounds.tls-allow-tlsv1.2<transmissions-api-listener>deprecatedDirectiveA separate switch for one protocol version for the HTTP API input; deprecated in PowerMTA 5.5 in favor of a pair of bounds.tls-allow-tlsv1.3<smtp-listener>deprecatedDirectiveA separate switch for one protocol version for the listener; deprecated in PowerMTA 5.5 in favor of a pair of bounds.tls-allow-tlsv1.3<transmissions-api-listener>deprecatedDirectiveA separate switch for one protocol version for the HTTP API input; deprecated in PowerMTA 5.5 in favor of a pair of bounds.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.The receiver declares an encryption requirement in its DNS zoneMechanismThe node looks at the recipient domain’s DANE records and, if STARTTLS is required, sends only over an encrypted channel with a certificate verified by fingerprint.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.The receiver declares an encryption requirement on its websiteMechanismThe node fetches the recipient domain’s policy over HTTPS and, if it is in enforce mode, delivers only when the MX matches, the connection is encrypted and the certificate is verified.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.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.The encryption library is part of the distribution, not the systemMechanismOpenSSL comes inside the PowerMTA distribution, so the set of versions and ciphers is determined by the product version, not by system libraries.What is not allowed in FIPS modeMechanismIn FIPS mode only a validated set of algorithms is available: some familiar encryption and signing settings become unavailable.Authentication during deliveryMechanismThe node logs in on the receiver’s side with the login and password from the <domain> block — CRAM-MD5, LOGIN or PLAIN, if the receiver supports them.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.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.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.<smtp-user>Configuration blockOne block, one login: what confirms the login and which named source gives it rights; declared at the root of the file.<vault>Configuration blockThe block describes the connection to Vault; from there the node takes signing keys, certificates and their passwords without keeping them in its files.clear secretscacheCommandClears the secrets cache; on the next access they are requested from the store again.ConsoleMonitor screenRuns node console commands right from the browser; the page link exists only while the service is running.FIPS module configuration fileFileThe cryptographic module configuration file used when FIPS mode is enabled.