Haraka 3.1.5 → 3.1.7

package/bin/haraka

@@ -11,7 +11,6 @@ const os = require('node:os')
 
 const nopt = require('nopt')
 const utils = require('haraka-utils')
-const sprintf = require('sprintf-js').sprintf
 const base = path.join(__dirname, '..')
 const ver = utils.getVersion(base)
 const knownOpts = {
@@ -313,15 +312,7 @@ if (parsed.version) {
   ;(async () => {
     const qlist = await outbound.list_queue()
     for (const todo of qlist) {
-      console.log(
-        sprintf(
-          'Q: %s rcpt:%d from:%s domain:%s',
-          todo.file,
-          todo.rcpt_to.length,
-          todo.mail_from.toString(),
-          todo.domain,
-        ),
-      )
+      console.log(`Q: ${todo.file} rcpt:${todo.rcpt_to.length} from:${todo.mail_from} domain:${todo.domain}`)
     }
     process.exit()
   })()
@@ -379,12 +370,14 @@ if (parsed.version) {
   console.log('')
   for (const hook of getHooks()) {
     if (!plugins.registered_hooks[hook]) continue
-    console.log(sprintf("%'--80s", `Hook: ${hook} `))
-    console.log(sprintf('%-35s %-35s %-4s %-3s', 'Plugin', 'Method', 'Prio', 'T/O'))
-    console.log(sprintf("%'-80s", ''))
+    console.log(`Hook: ${hook} `.padEnd(80, '-'))
+    console.log(`${'Plugin'.padEnd(35)} ${'Method'.padEnd(35)} ${'Prio'.padEnd(4)} T/O`)
+    console.log('-'.repeat(80))
     for (let p = 0; p < plugins.registered_hooks[hook].length; p++) {
       const item = plugins.registered_hooks[hook][p]
-      console.log(sprintf('%-35s %-35s %4d %3d', item.plugin, item.method, item.priority, item.timeout))
+      console.log(
+        `${item.plugin.padEnd(35)} ${item.method.padEnd(35)} ${String(item.priority).padStart(4)} ${String(item.timeout).padStart(3)}`,
+      )
     }
     console.log('')
   }

package/config/plugins

@@ -12,7 +12,6 @@
 # status
 # process_title
 # syslog
-# watch
 
 # CONNECT
 # ----------
@@ -20,7 +19,6 @@
 # karma
 # relay
 # access
-# p0f
 # geoip
 # asn
 # fcrdns
@@ -49,7 +47,6 @@ mail_from.is_resolvable
 # At least one rcpt_to plugin is REQUIRED for inbound email.
 rcpt_to.in_host_list
 # qmail-deliverable
-# rcpt_to.routes
 
 # DATA
 # ----------

package/config/smtp_forward.ini

@@ -19,3 +19,13 @@ port=2555
 ; should outbound messages be delivered by smtp_forward?
 ; see #1472 and #2795
 ; enable_outbound=false
+
+; Options here override the same option in tls.ini [main]
+[tls]
+; rejectUnauthorized=true
+; minVersion=TLSv1.2
+; ciphers=ECDHE-RSA-AES256-GCM-SHA384:ECDHE-RSA-AES128-GCM-SHA256
+; key=outbound_tls_key.pem
+; cert=outbound_tls_cert.pem
+; no_tls_hosts[]=10.0.0.5
+; force_tls_hosts[]=mx.example.com

package/config/smtp_proxy.ini

@@ -15,3 +15,13 @@ port=2555
 ; should outbound messages be delivered by smtp_proxy?
 ; see https://github.com/haraka/Haraka/issues/1472
 ; enable_outbound=true
+
+; Options here override the same option in tls.ini [main]
+[tls]
+; rejectUnauthorized=true
+; minVersion=TLSv1.2
+; ciphers=ECDHE-RSA-AES256-GCM-SHA384:ECDHE-RSA-AES128-GCM-SHA256
+; key=outbound_tls_key.pem
+; cert=outbound_tls_cert.pem
+; no_tls_hosts[]=10.0.0.5
+; force_tls_hosts[]=mx.example.com

package/connection.js

@@ -329,7 +329,7 @@ class Connection {
                 } catch (err) {
                     if (err.stack) {
                         this.logerror(`${method} failed: ${err}`)
-                        err.stack.split('\n').forEach(this.logerror)
+                        for (const line of err.stack.split('\n')) this.logerror(line)
                     } else {
                         this.logerror(`${method} failed: ${err}`)
                     }
@@ -1234,6 +1234,13 @@ class Connection {
         if (!host) {
             return this.respond(501, 'HELO requires domain/address - see RFC-2821 4.1.1.1')
         }
+        // RFC 5321 §4.1.1.1: the domain/address-literal cannot contain
+        // control characters. process_line() only strips the first \r?\n,
+        // so a bare \r could otherwise survive into hello.host and the
+        // generated Received: header / logs (header injection).
+        if (/[\x00-\x1f\x7f]/.test(host)) {
+            return this.respond(501, 'HELO syntax error - see RFC-2821 4.1.1.1')
+        }
 
         this.reset_transaction(() => {
             this.set('hello', 'verb', 'HELO')
@@ -1248,6 +1255,10 @@ class Connection {
         if (!host) {
             return this.respond(501, 'EHLO requires domain/address - see RFC-2821 4.1.1.1')
         }
+        // RFC 5321 §4.1.1.1: reject control chars (see cmd_helo).
+        if (/[\x00-\x1f\x7f]/.test(host)) {
+            return this.respond(501, 'EHLO syntax error - see RFC-2821 4.1.1.1')
+        }
 
         this.reset_transaction(() => {
             this.set('hello', 'verb', 'EHLO')
@@ -1320,10 +1331,10 @@ class Connection {
 
         // Get rest of key=value pairs
         const params = {}
-        results.forEach((param) => {
+        for (const param of results) {
             const kv = param.match(/^([^=]+)(?:=(.+))?$/)
             if (kv) params[kv[1].toUpperCase()] = kv[2] || null
-        })
+        }
 
         // Parameters are only valid if EHLO was sent
         if (!this.esmtp && Object.keys(params).length > 0) {
@@ -1379,10 +1390,10 @@ class Connection {
 
         // Get rest of key=value pairs
         const params = {}
-        results.forEach((param) => {
+        for (const param of results) {
             const kv = param.match(/^([^=]+)(?:=(.+))?$/)
             if (kv) params[kv[1].toUpperCase()] = kv[2] || null
-        })
+        }
 
         // Parameters are only valid if EHLO was sent
         if (!this.esmtp && Object.keys(params).length > 0) {
@@ -1433,17 +1444,23 @@ class Connection {
             this.transaction.notes.authentication_results = []
         }
 
+        // Strip CR/LF and other control chars: an attacker-influenced
+        // value (e.g. a failed AUTH username, see auth_base) must not be
+        // able to inject extra header lines into Authentication-Results.
+        // The legitimate folding (;\r\n\t) is added by the join below.
+        const ar_clean = (s) => String(s).replace(/[\x00-\x1f\x7f]/g, '')
+
         // if message, store it in the appropriate note
         if (message) {
             if (has_tran === true) {
-                this.transaction.notes.authentication_results.push(message)
+                this.transaction.notes.authentication_results.push(ar_clean(message))
             } else {
-                this.notes.authentication_results.push(message)
+                this.notes.authentication_results.push(ar_clean(message))
             }
         }
 
         // assemble the new header
-        let header = [this.local.host, ...this.notes.authentication_results]
+        let header = [ar_clean(this.local.host), ...this.notes.authentication_results]
         if (has_tran === true) {
             header = [...header, ...this.transaction.notes.authentication_results]
         }

package/docs/Connection.md

@@ -1,66 +1,153 @@
 # Connection Object
 
-For each connection to Haraka there is one connection object.
+For each connection to Haraka there is one connection object. It is the first argument passed to almost every plugin hook and is the primary context object plugins use to inspect and act on the SMTP session.
 
-## API
+## Properties
 
-- connection.uuid
+### connection.uuid
 
-A unique UUID for this connection.
+A unique UUID for this connection. Used as the connection identifier in logs and inherited by `transaction.uuid`.
 
-- connection.remote - info about the host that is connecting to Haraka.
+### connection.remote
 
-  - ip - remote IP address
-  - host - reverse DNS of the remote hosts IP
-  - is_private - true if the remote IP is from a private (loopback, RFC 1918, link local, etc.) IP address.
-  - is_local - true if the remote IP is localhost (loopback, link local)
+Information about the host connecting to Haraka.
 
-- connection.local - info about the host that is running Haraka
+- `ip` — remote IP address
+- `port` — remote TCP port
+- `host` — reverse DNS of the remote IP (populated by the `connect.rdns_access` / `connect` hooks)
+- `info` — free-form descriptor (e.g. populated by FCrDNS)
+- `closed` — `true` once the remote end has dropped the connection
+- `is_private` — `true` if the remote IP is in a private range (RFC 1918, loopback, link-local, etc.)
+- `is_local` — `true` if the remote IP is localhost / loopback
 
-  - ip - the IP of the Haraka server, as reported by the OS
-  - port - the port number handling the connection.
-  - host - the rDNS host name of the local IP
+### connection.local
 
-- connection.proxy - proxy properties set when a proxy is used (like haproxy)
+Information about the Haraka server endpoint handling this connection.
 
-  - allowed - if the remote IP has proxy permission
-  - ip - when proxied, the proxy servers IP address
-  - type - currently null or 'haproxy'
+- `ip` — the IP of the Haraka server, as reported by the OS
+- `port` — the port number handling the connection
+- `host` — the primary host name of the Haraka server
+- `info` — `Haraka` (with `/<version>` appended when `headers.show_version` is enabled in `connection.ini`)
 
-- connection.hello
+### connection.hello
 
-  - verb - Either 'EHLO' or 'HELO' whichever the remote end used
-  - host - The hostname given with HELO or EHLO
+The greeting given by the client.
 
-- connection.notes
+- `verb` — `EHLO` or `HELO`, whichever the client used
+- `host` — the hostname argument
 
-An object which persists during the lifetime of the connection. It is used to store connection-specific properties. See also, connection.results and [haraka-notes](https://github.com/haraka/haraka-notes).
+### connection.tls
 
-- connection.transaction
+State of the TLS layer on this connection.
 
-The current transaction object, valid after MAIL FROM, and destroyed at queue
-time, RSET time, or if MAIL FROM was rejected. See the Transaction Object
-documentation file.
+- `enabled` — `true` once STARTTLS has been negotiated (or the listener is `smtps`)
+- `advertised` — `true` if Haraka advertised STARTTLS in the EHLO response
+- `verified` — `true` if the peer certificate validated against the configured CAs
+- `cipher` — the negotiated cipher object (`name`, `version`, …)
+- `verifyError` — the verification error, if any
+- `peerCertificate` — the parsed peer certificate (when client certs are used)
 
-- connection.relaying
+### connection.proxy
 
-A boolean flag to say whether this connection is allowed to relay mails (i.e.
-deliver mails outbound). This is normally set by SMTP AUTH, or sometimes via
-an IP address check.
+Proxy-protocol state, set when the connection arrived via HAProxy (see [HAProxy.md](HAProxy.md)).
 
-- connection.current_line
+- `allowed` — `true` if the remote IP is in the `haproxy.hosts` allow-list
+- `ip` — the proxy server's IP (the real client IP appears in `connection.remote.ip` once PROXY is parsed)
+- `type` — currently `null` or `'haproxy'`
 
-For low level use. Contains the current line sent from the remote end,
-verbatim as it was sent. Can be useful in certain botnet detection techniques.
+### connection.notes
 
-- connection.last_response
+A plain object that persists for the lifetime of the connection. Use it to share state between plugin hooks. For structured per-test results prefer `connection.results`. See also [haraka-notes](https://github.com/haraka/haraka-notes).
 
-Contains the last SMTP response sent to the client.
+### connection.results
 
-- connection.remote_closed
+Structured store for plugin results. See [haraka-results](https://github.com/haraka/haraka-results).
 
-For low level use. This value is set when the remote host drops the connection.
+### connection.transaction
 
-- connection.results
+The current `Transaction` object. Valid between `MAIL FROM` and the end of `queue` / `RSET` (or until `MAIL FROM` is rejected). See [Transaction.md](Transaction.md).
 
-Store results of processing in a structured format. See [haraka-results](https://github.com/haraka/haraka-results)
+### connection.relaying
+
+Boolean. `true` if this connection is allowed to relay (i.e. deliver mail outbound). Normally set by an auth plugin or an IP allow-list. Reading or writing this property transparently routes through the current transaction when one exists, so the flag survives across multiple messages in a single connection only when set on the connection.
+
+### connection.capabilities
+
+Array of ESMTP capabilities advertised in the EHLO response (e.g. `['PIPELINING', '8BITMIME', 'SIZE 0', 'STARTTLS', 'AUTH PLAIN LOGIN']`). Plugins may push additional capability strings during the `capabilities` hook.
+
+### connection.esmtp
+
+`true` if the client used `EHLO` (as opposed to `HELO`).
+
+### connection.pipelining
+
+`true` once Haraka has advertised, and the client has used, SMTP pipelining.
+
+### connection.early_talker
+
+`true` if the client sent data before Haraka issued its banner — a
+common spam-bot signal.
+
+### connection.tran_count
+
+Number of transactions completed on this connection.
+
+### connection.rcpt_count / connection.msg_count
+
+Per-disposition counters (`accept`, `tempfail`, `reject`) tracking
+recipients and full messages on this connection.
+
+### connection.start_time
+
+Connection start time, in epoch milliseconds (`Date.now()`).
+
+### connection.last_response
+
+The last SMTP response line Haraka sent to the client.
+
+### connection.last_reject
+
+The text of the last rejection issued to this client (used by
+`max_unrecognized_commands` and similar throttling plugins).
+
+### connection.errors
+
+Count of protocol errors on this connection.
+
+### connection.current_line
+
+Low-level. The current line as sent by the remote end, verbatim. Useful
+for botnet fingerprinting.
+
+### connection.state
+
+The connection's protocol state — one of the values in `haraka-constants`'s `connection.state` table (`PAUSE`, `CMD`, `LOOP`, `DATA`, `DISCONNECTING`, `DISCONNECTED`).
+
+## Methods
+
+### connection.respond(code, msg, cb)
+
+Send an SMTP response to the client. `code` is the numeric SMTP code, `msg` is the human-readable text (a string or an array of strings for a multi-line response). The callback fires when the response has been written.
+
+### connection.disconnect()
+
+Close the connection after running the `disconnect` hook.
+
+### connection.reset_transaction(cb)
+
+Tear down the current transaction (equivalent to `RSET`) and invoke `cb` when complete.
+
+### connection.set(path, value)
+
+Assign a nested property safely, e.g. `connection.set('remote.host', 'mx.example.com')`. Setting `remote.ip`
+automatically recomputes `remote.is_private` / `remote.is_local`.
+
+### connection.get(path)
+
+Read a nested property, returning `undefined` if any segment is missing.
+
+### connection.loginfo / lognotice / logwarn / logerror / logdebug / logcrit / logalert / logemerg / logprotocol / logdata
+
+Log at the named level. Each takes either `(msg)` or `(plugin, msg, data)`.
+
+See [Logging.md](Logging.md).

package/docs/CoreConfig.md

@@ -1,76 +1,94 @@
 # Core Configuration Files
 
-See [Logging](Logging.md).
-
-The Haraka core reads some configuration files to determine a few actions:
-
-- smtp.yaml or smtp.json
-
-If either of these files exist then they are loaded first.
-This file is designed to use the JSON/YAML file overrides documented in
-[haraka-config](https://github.com/haraka/haraka-config) to optionally provide the entire configuration in a single file.
-
-- plugins
-
-The list of plugins to load
-
-- smtp.ini
-
-  Keys:
-
-  - listen_host, port - the host and port to listen on (default: ::0 and 25)
-  - listen - (default: [::0]:25) Comma separated IP:Port addresses to listen on
-  - inactivity_time - how long to let clients idle in seconds (default: 300)
-  - nodes - specifies how many processes to fork. The string "cpus" will fork as many children as there are CPUs (default: 1, which enables cluster mode with a single process)
-  - user - optionally a user to drop privileges to. Can be a string or UID.
-  - group - optionally a group to drop privileges to. Can be a string or GID.
-  - ignore_bad_plugins - If a plugin fails to compile by default Haraka will stop at load time.
-    If, however, you wish to continue on without that plugin's facilities, then
-    set this config option
-  - daemonize - enable this to cause Haraka to fork into the background on start-up (default: 0)
-  - daemon_log_file - (default: /var/log/haraka.log) where to redirect stdout/stderr when daemonized
-  - daemon_pid_file - (default: /var/run/haraka.pid) where to write a PID file to
-  - graceful_shutdown - (default: false) enable this to wait for sockets on shutdown instead of closing them quickly
-  - force_shutdown_timeout - (default: 30) number of seconds to wait for a graceful shutdown
-
-- me
-
-  A name to use for this server. Used in received lines and elsewhere. Setup
-  by default to be your hostname.
-
-- connection.ini
-
-  See inline comments in connection.ini for the following settings:
-
-  - main.spool_dir
-  - main.spool_after
-  - haproxy.hosts_ipv4
-  - haproxy.hosts_ipv6
-  - headers.\*
-  - max.bytes
-  - max.line_length
-  - max.data_line_length
-  - max.mime_parts
-  - message.greeting
-  - message.close
-  - smtputf8
-  - strict_rfc1869
-  - uuid.deny_chars
-  - uuid.banner_bytes
-
-- plugin_timeout
-
-  Seconds to allow a plugin to run before the next hook is called automatically
-  default: 30
-
-  Note also that each plugin can have a `config/<plugin_name>.timeout`
-  file specifying a per-plugin timeout. In this file you can set a timeout of 0 to mean that this plugin's hooks never time out. Use this with care.
-
-  If the plugin is in a sub-directory of plugins, then you must create this file
-  in the equivalent path e.g. the queue/smtp_forward would need a timeout file in `config/queue/smtp_forward.timeout`
-
-- outbound.ini
-
-- outbound.bounce_message
-
-  The bounce message if delivery of the message fails. The default is normally fine. Bounce messages contain a number of template replacement values which are best discovered by looking at the source code.
+Haraka reads the configuration files in this document directly. Plugins typically own their own files (named after the plugin); see the individual plugin docs.
+
+See also [Logging](Logging.md), [HAProxy](HAProxy.md), and [Outbound](Outbound.md).
+
+## smtp.yaml / smtp.json
+
+If either of these files exists it is loaded first. It uses the YAML/JSON override mechanism from [haraka-config](https://github.com/haraka/haraka-config) and can provide the entire configuration as a single file.
+
+## plugins
+
+A newline-delimited list of plugins to load. Lines starting with `#` are ignored.
+
+## smtp.ini
+
+Controls the SMTP listener and the master process.
+
+| Key | Default | Description |
+| --- | --- | --- |
+| `listen` | `[::0]:25` | Comma-separated `IP:port` pairs to listen on (e.g. `127.0.0.1:25,127.0.0.1:587`). |
+| `listen_host` / `port` | — | Legacy. If set, a `<listen_host>:<port>` entry is prepended to `listen`. Prefer `listen`. |
+| `smtps_port` | `465` | Port used by the optional implicit-TLS listener. |
+| `public_ip` | none | The server's public IP. Helps NAT-aware plugins (SPF, GeoIP) when Haraka is behind NAT. If `stun` is on `$PATH` Haraka will try to discover it automatically. |
+| `inactivity_timeout` | `300` | Idle seconds before a client socket is dropped. |
+| `nodes` | `1` | Number of worker processes to fork. The string `cpus` forks one per CPU. |
+| `user` / `group` | — | User and group to drop privileges to (name or numeric ID). |
+| `ignore_bad_plugins` | `0` | If `1`, Haraka starts even if some plugins fail to compile. |
+| `daemonize` | `false` | If `true`, fork into the background at start-up. |
+| `daemon_log_file` | `/var/log/haraka.log` | Where to redirect stdout/stderr when daemonized. |
+| `daemon_pid_file` | `/var/run/haraka.pid` | Where to write the PID file. |
+| `graceful_shutdown` | `false` | If `true`, wait for in-flight sockets on shutdown. |
+| `force_shutdown_timeout` | `30` | Seconds to wait before forcing shutdown. |
+
+## me
+
+A single-line file containing the server name used in `Received:` headers
+and elsewhere. Defaults to `hostname(1)`.
+
+## connection.ini
+
+Per-connection limits and behaviours. See inline comments in the shipped
+`config/connection.ini` for full details.
+
+| Section / Key | Default | Description |
+| --- | --- | --- |
+| `main.spool_dir` | `/tmp` | Directory for temporary spool files. |
+| `main.spool_after` | `-1` | Size (bytes) at which to spool the message to disk. `-1` never spools; `0` always spools. |
+| `main.strict_rfc1869` | `false` | Reject `MAIL FROM` / `RCPT TO` that violates RFC 1869/821 (spurious spaces, missing brackets). |
+| `main.smtputf8` | `true` | Advertise `SMTPUTF8` (RFC 6531). |
+| `haproxy.hosts` | empty | Array of IPs/CIDRs allowed to send the PROXY protocol. See [HAProxy.md](HAProxy.md). |
+| `headers.add_received` | `true` | Add a `Received:` header to incoming mail. |
+| `headers.clean_auth_results` | `true` | Strip inbound `Authentication-Results:` headers before plugins run. |
+| `headers.show_version` | `true` | Include the Haraka version in the SMTP banner and the `Received:` header. |
+| `headers.max_lines` | `1000` | Maximum number of header lines accepted. |
+| `headers.max_received` | `100` | Maximum number of `Received:` headers before mail is rejected as looping. |
+| `max.bytes` | `26214400` | Maximum message size (advertised as the `SIZE` ESMTP extension). |
+| `max.line_length` | `512` | SMTP command line length cap. Clients exceeding this are dropped with `521`. |
+| `max.data_line_length` | `992` | Maximum line length in `DATA`. Longer lines are wrapped with `CRLF SPACE` (Sendmail behaviour) and `transaction.notes.data_line_length_exceeded` is set. |
+| `max.mime_parts` | `1000` | Maximum MIME parts per message. |
+| `message.greeting` | — | Array. Lines used as the SMTP greeting banner. |
+| `message.helo` | `Haraka is at your service.` | Reply text for `HELO` / `EHLO`. |
+| `message.close` | `closing connection. …` | Reply text on `QUIT`. |
+| `uuid.banner_chars` | `6` | Number of UUID chars included in the SMTP banner (`0` to disable, `40` for the full UUID). |
+| `uuid.deny_chars` | `0` | Number of UUID chars prepended (in brackets) to deny messages. |
+
+## plugin_timeout
+
+Single-integer file. Seconds to allow a plugin hook to run before Haraka
+automatically advances to the next hook. Default: `30`.
+
+A per-plugin override may be placed at `config/<plugin>.timeout`. A value
+of `0` disables the timeout for that plugin — use with care. Plugins in
+subdirectories need a matching path: `queue/smtp_forward` looks for
+`config/queue/smtp_forward.timeout`.
+
+## outbound.ini
+
+Configures the outbound delivery engine. The most common keys are listed
+below; see [Outbound.md](Outbound.md) for the full set.
+
+| Key | Default | Description |
+| --- | --- | --- |
+| `disabled` | `false` | Disable outbound delivery entirely. |
+| `concurrency_max` | `100` | Maximum simultaneous outbound deliveries. |
+| `enable_tls` | `true` | Use STARTTLS opportunistically on outbound deliveries. |
+| `maxTempFailures` | `13` | Number of temporary failures before a message bounces. |
+| `always_split` | `false` | Create one queue file per recipient instead of one per destination domain. |
+| `received_header` | `Haraka outbound` | Value used in the outbound `Received:` header. |
+| `inet_prefer` | `default` | IP family preference for MX lookups: `v4`, `v6`, or `default` (OS preference). |
+
+## outbound.bounce_message
+
+Template used when an outbound message bounces. The default is usually fine. Available template variables are documented in the source of `outbound/hmail.js`.

package/docs/HAProxy.md

@@ -1,43 +1,59 @@
-# HAProxy PROXY protocol extension support
+# HAProxy PROXY Protocol Support
 
-Haraka supports PROXY protocol [1].
+Haraka supports version 1 (text format) of the HAProxy [PROXY protocol][proxy-spec], which allows an upstream proxy to tell Haraka the real client IP and port. DNSBLs, allow-lists, and other IP-based plugins then see the original client rather than the proxy.
 
-This allows an upstream proxy to pass the IP address and port of the remote client. Haraka will use the remote IP instead of the socket IP address (which is the proxy). This allows DNSBLs and access control lists to use the correct source address.
+The PROXY v2 binary header is not currently supported.
 
-Support is disabled by default. Attempts to send a PROXY command will return a DENYSOFTDISCONNECT error. DENYSOFT is used to prevent configuration errors from rejecting valid mail.
+## Configuration
 
-To enable support for PROXY you must populate connection.ini[haproxy]hosts[] with the IP addresses of the HAProxy hosts that MUST send the PROXY command. Ranges can be specified with CIDR notation.
+PROXY support is disabled by default. To enable it, list the IPs (or CIDRs) of trusted proxies in `connection.ini`:
 
-When a proxy host connects to Haraka, a banner is not sent. Instead Haraka awaits the PROXY command. The connection will timeout with `421 PROXY timed out` if the command is not sent within 30 seconds.
+```ini
+[haproxy]
+hosts[] = 192.0.2.4
+hosts[] = 192.0.2.5/30
+hosts[] = 2001:db8::1
+```
+
+Connections from any other IP get a `DENYSOFTDISCONNECT` if they send a `PROXY` command. `DENYSOFT` is deliberate — it avoids permanently rejecting valid mail when a misconfiguration causes a legitimate proxy to fall outside the allow-list.
+
+When a listed proxy connects, Haraka **does not** send the SMTP banner; it waits for the `PROXY` command. If none arrives within 30 seconds the connection is closed with `421 PROXY timed out`.
 
-NOTE: because Haraka does not send a banner when a listed HAProxy host connects you must set check-send-proxy to ensure that the service checks send a PROXY command before they run.
+## What plugins see after PROXY is parsed
 
-[1] http://haproxy.1wt.eu/download/1.5/doc/proxy-protocol.txt
+| Property | Value |
+| --- | --- |
+| `connection.remote.ip` / `.port` | the **real** client address from the PROXY header |
+| `connection.local.ip` / `.port` | the destination IP/port from the PROXY header |
+| `connection.proxy.allowed` | `true` |
+| `connection.proxy.ip` | the proxy's address (i.e. the original socket peer) |
+| `connection.proxy.type` | `'haproxy'` |
+| `connection.notes.proxy` | full parsed record: `{ type, proto, src_ip, src_port, dst_ip, dst_port, proxy_ip }` |
 
-HAProxy supports the PROXY protocol in version 1.5 or later.
+## HAProxy configuration
 
-Here is an example listener section for haproxy.cfg:
+You need HAProxy ≥ 1.5. The `send-proxy` option on each backend server tells HAProxy to emit the v1 header on every connection.
 
 ```
 listen smtp :25
-        mode tcp
-        option tcplog
-        option smtpchk
-        balance roundrobin
-        server smtp1 ip.of.haraka.server1:25 check-send-proxy check inter 10s send-proxy
-        server smtp2 ip.of.haraka.server2:25 check-send-proxy check inter 10s send-proxy
-        server smtp3 ip.of.haraka.server3:25 check-send-proxy check inter 10s send-proxy
-        server smtp4 ip.of.haraka.server4:25 check-send-proxy check inter 10s send-proxy
-        server smtp5 ip.of.haraka.server5:25 check-send-proxy check inter 10s send-proxy
+    mode tcp
+    option tcplog
+    balance roundrobin
+    server smtp1 ip.of.haraka1:25 check-send-proxy check inter 10s send-proxy
+    server smtp2 ip.of.haraka2:25 check-send-proxy check inter 10s send-proxy
 ```
 
-The important part is `send-proxy` which causes HAProxy to send the PROXY extension on connection.
+The `check-send-proxy` flag is required for HAProxy's health checks because Haraka does not respond with a banner before the PROXY header arrives.
 
-When using `option smtpchk` you will see CONNRESET errors reported in the Haraka logs as smtpchk drops the connection before the HELO response is still being written. You can use the `option tcp-check` instead to provide a better service check by having the check wait for the banner, send QUIT and then check the response:
+### Health checks
+
+`option smtpchk` drops the connection mid-handshake and shows up as `CONNRESET` in Haraka's logs. A cleaner check is to use `tcp-check` and politely close with `QUIT`:
 
 ```
-        option tcp-check
-        tcp-check expect rstring ^220\
-        tcp-check send QUIT\r\n
-        tcp-check expect rstring ^221\
+    option tcp-check
+    tcp-check expect rstring ^220
+    tcp-check send QUIT\r\n
+    tcp-check expect rstring ^221
 ```
+
+[proxy-spec]: https://www.haproxy.org/download/2.8/doc/proxy-protocol.txt