diff options
Diffstat (limited to 'usr.sbin/relayd/relayd.conf.5')
| -rw-r--r-- | usr.sbin/relayd/relayd.conf.5 | 310 |
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 . |