From: Rafael Sadowski <rafael@sizeofvoid.org>
Subject: relayd.conf.5: clarify "forward to", backup cascade and TLS scope
To: tech@openbsd.org
Date: Sun, 26 Jul 2026 13:10:55 +0200

Since there is no configuration warning/hints and the logging wasn't
helpful, it took me quite a while to figure this out. I think this makes
the documentation a bit clearer:

- Make it explicit that the target of "forward to" can also be a
  table, "destination", or "nat lookup". Also add [transparent] and
  [with tls] to those synopses so they read parallel to the address
  form.

- Document that "with tls" is a relay-wide flag, matching what the
  code actually does (F_TLSCLIENT lives on the relay, not the table).

- Correct the backup wording: multiple additional "forward to"
  directives cascade as backups in the order given, not just ONE.

OK? Rafael

diff --git a/relayd.conf.5 b/relayd.conf.5
index d067574..5d313b9 100644
--- a/relayd.conf.5
+++ b/relayd.conf.5
@@ -629,6 +629,11 @@ Start the relay but immediately close any accepted connections.
 .Ar options ...
 .Xc
 Specify the address and port of the target host to connect to.
+The target may also be a table of hosts, a
+.Ic destination
+lookup, or a
+.Ic nat lookup ;
+these forms are described below.
 If the
 .Ic port
 option is not specified, the port from the
@@ -646,6 +651,18 @@ Verification of server certificates can be enabled by setting the
 .Ic ca file
 option in the protocol section.
 .Pp
+The
+.Ic with tls
+directive is a relay-wide flag.
+If any
+.Ic forward to
+directive of a relay specifies
+.Ic with tls ,
+all
+.Ic forward to
+directives of that relay will use client-side TLS when connecting to
+their hosts.
+.Pp
 The following options may be specified for forward directives:
 .Bl -tag -width Ds
 .It Ic inet
@@ -682,7 +699,10 @@ data, with the IP address and port of the remote host as well as the
 server.
 .El
 .It Xo
-.Ic forward to
+.Op Ic transparent
+.Ic forward
+.Op Ic with tls
+.Ic to
 .Pf < Ar table Ns >
 .Op Ic port Ar port
 .Ar options ...
@@ -691,15 +711,16 @@ Like the previous directive, but connect to a host from the specified
 table; see the
 .Sx Tables
 section above for information about table options.
-This directive can be specified multiple times \(en subsequent entries
-will be used as the backup table if all hosts in the previous table
-are down.
+This directive can be specified multiple times.
+The first entry is the primary target.
+Each subsequent entry is used as a backup, in the order given, if
+all hosts in the previous entry are down.
 At least one entry for the main table is mandatory.
-As above, use the
-.Ic with tls
-directive to enable client-side TLS mode when connecting to the remote host.
 .It Xo
-.Ic forward to
+.Op Ic transparent
+.Ic forward
+.Op Ic with tls
+.Ic to
 .Ic destination
 .Ar options ...
 .Xc
@@ -708,15 +729,15 @@ When redirecting connections with a divert-to rule in
 to a relay listening on localhost, this directive will
 look up the real destination address of the intended target host,
 allowing the relay to be run as a transparent proxy.
-If an additional
+Additional
 .Ic forward to
-directive to a specified address or table is present,
-it will be used as a backup if the lookup failed.
-As above, use the
-.Ic with tls
-directive to enable client-side TLS mode when connecting to the remote host.
+directives to specified addresses or tables may be given.
+They are tried as backups, in the order given, if the lookup fails.
 .It Xo
-.Ic forward to
+.Op Ic transparent
+.Ic forward
+.Op Ic with tls
+.Ic to
 .Ic nat lookup
 .Ar options ...
 .Xc