1.\" $OpenBSD: relayd.conf.5,v 1.203 2021/01/09 08:53:58 denis Exp $ 2.\" 3.\" Copyright (c) 2006 - 2016 Reyk Floeter <reyk@openbsd.org> 4.\" Copyright (c) 2006, 2007 Pierre-Yves Ritschard <pyr@openbsd.org> 5.\" 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. 9.\" 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. 17.\" 18.Dd $Mdocdate: January 9 2021 $ 19.Dt RELAYD.CONF 5 20.Os 21.Sh NAME 22.Nm relayd.conf 23.Nd relay daemon configuration file 24.Sh DESCRIPTION 25.Nm 26is the configuration file for the relay daemon, 27.Xr relayd 8 . 28.Pp 29.Nm 30is divided into the following main sections: 31.Bl -tag -width xxxx 32.It Sy Macros 33User-defined variables may be defined and used later, simplifying the 34configuration file. 35.It Sy Global Configuration 36Global settings for 37.Xr relayd 8 . 38Do note that the config file allows global settings to be added after 39defining tables in the config file, but those tables will use the 40built-in defaults instead of the global settings below them. 41.It Sy Tables 42Table definitions describe a list of hosts, 43in a similar fashion to 44.Xr pf 4 45tables. 46They are used for relay, redirection, and router target selection with 47the described options and health checking on the host they contain. 48.It Sy Redirections 49Redirections are translated to 50.Xr pf 4 51rdr-to rules for stateful forwarding to a target host from a 52health-checked table on layer 3. 53.It Sy Relays 54Relays allow application layer load balancing, TLS acceleration, and 55general purpose TCP proxying on layer 7. 56.It Sy Protocols 57Protocols are predefined settings and filter rules for relays. 58.It Sy Routers 59Routers are used to insert routes with health-checked gateways for 60(WAN) link balancing. 61.El 62.Pp 63Within the sections, 64a host 65.Ar address 66can be specified by IPv4 address, IPv6 address, interface name, 67interface group, or DNS hostname. 68If the address is an interface name, 69.Xr relayd 8 70will look up the first IPv4 address and any other IPv4 and IPv6 71addresses of the specified network interface. 72A 73.Ar port 74can be specified by number or name. 75The port name to number mappings are found in the file 76.Pa /etc/services ; 77see 78.Xr services 5 79for details. 80.Pp 81The current line can be extended over multiple lines using a backslash 82.Pq Sq \e . 83Comments can be put anywhere in the file using a hash mark 84.Pq Sq # , 85and extend to the end of the current line. 86Care should be taken when commenting out multi-line text: 87the comment is effective until the end of the entire block. 88.Pp 89Argument names not beginning with a letter, digit, or underscore 90must be quoted. 91.Pp 92Additional configuration files can be included with the 93.Ic include 94keyword, for example: 95.Bd -literal -offset indent 96include "/etc/relayd.conf.local" 97.Ed 98.Sh MACROS 99Macros can be defined that will later be expanded in context. 100Macro names must start with a letter, digit, or underscore, 101and may contain any of those characters. 102Macro names may not be reserved words (for example, 103.Ic table , 104.Ic relay , 105or 106.Ic timeout ) . 107Macros are not expanded inside quotes. 108.Pp 109For example: 110.Bd -literal -offset indent 111www1="10.0.0.1" 112www2="10.0.0.2" 113table <webhosts> { 114 $www1 115 $www2 116} 117.Ed 118.Sh GLOBAL CONFIGURATION 119Here are the settings that can be set globally: 120.Bl -tag -width Ds 121.It Ic agentx Oo Ic context Ar context Oc Oo Ic path Ar path Oc 122Export 123.Xr relayd 8 124metrics via an agentx compatible 125.Pq snmp 126daemon by connecting to 127.Ar path . 128Metrics can be found under the relaydMIBObjects subtree 129.Pq enterprises.30155.3 . 130If 131.Ar path 132is omitted it will default to 133.Pa /var/agentx/master . 134.Ar Context 135is the SNMPv3 context and can usually be omitted. 136.It Ic interval Ar number 137Set the interval in seconds at which the hosts will be checked. 138The default interval is 10 seconds. 139.It Xo 140.Ic log 141.Pq Ic state changes Ns | Ns Ic host checks 142.Xc 143Log host checks: 144Either log only the 145.Ic state changes 146of hosts or log all 147.Ic host checks 148that were run, even if the state didn't change. 149The host state can be 150.Dq up 151(the health check completed successfully), 152.Dq down 153(the host is down or didn't match the check criteria), 154or 155.Dq unknown 156(the host is disabled or has not been checked yet). 157.It Xo 158.Ic log connection Op Ic errors 159.Xc 160When using relays, log all TCP connections. 161Optionally log only 162.Ic connection errors . 163.It Ic prefork Ar number 164When using relays, run the specified number of processes to handle 165relayed connections. 166This increases the performance and prevents delays when connecting 167to a relay. 168.Xr relayd 8 169runs 3 relay processes by default and every process will handle 170all configured relays. 171.It Ic socket Qo Ar path Qc 172Create a control socket at 173.Ar path . 174By default 175.Pa /var/run/relayd.sock 176is used. 177.It Ic timeout Ar number 178Set the global timeout in milliseconds for checks. 179This can be overridden by the timeout value in the table definitions. 180The default timeout is 200 milliseconds and it must not exceed the 181global interval. 182Please note that the default value is optimized for checks within the 183same collision domain \(en use a higher timeout, such as 1000 milliseconds, 184for checks of hosts in other subnets. 185If this option is to be set, it should be placed before overrides in tables. 186.El 187.Sh TABLES 188Tables are used to group a set of hosts as the target for redirections 189or relays; they will be mapped to a 190.Xr pf 4 191table for redirections. 192Tables may be defined with the following attribute: 193.Bl -tag -width disable 194.It Ic disable 195Start the table disabled \(en no hosts will be checked in this table. 196The table can be later enabled through 197.Xr relayctl 8 . 198.El 199.Pp 200Each table must contain at least one host 201.Ar address ; 202multiple hosts are separated by newline, comma, or whitespace. 203Host entries may be defined with the following attributes: 204.Bl -tag -width retry 205.It Ic ip ttl Ar number 206Change the default time-to-live value in the IP headers for host checks. 207.It Ic parent Ar number 208The optional parent option inherits the state from a parent 209host with the specified identifier. 210The check will be skipped for this host and copied from the parent host. 211This can be used to prevent multiple checks on hosts with multiple IP 212addresses for the same service. 213The host identifiers are sequentially assigned to the configured hosts 214starting with 1; it can be shown with the 215.Xr relayctl 8 216.Ic show summary 217commands. 218.It Ic priority Ar number 219Change the route priority used when adding a route. 220If not specified, the kernel will set a priority of 8 221.Pq Dv RTP_STATIC . 222In ordinary use, a fallback route should be added statically with a very 223high (e.g. 52) priority. 224Unused in all other modes. 225.It Ic retry Ar number 226The optional retry option adds a tolerance for failed host checks; 227the check will be retried for 228.Ar number 229more times before setting the host state to down. 230If this table is used by a relay, it will also specify the number of 231retries for outgoing connection attempts. 232.El 233.Pp 234For example: 235.Bd -literal -offset indent 236table <service> { 192.168.1.1, 192.168.1.2, 192.168.2.3 } 237table <fallback> disable { 10.1.5.1 retry 2 } 238 239redirect "www" { 240 listen on www.example.com port 80 241 forward to <service> check http "/" code 200 242 forward to <fallback> check http "/" code 200 243} 244.Ed 245.Pp 246Tables are used by 247.Ic forward to 248directives in redirections or relays with a set of general options, 249health-checking rules, and timings; 250see the 251.Sx REDIRECTIONS 252and 253.Sx RELAYS 254sections for more information about the forward context. 255Table specific configuration directives are described below. 256Multiple options can be appended to 257.Ic forward to 258directives, separated by whitespaces. 259.Pp 260The following options will configure the health-checking method for 261the table, and is mandatory for redirections: 262.Bl -tag -width Ds 263.It Xo 264.Ic check http Ar path 265.Op Ic host Ar hostname 266.Ic code Ar number 267.Xc 268For each host in the table, verify that retrieving the URL 269.Ar path 270gives the HTTP return code 271.Ar number . 272If 273.Ar hostname 274is specified, it is used as the 275.Dq Host: 276header to query a specific hostname at the target host. 277To validate the HTTP return code, use this shell command: 278.Bd -literal -offset indent 279$ echo -n "HEAD <path> HTTP/1.0\er\en\er\en" | \e 280 nc <host> <port> | head -n1 281.Ed 282.Pp 283This prints the status header including the actual return code: 284.Bd -literal -offset indent 285HTTP/1.1 200 OK 286.Ed 287.It Xo 288.Ic check https Ar path 289.Op Ic host Ar hostname 290.Ic code Ar number 291.Xc 292This has the same effect as above but wraps the HTTP request in TLS. 293.It Xo 294.Ic check http Ar path 295.Op Ic host Ar hostname 296.Ic digest Ar string 297.Xc 298For each host in the table, verify that retrieving the URL 299.Ar path 300produces non-binary content whose message digest matches the defined string. 301The algorithm used is determined by the string length of the 302.Ar digest 303argument, either SHA1 (40 characters) or MD5 (32 characters). 304If 305.Ar hostname 306is specified, it is used as the 307.Dq Host: 308header to query a specific hostname at the target host. 309The digest does not take the HTTP headers into account. 310Do not specify a binary object (such as a graphic) as the target of the 311request, as 312.Nm 313expects the data returned to be a string. 314To compute the digest, use this simple command: 315.Bd -literal -offset indent 316$ ftp -o - http://host[:port]/path | sha1 317.Ed 318.Pp 319This gives a digest that can be used as-is in a digest statement: 320.Bd -literal -offset indent 321a9993e36476816aba3e25717850c26c9cd0d89d 322.Ed 323.It Xo 324.Ic check https Ar path 325.Op Ic host Ar hostname 326.Ic digest Ar string 327.Xc 328This has the same effect as above but wraps the HTTP request in TLS. 329.It Ic check icmp 330Ping hosts in this table to determine whether they are up or not. 331This method will automatically use ICMP or ICMPV6 depending on the 332address family of each host. 333.It Ic check script Ar path 334Execute an external program to check the host state. 335The program will be executed for each host by specifying the hostname 336on the command line: 337.Bd -literal -offset indent 338/usr/local/bin/checkload.pl front-www1.private.example.com 339.Ed 340.Pp 341.Xr relayd 8 342expects a positive return value on success and zero on failure. 343Note that the script will be executed with the privileges of the 344.Qq _relayd 345user and terminated after 346.Ar timeout 347milliseconds. 348.It Xo 349.Ic check send 350.Ar data 351.Ic expect 352.Ar pattern 353.Op Ic tls 354.Xc 355For each host in the table, a TCP connection is established on the 356port specified, then 357.Ar data 358is sent. 359Incoming data is then read and is expected to match against 360.Ar pattern 361using shell globbing rules. 362If 363.Ar data 364is an empty string or 365.Ic nothing 366then nothing is sent on the connection and data is immediately 367read. 368This can be useful with protocols that output a banner like 369SMTP, NNTP, and FTP. 370If the 371.Ic tls 372keyword is present, 373the transaction will occur in a TLS tunnel. 374.It Xo 375.Ic check binary send 376.Ar data 377.Ic expect 378.Ar data 379.Op Ic tls 380.Xc 381For each host in the table, a TCP connection is established on the 382port specified, then the 383.Ic send 384.Ar data 385is converted into binary and sent. 386Incoming (binary) 387data is then read and is expected to match against a binary 388conversion of the 389.Ic expect 390.Ar data 391using 392.Xr memcmp 3 . 393.Ar data 394must be populated with a string containing an even number of hexadecimal 395single-byte characters and must not be empty. 396This can be useful with binary protocols such as LDAP and SNMP. 397If the 398.Ic tls 399keyword is present, 400the transaction will occur in a TLS tunnel. 401.It Ic check tcp 402Use a simple TCP connect to check that hosts are up. 403.It Ic check tls 404Perform a complete TLS handshake with each host to check their availability. 405.El 406.Pp 407The following general table options are available: 408.Bl -tag -width Ds 409.It Ic demote Ar group 410Enable the per-table 411.Xr carp 4 412demotion option. 413This will increment the carp demotion counter for the 414specified interface group if all hosts in the table are down. 415For more information on interface groups, 416see the 417.Ic group 418keyword in 419.Xr ifconfig 8 . 420.It Ic interval Ar number 421Override the global interval and specify one for this table. 422It must be a multiple of the global interval. 423.It Ic timeout Ar number 424Set the timeout in milliseconds for each host that is checked using 425TCP as the transport. 426This will override the global timeout, which is 200 milliseconds by default. 427.El 428.Pp 429The following options will set the scheduling algorithm to select a 430host from the specified table: 431.Bl -tag -width Ds 432.It Ic mode hash Op Ar key 433Balances the outgoing connections across the active hosts based on the 434.Ar key , 435IP address and port of the relay. 436Additional input can be fed into the 437hash by looking at HTTP headers and GET variables; 438see the 439.Sx PROTOCOLS 440section below. 441This mode is only supported by relays. 442.It Ic mode least-states 443Forward each outgoing connection to the active host with the least 444active 445.Xr pf 4 446states. 447This mode is only supported by redirections. 448.It Ic mode loadbalance Op Ar key 449Balances the outgoing connections across the active hosts based on the 450.Ar key , 451the source IP address of the client, and the IP address and port of the relay. 452This mode is only supported by relays. 453.It Ic mode random 454Distributes the outgoing connections randomly through all active hosts. 455This mode is supported by redirections and relays. 456.It Ic mode roundrobin 457Distributes the outgoing connections using a round-robin scheduler 458through all active hosts. 459This is the default mode and will be used if no option has been specified. 460This mode is supported by redirections and relays. 461.It Ic mode source-hash Op Ar key 462Balances the outgoing connections across the active hosts based on the 463.Ar key 464and the source IP address of the client. 465This mode is supported by redirections and relays. 466.El 467.Pp 468The optional 469.Ar key 470argument can be specified for the 471.Ic hash , 472.Ic loadbalance , 473and 474.Ic source-hash 475modes as either a hex value with a leading 476.Ql 0x 477or as a string. 478If omitted, 479.Xr relayd 8 480generates a random key when the configuration is loaded. 481.Sh REDIRECTIONS 482Redirections represent a 483.Xr pf 4 484rdr-to rule. 485They are used for stateful redirections to the hosts in the specified 486tables. 487.Xr pf 4 488rewrites the target IP addresses and ports of the incoming 489connections, operating on layer 3. 490The configuration directives that are valid in the 491.Ic redirect 492context are described below: 493.Bl -tag -width Ds 494.It Ic disable 495The redirection is initially disabled. 496It can be later enabled through 497.Xr relayctl 8 . 498.It Xo 499.Ic forward to 500.Pf < Ar table Ns > 501.Op Ic port Ar number 502.Ar options ... 503.Xc 504Specify the tables of target hosts to be used; see the 505.Sx TABLES 506section above for information about table options. 507If the 508.Ic port 509option is not specified, the first port from the 510.Ic listen on 511directive will be used. 512This directive can be specified twice \(en the second entry will be used 513as the backup table if all hosts in the main table are down. 514At least one entry for the main table is mandatory. 515.It Xo 516.Ic listen on Ar address 517.Op ip-proto 518.Ic port Ar port 519.Op Ic interface Ar name 520.Xc 521Specify an 522.Ar address 523and a 524.Ar port 525to listen on. 526.Xr pf 4 527will redirect incoming connections for the specified target to the 528hosts in the main or backup table. 529The 530.Ar port 531argument can optionally specify a port range instead of a single port; 532the format is 533.Ar min-port : Ns Ar max-port . 534The optional argument 535.Ar ip-proto 536can be used to specify an IP protocol like 537.Cm tcp 538or 539.Cm udp ; 540it defaults to 541.Cm tcp . 542The rule can be optionally restricted to a given interface name. 543.It Xo 544.Op Ic match 545.Ic pftag Ar name 546.Xc 547Automatically tag packets passing through the 548.Xr pf 4 549rdr-to rule with the name supplied. 550This allows simpler filter rules. 551The optional 552.Ic match 553keyword will change the default rule action from 554.Ql pass in quick 555to 556.Ql match in 557to allow further evaluation in the pf ruleset using the 558.Cm tagged Ar name 559rule option. 560.It Xo 561.Ic route to 562.Pf < Ar table Ns > 563.Op Ic port Ar number 564.Ar options ... 565.Xc 566Like the 567.Ic forward to 568directive, but directly routes the packets to the target host without 569modifying the target address using a 570.Xr pf 4 571route-to rule. 572This can be used for 573.Dq direct server return 574to force the target host to respond via a different gateway. 575Note that hosts have to accept sessions for the same address as 576the gateway, which is typically done by configuring a loopback 577interface on the host with this address. 578.It Ic session timeout Ar seconds 579Specify the inactivity timeout in seconds for established redirections. 580The default timeout is 600 seconds (10 minutes). 581The maximum is 2147483647 seconds (68 years). 582.It Ic sticky-address 583This has the same effect as specifying sticky-address 584for an rdr-to rule in 585.Xr pf.conf 5 . 586It will ensure that multiple connections from the same source are 587mapped to the same redirection address. 588.El 589.Sh RELAYS 590Relays will forward traffic between a client and a target server. 591In contrast to redirections and IP forwarding in the network stack, a 592relay will accept incoming connections from remote clients as a 593server, open an outgoing connection to a target host, and forward 594any traffic between the target host and the remote client, 595operating on layer 7. 596A relay is also called an application layer gateway or layer 7 proxy. 597.Pp 598The main purpose of a relay is to provide advanced load balancing 599functionality based on specified protocol characteristics, such as 600HTTP headers, to provide TLS acceleration and to allow 601basic handling of the underlying application protocol. 602.Pp 603The 604.Ic relay 605configuration directives are described below: 606.Bl -tag -width Ds 607.It Ic disable 608Start the relay but immediately close any accepted connections. 609.It Xo 610.Op Ic transparent 611.Ic forward 612.Op Ic with tls 613.Ic to 614.Ar address 615.Op Ic port Ar port 616.Ar options ... 617.Xc 618Specify the address and port of the target host to connect to. 619If the 620.Ic port 621option is not specified, the port from the 622.Ic listen on 623directive will be used. 624Use the 625.Ic transparent 626keyword to enable fully-transparent mode; the source address of the 627client will be retained in this case. 628.Pp 629The 630.Ic with tls 631directive enables client-side TLS mode to connect to the remote host. 632Verification of server certificates can be enabled by setting the 633.Ic ca file 634option in the protocol section. 635.Pp 636The following options may be specified for forward directives: 637.Bl -tag -width Ds 638.It Ic inet 639If the requested destination is an IPv6 address, 640.Xr relayd 8 641will forward the connection to an IPv4 address which is determined by 642the last 4 octets of the original IPv6 destination. 643For example, if the original IPv6 destination address is 6442001:db8:7395:ffff::a01:101, the session is relayed to the IPv4 645address 10.1.1.1 (a01:101). 646.It Ic inet6 Ar address-prefix 647If the requested destination is an IPv4 address, 648.Xr relayd 8 649will forward the connection to an IPv6 address which is determined by 650setting the last 4 octets of the specified IPv6 651.Ar address-prefix 652to the 4 octets of the original IPv4 destination. 653For example, if the original IPv4 destination address is 10.1.1.1 and 654the specified address prefix is 2001:db8:7395:ffff::, the session is 655relayed to the IPv6 address 2001:db8:7395:ffff::a01:101. 656.It Ic retry Ar number 657The optional host 658.Ic retry 659option will be used as a tolerance for failed 660host connections; the connection will be retried for 661.Ar number 662more times. 663.El 664.It Xo 665.Ic forward to 666.Pf < Ar table Ns > 667.Op Ic port Ar port 668.Ar options ... 669.Xc 670Like the previous directive, but connect to a host from the specified 671table; see the 672.Sx TABLES 673section above for information about table options. 674This directive can be specified multiple times \(en subsequent entries 675will be used as the backup table if all hosts in the previous table 676are down. 677At least one entry for the main table is mandatory. 678As above, use the 679.Ic with tls 680directive to enable client-side TLS mode when connecting to the remote host. 681.It Xo 682.Ic forward to 683.Ic destination 684.Ar options ... 685.Xc 686When redirecting connections with a divert-to rule in 687.Xr pf.conf 5 688to a relay listening on localhost, this directive will 689look up the real destination address of the intended target host, 690allowing the relay to be run as a transparent proxy. 691If an additional 692.Ic forward to 693directive to a specified address or table is present, 694it will be used as a backup if the lookup failed. 695As above, use the 696.Ic with tls 697directive to enable client-side TLS mode when connecting to the remote host. 698.It Xo 699.Ic forward to 700.Ic nat lookup 701.Ar options ... 702.Xc 703Like the previous directive, but for redirections with rdr-to in 704.Xr pf.conf 5 . 705.It Xo 706.Ic listen on Ar address Ic port Ar port 707.Op Ic tls 708.Xc 709Specify the address and port for the relay to listen on. 710The relay will accept incoming connections to the specified address. 711If the 712.Ic tls 713keyword is present, the relay will accept connections using the 714encrypted TLS protocol. 715.It Ic protocol Ar name 716Use the specified protocol definition for the relay. 717The generic TCP protocol options will be used by default; 718see the 719.Sx PROTOCOLS 720section below. 721.It Ic session timeout Ar seconds 722Specify the inactivity timeout in seconds for accepted sessions. 723The default timeout is 600 seconds (10 minutes). 724The maximum is 2147483647 seconds (68 years). 725.El 726.Sh TLS RELAYS 727In addition to plain TCP, 728.Xr relayd 8 729supports the Transport Layer Security (TLS) cryptographic protocol for 730authenticated and encrypted relays. 731TLS is the successor of the original Secure Sockets Layer (SSL) protocol, 732but the term SSL is sometimes still used in modern TLS-based applications. 733.Xr relayd 8 734can operate as a TLS client or server to offer a variety of options 735for different use cases related to TLS. 736.Bl -tag -width Ds 737.It Ic TLS client 738When configuring the relay 739.Ic forward 740statements with the 741.Ic with tls 742directive, 743.Xr relayd 8 744will enable client-side TLS to connect to the remote host. 745This is commonly used for TLS tunneling and transparent encapsulation 746of plain TCP connections. 747See the 748.Ic forward to 749description in the 750.Sx RELAYS 751section for more details. 752.It Ic TLS server 753When specifying the 754.Ic tls 755keyword in the relay 756.Ic listen 757statements, 758.Xr relayd 8 759will accept connections from clients as a TLS server. 760This mode is also known as 761.Dq SSL/TLS acceleration . 762See the 763.Ic listen on 764description in the 765.Sx RELAYS 766section for more details. 767.It Ic TLS client and server 768When combining both modes, TLS server and client, 769.Xr relayd 8 770can filter TLS connections as a man-in-the-middle. 771This combined mode is also called 772.Dq TLS inspection . 773The configuration requires additional X.509 certificate settings; 774see the 775.Ic ca key 776description in the 777.Sx PROTOCOLS 778section for more details. 779.El 780.Pp 781When configured for 782.Dq TLS inspection 783mode, 784.Xr relayd 8 785will listen for incoming connections which have been diverted to the 786local socket by PF. 787Before accepting and negotiating the incoming TLS connection as a 788server, it will look up the original destination address on the 789diverted socket, and pre-connect to the target server as a TLS client 790to obtain the remote TLS certificate. 791It will update or patch the obtained TLS certificate by replacing the 792included public key with its local server key because it doesn't have 793the private key of the remote server certificate. 794It also updates the X.509 issuer name to the local CA subject name and 795signs the certificate with its local CA key. 796This way it keeps all the other X.509 attributes that are already 797present in the server certificate, including the "green bar" extended 798validation attributes. 799Now it finally accepts the TLS connection from the diverted client 800using the updated certificate and continues to handle the connection 801and to connect to the remote server. 802.Sh PROTOCOLS 803Protocols are templates defining settings and rules for relays. 804They allow setting generic TCP options, TLS settings, and rules 805for the selected application layer protocol. 806.Pp 807The protocol directive is available for a number of different 808application layer protocols. 809There is no generic handler for UDP-based protocols because it is a 810stateless datagram-based protocol which has to look into the 811application layer protocol to find any possible state information. 812.Bl -tag -width Ds 813.It Ic dns protocol 814(UDP) 815Domain Name System (DNS) protocol. 816The requested IDs in the DNS header will be used to match the state. 817.Xr relayd 8 818replaces these IDs with random values to compensate for 819predictable values generated by some hosts. 820.It Ic http protocol 821Handle the HyperText Transfer Protocol 822(HTTP, or "HTTPS" if encapsulated in a TLS tunnel). 823.It Xo 824.Op Ic tcp 825.Ic protocol 826.Xc 827Generic handler for TCP-based protocols. 828This is the default. 829.El 830.Pp 831The available configuration directives are described below: 832.Bl -tag -width Ds 833.It Xo 834.Pq Ic block Ns | Ns Ic pass Ns | Ns Ic match 835.Op Ar rule 836.Xc 837Specify one or more rules to filter connections based on their 838network or application layer headers; 839see the 840.Sx FILTER RULES 841section for more details. 842.It Ic return error Op Ar option 843Return an error response to the client if an internal operation or the 844forward connection to the client failed. 845By default, the connection will be silently dropped. 846The effect of this option depends on the protocol: HTTP will send an 847error header and page to the client before closing the connection. 848Additional valid options are: 849.Bl -tag -width Ds 850.It Ic style Ar string 851Specify a Cascading Style Sheet (CSS) to be used for the returned 852HTTP error pages, for example: 853.Bd -literal -offset indent 854body { background: #a00000; color: white; } 855.Ed 856.El 857.It Ic tcp Ar option 858Enable or disable the specified TCP/IP options; see 859.Xr tcp 4 860and 861.Xr ip 4 862for more information about the options. 863Valid options are: 864.Bl -tag -width Ds 865.It Ic backlog Ar number 866Set the maximum length the queue of pending connections may grow to. 867The backlog option is 10 by default, is limited to 512 and capped by the 868.Ic kern.somaxconn 869.Xr sysctl 8 870variable. 871.It Ic ip minttl Ar number 872This option for the underlying IP connection may be used to discard packets 873with a TTL lower than the specified value. 874This can be used to implement the 875Generalized TTL Security Mechanism (GTSM) 876according to RFC 5082. 877.It Ic ip ttl Ar number 878Change the default time-to-live value in the IP headers. 879.It Ic nodelay 880Enable the TCP NODELAY option for this connection. 881This is recommended to avoid delays in the relayed data stream, 882e.g. for SSH connections. 883The default is 884.Ic no nodelay . 885.It Ic no splice 886Disable socket splicing for zero-copy data transfer. 887The default is to enable socket splicing. 888.It Ic sack 889Use selective acknowledgements for this connection. 890The default is 891.Ic no sack . 892.It Ic socket buffer Ar number 893Set the socket-level buffer size for input and output for this 894connection. 895This will affect the TCP window size. 896.El 897.It Ic tls Ar option 898Set the TLS options and session settings. 899This is only used if TLS is enabled in the relay. 900Valid options are: 901.Bl -tag -width Ds 902.It Ic ca cert Ar path 903Specify a CA certificate for TLS inspection. 904For more information, see the 905.Ic ca key 906option below. 907.It Ic ca file Ar path 908This option enables CA verification in TLS client mode. 909The daemon will load the CA (Certificate Authority) certificates from 910the specified path to verify the server certificates. 911.Ox 912provides a default CA bundle in 913.Pa /etc/ssl/cert.pem . 914.It Ic ca key Ar path Ic password Ar password 915Specify a CA key for TLS inspection. 916The 917.Ar password 918argument will specify the password to decrypt the CA key 919(typically an RSA key). 920This option will enable TLS inspection if the following conditions 921are true: 922.Pp 923.Bl -bullet -compact -offset indent 924.It 925TLS server mode is enabled by the 926.Ic listen 927directive: 928.Ic listen on ... tls . 929.It 930TLS client mode and divert lookups are enabled by the 931.Ic forward 932directive: 933.Ic forward with tls to destination . 934.It 935The 936.Ic ca cert 937option is specified. 938.It 939The 940.Ic ca key 941option is specified. 942.El 943.It Ic ciphers Ar string 944Set the string defining the TLS cipher suite. 945If not specified, the default value 946.Ql HIGH:!aNULL 947will be used (strong crypto cipher suites without anonymous DH). 948See the CIPHERS section of 949.Xr openssl 1 950for information about SSL/TLS cipher suites and preference lists. 951.It Ic client-renegotiation 952Allow client-initiated renegotiation. 953To mitigate a potential DoS risk, 954the default is 955.Ic no client-renegotiation . 956.It Ic ecdhe Ar curves 957Specify a comma separated list of elliptic curves to use for ECDHE cipher 958suites, in order of preference. 959The special value of "default" will use the default curves; see 960.Xr tls_config_set_ecdhecurves 3 961for further details. 962.It Ic edh Op Ic params Pq Ic none Ns | Ns Ic auto Ns | Ns Ic legacy 963Enable EDH-based cipher suites with Perfect Forward Secrecy (PFS) for 964older clients that do not support ECDHE. 965In 966.Ic auto 967mode, the key size of the ephemeral key is automatically selected 968based on the size of the private key used for signing. 969In 970.Ic legacy 971mode, a 1024 bit ephemeral key is used. 972If 973.Ic params 974is omitted, 975.Ic auto 976is used. 977The default is 978.Ic no edh . 979.It Ic keypair Ar name 980The relay will attempt to look up a private key in 981.Pa /etc/ssl/private/name:port.key 982and a public certificate in 983.Pa /etc/ssl/name:port.crt , 984where 985.Ar port 986is the specified port that the relay listens on. 987If these files are not present, the relay will continue to look in 988.Pa /etc/ssl/private/name.key 989and 990.Pa /etc/ssl/name.crt . 991This option can be specified multiple times for TLS Server Name Indication. 992If not specified, 993a keypair will be loaded using the specified IP address of the relay as 994.Ar name . 995See 996.Xr ssl 8 997for details about SSL/TLS server certificates. 998.Pp 999An optional OCSP staple file will be used during TLS handshakes with 1000this server if it is found as a non-empty file in 1001.Pa /etc/ssl/name:port.ocsp 1002or 1003.Pa /etc/ssl/name.ocsp . 1004The file should contain a DER-format OCSP response retrieved from an 1005OCSP server for the certificate in use, and can be created using 1006.Xr ocspcheck 8 . 1007.It Ic no cipher-server-preference 1008Prefer the client's cipher list over the server's preferences when 1009choosing a cipher for the connection. 1010The default is to prefer the server's cipher list. 1011.It Ic session tickets 1012Enable TLS session tickets. 1013.Xr relayd 8 1014supports stateless TLS session tickets (RFC 5077) to implement TLS session 1015resumption for connections not using TLSv1.3. 1016The default is to disable session tickets. 1017.It Ic no tlsv1.3 1018Disable the TLSv1.3 protocol. 1019The default is to enable TLSv1.3. 1020.It Ic no tlsv1.2 1021Disable the TLSv1.2 protocol. 1022The default is to enable TLSv1.2. 1023.It Ic sslv3 1024Enable the SSLv3 protocol. 1025The default is 1026.Ic no sslv3 . 1027.It Ic tlsv1 1028Enable all TLSv1 protocols. 1029This is an alias that includes 1030.Ic tlsv1.0 , 1031.Ic tlsv1.1 , 1032.Ic tlsv1.2 , 1033and 1034.Ic tlsv1.3 . 1035The default is 1036.Ic no tlsv1 . 1037.It Ic tlsv1.0 1038Enable the TLSv1.0 protocol. 1039The default is 1040.Ic no tlsv1.0 . 1041.It Ic tlsv1.1 1042Enable the TLSv1.1 protocol. 1043The default is 1044.Ic no tlsv1.1 . 1045.El 1046.It Ic http Ar option 1047Set the HTTP options and session settings. 1048This is only used if HTTP is enabled in the relay. 1049Valid options are: 1050.Bl -tag -width Ds 1051.It Ic headerlen Ar number 1052Set the maximum size of all HTTP headers in bytes. 1053The default value is 8192 and it is limited to a maximum of 131072. 1054.It Ic websockets 1055Allow connection upgrade to websocket protocol. 1056The default is 1057.Ic no websockets . 1058.El 1059.El 1060.Sh FILTER RULES 1061Relays have the ability to filter connections based 1062on their network or application layer headers. 1063Filter rules apply options to connections based on the specified 1064filter parameters. 1065.Pp 1066For each connection that is processed by a relay, the filter rules are 1067evaluated in sequential order, from first to last. 1068For 1069.Ic block 1070and 1071.Ic pass , 1072the last matching rule decides what action is taken; 1073if no rule matches the connection, the default action is to establish 1074the connection without any additional action. 1075For 1076.Ic match , 1077rules are evaluated every time they match; 1078the pass/block state of a connection remains unchanged. 1079.Pp 1080The filter action may be one of the following: 1081.Bl -tag -width Ds 1082.It Ic block 1083The connection is blocked. 1084If a 1085.Ic block 1086rule matches a new connection attempt, it will not be established. 1087.Ic block 1088rules can also trigger for existing connections after evaluating 1089application layer parameters; 1090any connection of the relay session will be instantly dropped. 1091.It Ic match 1092The connection is matched. 1093This action does not alter the connection state, but allows 1094additional parameters to the connection. 1095.It Ic pass 1096The connection is passed; 1097.Xr relayd 8 1098will continue to process the relay session normally. 1099.El 1100.Pp 1101These filter parameters can be used in the rules: 1102.Bl -tag -width Ds 1103.It Ic request No or Ic response 1104A relay session always consists of two connections: 1105the 1106.Ic request , 1107a client initiating a new connection to a server via the relay, 1108and the 1109.Ic response , 1110the server accepting the connection. 1111Depending on the protocol, 1112an established session can be purely request/response-based (like 1113HTTP), exchange data in a bidirectional way (like arbitrary TCP 1114sessions), or just contain a single datagram and an optional response 1115(like UDP-based protocols). 1116But the client always 1117.Em requests 1118to communicate with a remote peer; the server. 1119.It Ic quick 1120If a connection is matched by a rule with the 1121.Ic quick 1122option set, 1123the rule is considered to be the last matching rule and any further 1124evaluation is skipped. 1125.It Ic inet No or Ic inet6 1126Only match connections with the specified address family, 1127either of type IPv4 or IPv6. 1128.It Ic from Ar address Ns Oo Li / Ns Ar prefix Oc 1129This rule only matches for connections from the specified source. 1130.It Ic to Ar address Ns Oo Li / Ns Ar prefix Oc 1131This rule only matches for connections to the specified destination. 1132The destination is the address the client was connecting to, 1133typically the relay's listen address in non-transparent mode, 1134not the address of the forwarded backend connection. 1135.It Ic forward to Pf < Ar table Ns > 1136Forward the request to a server in the specified table. 1137With this option, requests can be passed to specific backend servers. 1138A corresponding 1139.Ic forward to 1140declaration in the 1141.Sx RELAYS 1142section is required. 1143.It Ic label Ar string 1144The label will be printed as part of the error message if the 1145.Ic return error 1146option is set and may contain HTML tags, for example: 1147.Bd -literal -offset indent 1148block request url digest 5c1e03f58f8ce0b457474ffb371fd1ef \e 1149 label "<a href='http://example.com/adv.pl?id=7359'>\e 1150 Advisory provided by example.com</a>" 1151.Ed 1152.It Ic no Ar parameter 1153Reset a sticky parameter that was previously set by a matching rule. 1154The 1155.Ar parameter 1156is a keyword that can be either 1157.Ic label 1158or 1159.Ic tag . 1160.It Ic tag Ar string 1161Add a "sticky" tag to connections matching this filter rule. 1162Tags can be used to filter the connection by further rules using the 1163.Ic tagged 1164option. 1165Only one tag is assigned per connection; 1166the tag will be replaced if the connection is already tagged. 1167.It Ic tagged Ar string 1168Match the connection if it is already tagged with a given tag by a 1169previous rule. 1170.El 1171.Pp 1172The following parameters are available when using the 1173.Ic http 1174protocol: 1175.Bl -tag -width Ds 1176.It Ic method Ar name 1177Match the HTTP request method. 1178The method is specified by 1179.Ar name 1180and can be either 1181.Ic ACL , 1182.Ic BASELINE-CONTROL , 1183.Ic CHECKIN , 1184.Ic CHECKOUT , 1185.Ic CONNECT , 1186.Ic COPY , 1187.Ic DELETE , 1188.Ic GET , 1189.Ic HEAD , 1190.Ic LABEL , 1191.Ic LOCK , 1192.Ic MERGE , 1193.Ic MKACTIVITY , 1194.Ic MKCOL , 1195.Ic MKREDIRECTREF , 1196.Ic MKWORKSPACE , 1197.Ic MOVE , 1198.Ic OPTIONS , 1199.Ic ORDERPATCH , 1200.Ic PATCH , 1201.Ic POST , 1202.Ic PROPFIND , 1203.Ic PROPPATCH , 1204.Ic PUT , 1205.Ic REPORT , 1206.Ic SEARCH , 1207.Ic TRACE , 1208.Ic UNCHECKOUT , 1209.Ic UNLOCK , 1210.Ic UPDATE , 1211.Ic UPDATEREDIRECTREF , 1212or 1213.Ic VERSION-CONTROL . 1214.It Xo 1215.Ar type option 1216.Oo Oo Ic digest Oc 1217.Pq Ar key Ns | Ns Ic file Ar path 1218.Oo Ic value Ar value Oc Oc 1219.Xc 1220Match a specified HTTP header entity and an optional 1221.Ic key 1222and 1223.Ic value . 1224An 1225.Ic option 1226can be specified to modify the matched entity or to trigger an event. 1227The entity is extracted from the HTTP request or response header and 1228can be either of 1229.Ar type 1230.Ic cookie , 1231.Ic header , 1232.Ic path , 1233.Ic query , 1234or 1235.Ic url . 1236.Pp 1237Instead of a single 1238.Ar key , 1239multiple keys can be loaded from a 1240.Ic file 1241specified by 1242.Ar path 1243that contains one key per line. 1244Lines will be stripped at the first whitespace or newline character 1245and any empty lines or lines beginning with a hash mark 1246.Pq Ql # 1247will be ignored. 1248.Pp 1249If the 1250.Ic digest 1251keyword is specified, 1252compare the message digest of the key against the defined string. 1253The algorithm used is determined by the string length of the 1254.Ar key 1255argument, either SHA1 (40 characters) or MD5 (32 characters). 1256To compute the digest, 1257for example for a 1258.Ic url , 1259use this simple command: 1260.Bd -literal -offset indent 1261$ echo -n "example.com/path/?args" | sha1 1262.Ed 1263.El 1264.Pp 1265.Bq Ar type 1266may be one of: 1267.Bl -tag -width Ds 1268.It Ic cookie Ar option Oo Ar key Oo Ic value Ar value Oc Oc 1269Look up the entity as a value in the Cookie header. 1270This type is only available with the direction 1271.Ic request . 1272.It Ic header Ar option Oo Ar key Oo Ic value Ar value Oc Oc 1273Look up the entity in the application protocol headers, like HTTP 1274headers in 1275.Ic http 1276mode. 1277.It Ic path Ar option Oo Ar key Oo Ic value Ar value Oc Oc 1278Look up the entity as a value in the URL path when using the 1279.Ic http 1280protocol. 1281This type is only available with the direction 1282.Ic request . 1283The 1284.Ar key 1285will match the path of the requested URL without the hostname 1286and query and the value will match the complete query, 1287for example: 1288.Bd -literal -offset indent 1289block path "/index.html" 1290block path "/cgi-bin/t.cgi" value "foo=bar*" 1291.Ed 1292.It Ic path strip Ar number 1293Strip 1294.Ar number 1295path components from the beginning of the path of the requested URL 1296when using the 1297.Ic http 1298protocol. 1299This type is only available with the direction 1300.Ic request . 1301.It Ic query Ar option Oo Ar key Oo Ic value Ar value Oc Oc 1302Look up the entity as a query variable in the URL when using the 1303.Ic http 1304protocol. 1305This type is only available with the direction 1306.Ic request , 1307for example: 1308.Bd -literal -offset indent 1309# Will match /cgi-bin/example.pl?foo=bar&ok=yes 1310pass request query "foo" value "bar" 1311.Ed 1312.It Ic url Ar option Oo Oo Ic digest Oc Ar key Oo Ic value Ar value Oc Oc 1313Look up the entity as a URL suffix/prefix expression consisting of a 1314canonicalized hostname without port or suffix and a path name or 1315prefix when using the 1316.Ic http 1317protocol. 1318This type is only available with the direction 1319.Ic request , 1320for example: 1321.Bd -literal -offset indent 1322block url "example.com/index.html" 1323block url "example.com/test.cgi?val=1" 1324.Ed 1325.Pp 1326.Xr relayd 8 1327will match the full URL and different possible suffix/prefix 1328combinations by stripping subdomains and path components (up to 5 1329levels), and the query string. 1330For example, the following 1331lookups will be done for 1332http://www.example.com:81/1/2/3/4/5.html?query=yes: 1333.Bd -literal -offset indent 1334www.example.com/1/2/3/4/5.html?query=yes 1335www.example.com/1/2/3/4/5.html 1336www.example.com/ 1337www.example.com/1/ 1338www.example.com/1/2/ 1339www.example.com/1/2/3/ 1340example.com/1/2/3/4/5.html?query=yes 1341example.com/1/2/3/4/5.html 1342example.com/ 1343example.com/1/ 1344example.com/1/2/ 1345example.com/1/2/3/ 1346.Ed 1347.El 1348.Pp 1349.Bq Ar option 1350may be one of: 1351.Bl -tag -width Ds 1352.It Ic append 1353Append the specified 1354.Ar value 1355to a protocol entity with the selected 1356.Ar key 1357name. 1358If it does not exist, it will be created with the new value. 1359.Pp 1360The value string may contain predefined macros that will be expanded 1361at runtime: 1362.Pp 1363.Bl -tag -width $SERVER_ADDR -offset indent -compact 1364.It Ic $HOST 1365The Host header's value of the relay. 1366.It Ic $REMOTE_ADDR 1367The IP address of the connected client. 1368.It Ic $REMOTE_PORT 1369The TCP source port of the connected client. 1370.It Ic $SERVER_ADDR 1371The configured IP address of the relay. 1372.It Ic $SERVER_PORT 1373The configured TCP server port of the relay. 1374.It Ic $SERVER_NAME 1375The server software name of 1376.Xr relayd 8 . 1377.It Ic $TIMEOUT 1378The configured session timeout of the relay. 1379.El 1380.It Ic hash 1381Feed the 1382.Ar value 1383of the selected entity into the load balancing hash to select the 1384target host. 1385See the 1386.Ic table 1387keyword in the 1388.Sx RELAYS 1389section above. 1390.It Ic log 1391Log the 1392.Ar key 1393name and the 1394.Ar value 1395of the entity. 1396.It Ic remove 1397Remove the entity with the selected 1398.Ar key 1399name. 1400.It Ic set 1401Like the 1402.Ic append 1403directive above, but change the contents of the specified entity. 1404If 1405.Ar key 1406does not exist in the request, it will be created with the new 1407.Ar value . 1408.Pp 1409The 1410.Ar value 1411string 1412may contain predefined macros that will be expanded at runtime, 1413as detailed for the 1414.Ic append 1415directive above. 1416.El 1417.Sh ROUTERS 1418Routers represent routing table entries in the kernel forwarding 1419database, see 1420.Xr route 4 , 1421and a table of associated gateways. 1422They are used to dynamically insert or remove routes with gateways 1423based on their availability and health-check results. 1424A router can include multiple network statements and a single forward 1425statement with a table of one or more gateways. 1426All entries in a single router directive must match the same address 1427family, either IPv4 or IPv6. 1428.Pp 1429The kernel supports multipath routing when multiple gateways exist to 1430the same destination address. 1431The multipath routing behaviour can be changed globally using the 1432.Xr sysctl 8 1433variables 1434.Va net.inet.ip.multipath 1435and 1436.Va net.inet6.ip6.multipath . 1437With the default setting of 0, 1438the first route selected will be used for subsequent packets to that 1439destination regardless of source. 1440Setting it to 1 will enable load balancing based on the packet source 1441address across gateways; multiple routes with the same priority are 1442used equally. 1443The kernel will also check the link state of the related network 1444interface and try a different route if it is not active. 1445.Pp 1446The configuration directives that are valid in the 1447.Ic routers 1448context are described below: 1449.Bl -tag -width Ds 1450.It Xo 1451.Ic forward to 1452.Pf < Ar table Ns > 1453.Ic port Ar number 1454.Ar options ... 1455.Xc 1456Specify the table of target gateways to be used; see the 1457.Sx TABLES 1458section above for information about table options. 1459This entry is mandatory and must be specified once. 1460.It Xo 1461.Ic route 1462.Ar address Ns Li / Ns Ar prefix 1463.Xc 1464Specify the network address and prefix length of a route destination 1465that is reachable via the active gateways. 1466This entry must be specified at least once in a router directive. 1467.It Ic rtable Ar id 1468Add the routes to the kernel routing table with the specified 1469.Ar id . 1470.It Ic rtlabel Ar label 1471Add the routes with the specified 1472.Ar label 1473to the kernel routing table. 1474.El 1475.Sh FILES 1476.Bl -tag -width Ds -compact 1477.It Pa /etc/relayd.conf 1478.Xr relayd 8 1479configuration file. 1480.Pp 1481.It Pa /etc/examples/relayd.conf 1482Example configuration file. 1483.Pp 1484.It Pa /etc/services 1485Service name database. 1486.Pp 1487.It Pa /etc/ssl/address.crt 1488.It Pa /etc/ssl/address:port.crt 1489.It Pa /etc/ssl/private/address.key 1490.It Pa /etc/ssl/private/address:port.key 1491Location of the relay TLS server certificates, where 1492.Ar address 1493is the configured IP address 1494and 1495.Ar port 1496is the configured port number of the relay. 1497.Pp 1498.It Pa /etc/ssl/cert.pem 1499Default location of the CA bundle that can be used with 1500.Xr relayd 8 . 1501.El 1502.Sh EXAMPLES 1503This configuration file would create a redirection service 1504.Dq www 1505which load balances four hosts 1506and falls back to one host containing a 1507.Dq sorry page : 1508.Bd -literal -offset indent 1509www1=front-www1.private.example.com 1510www2=front-www2.private.example.com 1511www3=front-www3.private.example.com 1512www4=front-www4.private.example.com 1513 1514interval 5 1515 1516table <phphosts> { $www1, $www2, $www3, $www4 } 1517table <sorryhost> disable { sorryhost.private.example.com } 1518 1519redirect "www" { 1520 listen on www.example.com port 8080 interface trunk0 1521 listen on www6.example.com port 80 interface trunk0 1522 1523 pftag REDIRECTED 1524 1525 forward to <phphosts> port 8080 timeout 300 \e 1526 check http "/" digest "630aa3c2f..." 1527 forward to <sorryhost> port 8080 timeout 300 check icmp 1528} 1529.Ed 1530.Pp 1531It is possible to specify multiple listen directives with different IP 1532protocols in a single redirection configuration: 1533.Bd -literal -offset indent 1534redirect "dns" { 1535 listen on dns.example.com tcp port 53 1536 listen on dns.example.com udp port 53 1537 1538 forward to <dnshosts> port 53 check tcp 1539} 1540.Ed 1541.Pp 1542The following configuration would add a relay to forward 1543secure HTTPS connections to a pool of HTTP webservers 1544using the 1545.Ic loadbalance 1546mode (TLS acceleration and layer 7 load balancing). 1547The HTTP protocol definition will add two HTTP headers containing 1548address information of the client and the server, set the 1549.Dq Keep-Alive 1550header value to the configured session timeout, 1551and include the 1552.Dq sessid 1553variable in the hash to calculate the target host: 1554.Bd -literal -offset indent 1555http protocol "https" { 1556 match header set "X-Forwarded-For" \e 1557 value "$REMOTE_ADDR" 1558 match header set "X-Forwarded-By" \e 1559 value "$SERVER_ADDR:$SERVER_PORT" 1560 match header set "Keep-Alive" value "$TIMEOUT" 1561 1562 match query hash "sessid" 1563 1564 pass 1565 block path "/cgi-bin/index.cgi" value "*command=*" 1566 1567 tls { no tlsv1.0, ciphers "HIGH" } 1568} 1569 1570relay "tlsaccel" { 1571 listen on www.example.com port 443 tls 1572 protocol "https" 1573 forward to <phphosts> port 8080 mode loadbalance check tcp 1574} 1575.Ed 1576.Pp 1577The second relay example will accept incoming connections to port 15782222 and forward them to a remote SSH server. 1579The TCP 1580.Ic nodelay 1581option will allow a 1582.Dq smooth 1583SSH session without delays between keystrokes or displayed output on 1584the terminal: 1585.Bd -literal -offset indent 1586protocol "myssh" { 1587 tcp { nodelay, socket buffer 65536 } 1588} 1589 1590relay "sshforward" { 1591 listen on www.example.com port 2222 1592 protocol "myssh" 1593 forward to shell.example.com port 22 1594} 1595.Ed 1596.Pp 1597The following relay example will configure 1598.Dq TLS inspection 1599as described in the 1600.Sx TLS RELAYS 1601section. 1602To start, first generate a new local CA key and certificate: 1603.Bd -literal -offset indent 1604# openssl req -x509 -days 365 -newkey rsa:2048 \e 1605 -keyout /etc/ssl/private/ca.key -out /etc/ssl/ca.crt 1606.Ed 1607.Pp 1608A TLS server key and self-signed cert for 127.0.0.1 are also required; 1609see 1610.Ic listen on 1611in the 1612.Sx RELAYS 1613section for more details about certificate locations. 1614Configure the packet filter with a matching divert rule in 1615.Xr pf.conf 5 : 1616.Bd -literal -offset indent 1617# Divert incoming HTTPS traffic to relayd 1618pass in on vlan1 inet proto tcp to port 443 \e 1619 divert-to localhost port 8443 1620.Ed 1621.Pp 1622And finally configure the TLS inspection in 1623.Nm : 1624.Bd -literal -offset indent 1625http protocol httpfilter { 1626 return error 1627 1628 pass 1629 match label "Prohibited!" 1630 block url "social.network.example.com/" 1631 1632 # New configuration directives for SSL/TLS Interception 1633 tls ca key "/etc/ssl/private/ca.key" password "password123" 1634 tls ca cert "/etc/ssl/ca.crt" 1635} 1636 1637relay tlsinspect { 1638 listen on 127.0.0.1 port 8443 tls 1639 protocol httpfilter 1640 forward with tls to destination 1641} 1642.Ed 1643.Pp 1644The next simple router configuration example can be used to run 1645redundant, health-checked WAN links: 1646.Bd -literal -offset indent 1647table <gateways> { $gw1 ip ttl 1, $gw2 ip ttl 1 } 1648router "uplinks" { 1649 route 0.0.0.0/0 1650 forward to <gateways> check icmp 1651} 1652.Ed 1653.Sh SEE ALSO 1654.Xr ocspcheck 8 , 1655.Xr relayctl 8 , 1656.Xr relayd 8 , 1657.Xr ssl 8 1658.Sh HISTORY 1659The 1660.Nm 1661file format, formerly known as 1662.Ic hoststated.conf , 1663first appeared in 1664.Ox 4.1 . 1665It was renamed to 1666.Nm 1667in 1668.Ox 4.3 . 1669.Sh AUTHORS 1670.An -nosplit 1671The 1672.Xr relayd 8 1673program was written by 1674.An Pierre-Yves Ritschard Aq Mt pyr@openbsd.org 1675and 1676.An Reyk Floeter Aq Mt reyk@openbsd.org . 1677.Sh CAVEATS 1678.Xr relayd 8 1679verification of TLS server certificates is based on a static CA bundle 1680and 1681.Xr relayd 8 1682currently does not support CRLs (Certificate Revocation Lists). 1683