1 ee259709 2026-05-19 rsadowski .\" $OpenBSD: relayd.conf.5,v 1.218 2026/05/19 05:06:41 rsadowski Exp $
3 4a9b7b24 2016-07-29 reyk .\" Copyright (c) 2006 - 2016 Reyk Floeter <reyk@openbsd.org>
4 8c736326 2007-09-28 pyr .\" Copyright (c) 2006, 2007 Pierre-Yves Ritschard <pyr@openbsd.org>
6 41042ecc 2006-12-16 reyk .\" Permission to use, copy, modify, and distribute this software for any
7 41042ecc 2006-12-16 reyk .\" purpose with or without fee is hereby granted, provided that the above
8 41042ecc 2006-12-16 reyk .\" copyright notice and this permission notice appear in all copies.
10 41042ecc 2006-12-16 reyk .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
11 41042ecc 2006-12-16 reyk .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
12 41042ecc 2006-12-16 reyk .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
13 41042ecc 2006-12-16 reyk .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
14 41042ecc 2006-12-16 reyk .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
15 41042ecc 2006-12-16 reyk .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
16 41042ecc 2006-12-16 reyk .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
18 ee259709 2026-05-19 rsadowski .Dd $Mdocdate: May 19 2026 $
19 0cf54f77 2007-12-07 deraadt .Dt RELAYD.CONF 5
22 0cf54f77 2007-12-07 deraadt .Nm relayd.conf
23 78f03736 2007-12-12 jmc .Nd relay daemon configuration file
24 41042ecc 2006-12-16 reyk .Sh DESCRIPTION
26 78f03736 2007-12-12 jmc is the configuration file for the relay daemon,
27 0cf54f77 2007-12-07 deraadt .Xr relayd 8 .
30 026d2c0e 2018-06-18 jmc is divided into the following main sections:
31 41042ecc 2006-12-16 reyk .Bl -tag -width xxxx
32 9b58f4a4 2025-07-08 schwarze .It Sx Macros
33 abfa295f 2025-07-07 schwarze Definitions of variables that can be used later, simplifying the
34 41042ecc 2006-12-16 reyk configuration file.
35 9b58f4a4 2025-07-08 schwarze .It Sx Global configuration
36 41042ecc 2006-12-16 reyk Global settings for
37 0cf54f77 2007-12-07 deraadt .Xr relayd 8 .
38 05fa2b6c 2009-06-02 jmc Do note that the config file allows global settings to be added after
39 b18a368f 2009-06-02 jj defining tables in the config file, but those tables will use the
40 b18a368f 2009-06-02 jj built-in defaults instead of the global settings below them.
41 9b58f4a4 2025-07-08 schwarze .It Sx Tables
42 78f03736 2007-12-12 jmc Table definitions describe a list of hosts,
43 78f03736 2007-12-12 jmc in a similar fashion to
46 39bc6125 2009-08-13 reyk They are used for relay, redirection, and router target selection with
47 39bc6125 2009-08-13 reyk the described options and health checking on the host they contain.
48 9b58f4a4 2025-07-08 schwarze .It Sx Redirections
49 78f03736 2007-12-12 jmc Redirections are translated to
51 05fcbce7 2009-09-01 reyk rdr-to rules for stateful forwarding to a target host from a
52 d7758aba 2007-12-08 reyk health-checked table on layer 3.
53 9b58f4a4 2025-07-08 schwarze .It Sx Relays
54 096ff28b 2014-12-12 reyk Relays allow application layer load balancing, TLS acceleration, and
55 d7758aba 2007-12-08 reyk general purpose TCP proxying on layer 7.
56 9b58f4a4 2025-07-08 schwarze .It Sx Protocols
57 69fde657 2014-07-09 reyk Protocols are predefined settings and filter rules for relays.
58 9b58f4a4 2025-07-08 schwarze .It Sx Routers
59 39bc6125 2009-08-13 reyk Routers are used to insert routes with health-checked gateways for
60 39bc6125 2009-08-13 reyk (WAN) link balancing.
63 a91b6709 2007-01-08 reyk Within the sections,
66 b0d88a11 2009-08-27 reyk can be specified by IPv4 address, IPv6 address, interface name,
67 bdd13866 2011-05-23 reyk interface group, or DNS hostname.
68 b0d88a11 2009-08-27 reyk If the address is an interface name,
69 b0d88a11 2009-08-27 reyk .Xr relayd 8
70 7dcffcda 2009-08-27 jmc will look up the first IPv4 address and any other IPv4 and IPv6
71 b0d88a11 2009-08-27 reyk addresses of the specified network interface.
74 78f03736 2007-12-12 jmc can be specified by number or name.
75 a91b6709 2007-01-08 reyk The port name to number mappings are found in the file
76 72bd104e 2007-01-10 jmc .Pa /etc/services ;
78 a91b6709 2007-01-08 reyk .Xr services 5
79 a91b6709 2007-01-08 reyk for details.
81 8f305e35 2011-06-23 sthen The current line can be extended over multiple lines using a backslash
82 8f305e35 2011-06-23 sthen .Pq Sq \e .
83 002d9ce9 2007-10-22 reyk Comments can be put anywhere in the file using a hash mark
85 002d9ce9 2007-10-22 reyk and extend to the end of the current line.
86 8f305e35 2011-06-23 sthen Care should be taken when commenting out multi-line text:
87 8f305e35 2011-06-23 sthen the comment is effective until the end of the entire block.
89 4f8b6369 2026-01-18 schwarze Arguments not beginning with a letter, digit, or underscore
90 bf8f85fb 2012-04-24 jmc must be quoted.
92 002d9ce9 2007-10-22 reyk Additional configuration files can be included with the
94 002d9ce9 2007-10-22 reyk keyword, for example:
95 002d9ce9 2007-10-22 reyk .Bd -literal -offset indent
96 0cf54f77 2007-12-07 deraadt include "/etc/relayd.conf.local"
98 9b58f4a4 2025-07-08 schwarze .Ss Macros
99 abfa295f 2025-07-07 schwarze A macro is defined with a command of the form
100 abfa295f 2025-07-07 schwarze .Ar name Ns = Ns Ar value .
101 abfa295f 2025-07-07 schwarze The macro
102 abfa295f 2025-07-07 schwarze .Ar name
103 abfa295f 2025-07-07 schwarze can contain letters, digits, and underscores and cannot be a reserved word
104 abfa295f 2025-07-07 schwarze (for example,
105 41042ecc 2006-12-16 reyk .Ic table ,
106 d7758aba 2007-12-08 reyk .Ic relay ,
108 41042ecc 2006-12-16 reyk .Ic timeout ) .
109 abfa295f 2025-07-07 schwarze Within unquoted arguments, the string
110 abfa295f 2025-07-07 schwarze .Pf $ Ar name
111 abfa295f 2025-07-07 schwarze is later expanded to
112 abfa295f 2025-07-07 schwarze .Ar value .
114 41042ecc 2006-12-16 reyk For example:
115 41042ecc 2006-12-16 reyk .Bd -literal -offset indent
116 41042ecc 2006-12-16 reyk www1="10.0.0.1"
117 41042ecc 2006-12-16 reyk www2="10.0.0.2"
118 f0f5730b 2015-11-06 bentley table <webhosts> {
123 9b58f4a4 2025-07-08 schwarze .Ss Global configuration
124 ae98db81 2006-12-25 reyk Here are the settings that can be set globally:
125 05fa2b6c 2009-06-02 jmc .Bl -tag -width Ds
126 04a2f953 2020-09-14 martijn .It Ic agentx Oo Ic context Ar context Oc Oo Ic path Ar path Oc
128 04a2f953 2020-09-14 martijn .Xr relayd 8
129 a799ac62 2020-10-30 martijn metrics via an agentx compatible
130 04a2f953 2020-09-14 martijn .Pq snmp
131 04a2f953 2020-09-14 martijn daemon by connecting to
132 04a2f953 2020-09-14 martijn .Ar path .
133 a799ac62 2020-10-30 martijn Metrics can be found under the relaydMIBObjects subtree
134 a799ac62 2020-10-30 martijn .Pq enterprises.30155.3 .
136 04a2f953 2020-09-14 martijn .Ar path
137 2b23fa0d 2022-03-31 naddy is omitted, it will default to
138 04a2f953 2020-09-14 martijn .Pa /var/agentx/master .
139 04a2f953 2020-09-14 martijn .Ar Context
140 04a2f953 2020-09-14 martijn is the SNMPv3 context and can usually be omitted.
141 05fa2b6c 2009-06-02 jmc .It Ic interval Ar number
142 41042ecc 2006-12-16 reyk Set the interval in seconds at which the hosts will be checked.
143 41042ecc 2006-12-16 reyk The default interval is 10 seconds.
146 37ed6014 2018-08-06 benno .Pq Ic state changes Ns | Ns Ic host checks
148 37ed6014 2018-08-06 benno Log host checks:
149 37ed6014 2018-08-06 benno Either log only the
150 37ed6014 2018-08-06 benno .Ic state changes
151 37ed6014 2018-08-06 benno of hosts or log all
152 37ed6014 2018-08-06 benno .Ic host checks
153 37ed6014 2018-08-06 benno that were run, even if the state didn't change.
154 f802d393 2007-02-07 reyk The host state can be
156 f802d393 2007-02-07 reyk (the health check completed successfully),
157 f0f5730b 2015-11-06 bentley .Dq down
158 f802d393 2007-02-07 reyk (the host is down or didn't match the check criteria),
160 f0f5730b 2015-11-06 bentley .Dq unknown
161 f802d393 2007-02-07 reyk (the host is disabled or has not been checked yet).
163 37ed6014 2018-08-06 benno .Ic log connection Op Ic errors
165 37ed6014 2018-08-06 benno When using relays, log all TCP connections.
166 37ed6014 2018-08-06 benno Optionally log only
167 2952c0d0 2018-08-06 jmc .Ic connection errors .
168 30640247 2007-02-22 reyk .It Ic prefork Ar number
169 30640247 2007-02-22 reyk When using relays, run the specified number of processes to handle
170 30640247 2007-02-22 reyk relayed connections.
171 78f03736 2007-12-12 jmc This increases the performance and prevents delays when connecting
172 30640247 2007-02-22 reyk to a relay.
173 0cf54f77 2007-12-07 deraadt .Xr relayd 8
174 c525adb9 2014-04-18 reyk runs 3 relay processes by default and every process will handle
175 30640247 2007-02-22 reyk all configured relays.
176 a98b5322 2017-11-29 benno .It Ic socket Qo Ar path Qc
177 a98b5322 2017-11-29 benno Create a control socket at
178 a98b5322 2017-11-29 benno .Ar path .
179 a98b5322 2017-11-29 benno By default
180 a98b5322 2017-11-29 benno .Pa /var/run/relayd.sock
182 05fa2b6c 2009-06-02 jmc .It Ic timeout Ar number
183 70547d98 2007-01-08 reyk Set the global timeout in milliseconds for checks.
184 419416e6 2008-11-09 tobias This can be overridden by the timeout value in the table definitions.
185 060fee47 2016-08-18 jmc The default timeout is 200 milliseconds and it must not exceed the
186 70547d98 2007-01-08 reyk global interval.
187 883c12f8 2022-02-06 jsg The default value is optimized for checks within the
188 f6e80275 2008-03-03 jmc same collision domain \(en use a higher timeout, such as 1000 milliseconds,
189 f6e80275 2008-03-03 jmc for checks of hosts in other subnets.
190 05fa2b6c 2009-06-02 jmc If this option is to be set, it should be placed before overrides in tables.
192 9b58f4a4 2025-07-08 schwarze .Ss Tables
193 d7758aba 2007-12-08 reyk Tables are used to group a set of hosts as the target for redirections
194 78f03736 2007-12-12 jmc or relays; they will be mapped to a
196 d7758aba 2007-12-08 reyk table for redirections.
197 d7758aba 2007-12-08 reyk Tables may be defined with the following attribute:
198 d7758aba 2007-12-08 reyk .Bl -tag -width disable
199 d7758aba 2007-12-08 reyk .It Ic disable
200 d7758aba 2007-12-08 reyk Start the table disabled \(en no hosts will be checked in this table.
201 d7758aba 2007-12-08 reyk The table can be later enabled through
202 d7758aba 2007-12-08 reyk .Xr relayctl 8 .
205 bdd13866 2011-05-23 reyk Each table must contain at least one host
206 bdd13866 2011-05-23 reyk .Ar address ;
207 78f03736 2007-12-12 jmc multiple hosts are separated by newline, comma, or whitespace.
208 17acabee 2008-07-19 reyk Host entries may be defined with the following attributes:
209 d7758aba 2007-12-08 reyk .Bl -tag -width retry
210 c3895d83 2009-08-07 reyk .It Ic ip ttl Ar number
211 c3895d83 2009-08-07 reyk Change the default time-to-live value in the IP headers for host checks.
212 17acabee 2008-07-19 reyk .It Ic parent Ar number
213 cde97fee 2008-07-19 jmc The optional parent option inherits the state from a parent
214 17acabee 2008-07-19 reyk host with the specified identifier.
215 17acabee 2008-07-19 reyk The check will be skipped for this host and copied from the parent host.
216 17acabee 2008-07-19 reyk This can be used to prevent multiple checks on hosts with multiple IP
217 17acabee 2008-07-19 reyk addresses for the same service.
218 17acabee 2008-07-19 reyk The host identifiers are sequentially assigned to the configured hosts
219 cde97fee 2008-07-19 jmc starting with 1; it can be shown with the
220 17acabee 2008-07-19 reyk .Xr relayctl 8
221 17acabee 2008-07-19 reyk .Ic show summary
223 246e5b16 2011-05-05 phessler .It Ic priority Ar number
224 246e5b16 2011-05-05 phessler Change the route priority used when adding a route.
225 f0f5730b 2015-11-06 bentley If not specified, the kernel will set a priority of 8
226 f0f5730b 2015-11-06 bentley .Pq Dv RTP_STATIC .
227 246e5b16 2011-05-05 phessler In ordinary use, a fallback route should be added statically with a very
228 246e5b16 2011-05-05 phessler high (e.g. 52) priority.
229 246e5b16 2011-05-05 phessler Unused in all other modes.
230 c3895d83 2009-08-07 reyk .It Ic retry Ar number
231 c3895d83 2009-08-07 reyk The optional retry option adds a tolerance for failed host checks;
232 c3895d83 2009-08-07 reyk the check will be retried for
234 c3895d83 2009-08-07 reyk more times before setting the host state to down.
235 c3895d83 2009-08-07 reyk If this table is used by a relay, it will also specify the number of
236 c3895d83 2009-08-07 reyk retries for outgoing connection attempts.
239 78f03736 2007-12-12 jmc For example:
240 d7758aba 2007-12-08 reyk .Bd -literal -offset indent
241 f0f5730b 2015-11-06 bentley table <service> { 192.168.1.1, 192.168.1.2, 192.168.2.3 }
242 f0f5730b 2015-11-06 bentley table <fallback> disable { 10.1.5.1 retry 2 }
244 d7758aba 2007-12-08 reyk redirect "www" {
245 d7758aba 2007-12-08 reyk listen on www.example.com port 80
246 f0f5730b 2015-11-06 bentley forward to <service> check http "/" code 200
247 f0f5730b 2015-11-06 bentley forward to <fallback> check http "/" code 200
251 78f03736 2007-12-12 jmc Tables are used by
252 d7758aba 2007-12-08 reyk .Ic forward to
253 d7758aba 2007-12-08 reyk directives in redirections or relays with a set of general options,
254 78f03736 2007-12-12 jmc health-checking rules, and timings;
256 9b58f4a4 2025-07-08 schwarze .Sx Redirections
258 9b58f4a4 2025-07-08 schwarze .Sx Relays
259 d7758aba 2007-12-08 reyk sections for more information about the forward context.
260 78f03736 2007-12-12 jmc Table specific configuration directives are described below.
261 78f03736 2007-12-12 jmc Multiple options can be appended to
262 d7758aba 2007-12-08 reyk .Ic forward to
263 d7758aba 2007-12-08 reyk directives, separated by whitespaces.
265 d7758aba 2007-12-08 reyk The following options will configure the health-checking method for
266 78f03736 2007-12-12 jmc the table, and is mandatory for redirections:
267 41042ecc 2006-12-16 reyk .Bl -tag -width Ds
269 85fb7214 2007-09-04 pyr .Ic check http Ar path
270 85fb7214 2007-09-04 pyr .Op Ic host Ar hostname
271 85fb7214 2007-09-04 pyr .Ic code Ar number
273 41042ecc 2006-12-16 reyk For each host in the table, verify that retrieving the URL
275 41042ecc 2006-12-16 reyk gives the HTTP return code
276 5d8d93a9 2006-12-18 jmc .Ar number .
278 85fb7214 2007-09-04 pyr .Ar hostname
279 85fb7214 2007-09-04 pyr is specified, it is used as the
281 78f03736 2007-12-12 jmc header to query a specific hostname at the target host.
282 b2665266 2008-12-05 reyk To validate the HTTP return code, use this shell command:
283 b2665266 2008-12-05 reyk .Bd -literal -offset indent
284 b2665266 2008-12-05 reyk $ echo -n "HEAD <path> HTTP/1.0\er\en\er\en" | \e
285 b2665266 2008-12-05 reyk nc <host> <port> | head -n1
288 b2665266 2008-12-05 reyk This prints the status header including the actual return code:
289 b2665266 2008-12-05 reyk .Bd -literal -offset indent
290 b2665266 2008-12-05 reyk HTTP/1.1 200 OK
293 85fb7214 2007-09-04 pyr .Ic check https Ar path
294 85fb7214 2007-09-04 pyr .Op Ic host Ar hostname
295 85fb7214 2007-09-04 pyr .Ic code Ar number
297 096ff28b 2014-12-12 reyk This has the same effect as above but wraps the HTTP request in TLS.
299 85fb7214 2007-09-04 pyr .Ic check http Ar path
300 85fb7214 2007-09-04 pyr .Op Ic host Ar hostname
301 85fb7214 2007-09-04 pyr .Ic digest Ar string
303 41042ecc 2006-12-16 reyk For each host in the table, verify that retrieving the URL
305 8f09694f 2008-05-06 reyk produces non-binary content whose message digest matches the defined string.
306 fa7bf744 2007-11-21 jmc The algorithm used is determined by the string length of the
308 fa7bf744 2007-11-21 jmc argument, either SHA1 (40 characters) or MD5 (32 characters).
310 85fb7214 2007-09-04 pyr .Ar hostname
311 85fb7214 2007-09-04 pyr is specified, it is used as the
313 78f03736 2007-12-12 jmc header to query a specific hostname at the target host.
314 7f80c950 2006-12-16 reyk The digest does not take the HTTP headers into account.
315 8f09694f 2008-05-06 reyk Do not specify a binary object (such as a graphic) as the target of the
318 837ba19e 2008-05-06 jmc expects the data returned to be a string.
319 5d8d93a9 2006-12-18 jmc To compute the digest, use this simple command:
320 5d8d93a9 2006-12-18 jmc .Bd -literal -offset indent
321 78f03736 2007-12-12 jmc $ ftp -o - http://host[:port]/path | sha1
324 b2665266 2008-12-05 reyk This gives a digest that can be used as-is in a digest statement:
325 5d8d93a9 2006-12-18 jmc .Bd -literal -offset indent
326 41042ecc 2006-12-16 reyk a9993e36476816aba3e25717850c26c9cd0d89d
329 f2fc00ac 2007-09-28 pascoe .Ic check https Ar path
330 85fb7214 2007-09-04 pyr .Op Ic host Ar hostname
331 85fb7214 2007-09-04 pyr .Ic digest Ar string
333 096ff28b 2014-12-12 reyk This has the same effect as above but wraps the HTTP request in TLS.
334 21bc5e6b 2006-12-19 jmc .It Ic check icmp
335 21bc5e6b 2006-12-19 jmc Ping hosts in this table to determine whether they are up or not.
336 21bc5e6b 2006-12-19 jmc This method will automatically use ICMP or ICMPV6 depending on the
337 21bc5e6b 2006-12-19 jmc address family of each host.
338 78f03736 2007-12-12 jmc .It Ic check script Ar path
339 78f03736 2007-12-12 jmc Execute an external program to check the host state.
340 67b7900b 2009-04-16 sobrado The program will be executed for each host by specifying the hostname
341 78f03736 2007-12-12 jmc on the command line:
342 78f03736 2007-12-12 jmc .Bd -literal -offset indent
343 78f03736 2007-12-12 jmc /usr/local/bin/checkload.pl front-www1.private.example.com
346 78f03736 2007-12-12 jmc .Xr relayd 8
347 78f03736 2007-12-12 jmc expects a positive return value on success and zero on failure.
348 78f03736 2007-12-12 jmc Note that the script will be executed with the privileges of the
350 78f03736 2007-12-12 jmc user and terminated after
352 78f03736 2007-12-12 jmc milliseconds.
354 50c4bd1a 2007-02-26 pyr .Ic check send
360 7c36f315 2007-01-08 reyk For each host in the table, a TCP connection is established on the
361 72bd104e 2007-01-10 jmc port specified, then
364 72bd104e 2007-01-10 jmc Incoming data is then read and is expected to match against
365 f89c70fd 2007-01-08 reyk .Ar pattern
366 f89c70fd 2007-01-08 reyk using shell globbing rules.
369 7c36f315 2007-01-08 reyk is an empty string or
370 7c36f315 2007-01-08 reyk .Ic nothing
371 7c36f315 2007-01-08 reyk then nothing is sent on the connection and data is immediately
373 7c36f315 2007-01-08 reyk This can be useful with protocols that output a banner like
374 78f03736 2007-12-12 jmc SMTP, NNTP, and FTP.
377 fbbd3fac 2007-02-27 jmc keyword is present,
378 53339de6 2015-07-24 jmc the transaction will occur in a TLS tunnel.
380 738b3cc9 2019-09-15 rob .Ic check binary send
386 738b3cc9 2019-09-15 rob For each host in the table, a TCP connection is established on the
387 738b3cc9 2019-09-15 rob port specified, then the
390 738b3cc9 2019-09-15 rob is converted into binary and sent.
391 738b3cc9 2019-09-15 rob Incoming (binary)
392 738b3cc9 2019-09-15 rob data is then read and is expected to match against a binary
393 738b3cc9 2019-09-15 rob conversion of the
397 738b3cc9 2019-09-15 rob .Xr memcmp 3 .
399 738b3cc9 2019-09-15 rob must be populated with a string containing an even number of hexadecimal
400 738b3cc9 2019-09-15 rob single-byte characters and must not be empty.
401 738b3cc9 2019-09-15 rob This can be useful with binary protocols such as LDAP and SNMP.
404 738b3cc9 2019-09-15 rob keyword is present,
405 738b3cc9 2019-09-15 rob the transaction will occur in a TLS tunnel.
406 21bc5e6b 2006-12-19 jmc .It Ic check tcp
407 21bc5e6b 2006-12-19 jmc Use a simple TCP connect to check that hosts are up.
408 096ff28b 2014-12-12 reyk .It Ic check tls
409 096ff28b 2014-12-12 reyk Perform a complete TLS handshake with each host to check their availability.
412 d7758aba 2007-12-08 reyk The following general table options are available:
413 d7758aba 2007-12-08 reyk .Bl -tag -width Ds
414 888f608a 2007-02-22 reyk .It Ic demote Ar group
415 888f608a 2007-02-22 reyk Enable the per-table
417 fbbd3fac 2007-02-27 jmc demotion option.
418 fbbd3fac 2007-02-27 jmc This will increment the carp demotion counter for the
419 888f608a 2007-02-22 reyk specified interface group if all hosts in the table are down.
420 888f608a 2007-02-22 reyk For more information on interface groups,
424 888f608a 2007-02-22 reyk .Xr ifconfig 8 .
425 182ad205 2007-11-20 pyr .It Ic interval Ar number
426 182ad205 2007-11-20 pyr Override the global interval and specify one for this table.
427 182ad205 2007-11-20 pyr It must be a multiple of the global interval.
428 21bc5e6b 2006-12-19 jmc .It Ic timeout Ar number
429 ae98db81 2006-12-25 reyk Set the timeout in milliseconds for each host that is checked using
430 ae98db81 2006-12-25 reyk TCP as the transport.
431 ae98db81 2006-12-25 reyk This will override the global timeout, which is 200 milliseconds by default.
434 67b7900b 2009-04-16 sobrado The following options will set the scheduling algorithm to select a
435 d7758aba 2007-12-08 reyk host from the specified table:
436 d7758aba 2007-12-08 reyk .Bl -tag -width Ds
437 3e04b122 2014-12-18 reyk .It Ic mode hash Op Ar key
438 78f03736 2007-12-12 jmc Balances the outgoing connections across the active hosts based on the
440 3e04b122 2014-12-18 reyk IP address and port of the relay.
441 f35090a9 2012-05-05 benno Additional input can be fed into the
442 f35090a9 2012-05-05 benno hash by looking at HTTP headers and GET variables;
444 9b58f4a4 2025-07-08 schwarze .Sx Protocols
445 d7758aba 2007-12-08 reyk section below.
446 d7758aba 2007-12-08 reyk This mode is only supported by relays.
447 d6c9879f 2012-10-19 reyk .It Ic mode least-states
448 d6c9879f 2012-10-19 reyk Forward each outgoing connection to the active host with the least
452 d6c9879f 2012-10-19 reyk This mode is only supported by redirections.
453 3e04b122 2014-12-18 reyk .It Ic mode loadbalance Op Ar key
454 78f03736 2007-12-12 jmc Balances the outgoing connections across the active hosts based on the
456 3e04b122 2014-12-18 reyk the source IP address of the client, and the IP address and port of the relay.
457 78f03736 2007-12-12 jmc This mode is only supported by relays.
458 d6c9879f 2012-10-19 reyk .It Ic mode random
459 d6c9879f 2012-10-19 reyk Distributes the outgoing connections randomly through all active hosts.
460 10638510 2014-12-23 reyk This mode is supported by redirections and relays.
461 78f03736 2007-12-12 jmc .It Ic mode roundrobin
462 78f03736 2007-12-12 jmc Distributes the outgoing connections using a round-robin scheduler
463 78f03736 2007-12-12 jmc through all active hosts.
464 78f03736 2007-12-12 jmc This is the default mode and will be used if no option has been specified.
465 78f03736 2007-12-12 jmc This mode is supported by redirections and relays.
466 3e04b122 2014-12-18 reyk .It Ic mode source-hash Op Ar key
467 d6c9879f 2012-10-19 reyk Balances the outgoing connections across the active hosts based on the
469 d6c9879f 2012-10-19 reyk and the source IP address of the client.
470 10638510 2014-12-23 reyk This mode is supported by redirections and relays.
473 3e04b122 2014-12-18 reyk The optional
475 3e04b122 2014-12-18 reyk argument can be specified for the
477 3e04b122 2014-12-18 reyk .Ic loadbalance ,
479 3e04b122 2014-12-18 reyk .Ic source-hash
480 4eb11f85 2014-12-18 jmc modes as either a hex value with a leading
482 3e04b122 2014-12-18 reyk or as a string.
483 3e04b122 2014-12-18 reyk If omitted,
484 3e04b122 2014-12-18 reyk .Xr relayd 8
485 3e04b122 2014-12-18 reyk generates a random key when the configuration is loaded.
486 9b58f4a4 2025-07-08 schwarze .Ss Redirections
487 d7758aba 2007-12-08 reyk Redirections represent a
489 05fcbce7 2009-09-01 reyk rdr-to rule.
490 d7758aba 2007-12-08 reyk They are used for stateful redirections to the hosts in the specified
493 78f03736 2007-12-12 jmc rewrites the target IP addresses and ports of the incoming
494 d7758aba 2007-12-08 reyk connections, operating on layer 3.
495 d7758aba 2007-12-08 reyk The configuration directives that are valid in the
496 d7758aba 2007-12-08 reyk .Ic redirect
497 d7758aba 2007-12-08 reyk context are described below:
498 41042ecc 2006-12-16 reyk .Bl -tag -width Ds
499 41042ecc 2006-12-16 reyk .It Ic disable
500 78f03736 2007-12-12 jmc The redirection is initially disabled.
501 7f80c950 2006-12-16 reyk It can be later enabled through
502 0cf54f77 2007-12-07 deraadt .Xr relayctl 8 .
504 d7758aba 2007-12-08 reyk .Ic forward to
505 f0f5730b 2015-11-06 bentley .Pf < Ar table Ns >
506 d7758aba 2007-12-08 reyk .Op Ic port Ar number
507 78f03736 2007-12-12 jmc .Ar options ...
509 78f03736 2007-12-12 jmc Specify the tables of target hosts to be used; see the
510 9b58f4a4 2025-07-08 schwarze .Sx Tables
511 78f03736 2007-12-12 jmc section above for information about table options.
514 09913286 2008-09-29 reyk option is not specified, the first port from the
515 d7758aba 2007-12-08 reyk .Ic listen on
516 d7758aba 2007-12-08 reyk directive will be used.
517 78f03736 2007-12-12 jmc This directive can be specified twice \(en the second entry will be used
518 d7758aba 2007-12-08 reyk as the backup table if all hosts in the main table are down.
519 d7758aba 2007-12-08 reyk At least one entry for the main table is mandatory.
521 d250825b 2009-04-24 reyk .Ic listen on Ar address
522 d250825b 2009-04-24 reyk .Op ip-proto
523 d250825b 2009-04-24 reyk .Ic port Ar port
524 d7758aba 2007-12-08 reyk .Op Ic interface Ar name
525 199fb283 2024-06-17 sashan .Op Ic pflog
528 d7758aba 2007-12-08 reyk .Ar address
531 d7758aba 2007-12-08 reyk to listen on.
533 d7758aba 2007-12-08 reyk will redirect incoming connections for the specified target to the
534 d7758aba 2007-12-08 reyk hosts in the main or backup table.
537 4e52738f 2008-10-05 jmc argument can optionally specify a port range instead of a single port;
538 09913286 2008-09-29 reyk the format is
539 4e52738f 2008-10-05 jmc .Ar min-port : Ns Ar max-port .
540 d250825b 2009-04-24 reyk The optional argument
541 d250825b 2009-04-24 reyk .Ar ip-proto
542 d250825b 2009-04-24 reyk can be used to specify an IP protocol like
545 f0f5730b 2015-11-06 bentley .Cm udp ;
546 d250825b 2009-04-24 reyk it defaults to
547 f0f5730b 2015-11-06 bentley .Cm tcp .
548 05fcbce7 2009-09-01 reyk The rule can be optionally restricted to a given interface name.
549 199fb283 2024-06-17 sashan The optional
550 199fb283 2024-06-17 sashan .Ic pflog
551 199fb283 2024-06-17 sashan keyword will add
553 2fbfb4ba 2024-07-14 jsg to the rule.
554 2fbfb4ba 2024-07-14 jsg The logged packets are sent to
555 199fb283 2024-06-17 sashan .Xr pflog 4 .
557 886ed1ae 2016-09-03 jmc .Op Ic match
558 886ed1ae 2016-09-03 jmc .Ic pftag Ar name
560 886ed1ae 2016-09-03 jmc Automatically tag packets passing through the
562 886ed1ae 2016-09-03 jmc rdr-to rule with the name supplied.
563 886ed1ae 2016-09-03 jmc This allows simpler filter rules.
564 886ed1ae 2016-09-03 jmc The optional
566 886ed1ae 2016-09-03 jmc keyword will change the default rule action from
567 886ed1ae 2016-09-03 jmc .Ql pass in quick
569 886ed1ae 2016-09-03 jmc .Ql match in
570 886ed1ae 2016-09-03 jmc to allow further evaluation in the pf ruleset using the
571 886ed1ae 2016-09-03 jmc .Cm tagged Ar name
572 886ed1ae 2016-09-03 jmc rule option.
574 8626b048 2008-06-10 reyk .Ic route to
575 f0f5730b 2015-11-06 bentley .Pf < Ar table Ns >
576 8626b048 2008-06-10 reyk .Op Ic port Ar number
577 8626b048 2008-06-10 reyk .Ar options ...
580 8626b048 2008-06-10 reyk .Ic forward to
581 c35bda3e 2008-06-11 jmc directive, but directly routes the packets to the target host without
582 05fcbce7 2009-09-01 reyk modifying the target address using a
584 05fcbce7 2009-09-01 reyk route-to rule.
585 8626b048 2008-06-10 reyk This can be used for
586 8626b048 2008-06-10 reyk .Dq direct server return
587 8626b048 2008-06-10 reyk to force the target host to respond via a different gateway.
588 c35bda3e 2008-06-11 jmc Note that hosts have to accept sessions for the same address as
589 c35bda3e 2008-06-11 jmc the gateway, which is typically done by configuring a loopback
590 8626b048 2008-06-10 reyk interface on the host with this address.
591 8626b048 2008-06-10 reyk .It Ic session timeout Ar seconds
592 879c2f2e 2008-06-10 reyk Specify the inactivity timeout in seconds for established redirections.
593 8626b048 2008-06-10 reyk The default timeout is 600 seconds (10 minutes).
594 983a954b 2013-04-27 benno The maximum is 2147483647 seconds (68 years).
595 59754064 2007-01-03 reyk .It Ic sticky-address
596 78f03736 2007-12-12 jmc This has the same effect as specifying sticky-address
597 05fcbce7 2009-09-01 reyk for an rdr-to rule in
598 59754064 2007-01-03 reyk .Xr pf.conf 5 .
599 59754064 2007-01-03 reyk It will ensure that multiple connections from the same source are
600 59754064 2007-01-03 reyk mapped to the same redirection address.
602 9b58f4a4 2025-07-08 schwarze .Ss Relays
603 d7758aba 2007-12-08 reyk Relays will forward traffic between a client and a target server.
604 d7758aba 2007-12-08 reyk In contrast to redirections and IP forwarding in the network stack, a
605 d7758aba 2007-12-08 reyk relay will accept incoming connections from remote clients as a
606 30640247 2007-02-22 reyk server, open an outgoing connection to a target host, and forward
607 d7758aba 2007-12-08 reyk any traffic between the target host and the remote client,
608 d7758aba 2007-12-08 reyk operating on layer 7.
609 d7758aba 2007-12-08 reyk A relay is also called an application layer gateway or layer 7 proxy.
611 9b4e9d87 2007-02-22 jmc The main purpose of a relay is to provide advanced load balancing
612 30640247 2007-02-22 reyk functionality based on specified protocol characteristics, such as
613 096ff28b 2014-12-12 reyk HTTP headers, to provide TLS acceleration and to allow
614 30640247 2007-02-22 reyk basic handling of the underlying application protocol.
618 d7758aba 2007-12-08 reyk configuration directives are described below:
619 30640247 2007-02-22 reyk .Bl -tag -width Ds
620 78f03736 2007-12-12 jmc .It Ic disable
621 78f03736 2007-12-12 jmc Start the relay but immediately close any accepted connections.
623 6d5340e6 2008-06-11 reyk .Op Ic transparent
624 6024acb8 2009-04-01 reyk .Ic forward
625 096ff28b 2014-12-12 reyk .Op Ic with tls
627 d7758aba 2007-12-08 reyk .Ar address
628 d7758aba 2007-12-08 reyk .Op Ic port Ar port
629 2e5903be 2008-07-22 reyk .Ar options ...
631 30640247 2007-02-22 reyk Specify the address and port of the target host to connect to.
634 d7758aba 2007-12-08 reyk option is not specified, the port from the
635 d7758aba 2007-12-08 reyk .Ic listen on
636 d7758aba 2007-12-08 reyk directive will be used.
638 6d5340e6 2008-06-11 reyk .Ic transparent
639 6d5340e6 2008-06-11 reyk keyword to enable fully-transparent mode; the source address of the
640 6d5340e6 2008-06-11 reyk client will be retained in this case.
643 096ff28b 2014-12-12 reyk .Ic with tls
644 096ff28b 2014-12-12 reyk directive enables client-side TLS mode to connect to the remote host.
645 6e8c1015 2009-04-02 reyk Verification of server certificates can be enabled by setting the
646 6e8c1015 2009-04-02 reyk .Ic ca file
647 6e8c1015 2009-04-02 reyk option in the protocol section.
649 2e5903be 2008-07-22 reyk The following options may be specified for forward directives:
650 2e5903be 2008-07-22 reyk .Bl -tag -width Ds
651 2e5903be 2008-07-22 reyk .It Ic inet
652 2e5903be 2008-07-22 reyk If the requested destination is an IPv6 address,
653 2e5903be 2008-07-22 reyk .Xr relayd 8
654 2e5903be 2008-07-22 reyk will forward the connection to an IPv4 address which is determined by
655 2e5903be 2008-07-22 reyk the last 4 octets of the original IPv6 destination.
656 2e5903be 2008-07-22 reyk For example, if the original IPv6 destination address is
657 2e5903be 2008-07-22 reyk 2001:db8:7395:ffff::a01:101, the session is relayed to the IPv4
658 2e5903be 2008-07-22 reyk address 10.1.1.1 (a01:101).
659 2e5903be 2008-07-22 reyk .It Ic inet6 Ar address-prefix
660 2e5903be 2008-07-22 reyk If the requested destination is an IPv4 address,
661 2e5903be 2008-07-22 reyk .Xr relayd 8
662 2e5903be 2008-07-22 reyk will forward the connection to an IPv6 address which is determined by
663 2e5903be 2008-07-22 reyk setting the last 4 octets of the specified IPv6
664 2e5903be 2008-07-22 reyk .Ar address-prefix
665 2e5903be 2008-07-22 reyk to the 4 octets of the original IPv4 destination.
666 2e5903be 2008-07-22 reyk For example, if the original IPv4 destination address is 10.1.1.1 and
667 2e5903be 2008-07-22 reyk the specified address prefix is 2001:db8:7395:ffff::, the session is
668 2e5903be 2008-07-22 reyk relayed to the IPv6 address 2001:db8:7395:ffff::a01:101.
669 886ed1ae 2016-09-03 jmc .It Ic retry Ar number
670 886ed1ae 2016-09-03 jmc The optional host
672 886ed1ae 2016-09-03 jmc option will be used as a tolerance for failed
673 886ed1ae 2016-09-03 jmc host connections; the connection will be retried for
676 80347df3 2026-02-18 kirill .It Ic proxy-protocol Pq Ic v1 Ns | Ns Ic v2
677 80347df3 2026-02-18 kirill Upon connection to the destination,
678 80347df3 2026-02-18 kirill .Xr relayd 8
679 80347df3 2026-02-18 kirill will prepend a PROXY protocol header of the specified version to the relayed
680 80347df3 2026-02-18 kirill data, with the IP address and port of the remote host as well as the
681 80347df3 2026-02-18 kirill .Xr relayd 8
685 d7758aba 2007-12-08 reyk .Ic forward to
686 f0f5730b 2015-11-06 bentley .Pf < Ar table Ns >
687 d7758aba 2007-12-08 reyk .Op Ic port Ar port
688 78f03736 2007-12-12 jmc .Ar options ...
690 d7758aba 2007-12-08 reyk Like the previous directive, but connect to a host from the specified
691 78f03736 2007-12-12 jmc table; see the
692 9b58f4a4 2025-07-08 schwarze .Sx Tables
693 78f03736 2007-12-12 jmc section above for information about table options.
694 0f7a5e2e 2012-10-03 reyk This directive can be specified multiple times \(en subsequent entries
695 0f7a5e2e 2012-10-03 reyk will be used as the backup table if all hosts in the previous table
697 fc057ff1 2010-08-01 sthen At least one entry for the main table is mandatory.
698 18a1936f 2015-10-24 benno As above, use the
699 18a1936f 2015-10-24 benno .Ic with tls
700 18a1936f 2015-10-24 benno directive to enable client-side TLS mode when connecting to the remote host.
702 d7758aba 2007-12-08 reyk .Ic forward to
703 9c52a29e 2011-04-07 reyk .Ic destination
704 2e5903be 2008-07-22 reyk .Ar options ...
706 1263d4f4 2011-04-07 jmc When redirecting connections with a divert-to rule in
707 30640247 2007-02-22 reyk .Xr pf.conf 5
708 9b4e9d87 2007-02-22 jmc to a relay listening on localhost, this directive will
709 9b4e9d87 2007-02-22 jmc look up the real destination address of the intended target host,
710 9b4e9d87 2007-02-22 jmc allowing the relay to be run as a transparent proxy.
711 d7758aba 2007-12-08 reyk If an additional
712 d7758aba 2007-12-08 reyk .Ic forward to
713 d7758aba 2007-12-08 reyk directive to a specified address or table is present,
714 9c52a29e 2011-04-07 reyk it will be used as a backup if the lookup failed.
715 18a1936f 2015-10-24 benno As above, use the
716 18a1936f 2015-10-24 benno .Ic with tls
717 18a1936f 2015-10-24 benno directive to enable client-side TLS mode when connecting to the remote host.
719 9c52a29e 2011-04-07 reyk .Ic forward to
720 9c52a29e 2011-04-07 reyk .Ic nat lookup
721 9c52a29e 2011-04-07 reyk .Ar options ...
723 9c52a29e 2011-04-07 reyk Like the previous directive, but for redirections with rdr-to in
724 9c52a29e 2011-04-07 reyk .Xr pf.conf 5 .
726 fe0c5b66 2015-05-15 reyk .Ic listen on Ar address Ic port Ar port
729 78f03736 2007-12-12 jmc Specify the address and port for the relay to listen on.
730 e9c39896 2026-05-17 kirill The relay will accept incoming connections to the specified address or
731 e9c39896 2026-05-17 kirill addresses.
733 e9c39896 2026-05-17 kirill .Ar address
734 e9c39896 2026-05-17 kirill resolves to multiple IPv4 or IPv6 addresses, such as an interface
735 e9c39896 2026-05-17 kirill name, interface group, or DNS hostname,
736 e9c39896 2026-05-17 kirill .Xr relayd 8
737 e9c39896 2026-05-17 kirill will create a listener for each local address.
738 e9c39896 2026-05-17 kirill For DNS hostnames, all resolved IPv4 and IPv6 addresses are considered,
739 e9c39896 2026-05-17 kirill but only addresses configured on a local interface are used.
740 e9c39896 2026-05-17 kirill Addresses that are not configured on a local interface are ignored.
741 e9c39896 2026-05-17 kirill If none of the resolved addresses are local, the configuration is
745 78f03736 2007-12-12 jmc keyword is present, the relay will accept connections using the
746 096ff28b 2014-12-12 reyk encrypted TLS protocol.
747 30640247 2007-02-22 reyk .It Ic protocol Ar name
748 30640247 2007-02-22 reyk Use the specified protocol definition for the relay.
749 9b4e9d87 2007-02-22 jmc The generic TCP protocol options will be used by default;
751 9b58f4a4 2025-07-08 schwarze .Sx Protocols
752 30640247 2007-02-22 reyk section below.
753 87e43bd7 2008-05-06 reyk .It Ic session timeout Ar seconds
754 879c2f2e 2008-06-10 reyk Specify the inactivity timeout in seconds for accepted sessions.
755 78f03736 2007-12-12 jmc The default timeout is 600 seconds (10 minutes).
756 983a954b 2013-04-27 benno The maximum is 2147483647 seconds (68 years).
758 9b58f4a4 2025-07-08 schwarze .Ss TLS relays
759 03668b6b 2013-05-30 reyk In addition to plain TCP,
760 03668b6b 2013-05-30 reyk .Xr relayd 8
761 096ff28b 2014-12-12 reyk supports the Transport Layer Security (TLS) cryptographic protocol for
762 096ff28b 2014-12-12 reyk authenticated and encrypted relays.
763 03668b6b 2013-05-30 reyk .Xr relayd 8
764 53339de6 2015-07-24 jmc can operate as a TLS client or server to offer a variety of options
765 096ff28b 2014-12-12 reyk for different use cases related to TLS.
766 03668b6b 2013-05-30 reyk .Bl -tag -width Ds
767 096ff28b 2014-12-12 reyk .It Ic TLS client
768 03668b6b 2013-05-30 reyk When configuring the relay
769 03668b6b 2013-05-30 reyk .Ic forward
770 03668b6b 2013-05-30 reyk statements with the
771 096ff28b 2014-12-12 reyk .Ic with tls
773 03668b6b 2013-05-30 reyk .Xr relayd 8
774 096ff28b 2014-12-12 reyk will enable client-side TLS to connect to the remote host.
775 096ff28b 2014-12-12 reyk This is commonly used for TLS tunneling and transparent encapsulation
776 03668b6b 2013-05-30 reyk of plain TCP connections.
778 03668b6b 2013-05-30 reyk .Ic forward to
779 03668b6b 2013-05-30 reyk description in the
780 9b58f4a4 2025-07-08 schwarze .Sx Relays
781 03668b6b 2013-05-30 reyk section for more details.
782 096ff28b 2014-12-12 reyk .It Ic TLS server
783 03668b6b 2013-05-30 reyk When specifying the
785 03668b6b 2013-05-30 reyk keyword in the relay
787 03668b6b 2013-05-30 reyk statements,
788 03668b6b 2013-05-30 reyk .Xr relayd 8
789 53339de6 2015-07-24 jmc will accept connections from clients as a TLS server.
790 03668b6b 2013-05-30 reyk This mode is also known as
791 fba21fa4 2023-10-29 kn .Dq TLS acceleration .
793 03668b6b 2013-05-30 reyk .Ic listen on
794 03668b6b 2013-05-30 reyk description in the
795 9b58f4a4 2025-07-08 schwarze .Sx Relays
796 03668b6b 2013-05-30 reyk section for more details.
797 096ff28b 2014-12-12 reyk .It Ic TLS client and server
798 096ff28b 2014-12-12 reyk When combining both modes, TLS server and client,
799 03668b6b 2013-05-30 reyk .Xr relayd 8
800 096ff28b 2014-12-12 reyk can filter TLS connections as a man-in-the-middle.
801 03668b6b 2013-05-30 reyk This combined mode is also called
802 096ff28b 2014-12-12 reyk .Dq TLS inspection .
803 03668b6b 2013-05-30 reyk The configuration requires additional X.509 certificate settings;
806 03668b6b 2013-05-30 reyk description in the
807 9b58f4a4 2025-07-08 schwarze .Sx Protocols
808 03668b6b 2013-05-30 reyk section for more details.
811 03668b6b 2013-05-30 reyk When configured for
812 096ff28b 2014-12-12 reyk .Dq TLS inspection
814 03668b6b 2013-05-30 reyk .Xr relayd 8
815 03668b6b 2013-05-30 reyk will listen for incoming connections which have been diverted to the
816 03668b6b 2013-05-30 reyk local socket by PF.
817 096ff28b 2014-12-12 reyk Before accepting and negotiating the incoming TLS connection as a
818 03668b6b 2013-05-30 reyk server, it will look up the original destination address on the
819 53339de6 2015-07-24 jmc diverted socket, and pre-connect to the target server as a TLS client
820 096ff28b 2014-12-12 reyk to obtain the remote TLS certificate.
821 096ff28b 2014-12-12 reyk It will update or patch the obtained TLS certificate by replacing the
822 03668b6b 2013-05-30 reyk included public key with its local server key because it doesn't have
823 03668b6b 2013-05-30 reyk the private key of the remote server certificate.
824 03668b6b 2013-05-30 reyk It also updates the X.509 issuer name to the local CA subject name and
825 03668b6b 2013-05-30 reyk signs the certificate with its local CA key.
826 03668b6b 2013-05-30 reyk This way it keeps all the other X.509 attributes that are already
827 03668b6b 2013-05-30 reyk present in the server certificate, including the "green bar" extended
828 03668b6b 2013-05-30 reyk validation attributes.
829 096ff28b 2014-12-12 reyk Now it finally accepts the TLS connection from the diverted client
830 03668b6b 2013-05-30 reyk using the updated certificate and continues to handle the connection
831 03668b6b 2013-05-30 reyk and to connect to the remote server.
832 9b58f4a4 2025-07-08 schwarze .Ss Protocols
833 69fde657 2014-07-09 reyk Protocols are templates defining settings and rules for relays.
834 096ff28b 2014-12-12 reyk They allow setting generic TCP options, TLS settings, and rules
835 69fde657 2014-07-09 reyk for the selected application layer protocol.
837 d7758aba 2007-12-08 reyk The protocol directive is available for a number of different
838 78f03736 2007-12-12 jmc application layer protocols.
839 7ba7514d 2007-09-10 reyk There is no generic handler for UDP-based protocols because it is a
840 57c3e59d 2007-09-28 jmc stateless datagram-based protocol which has to look into the
841 7ba7514d 2007-09-10 reyk application layer protocol to find any possible state information.
842 d7758aba 2007-12-08 reyk .Bl -tag -width Ds
843 d7758aba 2007-12-08 reyk .It Ic dns protocol
845 7ba7514d 2007-09-10 reyk Domain Name System (DNS) protocol.
846 78f03736 2007-12-12 jmc The requested IDs in the DNS header will be used to match the state.
847 0cf54f77 2007-12-07 deraadt .Xr relayd 8
848 78f03736 2007-12-12 jmc replaces these IDs with random values to compensate for
849 7ba7514d 2007-09-10 reyk predictable values generated by some hosts.
850 78f03736 2007-12-12 jmc .It Ic http protocol
851 a9100b69 2010-05-18 sobrado Handle the HyperText Transfer Protocol
852 53339de6 2015-07-24 jmc (HTTP, or "HTTPS" if encapsulated in a TLS tunnel).
855 78f03736 2007-12-12 jmc .Ic protocol
857 78f03736 2007-12-12 jmc Generic handler for TCP-based protocols.
858 78f03736 2007-12-12 jmc This is the default.
861 d7758aba 2007-12-08 reyk The available configuration directives are described below:
862 d7758aba 2007-12-08 reyk .Bl -tag -width Ds
864 69fde657 2014-07-09 reyk .Pq Ic block Ns | Ns Ic pass Ns | Ns Ic match
865 69fde657 2014-07-09 reyk .Op Ar rule
867 c537acf4 2014-07-09 jmc Specify one or more rules to filter connections based on their
868 69fde657 2014-07-09 reyk network or application layer headers;
870 9b58f4a4 2025-07-08 schwarze .Sx Filter rules
871 69fde657 2014-07-09 reyk section for more details.
872 691e5d5c 2007-11-20 reyk .It Ic return error Op Ar option
873 67b7900b 2009-04-16 sobrado Return an error response to the client if an internal operation or the
874 691e5d5c 2007-11-20 reyk forward connection to the client failed.
875 691e5d5c 2007-11-20 reyk By default, the connection will be silently dropped.
876 0571bde5 2007-11-20 jmc The effect of this option depends on the protocol: HTTP will send an
877 691e5d5c 2007-11-20 reyk error header and page to the client before closing the connection.
878 691e5d5c 2007-11-20 reyk Additional valid options are:
879 691e5d5c 2007-11-20 reyk .Bl -tag -width Ds
880 691e5d5c 2007-11-20 reyk .It Ic style Ar string
881 691e5d5c 2007-11-20 reyk Specify a Cascading Style Sheet (CSS) to be used for the returned
882 691e5d5c 2007-11-20 reyk HTTP error pages, for example:
883 691e5d5c 2007-11-20 reyk .Bd -literal -offset indent
884 691e5d5c 2007-11-20 reyk body { background: #a00000; color: white; }
887 096ff28b 2014-12-12 reyk .It Ic tcp Ar option
888 096ff28b 2014-12-12 reyk Enable or disable the specified TCP/IP options; see
892 096ff28b 2014-12-12 reyk for more information about the options.
893 78f03736 2007-12-12 jmc Valid options are:
894 78f03736 2007-12-12 jmc .Bl -tag -width Ds
895 096ff28b 2014-12-12 reyk .It Ic backlog Ar number
896 096ff28b 2014-12-12 reyk Set the maximum length the queue of pending connections may grow to.
897 62110500 2018-04-18 claudio The backlog option is 10 by default, is limited to 512 and capped by the
898 096ff28b 2014-12-12 reyk .Ic kern.somaxconn
899 096ff28b 2014-12-12 reyk .Xr sysctl 8
901 096ff28b 2014-12-12 reyk .It Ic ip minttl Ar number
902 096ff28b 2014-12-12 reyk This option for the underlying IP connection may be used to discard packets
903 096ff28b 2014-12-12 reyk with a TTL lower than the specified value.
904 096ff28b 2014-12-12 reyk This can be used to implement the
905 f0f5730b 2015-11-06 bentley Generalized TTL Security Mechanism (GTSM)
906 096ff28b 2014-12-12 reyk according to RFC 5082.
907 096ff28b 2014-12-12 reyk .It Ic ip ttl Ar number
908 096ff28b 2014-12-12 reyk Change the default time-to-live value in the IP headers.
909 886ed1ae 2016-09-03 jmc .It Ic nodelay
910 096ff28b 2014-12-12 reyk Enable the TCP NODELAY option for this connection.
911 096ff28b 2014-12-12 reyk This is recommended to avoid delays in the relayed data stream,
912 096ff28b 2014-12-12 reyk e.g. for SSH connections.
913 886ed1ae 2016-09-03 jmc The default is
914 886ed1ae 2016-09-03 jmc .Ic no nodelay .
915 9091119a 2017-07-11 bluhm .It Ic no splice
916 886ed1ae 2016-09-03 jmc Disable socket splicing for zero-copy data transfer.
917 886ed1ae 2016-09-03 jmc The default is to enable socket splicing.
919 096ff28b 2014-12-12 reyk Use selective acknowledgements for this connection.
920 886ed1ae 2016-09-03 jmc The default is
921 886ed1ae 2016-09-03 jmc .Ic no sack .
922 096ff28b 2014-12-12 reyk .It Ic socket buffer Ar number
923 096ff28b 2014-12-12 reyk Set the socket-level buffer size for input and output for this
924 096ff28b 2014-12-12 reyk connection.
925 096ff28b 2014-12-12 reyk This will affect the TCP window size.
927 096ff28b 2014-12-12 reyk .It Ic tls Ar option
928 096ff28b 2014-12-12 reyk Set the TLS options and session settings.
929 096ff28b 2014-12-12 reyk This is only used if TLS is enabled in the relay.
930 096ff28b 2014-12-12 reyk Valid options are:
931 096ff28b 2014-12-12 reyk .Bl -tag -width Ds
932 03668b6b 2013-05-30 reyk .It Ic ca cert Ar path
933 096ff28b 2014-12-12 reyk Specify a CA certificate for TLS inspection.
934 03668b6b 2013-05-30 reyk For more information, see the
936 03668b6b 2013-05-30 reyk option below.
937 6e8c1015 2009-04-02 reyk .It Ic ca file Ar path
938 096ff28b 2014-12-12 reyk This option enables CA verification in TLS client mode.
939 6e8c1015 2009-04-02 reyk The daemon will load the CA (Certificate Authority) certificates from
940 6e8c1015 2009-04-02 reyk the specified path to verify the server certificates.
942 6e8c1015 2009-04-02 reyk provides a default CA bundle in
943 6e8c1015 2009-04-02 reyk .Pa /etc/ssl/cert.pem .
944 03668b6b 2013-05-30 reyk .It Ic ca key Ar path Ic password Ar password
945 096ff28b 2014-12-12 reyk Specify a CA key for TLS inspection.
947 03668b6b 2013-05-30 reyk .Ar password
948 03668b6b 2013-05-30 reyk argument will specify the password to decrypt the CA key
949 03668b6b 2013-05-30 reyk (typically an RSA key).
950 096ff28b 2014-12-12 reyk This option will enable TLS inspection if the following conditions
953 03668b6b 2013-05-30 reyk .Bl -bullet -compact -offset indent
955 2c759de0 2015-05-15 jmc TLS server mode is enabled by the
958 096ff28b 2014-12-12 reyk .Ic listen on ... tls .
960 2c759de0 2015-05-15 jmc TLS client mode and divert lookups are enabled by the
961 03668b6b 2013-05-30 reyk .Ic forward
963 096ff28b 2014-12-12 reyk .Ic forward with tls to destination .
966 03668b6b 2013-05-30 reyk .Ic ca cert
967 03668b6b 2013-05-30 reyk option is specified.
971 03668b6b 2013-05-30 reyk option is specified.
973 78f03736 2007-12-12 jmc .It Ic ciphers Ar string
974 096ff28b 2014-12-12 reyk Set the string defining the TLS cipher suite.
975 78f03736 2007-12-12 jmc If not specified, the default value
976 f0f5730b 2015-11-06 bentley .Ql HIGH:!aNULL
977 78f03736 2007-12-12 jmc will be used (strong crypto cipher suites without anonymous DH).
978 c154ff18 2013-06-29 jmc See the CIPHERS section of
979 78f03736 2007-12-12 jmc .Xr openssl 1
980 fba21fa4 2023-10-29 kn for information about TLS cipher suites and preference lists.
981 c4efe747 2024-10-28 tb .It Ic client ca Ar path
982 c4efe747 2024-10-28 tb Require TLS client certificates that can be verified against the CA
983 c4efe747 2024-10-28 tb certificates in the specified file.
984 444d2307 2017-02-02 reyk .It Ic client-renegotiation
985 444d2307 2017-02-02 reyk Allow client-initiated renegotiation.
986 444d2307 2017-02-02 reyk To mitigate a potential DoS risk,
987 444d2307 2017-02-02 reyk the default is
988 444d2307 2017-02-02 reyk .Ic no client-renegotiation .
989 3fe6d92f 2017-11-27 claudio .It Ic ecdhe Ar curves
990 3fe6d92f 2017-11-27 claudio Specify a comma separated list of elliptic curves to use for ECDHE cipher
991 3fe6d92f 2017-11-27 claudio suites, in order of preference.
992 3fe6d92f 2017-11-27 claudio The special value of "default" will use the default curves; see
993 3fe6d92f 2017-11-27 claudio .Xr tls_config_set_ecdhecurves 3
994 3fe6d92f 2017-11-27 claudio for further details.
995 a31c2c8f 2020-05-02 benno .It Ic edh Op Ic params Pq Ic none Ns | Ns Ic auto Ns | Ns Ic legacy
996 7b8b16d5 2015-01-02 sobrado Enable EDH-based cipher suites with Perfect Forward Secrecy (PFS) for
997 4da92fab 2014-07-11 reyk older clients that do not support ECDHE.
1000 a31c2c8f 2020-05-02 benno mode, the key size of the ephemeral key is automatically selected
1001 a31c2c8f 2020-05-02 benno based on the size of the private key used for signing.
1003 a31c2c8f 2020-05-02 benno .Ic legacy
1004 a31c2c8f 2020-05-02 benno mode, a 1024 bit ephemeral key is used.
1006 a31c2c8f 2020-05-02 benno .Ic params
1007 a31c2c8f 2020-05-02 benno is omitted,
1010 886ed1ae 2016-09-03 jmc The default is
1011 886ed1ae 2016-09-03 jmc .Ic no edh .
1012 9261e0d8 2019-05-31 reyk .It Ic keypair Ar name
1013 36dd1e7a 2026-05-15 rsadowski .It Ic keypair Ar name Op Ic cert Ar "path"
1014 36dd1e7a 2026-05-15 rsadowski .It Ic keypair Ar name Op Ic key Ar "path"
1015 36dd1e7a 2026-05-15 rsadowski .It Ic keypair Ar name Op Ic ocsp Ar "path"
1016 36dd1e7a 2026-05-15 rsadowski The relay will attempt to look up the TLS assets associated with
1017 36dd1e7a 2026-05-15 rsadowski .Ar name .
1018 36dd1e7a 2026-05-15 rsadowski The optional
1019 36dd1e7a 2026-05-15 rsadowski .Ar path
1020 36dd1e7a 2026-05-15 rsadowski arguments must be enclosed in double quotes and specify the absolute path to
1021 36dd1e7a 2026-05-15 rsadowski the respective file.
1022 36dd1e7a 2026-05-15 rsadowski By default, it searches for a private key in
1023 9261e0d8 2019-05-31 reyk .Pa /etc/ssl/private/name:port.key
1024 9261e0d8 2019-05-31 reyk and a public certificate in
1025 9261e0d8 2019-05-31 reyk .Pa /etc/ssl/name:port.crt ,
1028 9261e0d8 2019-05-31 reyk is the specified port that the relay listens on.
1029 9261e0d8 2019-05-31 reyk If these files are not present, the relay will continue to look in
1030 9261e0d8 2019-05-31 reyk .Pa /etc/ssl/private/name.key
1032 9261e0d8 2019-05-31 reyk .Pa /etc/ssl/name.crt .
1034 36dd1e7a 2026-05-15 rsadowski If the
1035 36dd1e7a 2026-05-15 rsadowski .Ic cert ,
1036 36dd1e7a 2026-05-15 rsadowski .Ic key ,
1038 36dd1e7a 2026-05-15 rsadowski .Ic ocsp
1039 36dd1e7a 2026-05-15 rsadowski keywords are followed by an explicit
1040 36dd1e7a 2026-05-15 rsadowski .Ar path ,
1041 36dd1e7a 2026-05-15 rsadowski that file will be used instead of the default location.
1043 9261e0d8 2019-05-31 reyk This option can be specified multiple times for TLS Server Name Indication.
1044 9261e0d8 2019-05-31 reyk If not specified,
1045 9261e0d8 2019-05-31 reyk a keypair will be loaded using the specified IP address of the relay as
1046 9261e0d8 2019-05-31 reyk .Ar name .
1049 fba21fa4 2023-10-29 kn for details about TLS server certificates.
1051 36dd1e7a 2026-05-15 rsadowski An optional OCSP staple file will be used during TLS handshakes.
1052 36dd1e7a 2026-05-15 rsadowski If no explicit
1053 36dd1e7a 2026-05-15 rsadowski .Ic ocsp Ar path
1054 36dd1e7a 2026-05-15 rsadowski is given, it will be searched as a non-empty file in
1055 0c91187d 2019-06-26 reyk .Pa /etc/ssl/name:port.ocsp
1057 0c91187d 2019-06-26 reyk .Pa /etc/ssl/name.ocsp .
1058 0c91187d 2019-06-26 reyk The file should contain a DER-format OCSP response retrieved from an
1059 0c91187d 2019-06-26 reyk OCSP server for the certificate in use, and can be created using
1060 0c91187d 2019-06-26 reyk .Xr ocspcheck 8 .
1061 886ed1ae 2016-09-03 jmc .It Ic no cipher-server-preference
1062 886ed1ae 2016-09-03 jmc Prefer the client's cipher list over the server's preferences when
1063 886ed1ae 2016-09-03 jmc choosing a cipher for the connection.
1064 886ed1ae 2016-09-03 jmc The default is to prefer the server's cipher list.
1065 95aff4f7 2020-10-22 benno .It Ic session tickets
1066 95aff4f7 2020-10-22 benno Enable TLS session tickets.
1067 e5c598d0 2016-09-01 claudio .Xr relayd 8
1068 e5c598d0 2016-09-01 claudio supports stateless TLS session tickets (RFC 5077) to implement TLS session
1069 95aff4f7 2020-10-22 benno resumption for connections not using TLSv1.3.
1070 e5913210 2020-10-22 benno The default is to disable session tickets.
1071 8d09c191 2020-05-14 pvk .It Ic no tlsv1.3
1072 8d09c191 2020-05-14 pvk Disable the TLSv1.3 protocol.
1073 8d09c191 2020-05-14 pvk The default is to enable TLSv1.3.
1074 886ed1ae 2016-09-03 jmc .It Ic no tlsv1.2
1075 886ed1ae 2016-09-03 jmc Disable the TLSv1.2 protocol.
1076 886ed1ae 2016-09-03 jmc The default is to enable TLSv1.2.
1077 886ed1ae 2016-09-03 jmc .It Ic sslv3
1078 1785600c 2023-06-06 beck Is deprecated and does nothing.
1079 886ed1ae 2016-09-03 jmc .It Ic tlsv1
1080 eb9803db 2015-03-09 reyk Enable all TLSv1 protocols.
1081 1785600c 2023-06-06 beck This is an alias that currently includes
1082 8d09c191 2020-05-14 pvk .Ic tlsv1.2 ,
1084 8d09c191 2020-05-14 pvk .Ic tlsv1.3 .
1085 886ed1ae 2016-09-03 jmc The default is
1086 886ed1ae 2016-09-03 jmc .Ic no tlsv1 .
1087 886ed1ae 2016-09-03 jmc .It Ic tlsv1.0
1088 1785600c 2023-06-06 beck Is deprecated and does nothing.
1089 886ed1ae 2016-09-03 jmc .It Ic tlsv1.1
1090 1785600c 2023-06-06 beck Is deprecated and does nothing.
1092 b688796e 2017-11-15 benno .It Ic http Ar option
1093 b688796e 2017-11-15 benno Set the HTTP options and session settings.
1094 b688796e 2017-11-15 benno This is only used if HTTP is enabled in the relay.
1095 b688796e 2017-11-15 benno Valid options are:
1096 b688796e 2017-11-15 benno .Bl -tag -width Ds
1097 b688796e 2017-11-15 benno .It Ic headerlen Ar number
1098 b688796e 2017-11-15 benno Set the maximum size of all HTTP headers in bytes.
1099 b688796e 2017-11-15 benno The default value is 8192 and it is limited to a maximum of 131072.
1100 c0f9bf60 2019-03-04 benno .It Ic websockets
1101 c0f9bf60 2019-03-04 benno Allow connection upgrade to websocket protocol.
1102 c0f9bf60 2019-03-04 benno The default is
1103 c0f9bf60 2019-03-04 benno .Ic no websockets .
1106 9b58f4a4 2025-07-08 schwarze .Ss Filter rules
1107 c537acf4 2014-07-09 jmc Relays have the ability to filter connections based
1108 69fde657 2014-07-09 reyk on their network or application layer headers.
1109 69fde657 2014-07-09 reyk Filter rules apply options to connections based on the specified
1110 69fde657 2014-07-09 reyk filter parameters.
1112 69fde657 2014-07-09 reyk For each connection that is processed by a relay, the filter rules are
1113 69fde657 2014-07-09 reyk evaluated in sequential order, from first to last.
1115 f0f5730b 2015-11-06 bentley .Ic block
1117 f0f5730b 2015-11-06 bentley .Ic pass ,
1118 69fde657 2014-07-09 reyk the last matching rule decides what action is taken;
1119 69fde657 2014-07-09 reyk if no rule matches the connection, the default action is to establish
1120 69fde657 2014-07-09 reyk the connection without any additional action.
1122 f0f5730b 2015-11-06 bentley .Ic match ,
1123 69fde657 2014-07-09 reyk rules are evaluated every time they match;
1124 69fde657 2014-07-09 reyk the pass/block state of a connection remains unchanged.
1126 69fde657 2014-07-09 reyk The filter action may be one of the following:
1127 69fde657 2014-07-09 reyk .Bl -tag -width Ds
1128 69fde657 2014-07-09 reyk .It Ic block
1129 69fde657 2014-07-09 reyk The connection is blocked.
1132 69fde657 2014-07-09 reyk rule matches a new connection attempt, it will not be established.
1134 69fde657 2014-07-09 reyk rules can also trigger for existing connections after evaluating
1135 69fde657 2014-07-09 reyk application layer parameters;
1136 69fde657 2014-07-09 reyk any connection of the relay session will be instantly dropped.
1137 69fde657 2014-07-09 reyk .It Ic match
1138 69fde657 2014-07-09 reyk The connection is matched.
1139 c537acf4 2014-07-09 jmc This action does not alter the connection state, but allows
1140 69fde657 2014-07-09 reyk additional parameters to the connection.
1141 69fde657 2014-07-09 reyk .It Ic pass
1142 69fde657 2014-07-09 reyk The connection is passed;
1143 69fde657 2014-07-09 reyk .Xr relayd 8
1144 69fde657 2014-07-09 reyk will continue to process the relay session normally.
1147 69fde657 2014-07-09 reyk These filter parameters can be used in the rules:
1148 69fde657 2014-07-09 reyk .Bl -tag -width Ds
1149 69fde657 2014-07-09 reyk .It Ic request No or Ic response
1150 69fde657 2014-07-09 reyk A relay session always consists of two connections:
1152 69fde657 2014-07-09 reyk .Ic request ,
1153 69fde657 2014-07-09 reyk a client initiating a new connection to a server via the relay,
1155 69fde657 2014-07-09 reyk .Ic response ,
1156 69fde657 2014-07-09 reyk the server accepting the connection.
1157 69fde657 2014-07-09 reyk Depending on the protocol,
1158 69fde657 2014-07-09 reyk an established session can be purely request/response-based (like
1159 69fde657 2014-07-09 reyk HTTP), exchange data in a bidirectional way (like arbitrary TCP
1160 69fde657 2014-07-09 reyk sessions), or just contain a single datagram and an optional response
1161 69fde657 2014-07-09 reyk (like UDP-based protocols).
1162 c537acf4 2014-07-09 jmc But the client always
1163 f0f5730b 2015-11-06 bentley .Em requests
1164 69fde657 2014-07-09 reyk to communicate with a remote peer; the server.
1165 69fde657 2014-07-09 reyk .It Ic quick
1166 69fde657 2014-07-09 reyk If a connection is matched by a rule with the
1168 69fde657 2014-07-09 reyk option set,
1169 69fde657 2014-07-09 reyk the rule is considered to be the last matching rule and any further
1170 69fde657 2014-07-09 reyk evaluation is skipped.
1171 69fde657 2014-07-09 reyk .It Ic inet No or Ic inet6
1172 69fde657 2014-07-09 reyk Only match connections with the specified address family,
1173 69fde657 2014-07-09 reyk either of type IPv4 or IPv6.
1174 fc2c091b 2019-05-10 reyk .It Ic from Ar address Ns Oo Li / Ns Ar prefix Oc
1175 fc2c091b 2019-05-10 reyk This rule only matches for connections from the specified source.
1176 fc2c091b 2019-05-10 reyk .It Ic to Ar address Ns Oo Li / Ns Ar prefix Oc
1177 fc2c091b 2019-05-10 reyk This rule only matches for connections to the specified destination.
1178 fc2c091b 2019-05-10 reyk The destination is the address the client was connecting to,
1179 fc2c091b 2019-05-10 reyk typically the relay's listen address in non-transparent mode,
1180 fc2c091b 2019-05-10 reyk not the address of the forwarded backend connection.
1181 886ed1ae 2016-09-03 jmc .It Ic forward to Pf < Ar table Ns >
1182 886ed1ae 2016-09-03 jmc Forward the request to a server in the specified table.
1183 886ed1ae 2016-09-03 jmc With this option, requests can be passed to specific backend servers.
1184 886ed1ae 2016-09-03 jmc A corresponding
1185 886ed1ae 2016-09-03 jmc .Ic forward to
1186 886ed1ae 2016-09-03 jmc declaration in the
1187 9b58f4a4 2025-07-08 schwarze .Sx Relays
1188 886ed1ae 2016-09-03 jmc section is required.
1189 69fde657 2014-07-09 reyk .It Ic label Ar string
1190 69fde657 2014-07-09 reyk The label will be printed as part of the error message if the
1191 69fde657 2014-07-09 reyk .Ic return error
1192 69fde657 2014-07-09 reyk option is set and may contain HTML tags, for example:
1193 69fde657 2014-07-09 reyk .Bd -literal -offset indent
1194 69fde657 2014-07-09 reyk block request url digest 5c1e03f58f8ce0b457474ffb371fd1ef \e
1195 f0f5730b 2015-11-06 bentley label "<a href='http://example.com/adv.pl?id=7359'>\e
1196 f0f5730b 2015-11-06 bentley Advisory provided by example.com</a>"
1198 69fde657 2014-07-09 reyk .It Ic no Ar parameter
1199 69fde657 2014-07-09 reyk Reset a sticky parameter that was previously set by a matching rule.
1201 69fde657 2014-07-09 reyk .Ar parameter
1202 69fde657 2014-07-09 reyk is a keyword that can be either
1206 69fde657 2014-07-09 reyk .It Ic tag Ar string
1207 69fde657 2014-07-09 reyk Add a "sticky" tag to connections matching this filter rule.
1208 69fde657 2014-07-09 reyk Tags can be used to filter the connection by further rules using the
1209 69fde657 2014-07-09 reyk .Ic tagged
1211 69fde657 2014-07-09 reyk Only one tag is assigned per connection;
1212 69fde657 2014-07-09 reyk the tag will be replaced if the connection is already tagged.
1213 69fde657 2014-07-09 reyk .It Ic tagged Ar string
1214 69fde657 2014-07-09 reyk Match the connection if it is already tagged with a given tag by a
1215 69fde657 2014-07-09 reyk previous rule.
1218 69fde657 2014-07-09 reyk The following parameters are available when using the
1221 69fde657 2014-07-09 reyk .Bl -tag -width Ds
1222 f0f5730b 2015-11-06 bentley .It Ic method Ar name
1223 69fde657 2014-07-09 reyk Match the HTTP request method.
1224 69fde657 2014-07-09 reyk The method is specified by
1226 69fde657 2014-07-09 reyk and can be either
1228 7088e981 2016-07-29 reyk .Ic BASELINE-CONTROL ,
1229 7088e981 2016-07-29 reyk .Ic CHECKIN ,
1230 7088e981 2016-07-29 reyk .Ic CHECKOUT ,
1231 69fde657 2014-07-09 reyk .Ic CONNECT ,
1232 69fde657 2014-07-09 reyk .Ic COPY ,
1233 69fde657 2014-07-09 reyk .Ic DELETE ,
1235 69fde657 2014-07-09 reyk .Ic HEAD ,
1236 7088e981 2016-07-29 reyk .Ic LABEL ,
1237 69fde657 2014-07-09 reyk .Ic LOCK ,
1238 7088e981 2016-07-29 reyk .Ic MERGE ,
1239 7088e981 2016-07-29 reyk .Ic MKACTIVITY ,
1240 ee259709 2026-05-19 rsadowski .Ic MKCALENDAR ,
1241 69fde657 2014-07-09 reyk .Ic MKCOL ,
1242 7088e981 2016-07-29 reyk .Ic MKREDIRECTREF ,
1243 7088e981 2016-07-29 reyk .Ic MKWORKSPACE ,
1244 69fde657 2014-07-09 reyk .Ic MOVE ,
1245 69fde657 2014-07-09 reyk .Ic OPTIONS ,
1246 7088e981 2016-07-29 reyk .Ic ORDERPATCH ,
1247 69fde657 2014-07-09 reyk .Ic PATCH ,
1248 69fde657 2014-07-09 reyk .Ic POST ,
1249 69fde657 2014-07-09 reyk .Ic PROPFIND ,
1250 69fde657 2014-07-09 reyk .Ic PROPPATCH ,
1252 7088e981 2016-07-29 reyk .Ic REPORT ,
1253 7088e981 2016-07-29 reyk .Ic SEARCH ,
1254 69fde657 2014-07-09 reyk .Ic TRACE ,
1255 7088e981 2016-07-29 reyk .Ic UNCHECKOUT ,
1256 7088e981 2016-07-29 reyk .Ic UNLOCK ,
1257 7088e981 2016-07-29 reyk .Ic UPDATE ,
1258 7088e981 2016-07-29 reyk .Ic UPDATEREDIRECTREF ,
1260 7088e981 2016-07-29 reyk .Ic VERSION-CONTROL .
1262 8ae53411 2020-04-23 jmc .Ar type option
1263 69fde657 2014-07-09 reyk .Oo Oo Ic digest Oc
1264 69fde657 2014-07-09 reyk .Pq Ar key Ns | Ns Ic file Ar path
1265 69fde657 2014-07-09 reyk .Oo Ic value Ar value Oc Oc
1267 69fde657 2014-07-09 reyk Match a specified HTTP header entity and an optional
1270 69fde657 2014-07-09 reyk .Ic value .
1272 69fde657 2014-07-09 reyk .Ic option
1273 69fde657 2014-07-09 reyk can be specified to modify the matched entity or to trigger an event.
1274 69fde657 2014-07-09 reyk The entity is extracted from the HTTP request or response header and
1275 69fde657 2014-07-09 reyk can be either of
1277 69fde657 2014-07-09 reyk .Ic cookie ,
1278 69fde657 2014-07-09 reyk .Ic header ,
1279 69fde657 2014-07-09 reyk .Ic path ,
1280 69fde657 2014-07-09 reyk .Ic query ,
1284 69fde657 2014-07-09 reyk Instead of a single
1286 69fde657 2014-07-09 reyk multiple keys can be loaded from a
1288 69fde657 2014-07-09 reyk specified by
1290 69fde657 2014-07-09 reyk that contains one key per line.
1291 69fde657 2014-07-09 reyk Lines will be stripped at the first whitespace or newline character
1292 f0f5730b 2015-11-06 bentley and any empty lines or lines beginning with a hash mark
1293 f0f5730b 2015-11-06 bentley .Pq Ql #
1294 f0f5730b 2015-11-06 bentley will be ignored.
1297 69fde657 2014-07-09 reyk .Ic digest
1298 69fde657 2014-07-09 reyk keyword is specified,
1299 69fde657 2014-07-09 reyk compare the message digest of the key against the defined string.
1300 69fde657 2014-07-09 reyk The algorithm used is determined by the string length of the
1302 69fde657 2014-07-09 reyk argument, either SHA1 (40 characters) or MD5 (32 characters).
1303 69fde657 2014-07-09 reyk To compute the digest,
1304 c537acf4 2014-07-09 jmc for example for a
1306 69fde657 2014-07-09 reyk use this simple command:
1307 69fde657 2014-07-09 reyk .Bd -literal -offset indent
1308 69fde657 2014-07-09 reyk $ echo -n "example.com/path/?args" | sha1
1312 69fde657 2014-07-09 reyk .Bq Ar type
1313 69fde657 2014-07-09 reyk may be one of:
1314 69fde657 2014-07-09 reyk .Bl -tag -width Ds
1315 69fde657 2014-07-09 reyk .It Ic cookie Ar option Oo Ar key Oo Ic value Ar value Oc Oc
1316 69fde657 2014-07-09 reyk Look up the entity as a value in the Cookie header.
1317 69fde657 2014-07-09 reyk This type is only available with the direction
1318 69fde657 2014-07-09 reyk .Ic request .
1319 69fde657 2014-07-09 reyk .It Ic header Ar option Oo Ar key Oo Ic value Ar value Oc Oc
1320 69fde657 2014-07-09 reyk Look up the entity in the application protocol headers, like HTTP
1321 69fde657 2014-07-09 reyk headers in
1324 69fde657 2014-07-09 reyk .It Ic path Ar option Oo Ar key Oo Ic value Ar value Oc Oc
1325 69fde657 2014-07-09 reyk Look up the entity as a value in the URL path when using the
1328 69fde657 2014-07-09 reyk This type is only available with the direction
1329 69fde657 2014-07-09 reyk .Ic request .
1332 69fde657 2014-07-09 reyk will match the path of the requested URL without the hostname
1333 69fde657 2014-07-09 reyk and query and the value will match the complete query,
1334 69fde657 2014-07-09 reyk for example:
1335 69fde657 2014-07-09 reyk .Bd -literal -offset indent
1336 69fde657 2014-07-09 reyk block path "/index.html"
1337 69fde657 2014-07-09 reyk block path "/cgi-bin/t.cgi" value "foo=bar*"
1339 d498e80a 2021-01-09 denis .It Ic path strip Ar number
1341 d498e80a 2021-01-09 denis .Ar number
1342 d498e80a 2021-01-09 denis path components from the beginning of the path of the requested URL
1343 d498e80a 2021-01-09 denis when using the
1345 d498e80a 2021-01-09 denis protocol.
1346 d498e80a 2021-01-09 denis This type is only available with the direction
1347 d498e80a 2021-01-09 denis .Ic request .
1348 69fde657 2014-07-09 reyk .It Ic query Ar option Oo Ar key Oo Ic value Ar value Oc Oc
1349 69fde657 2014-07-09 reyk Look up the entity as a query variable in the URL when using the
1352 69fde657 2014-07-09 reyk This type is only available with the direction
1353 69fde657 2014-07-09 reyk .Ic request ,
1354 69fde657 2014-07-09 reyk for example:
1355 69fde657 2014-07-09 reyk .Bd -literal -offset indent
1356 69fde657 2014-07-09 reyk # Will match /cgi-bin/example.pl?foo=bar&ok=yes
1357 507cac58 2017-02-27 benno pass request query "foo" value "bar"
1359 69fde657 2014-07-09 reyk .It Ic url Ar option Oo Oo Ic digest Oc Ar key Oo Ic value Ar value Oc Oc
1360 69fde657 2014-07-09 reyk Look up the entity as a URL suffix/prefix expression consisting of a
1361 69fde657 2014-07-09 reyk canonicalized hostname without port or suffix and a path name or
1362 69fde657 2014-07-09 reyk prefix when using the
1365 69fde657 2014-07-09 reyk This type is only available with the direction
1366 69fde657 2014-07-09 reyk .Ic request ,
1367 69fde657 2014-07-09 reyk for example:
1368 69fde657 2014-07-09 reyk .Bd -literal -offset indent
1369 69fde657 2014-07-09 reyk block url "example.com/index.html"
1370 69fde657 2014-07-09 reyk block url "example.com/test.cgi?val=1"
1373 69fde657 2014-07-09 reyk .Xr relayd 8
1374 69fde657 2014-07-09 reyk will match the full URL and different possible suffix/prefix
1375 69fde657 2014-07-09 reyk combinations by stripping subdomains and path components (up to 5
1376 69fde657 2014-07-09 reyk levels), and the query string.
1377 69fde657 2014-07-09 reyk For example, the following
1378 69fde657 2014-07-09 reyk lookups will be done for
1379 f0f5730b 2015-11-06 bentley http://www.example.com:81/1/2/3/4/5.html?query=yes:
1380 69fde657 2014-07-09 reyk .Bd -literal -offset indent
1381 69fde657 2014-07-09 reyk www.example.com/1/2/3/4/5.html?query=yes
1382 69fde657 2014-07-09 reyk www.example.com/1/2/3/4/5.html
1383 69fde657 2014-07-09 reyk www.example.com/
1384 69fde657 2014-07-09 reyk www.example.com/1/
1385 69fde657 2014-07-09 reyk www.example.com/1/2/
1386 69fde657 2014-07-09 reyk www.example.com/1/2/3/
1387 69fde657 2014-07-09 reyk example.com/1/2/3/4/5.html?query=yes
1388 69fde657 2014-07-09 reyk example.com/1/2/3/4/5.html
1389 69fde657 2014-07-09 reyk example.com/
1390 69fde657 2014-07-09 reyk example.com/1/
1391 69fde657 2014-07-09 reyk example.com/1/2/
1392 69fde657 2014-07-09 reyk example.com/1/2/3/
1396 69fde657 2014-07-09 reyk .Bq Ar option
1397 69fde657 2014-07-09 reyk may be one of:
1398 69fde657 2014-07-09 reyk .Bl -tag -width Ds
1399 69fde657 2014-07-09 reyk .It Ic append
1400 69fde657 2014-07-09 reyk Append the specified
1402 69fde657 2014-07-09 reyk to a protocol entity with the selected
1405 69fde657 2014-07-09 reyk If it does not exist, it will be created with the new value.
1407 69fde657 2014-07-09 reyk The value string may contain predefined macros that will be expanded
1408 69fde657 2014-07-09 reyk at runtime:
1410 69fde657 2014-07-09 reyk .Bl -tag -width $SERVER_ADDR -offset indent -compact
1411 4cc2f5fd 2019-07-05 robert .It Ic $HOST
1412 4cc2f5fd 2019-07-05 robert The Host header's value of the relay.
1413 69fde657 2014-07-09 reyk .It Ic $REMOTE_ADDR
1414 69fde657 2014-07-09 reyk The IP address of the connected client.
1415 69fde657 2014-07-09 reyk .It Ic $REMOTE_PORT
1416 69fde657 2014-07-09 reyk The TCP source port of the connected client.
1417 69fde657 2014-07-09 reyk .It Ic $SERVER_ADDR
1418 69fde657 2014-07-09 reyk The configured IP address of the relay.
1419 69fde657 2014-07-09 reyk .It Ic $SERVER_PORT
1420 69fde657 2014-07-09 reyk The configured TCP server port of the relay.
1421 69fde657 2014-07-09 reyk .It Ic $SERVER_NAME
1422 69fde657 2014-07-09 reyk The server software name of
1423 69fde657 2014-07-09 reyk .Xr relayd 8 .
1424 69fde657 2014-07-09 reyk .It Ic $TIMEOUT
1425 69fde657 2014-07-09 reyk The configured session timeout of the relay.
1427 69fde657 2014-07-09 reyk .It Ic hash
1430 69fde657 2014-07-09 reyk of the selected entity into the load balancing hash to select the
1431 69fde657 2014-07-09 reyk target host.
1434 69fde657 2014-07-09 reyk keyword in the
1435 9b58f4a4 2025-07-08 schwarze .Sx Relays
1436 69fde657 2014-07-09 reyk section above.
1437 69fde657 2014-07-09 reyk .It Ic log
1440 69fde657 2014-07-09 reyk name and the
1442 69fde657 2014-07-09 reyk of the entity.
1443 69fde657 2014-07-09 reyk .It Ic remove
1444 69fde657 2014-07-09 reyk Remove the entity with the selected
1447 69fde657 2014-07-09 reyk .It Ic set
1449 69fde657 2014-07-09 reyk .Ic append
1450 69fde657 2014-07-09 reyk directive above, but change the contents of the specified entity.
1453 69fde657 2014-07-09 reyk does not exist in the request, it will be created with the new
1454 69fde657 2014-07-09 reyk .Ar value .
1459 69fde657 2014-07-09 reyk may contain predefined macros that will be expanded at runtime,
1460 69fde657 2014-07-09 reyk as detailed for the
1461 69fde657 2014-07-09 reyk .Ic append
1462 69fde657 2014-07-09 reyk directive above.
1464 9b58f4a4 2025-07-08 schwarze .Ss Routers
1465 39bc6125 2009-08-13 reyk Routers represent routing table entries in the kernel forwarding
1466 39bc6125 2009-08-13 reyk database, see
1467 39bc6125 2009-08-13 reyk .Xr route 4 ,
1468 39bc6125 2009-08-13 reyk and a table of associated gateways.
1469 39bc6125 2009-08-13 reyk They are used to dynamically insert or remove routes with gateways
1470 39bc6125 2009-08-13 reyk based on their availability and health-check results.
1471 39bc6125 2009-08-13 reyk A router can include multiple network statements and a single forward
1472 39bc6125 2009-08-13 reyk statement with a table of one or more gateways.
1473 39bc6125 2009-08-13 reyk All entries in a single router directive must match the same address
1474 39bc6125 2009-08-13 reyk family, either IPv4 or IPv6.
1476 39bc6125 2009-08-13 reyk The kernel supports multipath routing when multiple gateways exist to
1477 39bc6125 2009-08-13 reyk the same destination address.
1478 39bc6125 2009-08-13 reyk The multipath routing behaviour can be changed globally using the
1479 39bc6125 2009-08-13 reyk .Xr sysctl 8
1481 39bc6125 2009-08-13 reyk .Va net.inet.ip.multipath
1483 39bc6125 2009-08-13 reyk .Va net.inet6.ip6.multipath .
1484 39bc6125 2009-08-13 reyk With the default setting of 0,
1485 39bc6125 2009-08-13 reyk the first route selected will be used for subsequent packets to that
1486 39bc6125 2009-08-13 reyk destination regardless of source.
1487 39bc6125 2009-08-13 reyk Setting it to 1 will enable load balancing based on the packet source
1488 39bc6125 2009-08-13 reyk address across gateways; multiple routes with the same priority are
1489 39bc6125 2009-08-13 reyk used equally.
1490 39bc6125 2009-08-13 reyk The kernel will also check the link state of the related network
1491 39bc6125 2009-08-13 reyk interface and try a different route if it is not active.
1493 39bc6125 2009-08-13 reyk The configuration directives that are valid in the
1494 39bc6125 2009-08-13 reyk .Ic routers
1495 39bc6125 2009-08-13 reyk context are described below:
1496 39bc6125 2009-08-13 reyk .Bl -tag -width Ds
1498 39bc6125 2009-08-13 reyk .Ic forward to
1499 f0f5730b 2015-11-06 bentley .Pf < Ar table Ns >
1500 39bc6125 2009-08-13 reyk .Ic port Ar number
1501 39bc6125 2009-08-13 reyk .Ar options ...
1503 39bc6125 2009-08-13 reyk Specify the table of target gateways to be used; see the
1504 9b58f4a4 2025-07-08 schwarze .Sx Tables
1505 39bc6125 2009-08-13 reyk section above for information about table options.
1506 39bc6125 2009-08-13 reyk This entry is mandatory and must be specified once.
1509 39bc6125 2009-08-13 reyk .Ar address Ns Li / Ns Ar prefix
1511 39bc6125 2009-08-13 reyk Specify the network address and prefix length of a route destination
1512 39bc6125 2009-08-13 reyk that is reachable via the active gateways.
1513 39bc6125 2009-08-13 reyk This entry must be specified at least once in a router directive.
1514 39bc6125 2009-08-13 reyk .It Ic rtable Ar id
1515 39bc6125 2009-08-13 reyk Add the routes to the kernel routing table with the specified
1517 39bc6125 2009-08-13 reyk .It Ic rtlabel Ar label
1518 39bc6125 2009-08-13 reyk Add the routes with the specified
1520 39bc6125 2009-08-13 reyk to the kernel routing table.
1523 a397220c 2013-07-04 jmc .Bl -tag -width Ds -compact
1524 0cf54f77 2007-12-07 deraadt .It Pa /etc/relayd.conf
1525 0cf54f77 2007-12-07 deraadt .Xr relayd 8
1526 9b4e9d87 2007-02-22 jmc configuration file.
1528 dba8a03f 2020-02-10 schwarze .It Pa /etc/examples/relayd.conf
1529 dba8a03f 2020-02-10 schwarze Example configuration file.
1531 9b4e9d87 2007-02-22 jmc .It Pa /etc/services
1532 9b4e9d87 2007-02-22 jmc Service name database.
1534 9b4e9d87 2007-02-22 jmc .It Pa /etc/ssl/address.crt
1535 5c2d6e5a 2012-03-24 sthen .It Pa /etc/ssl/address:port.crt
1536 9b4e9d87 2007-02-22 jmc .It Pa /etc/ssl/private/address.key
1537 5c2d6e5a 2012-03-24 sthen .It Pa /etc/ssl/private/address:port.key
1538 096ff28b 2014-12-12 reyk Location of the relay TLS server certificates, where
1539 9b4e9d87 2007-02-22 jmc .Ar address
1540 5c2d6e5a 2012-03-24 sthen is the configured IP address
1543 5c2d6e5a 2012-03-24 sthen is the configured port number of the relay.
1545 6e8c1015 2009-04-02 reyk .It Pa /etc/ssl/cert.pem
1546 6e8c1015 2009-04-02 reyk Default location of the CA bundle that can be used with
1547 6e8c1015 2009-04-02 reyk .Xr relayd 8 .
1549 30640247 2007-02-22 reyk .Sh EXAMPLES
1550 d250825b 2009-04-24 reyk This configuration file would create a redirection service
1552 5d8d93a9 2006-12-18 jmc which load balances four hosts
1553 5d8d93a9 2006-12-18 jmc and falls back to one host containing a
1554 5d8d93a9 2006-12-18 jmc .Dq sorry page :
1555 41042ecc 2006-12-16 reyk .Bd -literal -offset indent
1556 41042ecc 2006-12-16 reyk www1=front-www1.private.example.com
1557 41042ecc 2006-12-16 reyk www2=front-www2.private.example.com
1558 41042ecc 2006-12-16 reyk www3=front-www3.private.example.com
1559 41042ecc 2006-12-16 reyk www4=front-www4.private.example.com
1561 41042ecc 2006-12-16 reyk interval 5
1563 f0f5730b 2015-11-06 bentley table <phphosts> { $www1, $www2, $www3, $www4 }
1564 f0f5730b 2015-11-06 bentley table <sorryhost> disable { sorryhost.private.example.com }
1566 d7758aba 2007-12-08 reyk redirect "www" {
1567 d7758aba 2007-12-08 reyk listen on www.example.com port 8080 interface trunk0
1568 d7758aba 2007-12-08 reyk listen on www6.example.com port 80 interface trunk0
1570 c209fd5d 2014-07-09 reyk pftag REDIRECTED
1572 f0f5730b 2015-11-06 bentley forward to <phphosts> port 8080 timeout 300 \e
1573 d7758aba 2007-12-08 reyk check http "/" digest "630aa3c2f..."
1574 f0f5730b 2015-11-06 bentley forward to <sorryhost> port 8080 timeout 300 check icmp
1578 d250825b 2009-04-24 reyk It is possible to specify multiple listen directives with different IP
1579 d250825b 2009-04-24 reyk protocols in a single redirection configuration:
1580 d250825b 2009-04-24 reyk .Bd -literal -offset indent
1581 d250825b 2009-04-24 reyk redirect "dns" {
1582 d250825b 2009-04-24 reyk listen on dns.example.com tcp port 53
1583 d250825b 2009-04-24 reyk listen on dns.example.com udp port 53
1585 f0f5730b 2015-11-06 bentley forward to <dnshosts> port 53 check tcp
1589 ee78cec1 2024-09-21 aisha To load balance an IP address over multiple backend servers using a
1591 ee78cec1 2024-09-21 aisha .Cm route-to
1592 ee78cec1 2024-09-21 aisha directive:
1593 ee78cec1 2024-09-21 aisha .Bd -literal -offset indent
1594 ee78cec1 2024-09-21 aisha table <backends> { 10.100.42.71 10.100.42.72 10.100.42.73 }
1596 ee78cec1 2024-09-21 aisha redirect "xmpp" {
1597 ee78cec1 2024-09-21 aisha listen on 10.100.42.2 tcp port 5222
1599 ee78cec1 2024-09-21 aisha route to <backends> port 5222 check tcp interface em0
1603 30640247 2007-02-22 reyk The following configuration would add a relay to forward
1604 30640247 2007-02-22 reyk secure HTTPS connections to a pool of HTTP webservers
1606 30640247 2007-02-22 reyk .Ic loadbalance
1607 096ff28b 2014-12-12 reyk mode (TLS acceleration and layer 7 load balancing).
1608 30640247 2007-02-22 reyk The HTTP protocol definition will add two HTTP headers containing
1609 30640247 2007-02-22 reyk address information of the client and the server, set the
1610 30640247 2007-02-22 reyk .Dq Keep-Alive
1611 30640247 2007-02-22 reyk header value to the configured session timeout,
1612 30640247 2007-02-22 reyk and include the
1613 30640247 2007-02-22 reyk .Dq sessid
1614 30640247 2007-02-22 reyk variable in the hash to calculate the target host:
1615 30640247 2007-02-22 reyk .Bd -literal -offset indent
1616 096ff28b 2014-12-12 reyk http protocol "https" {
1617 40fec2a0 2017-04-19 jmc match header set "X-Forwarded-For" \e
1618 69fde657 2014-07-09 reyk value "$REMOTE_ADDR"
1619 40fec2a0 2017-04-19 jmc match header set "X-Forwarded-By" \e
1620 44765b0d 2017-03-25 claudio value "$SERVER_ADDR:$SERVER_PORT"
1621 69fde657 2014-07-09 reyk match header set "Keep-Alive" value "$TIMEOUT"
1623 69fde657 2014-07-09 reyk match query hash "sessid"
1626 69fde657 2014-07-09 reyk block path "/cgi-bin/index.cgi" value "*command=*"
1628 096ff28b 2014-12-12 reyk tls { no tlsv1.0, ciphers "HIGH" }
1631 096ff28b 2014-12-12 reyk relay "tlsaccel" {
1632 096ff28b 2014-12-12 reyk listen on www.example.com port 443 tls
1633 096ff28b 2014-12-12 reyk protocol "https"
1634 f0f5730b 2015-11-06 bentley forward to <phphosts> port 8080 mode loadbalance check tcp
1638 30640247 2007-02-22 reyk The second relay example will accept incoming connections to port
1639 30640247 2007-02-22 reyk 2222 and forward them to a remote SSH server.
1641 30640247 2007-02-22 reyk .Ic nodelay
1642 30640247 2007-02-22 reyk option will allow a
1643 30640247 2007-02-22 reyk .Dq smooth
1644 30640247 2007-02-22 reyk SSH session without delays between keystrokes or displayed output on
1645 30640247 2007-02-22 reyk the terminal:
1646 30640247 2007-02-22 reyk .Bd -literal -offset indent
1647 ca01b046 2007-12-08 reyk protocol "myssh" {
1648 bd2a0921 2012-11-29 bluhm tcp { nodelay, socket buffer 65536 }
1651 d7758aba 2007-12-08 reyk relay "sshforward" {
1652 bd2a0921 2012-11-29 bluhm listen on www.example.com port 2222
1653 d7758aba 2007-12-08 reyk protocol "myssh"
1654 30640247 2007-02-22 reyk forward to shell.example.com port 22
1658 03668b6b 2013-05-30 reyk The following relay example will configure
1659 096ff28b 2014-12-12 reyk .Dq TLS inspection
1660 03668b6b 2013-05-30 reyk as described in the
1661 9b58f4a4 2025-07-08 schwarze .Sx TLS relays
1663 03668b6b 2013-05-30 reyk To start, first generate a new local CA key and certificate:
1664 03668b6b 2013-05-30 reyk .Bd -literal -offset indent
1665 03668b6b 2013-05-30 reyk # openssl req -x509 -days 365 -newkey rsa:2048 \e
1666 03668b6b 2013-05-30 reyk -keyout /etc/ssl/private/ca.key -out /etc/ssl/ca.crt
1669 53339de6 2015-07-24 jmc A TLS server key and self-signed cert for 127.0.0.1 are also required;
1671 03668b6b 2013-05-30 reyk .Ic listen on
1673 9b58f4a4 2025-07-08 schwarze .Sx Relays
1674 03668b6b 2013-05-30 reyk section for more details about certificate locations.
1675 03668b6b 2013-05-30 reyk Configure the packet filter with a matching divert rule in
1676 03668b6b 2013-05-30 reyk .Xr pf.conf 5 :
1677 03668b6b 2013-05-30 reyk .Bd -literal -offset indent
1678 03668b6b 2013-05-30 reyk # Divert incoming HTTPS traffic to relayd
1679 03668b6b 2013-05-30 reyk pass in on vlan1 inet proto tcp to port 443 \e
1680 03668b6b 2013-05-30 reyk divert-to localhost port 8443
1683 096ff28b 2014-12-12 reyk And finally configure the TLS inspection in
1685 03668b6b 2013-05-30 reyk .Bd -literal -offset indent
1686 03668b6b 2013-05-30 reyk http protocol httpfilter {
1687 03668b6b 2013-05-30 reyk return error
1690 69fde657 2014-07-09 reyk match label "Prohibited!"
1691 69fde657 2014-07-09 reyk block url "social.network.example.com/"
1693 fba21fa4 2023-10-29 kn # New configuration directives for TLS Interception
1694 096ff28b 2014-12-12 reyk tls ca key "/etc/ssl/private/ca.key" password "password123"
1695 096ff28b 2014-12-12 reyk tls ca cert "/etc/ssl/ca.crt"
1698 096ff28b 2014-12-12 reyk relay tlsinspect {
1699 096ff28b 2014-12-12 reyk listen on 127.0.0.1 port 8443 tls
1700 03668b6b 2013-05-30 reyk protocol httpfilter
1701 096ff28b 2014-12-12 reyk forward with tls to destination
1705 39bc6125 2009-08-13 reyk The next simple router configuration example can be used to run
1706 39bc6125 2009-08-13 reyk redundant, health-checked WAN links:
1707 39bc6125 2009-08-13 reyk .Bd -literal -offset indent
1708 f0f5730b 2015-11-06 bentley table <gateways> { $gw1 ip ttl 1, $gw2 ip ttl 1 }
1709 39bc6125 2009-08-13 reyk router "uplinks" {
1710 39bc6125 2009-08-13 reyk route 0.0.0.0/0
1711 f0f5730b 2015-11-06 bentley forward to <gateways> check icmp
1714 41042ecc 2006-12-16 reyk .Sh SEE ALSO
1715 0c91187d 2019-06-26 reyk .Xr ocspcheck 8 ,
1716 0cf54f77 2007-12-07 deraadt .Xr relayctl 8 ,
1717 0cf54f77 2007-12-07 deraadt .Xr relayd 8 ,
1719 30640247 2007-02-22 reyk .Sh HISTORY
1722 d7758aba 2007-12-08 reyk file format, formerly known as
1723 d7758aba 2007-12-08 reyk .Ic hoststated.conf ,
1724 d7758aba 2007-12-08 reyk first appeared in
1726 d7758aba 2007-12-08 reyk It was renamed to
1730 30640247 2007-02-22 reyk .Sh AUTHORS
1731 9b4e9d87 2007-02-22 jmc .An -nosplit
1733 0cf54f77 2007-12-07 deraadt .Xr relayd 8
1734 30640247 2007-02-22 reyk program was written by
1735 1b7259ca 2013-07-16 schwarze .An Pierre-Yves Ritschard Aq Mt pyr@openbsd.org
1737 1b7259ca 2013-07-16 schwarze .An Reyk Floeter Aq Mt reyk@openbsd.org .
1738 6024acb8 2009-04-01 reyk .Sh CAVEATS
1739 6024acb8 2009-04-01 reyk .Xr relayd 8
1740 886ed1ae 2016-09-03 jmc verification of TLS server certificates is based on a static CA bundle
1742 6e8c1015 2009-04-02 reyk .Xr relayd 8
1743 6e8c1015 2009-04-02 reyk currently does not support CRLs (Certificate Revocation Lists).
