1 .\" $OpenBSD: relayd.conf.5,v 1.218 2026/05/19 05:06:41 rsadowski Exp $
3 .\" Copyright (c) 2006 - 2016 Reyk Floeter <reyk@openbsd.org>
4 .\" Copyright (c) 2006, 2007 Pierre-Yves Ritschard <pyr@openbsd.org>
6 .\" Permission to use, copy, modify, and distribute this software for any
7 .\" purpose with or without fee is hereby granted, provided that the above
8 .\" copyright notice and this permission notice appear in all copies.
10 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
11 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
12 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
13 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
14 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
15 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
16 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
18 .Dd $Mdocdate: May 19 2026 $
23 .Nd relay daemon configuration file
26 is the configuration file for the relay daemon,
30 is divided into the following main sections:
33 Definitions of variables that can be used later, simplifying the
35 .It Sx Global configuration
38 Do note that the config file allows global settings to be added after
39 defining tables in the config file, but those tables will use the
40 built-in defaults instead of the global settings below them.
42 Table definitions describe a list of hosts,
43 in a similar fashion to
46 They are used for relay, redirection, and router target selection with
47 the described options and health checking on the host they contain.
49 Redirections are translated to
51 rdr-to rules for stateful forwarding to a target host from a
52 health-checked table on layer 3.
54 Relays allow application layer load balancing, TLS acceleration, and
55 general purpose TCP proxying on layer 7.
57 Protocols are predefined settings and filter rules for relays.
59 Routers are used to insert routes with health-checked gateways for
66 can be specified by IPv4 address, IPv6 address, interface name,
67 interface group, or DNS hostname.
68 If the address is an interface name,
70 will look up the first IPv4 address and any other IPv4 and IPv6
71 addresses of the specified network interface.
74 can be specified by number or name.
75 The port name to number mappings are found in the file
81 The current line can be extended over multiple lines using a backslash
83 Comments can be put anywhere in the file using a hash mark
85 and extend to the end of the current line.
86 Care should be taken when commenting out multi-line text:
87 the comment is effective until the end of the entire block.
89 Arguments not beginning with a letter, digit, or underscore
92 Additional configuration files can be included with the
95 .Bd -literal -offset indent
96 include "/etc/relayd.conf.local"
99 A macro is defined with a command of the form
100 .Ar name Ns = Ns Ar value .
103 can contain letters, digits, and underscores and cannot be a reserved word
109 Within unquoted arguments, the string
115 .Bd -literal -offset indent
123 .Ss Global configuration
124 Here are the settings that can be set globally:
126 .It Ic agentx Oo Ic context Ar context Oc Oo Ic path Ar path Oc
129 metrics via an agentx compatible
131 daemon by connecting to
133 Metrics can be found under the relaydMIBObjects subtree
134 .Pq enterprises.30155.3 .
137 is omitted, it will default to
138 .Pa /var/agentx/master .
140 is the SNMPv3 context and can usually be omitted.
141 .It Ic interval Ar number
142 Set the interval in seconds at which the hosts will be checked.
143 The default interval is 10 seconds.
146 .Pq Ic state changes Ns | Ns Ic host checks
153 that were run, even if the state didn't change.
154 The host state can be
156 (the health check completed successfully),
158 (the host is down or didn't match the check criteria),
161 (the host is disabled or has not been checked yet).
163 .Ic log connection Op Ic errors
165 When using relays, log all TCP connections.
167 .Ic connection errors .
168 .It Ic prefork Ar number
169 When using relays, run the specified number of processes to handle
171 This increases the performance and prevents delays when connecting
174 runs 3 relay processes by default and every process will handle
175 all configured relays.
176 .It Ic socket Qo Ar path Qc
177 Create a control socket at
180 .Pa /var/run/relayd.sock
182 .It Ic timeout Ar number
183 Set the global timeout in milliseconds for checks.
184 This can be overridden by the timeout value in the table definitions.
185 The default timeout is 200 milliseconds and it must not exceed the
187 The default value is optimized for checks within the
188 same collision domain \(en use a higher timeout, such as 1000 milliseconds,
189 for checks of hosts in other subnets.
190 If this option is to be set, it should be placed before overrides in tables.
193 Tables are used to group a set of hosts as the target for redirections
194 or relays; they will be mapped to a
196 table for redirections.
197 Tables may be defined with the following attribute:
198 .Bl -tag -width disable
200 Start the table disabled \(en no hosts will be checked in this table.
201 The table can be later enabled through
205 Each table must contain at least one host
207 multiple hosts are separated by newline, comma, or whitespace.
208 Host entries may be defined with the following attributes:
209 .Bl -tag -width retry
210 .It Ic ip ttl Ar number
211 Change the default time-to-live value in the IP headers for host checks.
212 .It Ic parent Ar number
213 The optional parent option inherits the state from a parent
214 host with the specified identifier.
215 The check will be skipped for this host and copied from the parent host.
216 This can be used to prevent multiple checks on hosts with multiple IP
217 addresses for the same service.
218 The host identifiers are sequentially assigned to the configured hosts
219 starting with 1; it can be shown with the
223 .It Ic priority Ar number
224 Change the route priority used when adding a route.
225 If not specified, the kernel will set a priority of 8
227 In ordinary use, a fallback route should be added statically with a very
228 high (e.g. 52) priority.
229 Unused in all other modes.
230 .It Ic retry Ar number
231 The optional retry option adds a tolerance for failed host checks;
232 the check will be retried for
234 more times before setting the host state to down.
235 If this table is used by a relay, it will also specify the number of
236 retries for outgoing connection attempts.
240 .Bd -literal -offset indent
241 table <service> { 192.168.1.1, 192.168.1.2, 192.168.2.3 }
242 table <fallback> disable { 10.1.5.1 retry 2 }
245 listen on www.example.com port 80
246 forward to <service> check http "/" code 200
247 forward to <fallback> check http "/" code 200
253 directives in redirections or relays with a set of general options,
254 health-checking rules, and timings;
259 sections for more information about the forward context.
260 Table specific configuration directives are described below.
261 Multiple options can be appended to
263 directives, separated by whitespaces.
265 The following options will configure the health-checking method for
266 the table, and is mandatory for redirections:
269 .Ic check http Ar path
270 .Op Ic host Ar hostname
273 For each host in the table, verify that retrieving the URL
275 gives the HTTP return code
279 is specified, it is used as the
281 header to query a specific hostname at the target host.
282 To validate the HTTP return code, use this shell command:
283 .Bd -literal -offset indent
284 $ echo -n "HEAD <path> HTTP/1.0\er\en\er\en" | \e
285 nc <host> <port> | head -n1
288 This prints the status header including the actual return code:
289 .Bd -literal -offset indent
293 .Ic check https Ar path
294 .Op Ic host Ar hostname
297 This has the same effect as above but wraps the HTTP request in TLS.
299 .Ic check http Ar path
300 .Op Ic host Ar hostname
303 For each host in the table, verify that retrieving the URL
305 produces non-binary content whose message digest matches the defined string.
306 The algorithm used is determined by the string length of the
308 argument, either SHA1 (40 characters) or MD5 (32 characters).
311 is specified, it is used as the
313 header to query a specific hostname at the target host.
314 The digest does not take the HTTP headers into account.
315 Do not specify a binary object (such as a graphic) as the target of the
318 expects the data returned to be a string.
319 To compute the digest, use this simple command:
320 .Bd -literal -offset indent
321 $ ftp -o - http://host[:port]/path | sha1
324 This gives a digest that can be used as-is in a digest statement:
325 .Bd -literal -offset indent
326 a9993e36476816aba3e25717850c26c9cd0d89d
329 .Ic check https Ar path
330 .Op Ic host Ar hostname
333 This has the same effect as above but wraps the HTTP request in TLS.
335 Ping hosts in this table to determine whether they are up or not.
336 This method will automatically use ICMP or ICMPV6 depending on the
337 address family of each host.
338 .It Ic check script Ar path
339 Execute an external program to check the host state.
340 The program will be executed for each host by specifying the hostname
342 .Bd -literal -offset indent
343 /usr/local/bin/checkload.pl front-www1.private.example.com
347 expects a positive return value on success and zero on failure.
348 Note that the script will be executed with the privileges of the
350 user and terminated after
360 For each host in the table, a TCP connection is established on the
364 Incoming data is then read and is expected to match against
366 using shell globbing rules.
369 is an empty string or
371 then nothing is sent on the connection and data is immediately
373 This can be useful with protocols that output a banner like
378 the transaction will occur in a TLS tunnel.
380 .Ic check binary send
386 For each host in the table, a TCP connection is established on the
387 port specified, then the
390 is converted into binary and sent.
392 data is then read and is expected to match against a binary
399 must be populated with a string containing an even number of hexadecimal
400 single-byte characters and must not be empty.
401 This can be useful with binary protocols such as LDAP and SNMP.
405 the transaction will occur in a TLS tunnel.
407 Use a simple TCP connect to check that hosts are up.
409 Perform a complete TLS handshake with each host to check their availability.
412 The following general table options are available:
414 .It Ic demote Ar group
418 This will increment the carp demotion counter for the
419 specified interface group if all hosts in the table are down.
420 For more information on interface groups,
425 .It Ic interval Ar number
426 Override the global interval and specify one for this table.
427 It must be a multiple of the global interval.
428 .It Ic timeout Ar number
429 Set the timeout in milliseconds for each host that is checked using
430 TCP as the transport.
431 This will override the global timeout, which is 200 milliseconds by default.
434 The following options will set the scheduling algorithm to select a
435 host from the specified table:
437 .It Ic mode hash Op Ar key
438 Balances the outgoing connections across the active hosts based on the
440 IP address and port of the relay.
441 Additional input can be fed into the
442 hash by looking at HTTP headers and GET variables;
446 This mode is only supported by relays.
447 .It Ic mode least-states
448 Forward each outgoing connection to the active host with the least
452 This mode is only supported by redirections.
453 .It Ic mode loadbalance Op Ar key
454 Balances the outgoing connections across the active hosts based on the
456 the source IP address of the client, and the IP address and port of the relay.
457 This mode is only supported by relays.
459 Distributes the outgoing connections randomly through all active hosts.
460 This mode is supported by redirections and relays.
461 .It Ic mode roundrobin
462 Distributes the outgoing connections using a round-robin scheduler
463 through all active hosts.
464 This is the default mode and will be used if no option has been specified.
465 This mode is supported by redirections and relays.
466 .It Ic mode source-hash Op Ar key
467 Balances the outgoing connections across the active hosts based on the
469 and the source IP address of the client.
470 This mode is supported by redirections and relays.
475 argument can be specified for the
480 modes as either a hex value with a leading
485 generates a random key when the configuration is loaded.
487 Redirections represent a
490 They are used for stateful redirections to the hosts in the specified
493 rewrites the target IP addresses and ports of the incoming
494 connections, operating on layer 3.
495 The configuration directives that are valid in the
497 context are described below:
500 The redirection is initially disabled.
501 It can be later enabled through
506 .Op Ic port Ar number
509 Specify the tables of target hosts to be used; see the
511 section above for information about table options.
514 option is not specified, the first port from the
516 directive will be used.
517 This directive can be specified twice \(en the second entry will be used
518 as the backup table if all hosts in the main table are down.
519 At least one entry for the main table is mandatory.
521 .Ic listen on Ar address
524 .Op Ic interface Ar name
533 will redirect incoming connections for the specified target to the
534 hosts in the main or backup table.
537 argument can optionally specify a port range instead of a single port;
539 .Ar min-port : Ns Ar max-port .
540 The optional argument
542 can be used to specify an IP protocol like
548 The rule can be optionally restricted to a given interface name.
554 The logged packets are sent to
560 Automatically tag packets passing through the
562 rdr-to rule with the name supplied.
563 This allows simpler filter rules.
566 keyword will change the default rule action from
570 to allow further evaluation in the pf ruleset using the
576 .Op Ic port Ar number
581 directive, but directly routes the packets to the target host without
582 modifying the target address using a
586 .Dq direct server return
587 to force the target host to respond via a different gateway.
588 Note that hosts have to accept sessions for the same address as
589 the gateway, which is typically done by configuring a loopback
590 interface on the host with this address.
591 .It Ic session timeout Ar seconds
592 Specify the inactivity timeout in seconds for established redirections.
593 The default timeout is 600 seconds (10 minutes).
594 The maximum is 2147483647 seconds (68 years).
595 .It Ic sticky-address
596 This has the same effect as specifying sticky-address
597 for an rdr-to rule in
599 It will ensure that multiple connections from the same source are
600 mapped to the same redirection address.
603 Relays will forward traffic between a client and a target server.
604 In contrast to redirections and IP forwarding in the network stack, a
605 relay will accept incoming connections from remote clients as a
606 server, open an outgoing connection to a target host, and forward
607 any traffic between the target host and the remote client,
608 operating on layer 7.
609 A relay is also called an application layer gateway or layer 7 proxy.
611 The main purpose of a relay is to provide advanced load balancing
612 functionality based on specified protocol characteristics, such as
613 HTTP headers, to provide TLS acceleration and to allow
614 basic handling of the underlying application protocol.
618 configuration directives are described below:
621 Start the relay but immediately close any accepted connections.
631 Specify the address and port of the target host to connect to.
634 option is not specified, the port from the
636 directive will be used.
639 keyword to enable fully-transparent mode; the source address of the
640 client will be retained in this case.
644 directive enables client-side TLS mode to connect to the remote host.
645 Verification of server certificates can be enabled by setting the
647 option in the protocol section.
649 The following options may be specified for forward directives:
652 If the requested destination is an IPv6 address,
654 will forward the connection to an IPv4 address which is determined by
655 the last 4 octets of the original IPv6 destination.
656 For example, if the original IPv6 destination address is
657 2001:db8:7395:ffff::a01:101, the session is relayed to the IPv4
658 address 10.1.1.1 (a01:101).
659 .It Ic inet6 Ar address-prefix
660 If the requested destination is an IPv4 address,
662 will forward the connection to an IPv6 address which is determined by
663 setting the last 4 octets of the specified IPv6
665 to the 4 octets of the original IPv4 destination.
666 For example, if the original IPv4 destination address is 10.1.1.1 and
667 the specified address prefix is 2001:db8:7395:ffff::, the session is
668 relayed to the IPv6 address 2001:db8:7395:ffff::a01:101.
669 .It Ic retry Ar number
672 option will be used as a tolerance for failed
673 host connections; the connection will be retried for
676 .It Ic proxy-protocol Pq Ic v1 Ns | Ns Ic v2
677 Upon connection to the destination,
679 will prepend a PROXY protocol header of the specified version to the relayed
680 data, with the IP address and port of the remote host as well as the
690 Like the previous directive, but connect to a host from the specified
693 section above for information about table options.
694 This directive can be specified multiple times \(en subsequent entries
695 will be used as the backup table if all hosts in the previous table
697 At least one entry for the main table is mandatory.
700 directive to enable client-side TLS mode when connecting to the remote host.
706 When redirecting connections with a divert-to rule in
708 to a relay listening on localhost, this directive will
709 look up the real destination address of the intended target host,
710 allowing the relay to be run as a transparent proxy.
713 directive to a specified address or table is present,
714 it will be used as a backup if the lookup failed.
717 directive to enable client-side TLS mode when connecting to the remote host.
723 Like the previous directive, but for redirections with rdr-to in
726 .Ic listen on Ar address Ic port Ar port
729 Specify the address and port for the relay to listen on.
730 The relay will accept incoming connections to the specified address or
734 resolves to multiple IPv4 or IPv6 addresses, such as an interface
735 name, interface group, or DNS hostname,
737 will create a listener for each local address.
738 For DNS hostnames, all resolved IPv4 and IPv6 addresses are considered,
739 but only addresses configured on a local interface are used.
740 Addresses that are not configured on a local interface are ignored.
741 If none of the resolved addresses are local, the configuration is
745 keyword is present, the relay will accept connections using the
746 encrypted TLS protocol.
747 .It Ic protocol Ar name
748 Use the specified protocol definition for the relay.
749 The generic TCP protocol options will be used by default;
753 .It Ic session timeout Ar seconds
754 Specify the inactivity timeout in seconds for accepted sessions.
755 The default timeout is 600 seconds (10 minutes).
756 The maximum is 2147483647 seconds (68 years).
759 In addition to plain TCP,
761 supports the Transport Layer Security (TLS) cryptographic protocol for
762 authenticated and encrypted relays.
764 can operate as a TLS client or server to offer a variety of options
765 for different use cases related to TLS.
768 When configuring the relay
774 will enable client-side TLS to connect to the remote host.
775 This is commonly used for TLS tunneling and transparent encapsulation
776 of plain TCP connections.
781 section for more details.
789 will accept connections from clients as a TLS server.
790 This mode is also known as
791 .Dq TLS acceleration .
796 section for more details.
797 .It Ic TLS client and server
798 When combining both modes, TLS server and client,
800 can filter TLS connections as a man-in-the-middle.
801 This combined mode is also called
803 The configuration requires additional X.509 certificate settings;
808 section for more details.
815 will listen for incoming connections which have been diverted to the
817 Before accepting and negotiating the incoming TLS connection as a
818 server, it will look up the original destination address on the
819 diverted socket, and pre-connect to the target server as a TLS client
820 to obtain the remote TLS certificate.
821 It will update or patch the obtained TLS certificate by replacing the
822 included public key with its local server key because it doesn't have
823 the private key of the remote server certificate.
824 It also updates the X.509 issuer name to the local CA subject name and
825 signs the certificate with its local CA key.
826 This way it keeps all the other X.509 attributes that are already
827 present in the server certificate, including the "green bar" extended
828 validation attributes.
829 Now it finally accepts the TLS connection from the diverted client
830 using the updated certificate and continues to handle the connection
831 and to connect to the remote server.
833 Protocols are templates defining settings and rules for relays.
834 They allow setting generic TCP options, TLS settings, and rules
835 for the selected application layer protocol.
837 The protocol directive is available for a number of different
838 application layer protocols.
839 There is no generic handler for UDP-based protocols because it is a
840 stateless datagram-based protocol which has to look into the
841 application layer protocol to find any possible state information.
845 Domain Name System (DNS) protocol.
846 The requested IDs in the DNS header will be used to match the state.
848 replaces these IDs with random values to compensate for
849 predictable values generated by some hosts.
851 Handle the HyperText Transfer Protocol
852 (HTTP, or "HTTPS" if encapsulated in a TLS tunnel).
857 Generic handler for TCP-based protocols.
861 The available configuration directives are described below:
864 .Pq Ic block Ns | Ns Ic pass Ns | Ns Ic match
867 Specify one or more rules to filter connections based on their
868 network or application layer headers;
871 section for more details.
872 .It Ic return error Op Ar option
873 Return an error response to the client if an internal operation or the
874 forward connection to the client failed.
875 By default, the connection will be silently dropped.
876 The effect of this option depends on the protocol: HTTP will send an
877 error header and page to the client before closing the connection.
878 Additional valid options are:
880 .It Ic style Ar string
881 Specify a Cascading Style Sheet (CSS) to be used for the returned
882 HTTP error pages, for example:
883 .Bd -literal -offset indent
884 body { background: #a00000; color: white; }
888 Enable or disable the specified TCP/IP options; see
892 for more information about the options.
895 .It Ic backlog Ar number
896 Set the maximum length the queue of pending connections may grow to.
897 The backlog option is 10 by default, is limited to 512 and capped by the
901 .It Ic ip minttl Ar number
902 This option for the underlying IP connection may be used to discard packets
903 with a TTL lower than the specified value.
904 This can be used to implement the
905 Generalized TTL Security Mechanism (GTSM)
906 according to RFC 5082.
907 .It Ic ip ttl Ar number
908 Change the default time-to-live value in the IP headers.
910 Enable the TCP NODELAY option for this connection.
911 This is recommended to avoid delays in the relayed data stream,
912 e.g. for SSH connections.
916 Disable socket splicing for zero-copy data transfer.
917 The default is to enable socket splicing.
919 Use selective acknowledgements for this connection.
922 .It Ic socket buffer Ar number
923 Set the socket-level buffer size for input and output for this
925 This will affect the TCP window size.
928 Set the TLS options and session settings.
929 This is only used if TLS is enabled in the relay.
932 .It Ic ca cert Ar path
933 Specify a CA certificate for TLS inspection.
934 For more information, see the
937 .It Ic ca file Ar path
938 This option enables CA verification in TLS client mode.
939 The daemon will load the CA (Certificate Authority) certificates from
940 the specified path to verify the server certificates.
942 provides a default CA bundle in
943 .Pa /etc/ssl/cert.pem .
944 .It Ic ca key Ar path Ic password Ar password
945 Specify a CA key for TLS inspection.
948 argument will specify the password to decrypt the CA key
949 (typically an RSA key).
950 This option will enable TLS inspection if the following conditions
953 .Bl -bullet -compact -offset indent
955 TLS server mode is enabled by the
958 .Ic listen on ... tls .
960 TLS client mode and divert lookups are enabled by the
963 .Ic forward with tls to destination .
973 .It Ic ciphers Ar string
974 Set the string defining the TLS cipher suite.
975 If not specified, the default value
977 will be used (strong crypto cipher suites without anonymous DH).
978 See the CIPHERS section of
980 for information about TLS cipher suites and preference lists.
981 .It Ic client ca Ar path
982 Require TLS client certificates that can be verified against the CA
983 certificates in the specified file.
984 .It Ic client-renegotiation
985 Allow client-initiated renegotiation.
986 To mitigate a potential DoS risk,
988 .Ic no client-renegotiation .
989 .It Ic ecdhe Ar curves
990 Specify a comma separated list of elliptic curves to use for ECDHE cipher
991 suites, in order of preference.
992 The special value of "default" will use the default curves; see
993 .Xr tls_config_set_ecdhecurves 3
995 .It Ic edh Op Ic params Pq Ic none Ns | Ns Ic auto Ns | Ns Ic legacy
996 Enable EDH-based cipher suites with Perfect Forward Secrecy (PFS) for
997 older clients that do not support ECDHE.
1000 mode, the key size of the ephemeral key is automatically selected
1001 based on the size of the private key used for signing.
1004 mode, a 1024 bit ephemeral key is used.
1012 .It Ic keypair Ar name
1013 .It Ic keypair Ar name Op Ic cert Ar "path"
1014 .It Ic keypair Ar name Op Ic key Ar "path"
1015 .It Ic keypair Ar name Op Ic ocsp Ar "path"
1016 The relay will attempt to look up the TLS assets associated with
1020 arguments must be enclosed in double quotes and specify the absolute path to
1021 the respective file.
1022 By default, it searches for a private key in
1023 .Pa /etc/ssl/private/name:port.key
1024 and a public certificate in
1025 .Pa /etc/ssl/name:port.crt ,
1028 is the specified port that the relay listens on.
1029 If these files are not present, the relay will continue to look in
1030 .Pa /etc/ssl/private/name.key
1032 .Pa /etc/ssl/name.crt .
1039 keywords are followed by an explicit
1041 that file will be used instead of the default location.
1043 This option can be specified multiple times for TLS Server Name Indication.
1045 a keypair will be loaded using the specified IP address of the relay as
1049 for details about TLS server certificates.
1051 An optional OCSP staple file will be used during TLS handshakes.
1054 is given, it will be searched as a non-empty file in
1055 .Pa /etc/ssl/name:port.ocsp
1057 .Pa /etc/ssl/name.ocsp .
1058 The file should contain a DER-format OCSP response retrieved from an
1059 OCSP server for the certificate in use, and can be created using
1061 .It Ic no cipher-server-preference
1062 Prefer the client's cipher list over the server's preferences when
1063 choosing a cipher for the connection.
1064 The default is to prefer the server's cipher list.
1065 .It Ic session tickets
1066 Enable TLS session tickets.
1068 supports stateless TLS session tickets (RFC 5077) to implement TLS session
1069 resumption for connections not using TLSv1.3.
1070 The default is to disable session tickets.
1072 Disable the TLSv1.3 protocol.
1073 The default is to enable TLSv1.3.
1075 Disable the TLSv1.2 protocol.
1076 The default is to enable TLSv1.2.
1078 Is deprecated and does nothing.
1080 Enable all TLSv1 protocols.
1081 This is an alias that currently includes
1088 Is deprecated and does nothing.
1090 Is deprecated and does nothing.
1092 .It Ic http Ar option
1093 Set the HTTP options and session settings.
1094 This is only used if HTTP is enabled in the relay.
1097 .It Ic headerlen Ar number
1098 Set the maximum size of all HTTP headers in bytes.
1099 The default value is 8192 and it is limited to a maximum of 131072.
1101 Allow connection upgrade to websocket protocol.
1107 Relays have the ability to filter connections based
1108 on their network or application layer headers.
1109 Filter rules apply options to connections based on the specified
1112 For each connection that is processed by a relay, the filter rules are
1113 evaluated in sequential order, from first to last.
1118 the last matching rule decides what action is taken;
1119 if no rule matches the connection, the default action is to establish
1120 the connection without any additional action.
1123 rules are evaluated every time they match;
1124 the pass/block state of a connection remains unchanged.
1126 The filter action may be one of the following:
1129 The connection is blocked.
1132 rule matches a new connection attempt, it will not be established.
1134 rules can also trigger for existing connections after evaluating
1135 application layer parameters;
1136 any connection of the relay session will be instantly dropped.
1138 The connection is matched.
1139 This action does not alter the connection state, but allows
1140 additional parameters to the connection.
1142 The connection is passed;
1144 will continue to process the relay session normally.
1147 These filter parameters can be used in the rules:
1149 .It Ic request No or Ic response
1150 A relay session always consists of two connections:
1153 a client initiating a new connection to a server via the relay,
1156 the server accepting the connection.
1157 Depending on the protocol,
1158 an established session can be purely request/response-based (like
1159 HTTP), exchange data in a bidirectional way (like arbitrary TCP
1160 sessions), or just contain a single datagram and an optional response
1161 (like UDP-based protocols).
1162 But the client always
1164 to communicate with a remote peer; the server.
1166 If a connection is matched by a rule with the
1169 the rule is considered to be the last matching rule and any further
1170 evaluation is skipped.
1171 .It Ic inet No or Ic inet6
1172 Only match connections with the specified address family,
1173 either of type IPv4 or IPv6.
1174 .It Ic from Ar address Ns Oo Li / Ns Ar prefix Oc
1175 This rule only matches for connections from the specified source.
1176 .It Ic to Ar address Ns Oo Li / Ns Ar prefix Oc
1177 This rule only matches for connections to the specified destination.
1178 The destination is the address the client was connecting to,
1179 typically the relay's listen address in non-transparent mode,
1180 not the address of the forwarded backend connection.
1181 .It Ic forward to Pf < Ar table Ns >
1182 Forward the request to a server in the specified table.
1183 With this option, requests can be passed to specific backend servers.
1188 section is required.
1189 .It Ic label Ar string
1190 The label will be printed as part of the error message if the
1192 option is set and may contain HTML tags, for example:
1193 .Bd -literal -offset indent
1194 block request url digest 5c1e03f58f8ce0b457474ffb371fd1ef \e
1195 label "<a href='http://example.com/adv.pl?id=7359'>\e
1196 Advisory provided by example.com</a>"
1198 .It Ic no Ar parameter
1199 Reset a sticky parameter that was previously set by a matching rule.
1202 is a keyword that can be either
1206 .It Ic tag Ar string
1207 Add a "sticky" tag to connections matching this filter rule.
1208 Tags can be used to filter the connection by further rules using the
1211 Only one tag is assigned per connection;
1212 the tag will be replaced if the connection is already tagged.
1213 .It Ic tagged Ar string
1214 Match the connection if it is already tagged with a given tag by a
1218 The following parameters are available when using the
1222 .It Ic method Ar name
1223 Match the HTTP request method.
1224 The method is specified by
1228 .Ic BASELINE-CONTROL ,
1258 .Ic UPDATEREDIRECTREF ,
1260 .Ic VERSION-CONTROL .
1264 .Pq Ar key Ns | Ns Ic file Ar path
1265 .Oo Ic value Ar value Oc Oc
1267 Match a specified HTTP header entity and an optional
1273 can be specified to modify the matched entity or to trigger an event.
1274 The entity is extracted from the HTTP request or response header and
1286 multiple keys can be loaded from a
1290 that contains one key per line.
1291 Lines will be stripped at the first whitespace or newline character
1292 and any empty lines or lines beginning with a hash mark
1298 keyword is specified,
1299 compare the message digest of the key against the defined string.
1300 The algorithm used is determined by the string length of the
1302 argument, either SHA1 (40 characters) or MD5 (32 characters).
1303 To compute the digest,
1306 use this simple command:
1307 .Bd -literal -offset indent
1308 $ echo -n "example.com/path/?args" | sha1
1315 .It Ic cookie Ar option Oo Ar key Oo Ic value Ar value Oc Oc
1316 Look up the entity as a value in the Cookie header.
1317 This type is only available with the direction
1319 .It Ic header Ar option Oo Ar key Oo Ic value Ar value Oc Oc
1320 Look up the entity in the application protocol headers, like HTTP
1324 .It Ic path Ar option Oo Ar key Oo Ic value Ar value Oc Oc
1325 Look up the entity as a value in the URL path when using the
1328 This type is only available with the direction
1332 will match the path of the requested URL without the hostname
1333 and query and the value will match the complete query,
1335 .Bd -literal -offset indent
1336 block path "/index.html"
1337 block path "/cgi-bin/t.cgi" value "foo=bar*"
1339 .It Ic path strip Ar number
1342 path components from the beginning of the path of the requested URL
1346 This type is only available with the direction
1348 .It Ic query Ar option Oo Ar key Oo Ic value Ar value Oc Oc
1349 Look up the entity as a query variable in the URL when using the
1352 This type is only available with the direction
1355 .Bd -literal -offset indent
1356 # Will match /cgi-bin/example.pl?foo=bar&ok=yes
1357 pass request query "foo" value "bar"
1359 .It Ic url Ar option Oo Oo Ic digest Oc Ar key Oo Ic value Ar value Oc Oc
1360 Look up the entity as a URL suffix/prefix expression consisting of a
1361 canonicalized hostname without port or suffix and a path name or
1362 prefix when using the
1365 This type is only available with the direction
1368 .Bd -literal -offset indent
1369 block url "example.com/index.html"
1370 block url "example.com/test.cgi?val=1"
1374 will match the full URL and different possible suffix/prefix
1375 combinations by stripping subdomains and path components (up to 5
1376 levels), and the query string.
1377 For example, the following
1378 lookups will be done for
1379 http://www.example.com:81/1/2/3/4/5.html?query=yes:
1380 .Bd -literal -offset indent
1381 www.example.com/1/2/3/4/5.html?query=yes
1382 www.example.com/1/2/3/4/5.html
1385 www.example.com/1/2/
1386 www.example.com/1/2/3/
1387 example.com/1/2/3/4/5.html?query=yes
1388 example.com/1/2/3/4/5.html
1400 Append the specified
1402 to a protocol entity with the selected
1405 If it does not exist, it will be created with the new value.
1407 The value string may contain predefined macros that will be expanded
1410 .Bl -tag -width $SERVER_ADDR -offset indent -compact
1412 The Host header's value of the relay.
1414 The IP address of the connected client.
1416 The TCP source port of the connected client.
1418 The configured IP address of the relay.
1420 The configured TCP server port of the relay.
1422 The server software name of
1425 The configured session timeout of the relay.
1430 of the selected entity into the load balancing hash to select the
1444 Remove the entity with the selected
1450 directive above, but change the contents of the specified entity.
1453 does not exist in the request, it will be created with the new
1459 may contain predefined macros that will be expanded at runtime,
1465 Routers represent routing table entries in the kernel forwarding
1468 and a table of associated gateways.
1469 They are used to dynamically insert or remove routes with gateways
1470 based on their availability and health-check results.
1471 A router can include multiple network statements and a single forward
1472 statement with a table of one or more gateways.
1473 All entries in a single router directive must match the same address
1474 family, either IPv4 or IPv6.
1476 The kernel supports multipath routing when multiple gateways exist to
1477 the same destination address.
1478 The multipath routing behaviour can be changed globally using the
1481 .Va net.inet.ip.multipath
1483 .Va net.inet6.ip6.multipath .
1484 With the default setting of 0,
1485 the first route selected will be used for subsequent packets to that
1486 destination regardless of source.
1487 Setting it to 1 will enable load balancing based on the packet source
1488 address across gateways; multiple routes with the same priority are
1490 The kernel will also check the link state of the related network
1491 interface and try a different route if it is not active.
1493 The configuration directives that are valid in the
1495 context are described below:
1503 Specify the table of target gateways to be used; see the
1505 section above for information about table options.
1506 This entry is mandatory and must be specified once.
1509 .Ar address Ns Li / Ns Ar prefix
1511 Specify the network address and prefix length of a route destination
1512 that is reachable via the active gateways.
1513 This entry must be specified at least once in a router directive.
1515 Add the routes to the kernel routing table with the specified
1517 .It Ic rtlabel Ar label
1518 Add the routes with the specified
1520 to the kernel routing table.
1523 .Bl -tag -width Ds -compact
1524 .It Pa /etc/relayd.conf
1528 .It Pa /etc/examples/relayd.conf
1529 Example configuration file.
1531 .It Pa /etc/services
1532 Service name database.
1534 .It Pa /etc/ssl/address.crt
1535 .It Pa /etc/ssl/address:port.crt
1536 .It Pa /etc/ssl/private/address.key
1537 .It Pa /etc/ssl/private/address:port.key
1538 Location of the relay TLS server certificates, where
1540 is the configured IP address
1543 is the configured port number of the relay.
1545 .It Pa /etc/ssl/cert.pem
1546 Default location of the CA bundle that can be used with
1550 This configuration file would create a redirection service
1552 which load balances four hosts
1553 and falls back to one host containing a
1555 .Bd -literal -offset indent
1556 www1=front-www1.private.example.com
1557 www2=front-www2.private.example.com
1558 www3=front-www3.private.example.com
1559 www4=front-www4.private.example.com
1563 table <phphosts> { $www1, $www2, $www3, $www4 }
1564 table <sorryhost> disable { sorryhost.private.example.com }
1567 listen on www.example.com port 8080 interface trunk0
1568 listen on www6.example.com port 80 interface trunk0
1572 forward to <phphosts> port 8080 timeout 300 \e
1573 check http "/" digest "630aa3c2f..."
1574 forward to <sorryhost> port 8080 timeout 300 check icmp
1578 It is possible to specify multiple listen directives with different IP
1579 protocols in a single redirection configuration:
1580 .Bd -literal -offset indent
1582 listen on dns.example.com tcp port 53
1583 listen on dns.example.com udp port 53
1585 forward to <dnshosts> port 53 check tcp
1589 To load balance an IP address over multiple backend servers using a
1593 .Bd -literal -offset indent
1594 table <backends> { 10.100.42.71 10.100.42.72 10.100.42.73 }
1597 listen on 10.100.42.2 tcp port 5222
1599 route to <backends> port 5222 check tcp interface em0
1603 The following configuration would add a relay to forward
1604 secure HTTPS connections to a pool of HTTP webservers
1607 mode (TLS acceleration and layer 7 load balancing).
1608 The HTTP protocol definition will add two HTTP headers containing
1609 address information of the client and the server, set the
1611 header value to the configured session timeout,
1614 variable in the hash to calculate the target host:
1615 .Bd -literal -offset indent
1616 http protocol "https" {
1617 match header set "X-Forwarded-For" \e
1618 value "$REMOTE_ADDR"
1619 match header set "X-Forwarded-By" \e
1620 value "$SERVER_ADDR:$SERVER_PORT"
1621 match header set "Keep-Alive" value "$TIMEOUT"
1623 match query hash "sessid"
1626 block path "/cgi-bin/index.cgi" value "*command=*"
1628 tls { no tlsv1.0, ciphers "HIGH" }
1632 listen on www.example.com port 443 tls
1634 forward to <phphosts> port 8080 mode loadbalance check tcp
1638 The second relay example will accept incoming connections to port
1639 2222 and forward them to a remote SSH server.
1644 SSH session without delays between keystrokes or displayed output on
1646 .Bd -literal -offset indent
1648 tcp { nodelay, socket buffer 65536 }
1651 relay "sshforward" {
1652 listen on www.example.com port 2222
1654 forward to shell.example.com port 22
1658 The following relay example will configure
1663 To start, first generate a new local CA key and certificate:
1664 .Bd -literal -offset indent
1665 # openssl req -x509 -days 365 -newkey rsa:2048 \e
1666 -keyout /etc/ssl/private/ca.key -out /etc/ssl/ca.crt
1669 A TLS server key and self-signed cert for 127.0.0.1 are also required;
1674 section for more details about certificate locations.
1675 Configure the packet filter with a matching divert rule in
1677 .Bd -literal -offset indent
1678 # Divert incoming HTTPS traffic to relayd
1679 pass in on vlan1 inet proto tcp to port 443 \e
1680 divert-to localhost port 8443
1683 And finally configure the TLS inspection in
1685 .Bd -literal -offset indent
1686 http protocol httpfilter {
1690 match label "Prohibited!"
1691 block url "social.network.example.com/"
1693 # New configuration directives for TLS Interception
1694 tls ca key "/etc/ssl/private/ca.key" password "password123"
1695 tls ca cert "/etc/ssl/ca.crt"
1699 listen on 127.0.0.1 port 8443 tls
1701 forward with tls to destination
1705 The next simple router configuration example can be used to run
1706 redundant, health-checked WAN links:
1707 .Bd -literal -offset indent
1708 table <gateways> { $gw1 ip ttl 1, $gw2 ip ttl 1 }
1711 forward to <gateways> check icmp
1722 file format, formerly known as
1723 .Ic hoststated.conf ,
1734 program was written by
1735 .An Pierre-Yves Ritschard Aq Mt pyr@openbsd.org
1737 .An Reyk Floeter Aq Mt reyk@openbsd.org .
1740 verification of TLS server certificates is based on a static CA bundle
1743 currently does not support CRLs (Certificate Revocation Lists).
