Re: relayd.conf.5: clarify "forward to", backup cascade and TLS scope

On Sun, 26 Jul 2026 13:10:55 +0200,
Rafael Sadowski <[email protected]> wrote:
> 
> 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
>

FWIW it reads OK and sane kirill@, but I think someone with native english
better to re-read it

> 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
> 

-- 
wbr, Kirill