Add layer 7 functionality to hoststated used for layer 7

loadbalancing, SSL acceleration, general-purpose TCP relaying, and
transparent proxying.

see hoststated.conf(5) and my upcoming article on undeadly.org for
details.

ok to commit deraadt@ pyr@

1 files changed, 306 insertions, 4 deletions

diff --git a/usr.sbin/relayd/relayd.conf.5 b/usr.sbin/relayd/relayd.conf.5
index cbf5efe1ad3..3dbfdfc8a9c 100644
--- a/usr.sbin/relayd/relayd.conf.5
+++ b/usr.sbin/relayd/relayd.conf.5
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: relayd.conf.5,v 1.17 2007/02/07 15:17:46 reyk Exp $
+.\"	$OpenBSD: relayd.conf.5,v 1.18 2007/02/22 03:32:39 reyk Exp $
 .\"
 .\" Copyright (c) 2006 Pierre-Yves Ritschard <pyr@spootnik.org>
 .\"
@@ -26,7 +26,7 @@ is the configuration file for the Host Status Daemon,
 .Xr hoststated 8 .
 .Sh SECTIONS
 .Nm
-is divided into four main sections:
+is divided into six main sections:
 .Bl -tag -width xxxx
 .It Sy Macros
 User-defined variables may be defined and used later, simplifying the
@@ -43,6 +43,11 @@ they contain.
 Services will be translated to
 .Xr pf 4
 rdr rules if their table or backup table have content.
+.It Sy Relays
+Relays allow layer 7 loadbalancing, SSL acceleration, and
+general-purpose TCP proxying.
+.It Sy Protocols
+Protocols are predefined protocol handlers and settings for relays.
 .El
 .Pp
 Within the sections,
@@ -109,6 +114,15 @@ or
 .Ar unknown
 (the host is disabled or has not been checked yet).
 .Pp
+.It Ic prefork Ar number
+When using relays, run the specified number of processes to handle
+relayed connections.
+This will increase the performance and prevents delays when connecting
+to a relay.
+.Xr hoststated 8
+will run 5 relay processes by default and every process will handle
+all configured relays.
+.Pp
 .It Xo
 .Ic timeout Ar number
 .Xc
@@ -252,7 +266,231 @@ to specify which interface the rdr rule will be enabled on:
 interface ``ifname''
 .Ed
 .El
-.Sh EXAMPLE
+.Sh RELAYS
+Relays will forward TCP traffic between a client and a target server.
+In contrast to IP forwarding and redirection in the network stack, a
+relay will accept incoming TCP 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.
+A relay is also called an application layer or layer 7 proxy.
+.Pp
+The main purpose of a relay is to provide advanced loadbalancing
+functionality based on specified protocol characteristics, such as
+HTTP headers, to provide SSL acceleration functionality and to allow
+basic handling of the underlying application protocol.
+.Pp
+The relay configuration directives are described below.
+.Bl -tag -width Ds
+.It Xo
+.Ic listen on Ar address 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.
+.Pp
+If the 
+.Ic ssl
+keyword is present, the relay will accept connections using the
+encrypted SSL protocol.
+The relay will lookup a private key in
+.Pa /etc/ssl/private/address.key
+and a public certificate in
+.Pa /etc/ssl/address.crt
+in this case, 
+where
+.Ar address
+is the specified IP address of the relay to listen on.
+See
+.Xr ssl 8
+for details about SSL server certificates.
+.It Ic forward to Ar address Ic port Ar port
+Specify the address and port of the target host to connect to.
+.It Ic service Ar name
+Use the first virtual IP address and port from the specified service
+as the target host to connect to.
+This is exclusive to the
+.Ic forward to
+and
+.Ic table
+directives.
+.It Xo
+.Ic table Ar name Ar mode
+.Op Ic no check
+.Xc
+Get the target host from the specified table.
+The following modes are available to select a host from the specified
+table:
+.Pp
+.Bl -tag -width loadbalance -offset indent -compact
+.It Ic roundrobin
+distributes the outgoing connections using a round-robin scheduler
+through all active hosts.
+.It Ic loadbalance
+Balances the outgoing connections across the active hosts based on the
+hashed name of the table, the source and destination addresses,
+and the corresponding ports.
+.It Ic hash
+Like the
+.Ic loadbalance
+mode, but without including the source and destination addresses and
+ports.
+Additional input can be feeded into the hash by looking at HTTP
+headers and GET variables, see the
+.Sx Protocols
+section below.
+.El
+.It Ic nat lookup
+When redirecting connections with a
+.Ar rdr
+rule in
+.Xr pf.conf 5
+to a relay listening on localhost, this directive will allow to
+lookup the real destination address of the intended target host.
+This allows to run the relay as a transparent proxy.
+If either the
+.Ic forward to ,
+.Ic service ,
+or
+.Ic table
+directive is present, it will be used as a backup if the NAT lookup
+failed.
+.It Ic timeout Ar seconds
+Specify the timeout in seconds for accepted sessions.
+The default timeout is 600 seconds (10 minutes).
+.It Ic disable
+Start the relay but immediately close any accepted connections.
+.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.
+.El
+.Sh PROTOCOLS
+Protocols are templates defining actions and settings for relays.
+They allow to set generic TCP options, SSL settings, and actions
+specific to the selected application layer protocol.
+.Pp
+The protocol configuration directives are described below.
+.Bl -tag -width Ds
+.It Ic protocol Ar type
+Enable special handling of the specified application layer protocol.
+The supported protocols are:
+.Pp
+.Bl -tag -width http -offset indent -compact
+.It Ic http
+Handle the Hypertext Transfer Protocol
+(HTTP or "HTTPS" if encapsulated in a SSL tunnel).
+.It Ic tcp
+Generic handler for TCP-based protocols.
+.El
+.It Ic append Ar value Ic to Ar key
+Append the specified value to a protocol entity with the selected name.
+When using the
+.Ic http
+protocol,
+.Ic key
+will indicate a specified HTTP header.
+.It Ic change Ar key Ic to Ar value
+Like the
+.Ic append
+directive above, but change the contents of the specified entity.
+.It Ic remove Ar key
+Remove the entity with the selected name.
+.It Xo
+.Op Ic url
+.Ic expect Ar value Ic from Ar key
+.Xc
+Expect an entity with the specified value.
+If the entity is not present or the value doesn't match, the connection
+will be dropped.
+The
+.Ic url
+keyword will expect the value as a GET variable in the URL instead
+of a HTTP header value when using the
+.Ic http
+protocol.
+.It Xo
+.Op Ic url
+.Ic filter Ar value Ic from Ar key
+.Xc
+Like the
+.Ic expect
+directive above, but drop any connections with the specified entity
+and value.
+.It Xo
+.Op Ic url
+.Ic hash Ar key
+.Xc
+Feed the value of the selected entity into the loadbalancing hash to
+select the target host.
+See the
+.Ic table
+keyword in the
+.Sx Relays
+section above.
+The
+.Ic url
+keyword will lookup the entity as a GET variable in the URL instead
+of a HTTP header value when using the
+.Ic http
+protocol.
+.It Ic tcp Ar option
+Enable or disable the specified TCP option, see
+.Xr tcp 4
+for details about TCP options.
+Valid options are:
+.Pp
+.Bl -tag -width Ds
+.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,
+ie. 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.
+.El
+.It Ic ssl 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 maximun size in bytes and the
+keyword
+.Ic disable
+will disable the SSL session cache.
+.El
+.Pp
+The
+.Ar value
+strings of the
+.Ic append
+and
+.Ic change
+directives may contain predefined macros that will be expanded on 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 $TIMEOUT
+The configured session timeout of the relay.
+.El
+.Sh EXAMPLES
 This configuration file would create a service
 .Dq www
 which load balances four hosts
@@ -293,6 +531,52 @@ service www {
 	backup table sorryhost
 }
 .Ed
+.Pp
+The following configuration would add a relay to forward
+secure HTTPS connections to a pool of HTTP webservers
+using the
+.Ic loadbalance
+protocol (SSL acceleration and layer 7 loadbalancing).
+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
+protocol http_ssl {
+        protocol http
+        append "$REMOTE_ADDR" to "X-Forwarded-For"
+        append "$SERVER_ADDR:$SERVER_PORT" to "X-Forwarded-By"
+        change "Keep-Alive" to "$TIMEOUT"
+	url hash "sessid"
+}
+
+relay sslaccel {
+        listen on www.example.com port 443 ssl
+        protocol http_ssl
+        table phphosts loadbalance
+}
+.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 http_ssl {
+        tcp { nodelay, socket buffer 65536 }
+}
+
+relay sshforward {
+        listen on www.example.com port 2222
+	forward to shell.example.com port 22
+}
 .Sh FILES
 .Bl -tag -width "/etc/hoststated.conf" -compact
 .It Pa /etc/hoststated.conf
@@ -300,7 +584,25 @@ service www {
 configuration file
 .It Pa /etc/services
 Service name database
+.It Pa /etc/ssl/private/address.key
+.It Pa /etc/ssl/address.crt
+Location of the relay SSL server certificates, where
+.Ar address
+is the configured IP address of the relay.
 .El
 .Sh SEE ALSO
 .Xr hoststatectl 8 ,
-.Xr hoststated 8
+.Xr hoststated 8 ,
+.Xr ssl 8
+.Sh HISTORY
+The
+.Nm
+program first appeared in
+.Ox 4.1 .
+.Sh AUTHORS
+The
+.Nm
+program was written by
+.An Pierre-Yves Ritschard Aq pyr@openbsd.org
+and
+.An Reyk Floeter Aq reyk@openbsd.org .