Import httpd experiment based on relayd.

1 files changed, 1567 insertions, 0 deletions

diff --git a/httpd.conf.5 b/httpd.conf.5
new file mode 100644
index 0000000..24f823f
--- /dev/null
+++ b/httpd.conf.5
@@ -0,0 +1,1567 @@
+.\"	$OpenBSD: relayd.conf.5,v 1.147 2014/07/11 16:59:38 reyk Exp $
+.\"
+.\" Copyright (c) 2006 - 2014 Reyk Floeter <reyk@openbsd.org>
+.\" Copyright (c) 2006, 2007 Pierre-Yves Ritschard <pyr@openbsd.org>
+.\"
+.\" Permission to use, copy, modify, and distribute this software for any
+.\" purpose with or without fee is hereby granted, provided that the above
+.\" copyright notice and this permission notice appear in all copies.
+.\"
+.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+.\"
+.Dd $Mdocdate: July 11 2014 $
+.Dt RELAYD.CONF 5
+.Os
+.Sh NAME
+.Nm relayd.conf
+.Nd relay daemon configuration file
+.Sh DESCRIPTION
+.Nm
+is the configuration file for the relay daemon,
+.Xr relayd 8 .
+.Sh SECTIONS
+.Nm
+is divided into seven main sections:
+.Bl -tag -width xxxx
+.It Sy Macros
+User-defined variables may be defined and used later, simplifying the
+configuration file.
+.It Sy Global Configuration
+Global settings for
+.Xr relayd 8 .
+Do note that the config file allows global settings to be added after
+defining tables in the config file, but those tables will use the
+built-in defaults instead of the global settings below them.
+.It Sy Tables
+Table definitions describe a list of hosts,
+in a similar fashion to
+.Xr pf 4
+tables.
+They are used for relay, redirection, and router target selection with
+the described options and health checking on the host they contain.
+.It Sy Redirections
+Redirections are translated to
+.Xr pf 4
+rdr-to rules for stateful forwarding to a target host from a
+health-checked table on layer 3.
+.It Sy Relays
+Relays allow application layer load balancing, SSL acceleration, and
+general purpose TCP proxying on layer 7.
+.It Sy Protocols
+Protocols are predefined settings and filter rules for relays.
+.It Sy Routers
+Routers are used to insert routes with health-checked gateways for
+(WAN) link balancing.
+.El
+.Pp
+Within the sections,
+a host
+.Ar address
+can be specified by IPv4 address, IPv6 address, interface name,
+interface group, or DNS hostname.
+If the address is an interface name,
+.Xr relayd 8
+will look up the first IPv4 address and any other IPv4 and IPv6
+addresses of the specified network interface.
+A
+.Ar port
+can be specified by number or name.
+The port name to number mappings are found in the file
+.Pa /etc/services ;
+see
+.Xr services 5
+for details.
+.Pp
+The current line can be extended over multiple lines using a backslash
+.Pq Sq \e .
+Comments can be put anywhere in the file using a hash mark
+.Pq Sq # ,
+and extend to the end of the current line.
+Care should be taken when commenting out multi-line text:
+the comment is effective until the end of the entire block.
+.Pp
+Argument names not beginning with a letter, digit, or underscore
+must be quoted.
+.Pp
+Additional configuration files can be included with the
+.Ic include
+keyword, for example:
+.Bd -literal -offset indent
+include "/etc/relayd.conf.local"
+.Ed
+.Sh MACROS
+Macros can be defined that will later be expanded in context.
+Macro names must start with a letter, digit, or underscore,
+and may contain any of those characters.
+Macro names may not be reserved words (for example,
+.Ic table ,
+.Ic relay ,
+or
+.Ic timeout ) .
+Macros are not expanded inside quotes.
+.Pp
+For example:
+.Bd -literal -offset indent
+www1="10.0.0.1"
+www2="10.0.0.2"
+table \*(Ltwebhosts\*(Gt {
+	$www1
+	$www2
+}
+.Ed
+.Sh GLOBAL CONFIGURATION
+Here are the settings that can be set globally:
+.Bl -tag -width Ds
+.It Ic interval Ar number
+Set the interval in seconds at which the hosts will be checked.
+The default interval is 10 seconds.
+.It Xo
+.Ic log
+.Pq Ic updates Ns | Ns Ic all
+.Xc
+Log state notifications after completed host checks.
+Either only log the
+.Ic updates
+to new states or log
+.Ic all
+state notifications, even if the state didn't change.
+The host state can be
+.Ar up
+(the health check completed successfully),
+.Ar down
+(the host is down or didn't match the check criteria),
+or
+.Ar unknown
+(the host is disabled or has not been checked yet).
+.It Ic prefork Ar number
+When using relays, run the specified number of processes to handle
+relayed connections.
+This increases the performance and prevents delays when connecting
+to a relay.
+.Xr relayd 8
+runs 3 relay processes by default and every process will handle
+all configured relays.
+.It Ic snmp Oo Ic trap Oc Op Qq Ar path
+Send an SNMP trap when the state of a host changes.
+.Xr relayd 8
+will try to connect to
+.Xr snmpd 8
+over the AgentX SNMP socket specified by
+.Ar path
+and request it send a trap to the registered trap receivers.
+If
+.Ar path
+is not specified, a default path of
+.Ar /var/run/agentx.sock
+will be used.
+See
+.Xr snmpd.conf 5
+for more information about SNMP configuration.
+.It Ic timeout Ar number
+Set the global timeout in milliseconds for checks.
+This can be overridden by the timeout value in the table definitions.
+The default interval is 200 milliseconds and it must not exceed the
+global interval.
+Please note that the default value is optimized for checks within the
+same collision domain \(en use a higher timeout, such as 1000 milliseconds,
+for checks of hosts in other subnets.
+If this option is to be set, it should be placed before overrides in tables.
+.El
+.Sh TABLES
+Tables are used to group a set of hosts as the target for redirections
+or relays; they will be mapped to a
+.Xr pf 4
+table for redirections.
+Tables may be defined with the following attribute:
+.Bl -tag -width disable
+.It Ic disable
+Start the table disabled \(en no hosts will be checked in this table.
+The table can be later enabled through
+.Xr relayctl 8 .
+.El
+.Pp
+Each table must contain at least one host
+.Ar address ;
+multiple hosts are separated by newline, comma, or whitespace.
+Host entries may be defined with the following attributes:
+.Bl -tag -width retry
+.It Ic ip ttl Ar number
+Change the default time-to-live value in the IP headers for host checks.
+.It Ic parent Ar number
+The optional parent option inherits the state from a parent
+host with the specified identifier.
+The check will be skipped for this host and copied from the parent host.
+This can be used to prevent multiple checks on hosts with multiple IP
+addresses for the same service.
+The host identifiers are sequentially assigned to the configured hosts
+starting with 1; it can be shown with the
+.Xr relayctl 8
+.Ic show summary
+commands.
+.It Ic priority Ar number
+Change the route priority used when adding a route.
+If not specified, the kernel will set a priority of 8 (RTP_STATIC).
+In ordinary use, a fallback route should be added statically with a very
+high (e.g. 52) priority.
+Unused in all other modes.
+.It Ic retry Ar number
+The optional retry option adds a tolerance for failed host checks;
+the check will be retried for
+.Ar number
+more times before setting the host state to down.
+If this table is used by a relay, it will also specify the number of
+retries for outgoing connection attempts.
+.El
+.Pp
+For example:
+.Bd -literal -offset indent
+table \*(Ltservice\*(Gt { 192.168.1.1, 192.168.1.2, 192.168.2.3 }
+table \*(Ltfallback\*(Gt disable { 10.1.5.1 retry 2 }
+
+redirect "www" {
+	listen on www.example.com port 80
+	forward to \*(Ltservice\*(Gt check http "/" code 200
+	forward to \*(Ltfallback\*(Gt check http "/" code 200
+}
+.Ed
+.Pp
+Tables are used by
+.Ic forward to
+directives in redirections or relays with a set of general options,
+health-checking rules, and timings;
+see the
+.Sx REDIRECTIONS
+and
+.Sx RELAYS
+sections for more information about the forward context.
+Table specific configuration directives are described below.
+Multiple options can be appended to
+.Ic forward to
+directives, separated by whitespaces.
+.Pp
+The following options will configure the health-checking method for
+the table, and is mandatory for redirections:
+.Bl -tag -width Ds
+.It Xo
+.Ic check http Ar path
+.Op Ic host Ar hostname
+.Ic code Ar number
+.Xc
+For each host in the table, verify that retrieving the URL
+.Ar path
+gives the HTTP return code
+.Ar number .
+If
+.Ar hostname
+is specified, it is used as the
+.Dq Host:
+header to query a specific hostname at the target host.
+To validate the HTTP return code, use this shell command:
+.Bd -literal -offset indent
+$ echo -n "HEAD <path> HTTP/1.0\er\en\er\en" | \e
+	nc <host> <port> | head -n1
+.Ed
+.Pp
+This prints the status header including the actual return code:
+.Bd -literal -offset indent
+HTTP/1.1 200 OK
+.Ed
+.It Xo
+.Ic check https Ar path
+.Op Ic host Ar hostname
+.Ic code Ar number
+.Xc
+This has the same effect as above but wraps the HTTP request in SSL.
+.It Xo
+.Ic check http Ar path
+.Op Ic host Ar hostname
+.Ic digest Ar string
+.Xc
+For each host in the table, verify that retrieving the URL
+.Ar path
+produces non-binary content whose message digest matches the defined string.
+The algorithm used is determined by the string length of the
+.Ar digest
+argument, either SHA1 (40 characters) or MD5 (32 characters).
+If
+.Ar hostname
+is specified, it is used as the
+.Dq Host:
+header to query a specific hostname at the target host.
+The digest does not take the HTTP headers into account.
+Do not specify a binary object (such as a graphic) as the target of the
+request, as
+.Nm
+expects the data returned to be a string.
+To compute the digest, use this simple command:
+.Bd -literal -offset indent
+$ ftp -o - http://host[:port]/path | sha1
+.Ed
+.Pp
+This gives a digest that can be used as-is in a digest statement:
+.Bd -literal -offset indent
+a9993e36476816aba3e25717850c26c9cd0d89d
+.Ed
+.It Xo
+.Ic check https Ar path
+.Op Ic host Ar hostname
+.Ic digest Ar string
+.Xc
+This has the same effect as above but wraps the HTTP request in SSL.
+.It Ic check icmp
+Ping hosts in this table to determine whether they are up or not.
+This method will automatically use ICMP or ICMPV6 depending on the
+address family of each host.
+.It Ic check script Ar path
+Execute an external program to check the host state.
+The program will be executed for each host by specifying the hostname
+on the command line:
+.Bd -literal -offset indent
+/usr/local/bin/checkload.pl front-www1.private.example.com
+.Ed
+.Pp
+.Xr relayd 8
+expects a positive return value on success and zero on failure.
+Note that the script will be executed with the privileges of the
+.Qq _relayd
+user and terminated after
+.Ar timeout
+milliseconds.
+.It Xo
+.Ic check send
+.Ar data
+.Ic expect
+.Ar pattern
+.Op Ic ssl
+.Xc
+For each host in the table, a TCP connection is established on the
+port specified, then
+.Ar data
+is sent.
+Incoming data is then read and is expected to match against
+.Ar pattern
+using shell globbing rules.
+If
+.Ar data
+is an empty string or
+.Ic nothing
+then nothing is sent on the connection and data is immediately
+read.
+This can be useful with protocols that output a banner like
+SMTP, NNTP, and FTP.
+If the
+.Ic ssl
+keyword is present,
+the transaction will occur in an SSL tunnel.
+.It Ic check ssl
+Perform a complete SSL handshake with each host to check their availability.
+.It Ic check tcp
+Use a simple TCP connect to check that hosts are up.
+.El
+.Pp
+The following general table options are available:
+.Bl -tag -width Ds
+.It Ic demote Ar group
+Enable the per-table
+.Xr carp 4
+demotion option.
+This will increment the carp demotion counter for the
+specified interface group if all hosts in the table are down.
+For more information on interface groups,
+see the
+.Ic group
+keyword in
+.Xr ifconfig 8 .
+.It Ic interval Ar number
+Override the global interval and specify one for this table.
+It must be a multiple of the global interval.
+.It Ic timeout Ar number
+Set the timeout in milliseconds for each host that is checked using
+TCP as the transport.
+This will override the global timeout, which is 200 milliseconds by default.
+.El
+.Pp
+The following options will set the scheduling algorithm to select a
+host from the specified table:
+.Bl -tag -width Ds
+.It Ic mode hash
+Balances the outgoing connections across the active hosts based on the
+hashed name of the relay, the hashed name of the table, and the IP
+address and port of the relay.
+Additional input can be fed into the
+hash by looking at HTTP headers and GET variables;
+see the
+.Sx PROTOCOLS
+section below.
+This mode is only supported by relays.
+.It Ic mode least-states
+Forward each outgoing connection to the active host with the least
+active
+.Xr pf 4
+states.
+This mode is only supported by redirections.
+.It Ic mode loadbalance
+Balances the outgoing connections across the active hosts based on the
+hashed name of the relay, the hashed name of the table, the source IP
+address of the client, and the IP address and port of the relay.
+This mode is only supported by relays.
+.It Ic mode random
+Distributes the outgoing connections randomly through all active hosts.
+This mode is only supported by relays.
+.It Ic mode roundrobin
+Distributes the outgoing connections using a round-robin scheduler
+through all active hosts.
+This is the default mode and will be used if no option has been specified.
+This mode is supported by redirections and relays.
+.It Ic mode source-hash
+Balances the outgoing connections across the active hosts based on the
+hashed name of the redirection or relay, the hashed name of the table,
+and the source IP address of the client.
+This mode is only supported by relays.
+.El
+.Sh REDIRECTIONS
+Redirections represent a
+.Xr pf 4
+rdr-to rule.
+They are used for stateful redirections to the hosts in the specified
+tables.
+.Xr pf 4
+rewrites the target IP addresses and ports of the incoming
+connections, operating on layer 3.
+The configuration directives that are valid in the
+.Ic redirect
+context are described below:
+.Bl -tag -width Ds
+.It Ic disable
+The redirection is initially disabled.
+It can be later enabled through
+.Xr relayctl 8 .
+.It Xo
+.Ic forward to
+.Aq Ar table
+.Op Ic port Ar number
+.Ar options ...
+.Xc
+Specify the tables of target hosts to be used; see the
+.Sx TABLES
+section above for information about table options.
+If the
+.Ic port
+option is not specified, the first port from the
+.Ic listen on
+directive will be used.
+This directive can be specified twice \(en the second entry will be used
+as the backup table if all hosts in the main table are down.
+At least one entry for the main table is mandatory.
+.It Xo
+.Ic listen on Ar address
+.Op ip-proto
+.Ic port Ar port
+.Op Ic interface Ar name
+.Xc
+Specify an
+.Ar address
+and a
+.Ar port
+to listen on.
+.Xr pf 4
+will redirect incoming connections for the specified target to the
+hosts in the main or backup table.
+The
+.Ar port
+argument can optionally specify a port range instead of a single port;
+the format is
+.Ar min-port : Ns Ar max-port .
+The optional argument
+.Ar ip-proto
+can be used to specify an IP protocol like
+.Ar tcp
+or
+.Ar udp ;
+it defaults to
+.Ar tcp .
+The rule can be optionally restricted to a given interface name.
+.It Xo
+.Ic route to
+.Aq Ar table
+.Op Ic port Ar number
+.Ar options ...
+.Xc
+Like the
+.Ic forward to
+directive, but directly routes the packets to the target host without
+modifying the target address using a
+.Xr pf 4
+route-to rule.
+This can be used for
+.Dq direct server return
+to force the target host to respond via a different gateway.
+Note that hosts have to accept sessions for the same address as
+the gateway, which is typically done by configuring a loopback
+interface on the host with this address.
+.It Ic session timeout Ar seconds
+Specify the inactivity timeout in seconds for established redirections.
+The default timeout is 600 seconds (10 minutes).
+The maximum is 2147483647 seconds (68 years).
+.It Ic sticky-address
+This has the same effect as specifying sticky-address
+for an rdr-to rule in
+.Xr pf.conf 5 .
+It will ensure that multiple connections from the same source are
+mapped to the same redirection address.
+.It Xo
+.Op Ic match
+.Ic pftag Ar name
+.Xc
+Automatically tag packets passing through the
+.Xr pf 4
+rdr-to rule with the name supplied.
+This allows simpler filter rules.
+The optional
+.Ic match
+keyword will change the default rule action from
+.Ar pass in quick
+to
+.Ar match in
+to allow further evaluation in the pf ruleset using the
+.Ar tagged name
+rule option.
+.El
+.Sh RELAYS
+Relays will forward traffic between a client and a target server.
+In contrast to redirections and IP forwarding in the network stack, a
+relay will accept incoming connections from remote clients as a
+server, open an outgoing connection to a target host, and forward
+any traffic between the target host and the remote client,
+operating on layer 7.
+A relay is also called an application layer gateway or layer 7 proxy.
+.Pp
+The main purpose of a relay is to provide advanced load balancing
+functionality based on specified protocol characteristics, such as
+HTTP headers, to provide SSL acceleration and to allow
+basic handling of the underlying application protocol.
+.Pp
+The
+.Ic relay
+configuration directives are described below:
+.Bl -tag -width Ds
+.It Ic disable
+Start the relay but immediately close any accepted connections.
+.It Xo
+.Op Ic transparent
+.Ic forward
+.Op Ic with ssl
+.Ic to
+.Ar address
+.Op Ic port Ar port
+.Ar options ...
+.Xc
+Specify the address and port of the target host to connect to.
+If the
+.Ic port
+option is not specified, the port from the
+.Ic listen on
+directive will be used.
+Use the
+.Ic transparent
+keyword to enable fully-transparent mode; the source address of the
+client will be retained in this case.
+.Pp
+The
+.Ic with ssl
+directive enables client-side SSL mode to connect to the remote host.
+Verification of server certificates can be enabled by setting the
+.Ic ca file
+option in the protocol section.
+.Pp
+The following options may be specified for forward directives:
+.Bl -tag -width Ds
+.It Ic retry Ar number
+The optional host
+.Ic retry
+option will be used as a tolerance for failed
+host connections; the connection will be retried for
+.Ar number
+more times.
+.It Ic inet
+If the requested destination is an IPv6 address,
+.Xr relayd 8
+will forward the connection to an IPv4 address which is determined by
+the last 4 octets of the original IPv6 destination.
+For example, if the original IPv6 destination address is
+2001:db8:7395:ffff::a01:101, the session is relayed to the IPv4
+address 10.1.1.1 (a01:101).
+.It Ic inet6 Ar address-prefix
+If the requested destination is an IPv4 address,
+.Xr relayd 8
+will forward the connection to an IPv6 address which is determined by
+setting the last 4 octets of the specified IPv6
+.Ar address-prefix
+to the 4 octets of the original IPv4 destination.
+For example, if the original IPv4 destination address is 10.1.1.1 and
+the specified address prefix is 2001:db8:7395:ffff::, the session is
+relayed to the IPv6 address 2001:db8:7395:ffff::a01:101.
+.El
+.It Xo
+.Ic forward to
+.Aq Ar table
+.Op Ic port Ar port
+.Ar options ...
+.Xc
+Like the previous directive, but connect to a host from the specified
+table; see the
+.Sx TABLES
+section above for information about table options.
+This directive can be specified multiple times \(en subsequent entries
+will be used as the backup table if all hosts in the previous table
+are down.
+At least one entry for the main table is mandatory.
+.It Xo
+.Ic forward to
+.Ic destination
+.Ar options ...
+.Xc
+When redirecting connections with a divert-to rule in
+.Xr pf.conf 5
+to a relay listening on localhost, this directive will
+look up the real destination address of the intended target host,
+allowing the relay to be run as a transparent proxy.
+If an additional
+.Ic forward to
+directive to a specified address or table is present,
+it will be used as a backup if the lookup failed.
+.It Xo
+.Ic forward to
+.Ic nat lookup
+.Ar options ...
+.Xc
+Like the previous directive, but for redirections with rdr-to in
+.Xr pf.conf 5 .
+.It Xo
+.Ic listen on Ar address
+.Op Ic port Ar port
+.Op Ic ssl
+.Xc
+Specify the address and port for the relay to listen on.
+The relay will accept incoming connections to the specified address.
+If the
+.Ic port
+option is not specified, the port from the
+.Ic listen on
+directive will be used.
+.Pp
+If the
+.Ic ssl
+keyword is present, the relay will accept connections using the
+encrypted SSL protocol.
+The relay will attempt to look up a private key in
+.Pa /etc/ssl/private/address:port.key
+and a public certificate in
+.Pa /etc/ssl/address:port.crt ,
+where
+.Ar address
+is the specified IP address and
+.Ar port
+is the specified port that the relay listens on.
+If these files are not present, the relay will continue to look in
+.Pa /etc/ssl/private/address.key
+and
+.Pa /etc/ssl/address.crt .
+See
+.Xr ssl 8
+for details about SSL server certificates.
+.It Ic protocol Ar name
+Use the specified protocol definition for the relay.
+The generic TCP protocol options will be used by default;
+see the
+.Sx PROTOCOLS
+section below.
+.It Ic session timeout Ar seconds
+Specify the inactivity timeout in seconds for accepted sessions.
+The default timeout is 600 seconds (10 minutes).
+The maximum is 2147483647 seconds (68 years).
+.El
+.Sh SSL RELAYS
+In addition to plain TCP,
+.Xr relayd 8
+supports the Secure Sockets Layer (SSL) and Transport Layer Security
+(TLS) cryptographic protocols for authenticated and encrypted relays.
+TLS is the successor of the original SSL protocol but the term SSL can
+refer to either of the protocols in
+.Nm .
+.Xr relayd 8
+can operate as an SSL client or server to offer a variety of options
+for different use cases related to SSL.
+.Bl -tag -width Ds
+.It Ic SSL client
+When configuring the relay
+.Ic forward
+statements with the
+.Ic with ssl
+directive,
+.Xr relayd 8
+will enable client-side SSL to connect to the remote host.
+This is commonly used for SSL tunneling and transparent encapsulation
+of plain TCP connections.
+See the
+.Ic forward to
+description in the
+.Sx RELAYS
+section for more details.
+.It Ic SSL server
+When specifying the
+.Ic ssl
+keyword in the relay
+.Ic listen
+statements,
+.Xr relayd 8
+will accept connections from clients as an SSL server.
+This mode is also known as
+.Dq SSL acceleration .
+See the
+.Ic listen on
+description in the
+.Sx RELAYS
+section for more details.
+.It Ic SSL client and server
+When combining both modes, SSL server and client,
+.Xr relayd 8
+can filter SSL connections as a man-in-the-middle.
+This combined mode is also called
+.Dq SSL inspection .
+The configuration requires additional X.509 certificate settings;
+see the
+.Ic ca key
+description in the
+.Sx PROTOCOLS
+section for more details.
+.El
+.Pp
+When configured for
+.Dq SSL inspection
+mode,
+.Xr relayd 8
+will listen for incoming connections which have been diverted to the
+local socket by PF.
+Before accepting and negotiating the incoming SSL connection as a
+server, it will look up the original destination address on the
+diverted socket, and pre-connect to the target server as an SSL client
+to obtain the remote SSL certificate.
+It will update or patch the obtained SSL certificate by replacing the
+included public key with its local server key because it doesn't have
+the private key of the remote server certificate.
+It also updates the X.509 issuer name to the local CA subject name and
+signs the certificate with its local CA key.
+This way it keeps all the other X.509 attributes that are already
+present in the server certificate, including the "green bar" extended
+validation attributes.
+Now it finally accepts the SSL connection from the diverted client
+using the updated certificate and continues to handle the connection
+and to connect to the remote server.
+.Sh PROTOCOLS
+Protocols are templates defining settings and rules for relays.
+They allow setting generic TCP options, SSL settings, and rules
+for the selected application layer protocol.
+.Pp
+The protocol directive is available for a number of different
+application layer protocols.
+There is no generic handler for UDP-based protocols because it is a
+stateless datagram-based protocol which has to look into the
+application layer protocol to find any possible state information.
+.Bl -tag -width Ds
+.It Ic dns protocol
+(UDP)
+Domain Name System (DNS) protocol.
+The requested IDs in the DNS header will be used to match the state.
+.Xr relayd 8
+replaces these IDs with random values to compensate for
+predictable values generated by some hosts.
+.It Ic http protocol
+Handle the HyperText Transfer Protocol
+(HTTP, or "HTTPS" if encapsulated in an SSL tunnel).
+.It Xo
+.Op Ic tcp
+.Ic protocol
+.Xc
+Generic handler for TCP-based protocols.
+This is the default.
+.El
+.Pp
+The available configuration directives are described below:
+.Bl -tag -width Ds
+.It Xo
+.Pq Ic block Ns | Ns Ic pass Ns | Ns Ic match
+.Op Ar rule
+.Xc
+Specify one or more rules to filter connections based on their
+network or application layer headers;
+see the
+.Sx FILTER RULES
+section for more details.
+.It Ic return error Op Ar option
+Return an error response to the client if an internal operation or the
+forward connection to the client failed.
+By default, the connection will be silently dropped.
+The effect of this option depends on the protocol: HTTP will send an
+error header and page to the client before closing the connection.
+Additional valid options are:
+.Bl -tag -width Ds
+.It Ic style Ar string
+Specify a Cascading Style Sheet (CSS) to be used for the returned
+HTTP error pages, for example:
+.Bd -literal -offset indent
+body { background: #a00000; color: white; }
+.Ed
+.El
+.It Ic ssl Ar option
+Set the SSL options and session settings.
+This is only used if SSL is enabled in the relay.
+Valid options are:
+.Bl -tag -width Ds
+.It Ic ca cert Ar path
+Specify a CA certificate for SSL inspection.
+For more information, see the
+.Ic ca key
+option below.
+.It Ic ca file Ar path
+This option enables CA verification in SSL client mode.
+The daemon will load the CA (Certificate Authority) certificates from
+the specified path to verify the server certificates.
+.Ox
+provides a default CA bundle in
+.Pa /etc/ssl/cert.pem .
+.It Ic ca key Ar path Ic password Ar password
+Specify a CA key for SSL inspection.
+The
+.Ar password
+argument will specify the password to decrypt the CA key
+(typically an RSA key).
+This option will enable SSL inspection if the following conditions
+are true:
+.Pp
+.Bl -bullet -compact -offset indent
+.It
+SSL client mode is enabled by the
+.Ic listen
+directive:
+.Ic listen on ... ssl .
+.It
+SSL server mode and divert lookups are enabled by the
+.Ic forward
+directive:
+.Ic forward with ssl to destination .
+.It
+The
+.Ic ca cert
+option is specified.
+.It
+The
+.Ic ca key
+option is specified.
+.El
+.It Ic ciphers Ar string
+Set the string defining the SSL cipher suite.
+If not specified, the default value
+.Ar HIGH:!aNULL
+will be used (strong crypto cipher suites without anonymous DH).
+See the CIPHERS section of
+.Xr openssl 1
+for information about SSL cipher suites and preference lists.
+.It Oo Ic no Oc Ic cipher-server-preference
+Prefer the server's cipher list over the client's preferences when
+choosing a cipher for the connection;
+disabled by default.
+.It Oo Ic no Oc Ic client-renegotiation
+Allow client-initiated renegotiation;
+enabled by default.
+Disable to mitigate a potential DoS risk.
+.It Ic ecdh Op Ic curve Ar name
+Set a named curve to use when generating EC keys for ECDHE-based
+cipher suites with Perfect Forward Security (PFS).
+If the curve
+.Ar name
+is not specified, the default curve
+.Ar prime256v1
+will be used.
+ECDHE is enabled by default.
+.It Ic no ecdh
+Disable ECDHE support.
+.It Ic edh Op Ic params Ar maximum
+Enable EDH-based cipher suites with Perfect Forward Security (PFS) for
+older clients that do not support ECDHE.
+If the
+.Ar maximum
+length of the DH params for EDH is not specified, the default value of
+.Ar 1024
+bits will be used.
+Other possible values are numbers between 1024 and 8192, including
+.Ar 1024 ,
+.Ar 1536 ,
+.Ar 2048 ,
+.Ar 4096 ,
+or
+.Ar 8192 .
+Values higher than 1024 bits can cause incompatibilities with older
+SSL clients.
+.It Ic no edh
+Disable EDH support.
+This is the default.
+.It Ic session cache Ar value
+Set the maximum size of the SSL session cache.
+If the
+.Ar value
+is zero, the default size defined by the SSL library will be used.
+A positive number will set the maximum size in bytes and the keyword
+.Ic disable
+will disable the SSL session cache.
+.It Xo
+.Op Ic no
+.Ic sslv2
+.Xc
+Enable the SSLv2 protocol;
+disabled by default.
+.It Xo
+.Op Ic no
+.Ic sslv3
+.Xc
+Disable the SSLv3 protocol;
+enabled by default.
+.It Xo
+.Op Ic no
+.Ic tlsv1
+.Xc
+Disable the TLSv1/SSLv3.1 protocol;
+enabled by default.
+.El
+.It Ic tcp Ar option
+Enable or disable the specified TCP/IP options; see
+.Xr tcp 4
+and
+.Xr ip 4
+for more information about the options.
+Valid options are:
+.Bl -tag -width Ds
+.It Ic backlog Ar number
+Set the maximum length the queue of pending connections may grow to.
+The backlog option is 10 by default and is limited by the
+.Ic kern.somaxconn
+.Xr sysctl 8
+variable.
+.It Ic ip minttl Ar number
+This option for the underlying IP connection may be used to discard packets
+with a TTL lower than the specified value.
+This can be used to implement the
+.Ar Generalized TTL Security Mechanism (GTSM)
+according to RFC 5082.
+.It Ic ip ttl Ar number
+Change the default time-to-live value in the IP headers.
+.It Xo
+.Op Ic no
+.Ic nodelay
+.Xc
+Enable the TCP NODELAY option for this connection.
+This is recommended to avoid delays in the relayed data stream,
+e.g. for SSH connections.
+.It Xo
+.Op Ic no
+.Ic sack
+.Xc
+Use selective acknowledgements for this connection.
+.It Ic socket buffer Ar number
+Set the socket-level buffer size for input and output for this
+connection.
+This will affect the TCP window size.
+.It Xo
+.Op Ic no
+.Ic splice
+.Xc
+Use socket splicing for zero-copy data transfer.
+This option is enabled by default.
+.El
+.El
+.Sh FILTER RULES
+Relays have the ability to filter connections based
+on their network or application layer headers.
+Filter rules apply options to connections based on the specified
+filter parameters.
+.Pp
+For each connection that is processed by a relay, the filter rules are
+evaluated in sequential order, from first to last.
+For
+.Ar block
+and
+.Ar pass ,
+the last matching rule decides what action is taken;
+if no rule matches the connection, the default action is to establish
+the connection without any additional action.
+For
+.Ar match ,
+rules are evaluated every time they match;
+the pass/block state of a connection remains unchanged.
+.Pp
+The filter action may be one of the following:
+.Bl -tag -width Ds
+.It Ic block
+The connection is blocked.
+If a
+.Ic block
+rule matches a new connection attempt, it will not be established.
+.Ic block
+rules can also trigger for existing connections after evaluating
+application layer parameters;
+any connection of the relay session will be instantly dropped.
+.It Ic match
+The connection is matched.
+This action does not alter the connection state, but allows
+additional parameters to the connection.
+.It Ic pass
+The connection is passed;
+.Xr relayd 8
+will continue to process the relay session normally.
+.El
+.Pp
+These filter parameters can be used in the rules:
+.Bl -tag -width Ds
+.It Ic request No or Ic response
+A relay session always consists of two connections:
+the
+.Ic request ,
+a client initiating a new connection to a server via the relay,
+and the
+.Ic response ,
+the server accepting the connection.
+Depending on the protocol,
+an established session can be purely request/response-based (like
+HTTP), exchange data in a bidirectional way (like arbitrary TCP
+sessions), or just contain a single datagram and an optional response
+(like UDP-based protocols).
+But the client always
+.Ar requests
+to communicate with a remote peer; the server.
+.It Ic quick
+If a connection is matched by a rule with the
+.Ic quick
+option set,
+the rule is considered to be the last matching rule and any further
+evaluation is skipped.
+.It Ic inet No or Ic inet6
+Only match connections with the specified address family,
+either of type IPv4 or IPv6.
+.\" XXX .It Ic from
+.\" XXX .It Ic to
+.It Ic label Ar string
+The label will be printed as part of the error message if the
+.Ic return error
+option is set and may contain HTML tags, for example:
+.Bd -literal -offset indent
+block request url digest 5c1e03f58f8ce0b457474ffb371fd1ef \e
+	label "\*(Lta href='http://example.com/adv.pl?id=7359'\*(Gt\e
+	Advisory provided by example.com\*(Lt/a\*(Gt"
+.Ed
+.It Ic no Ar parameter
+Reset a sticky parameter that was previously set by a matching rule.
+The
+.Ar parameter
+is a keyword that can be either
+.Ic label
+or
+.Ic tag .
+.It Ic tag Ar string
+Add a "sticky" tag to connections matching this filter rule.
+Tags can be used to filter the connection by further rules using the
+.Ic tagged
+option.
+Only one tag is assigned per connection;
+the tag will be replaced if the connection is already tagged.
+.It Ic tagged Ar string
+Match the connection if it is already tagged with a given tag by a
+previous rule.
+.El
+.Pp
+The following parameters are available when using the
+.Ic http
+protocol:
+.Bl -tag -width Ds
+.It Ic method Ar NAME
+Match the HTTP request method.
+The method is specified by
+.Ar name
+and can be either
+.Ic CONNECT ,
+.Ic COPY ,
+.Ic DELETE ,
+.Ic GET ,
+.Ic HEAD ,
+.Ic LOCK ,
+.Ic MKCOL ,
+.Ic MOVE ,
+.Ic OPTIONS ,
+.Ic PATCH ,
+.Ic POST ,
+.Ic PROPFIND ,
+.Ic PROPPATCH ,
+.Ic PUT ,
+.Ic TRACE ,
+or
+.Ic UNLOCK .
+.It Xo
+.Ar type Ar option
+.Oo Oo Ic digest Oc
+.Pq Ar key Ns | Ns Ic file Ar path
+.Oo Ic value Ar value Oc Oc
+.Xc
+Match a specified HTTP header entity and an optional
+.Ic key
+and
+.Ic value .
+An
+.Ic option
+can be specified to modify the matched entity or to trigger an event.
+The entity is extracted from the HTTP request or response header and
+can be either of
+.Ar type
+.Ic cookie ,
+.Ic header ,
+.Ic path ,
+.Ic query ,
+or
+.Ic url .
+.Pp
+Instead of a single
+.Ar key ,
+multiple keys can be loaded from a
+.Ic file
+specified by
+.Ar path
+that contains one key per line.
+Lines will be stripped at the first whitespace or newline character
+and any empty lines or lines beginning with a hash mark (`#') will be
+ignored.
+.Pp
+If the
+.Ic digest
+keyword is specified,
+compare the message digest of the key against the defined string.
+The algorithm used is determined by the string length of the
+.Ar key
+argument, either SHA1 (40 characters) or MD5 (32 characters).
+To compute the digest,
+for example for a
+.Ic url ,
+use this simple command:
+.Bd -literal -offset indent
+$ echo -n "example.com/path/?args" | sha1
+.Ed
+.El
+.Pp
+.Bq Ar type
+may be one of:
+.Bl -tag -width Ds
+.It Ic cookie Ar option Oo Ar key Oo Ic value Ar value Oc Oc
+Look up the entity as a value in the Cookie header.
+This type is only available with the direction
+.Ic request .
+.It Ic header Ar option Oo Ar key Oo Ic value Ar value Oc Oc
+Look up the entity in the application protocol headers, like HTTP
+headers in
+.Ic http
+mode.
+.It Ic path Ar option Oo Ar key Oo Ic value Ar value Oc Oc
+Look up the entity as a value in the URL path when using the
+.Ic http
+protocol.
+This type is only available with the direction
+.Ic request .
+The
+.Ar key
+will match the path of the requested URL without the hostname
+and query and the value will match the complete query,
+for example:
+.Bd -literal -offset indent
+block path "/index.html"
+block path "/cgi-bin/t.cgi" value "foo=bar*"
+.Ed
+.It Ic query Ar option Oo Ar key Oo Ic value Ar value Oc Oc
+Look up the entity as a query variable in the URL when using the
+.Ic http
+protocol.
+This type is only available with the direction
+.Ic request ,
+for example:
+.Bd -literal -offset indent
+# Will match /cgi-bin/example.pl?foo=bar&ok=yes
+request query expect "bar" from "foo"
+.Ed
+.It Ic url Ar option Oo Oo Ic digest Oc Ar key Oo Ic value Ar value Oc Oc
+Look up the entity as a URL suffix/prefix expression consisting of a
+canonicalized hostname without port or suffix and a path name or
+prefix when using the
+.Ic http
+protocol.
+This type is only available with the direction
+.Ic request ,
+for example:
+.Bd -literal -offset indent
+block url "example.com/index.html"
+block url "example.com/test.cgi?val=1"
+.Ed
+.Pp
+.Xr relayd 8
+will match the full URL and different possible suffix/prefix
+combinations by stripping subdomains and path components (up to 5
+levels), and the query string.
+For example, the following
+lookups will be done for
+.Ar http://www.example.com:81/1/2/3/4/5.html?query=yes :
+.Bd -literal -offset indent
+www.example.com/1/2/3/4/5.html?query=yes
+www.example.com/1/2/3/4/5.html
+www.example.com/
+www.example.com/1/
+www.example.com/1/2/
+www.example.com/1/2/3/
+example.com/1/2/3/4/5.html?query=yes
+example.com/1/2/3/4/5.html
+example.com/
+example.com/1/
+example.com/1/2/
+example.com/1/2/3/
+.Ed
+.El
+.Pp
+.Bq Ar option
+may be one of:
+.Bl -tag -width Ds
+.It Ic append
+Append the specified
+.Ar value
+to a protocol entity with the selected
+.Ar key
+name.
+If it does not exist, it will be created with the new value.
+.Pp
+The value string may contain predefined macros that will be expanded
+at runtime:
+.Pp
+.Bl -tag -width $SERVER_ADDR -offset indent -compact
+.It Ic $REMOTE_ADDR
+The IP address of the connected client.
+.It Ic $REMOTE_PORT
+The TCP source port of the connected client.
+.It Ic $SERVER_ADDR
+The configured IP address of the relay.
+.It Ic $SERVER_PORT
+The configured TCP server port of the relay.
+.It Ic $SERVER_NAME
+The server software name of
+.Xr relayd 8 .
+.It Ic $TIMEOUT
+The configured session timeout of the relay.
+.El
+.It Ic hash
+Feed the
+.Ar value
+of the selected entity into the load balancing hash to select the
+target host.
+See the
+.Ic table
+keyword in the
+.Sx RELAYS
+section above.
+.It Ic log
+Log the
+.Ar key
+name and the
+.Ar value
+of the entity.
+.It Ic remove
+Remove the entity with the selected
+.Ar key
+name.
+.It Ic set
+Like the
+.Ic append
+directive above, but change the contents of the specified entity.
+If
+.Ar key
+does not exist in the request, it will be created with the new
+.Ar value .
+.Pp
+The
+.Ar value
+string
+may contain predefined macros that will be expanded at runtime,
+as detailed for the
+.Ic append
+directive above.
+.El
+.Sh ROUTERS
+Routers represent routing table entries in the kernel forwarding
+database, see
+.Xr route 4 ,
+and a table of associated gateways.
+They are used to dynamically insert or remove routes with gateways
+based on their availability and health-check results.
+A router can include multiple network statements and a single forward
+statement with a table of one or more gateways.
+All entries in a single router directive must match the same address
+family, either IPv4 or IPv6.
+.Pp
+The kernel supports multipath routing when multiple gateways exist to
+the same destination address.
+The multipath routing behaviour can be changed globally using the
+.Xr sysctl 8
+variables
+.Va net.inet.ip.multipath
+and
+.Va net.inet6.ip6.multipath .
+With the default setting of 0,
+the first route selected will be used for subsequent packets to that
+destination regardless of source.
+Setting it to 1 will enable load balancing based on the packet source
+address across gateways; multiple routes with the same priority are
+used equally.
+The kernel will also check the link state of the related network
+interface and try a different route if it is not active.
+.Pp
+The configuration directives that are valid in the
+.Ic routers
+context are described below:
+.Bl -tag -width Ds
+.It Xo
+.Ic forward to
+.Aq Ar table
+.Ic port Ar number
+.Ar options ...
+.Xc
+Specify the table of target gateways to be used; see the
+.Sx TABLES
+section above for information about table options.
+This entry is mandatory and must be specified once.
+.It Xo
+.Ic route
+.Ar address Ns Li / Ns Ar prefix
+.Xc
+Specify the network address and prefix length of a route destination
+that is reachable via the active gateways.
+This entry must be specified at least once in a router directive.
+.It Ic rtable Ar id
+Add the routes to the kernel routing table with the specified
+.Ar id .
+.It Ic rtlabel Ar label
+Add the routes with the specified
+.Ar label
+to the kernel routing table.
+.El
+.Sh FILES
+.Bl -tag -width Ds -compact
+.It Pa /etc/relayd.conf
+.Xr relayd 8
+configuration file.
+.Pp
+.It Pa /etc/services
+Service name database.
+.Pp
+.It Pa /etc/ssl/address.crt
+.It Pa /etc/ssl/address:port.crt
+.It Pa /etc/ssl/private/address.key
+.It Pa /etc/ssl/private/address:port.key
+Location of the relay SSL server certificates, where
+.Ar address
+is the configured IP address
+and
+.Ar port
+is the configured port number of the relay.
+.Pp
+.It Pa /etc/ssl/cert.pem
+Default location of the CA bundle that can be used with
+.Xr relayd 8 .
+.El
+.Sh EXAMPLES
+This configuration file would create a redirection service
+.Dq www
+which load balances four hosts
+and falls back to one host containing a
+.Dq sorry page :
+.Bd -literal -offset indent
+www1=front-www1.private.example.com
+www2=front-www2.private.example.com
+www3=front-www3.private.example.com
+www4=front-www4.private.example.com
+
+interval 5
+
+table \*(Ltphphosts\*(Gt { $www1, $www2, $www3, $www4 }
+table \*(Ltsorryhost\*(Gt disable { sorryhost.private.example.com }
+
+redirect "www" {
+	listen on www.example.com port 8080 interface trunk0
+	listen on www6.example.com port 80 interface trunk0
+
+	pftag REDIRECTED
+
+	forward to \*(Ltphphosts\*(Gt port 8080 timeout 300 \e
+		check http "/" digest "630aa3c2f..."
+	forward to \*(Ltsorryhost\*(Gt port 8080 timeout 300 check icmp
+}
+.Ed
+.Pp
+It is possible to specify multiple listen directives with different IP
+protocols in a single redirection configuration:
+.Bd -literal -offset indent
+redirect "dns" {
+	listen on dns.example.com tcp port 53
+	listen on dns.example.com udp port 53
+
+	forward to \*(Ltdnshosts\*(Gt port 53 check tcp
+}
+.Ed
+.Pp
+The following configuration would add a relay to forward
+secure HTTPS connections to a pool of HTTP webservers
+using the
+.Ic loadbalance
+mode (SSL acceleration and layer 7 load balancing).
+The HTTP protocol definition will add two HTTP headers containing
+address information of the client and the server, set the
+.Dq Keep-Alive
+header value to the configured session timeout,
+and include the
+.Dq sessid
+variable in the hash to calculate the target host:
+.Bd -literal -offset indent
+http protocol "http_ssl" {
+	match header append "X-Forwarded-For" \e
+		value "$REMOTE_ADDR"
+	match header append "X-Forwarded-By" \e
+		value "$REMOTE_ADDR:$SERVER_PORT"
+	match header set "Keep-Alive" value "$TIMEOUT"
+
+	match query hash "sessid"
+	match hash "sessid"
+
+	pass
+	block path "/cgi-bin/index.cgi" value "*command=*"
+
+	ssl { sslv2, ciphers "MEDIUM:HIGH" }
+}
+
+relay "sslaccel" {
+	listen on www.example.com port 443 ssl
+	protocol "http_ssl"
+	forward to \*(Ltphphosts\*(Gt port 8080 mode loadbalance check tcp
+}
+.Ed
+.Pp
+The second relay example will accept incoming connections to port
+2222 and forward them to a remote SSH server.
+The TCP
+.Ic nodelay
+option will allow a
+.Dq smooth
+SSH session without delays between keystrokes or displayed output on
+the terminal:
+.Bd -literal -offset indent
+protocol "myssh" {
+	tcp { nodelay, socket buffer 65536 }
+}
+
+relay "sshforward" {
+	listen on www.example.com port 2222
+	protocol "myssh"
+	forward to shell.example.com port 22
+}
+.Ed
+.Pp
+The following relay example will configure
+.Dq SSL inspection
+as described in the
+.Sx SSL RELAYS
+section.
+To start, first generate a new local CA key and certificate:
+.Bd -literal -offset indent
+# openssl req -x509 -days 365 -newkey rsa:2048 \e
+	-keyout /etc/ssl/private/ca.key -out /etc/ssl/ca.crt
+.Ed
+.Pp
+An SSL server key and self-signed cert for 127.0.0.1 are also required;
+see
+.Ic listen on
+in the
+.Sx RELAYS
+section for more details about certificate locations.
+Configure the packet filter with a matching divert rule in
+.Xr pf.conf 5 :
+.Bd -literal -offset indent
+# Divert incoming HTTPS traffic to relayd
+pass in on vlan1 inet proto tcp to port 443 \e
+	divert-to localhost port 8443
+.Ed
+.Pp
+And finally configure the SSL inspection in
+.Nm :
+.Bd -literal -offset indent
+http protocol httpfilter {
+	return error
+
+	pass
+	match label "Prohibited!"
+	block url "social.network.example.com/"
+
+	# New configuration directives for SSL Interception
+	ssl ca key "/etc/ssl/private/ca.key" password "password123"
+	ssl ca cert "/etc/ssl/ca.crt"
+}
+
+relay sslinspect {
+	listen on 127.0.0.1 port 8443 ssl
+	protocol httpfilter
+	forward with ssl to destination
+}
+.Ed
+.Pp
+The next simple router configuration example can be used to run
+redundant, health-checked WAN links:
+.Bd -literal -offset indent
+table \*(Ltgateways\*(Gt { $gw1 ip ttl 1, $gw2 ip ttl 1 }
+router "uplinks" {
+	route 0.0.0.0/0
+	forward to \*(Ltgateways\*(Gt check icmp
+}
+.Ed
+.Sh SEE ALSO
+.Xr relayctl 8 ,
+.Xr relayd 8 ,
+.Xr snmpd 8 ,
+.Xr ssl 8
+.Sh HISTORY
+The
+.Nm
+file format, formerly known as
+.Ic hoststated.conf ,
+first appeared in
+.Ox 4.1 .
+It was renamed to
+.Nm
+in
+.Ox 4.3 .
+.Sh AUTHORS
+.An -nosplit
+The
+.Xr relayd 8
+program was written by
+.An Pierre-Yves Ritschard Aq Mt pyr@openbsd.org
+and
+.An Reyk Floeter Aq Mt reyk@openbsd.org .
+.Sh CAVEATS
+.Xr relayd 8
+Verification of SSL server certificates is based on a static CA bundle
+and
+.Xr relayd 8
+currently does not support CRLs (Certificate Revocation Lists).