.\" $OpenBSD: hoststated.conf.5,v 1.28 2007/02/26 11:59:48 reyk Exp $ .\" .\" Copyright (c) 2006 Pierre-Yves Ritschard .\" .\" 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 November 1, 2006 .Dt HOSTSTATED.CONF 5 .Os .Sh NAME .Nm hoststated.conf .Nd Host Status daemon configuration file .Sh DESCRIPTION .Nm is the configuration file for the Host Status Daemon, .Xr hoststated 8 . .Sh SECTIONS .Nm is divided into six 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 hoststated 8 . .It Sy Tables Table definitions describe the content of a .Xr pf 4 table and the method used for checking the health of the hosts they contain. .It Sy Services 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 load balancing, SSL acceleration, and general purpose TCP proxying. .It Sy Protocols Protocols are predefined protocol handlers and settings for relays. .El .Pp Within the sections, a host .Ar address can be either specified by IPv4 address, IPv6 address, or DNS host name. A .Ar port can be either specified by number or by name. The port name to number mappings are found in the file .Pa /etc/services ; see .Xr services 5 for details. .Sh MACROS Macros can be defined that will later be expanded in context. Macro names must start with a letter, and may contain letters, digits, and underscores. Macro names may not be reserved words (for example, .Ic table , .Ic service , 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 webhosts { check tcp timeout 300 real port 80 host $www1 host $www2 } .Ed .Sh GLOBAL CONFIGURATION Here are the settings that can be set globally: .Pp .Bl -tag -width Ds -compact .It Ic demote Ar group Enable the global .Xr carp 4 demotion option, this will reset the carp demotion counter for the specified interface group to zero on startup and to 128 on shutdown of the daemon. For more information on interface groups, see the .Ic group keyword in .Xr ifconfig 8 . .Pp .It Xo .Ic interval Ar number .Xc Set the interval in seconds at which the hosts will be checked. The default interval is 10 seconds. .Pp .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). .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 Set the global timeout in milliseconds for checks. This can be overriden by the timeout value in the table definitions. The default interval is 200 milliseconds and it must not exceed the global interval. .El .Sh TABLES Tables are used to group a set of hosts that can be checked using the same method. Only one health-checking method can be used per table. Table specific configuration directives are described below. .Bl -tag -width Ds .It Ic check http Ar path Ic code Ar number For each host in the table, verify that retrieving the URL .Ar path gives the HTTP return code .Ar number . If .Ic use ssl is specified, HTTPS will be used to contact the host. .It Ic check https Ar path Ic code Ar number This has the same effect as above but also implies .Ic use ssl . .It Ic check http Ar path Ic digest Ar string For each host in the table, verify that retrieving the URL .Ar path produces a content whose SHA1 digest is .Ar digest . The digest does not take the HTTP headers into account. 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 If .Ic use ssl is specified, HTTPS will be used to contact the host. .It Ic check https Ar path Ic digest Ar string This has the same effect as above but also implies .Ic use 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 send Ar data Ic expect Ar pattern 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 .Ic use ssl is specified, the data will be sent and/or received inside an SSL tunnel. .It Ic check ssl This has the same effect as .Ic check tcp but also implies .Ic use ssl . .It Ic check tcp Use a simple TCP connect to check that hosts are up. If .Ic use ssl is specified, a complete SSL handshake will also be performed. .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 disable Start the table disabled \(en no hosts will be checked in this table. The table can be later enabled through .Xr hoststatectl 8 . .It Xo .Ic host Ar address .Op Ic retry Ar number .Xc Add the host whose address is .Ar address to the list of hosts to be checked in this table. Each table needs at least one host. 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. .It Ic real port Ar port When using the TCP or HTTP checking methods, use this .Ar port to connect to hosts. This parameter is mandatory. Main and backup tables need to have the same real port. .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. .It Ic use ssl If the table uses a TCP check, wrap it in SSL. .El .Sh SERVICES Services represent a .Xr pf 4 rdr rule. They are used to specify which addresses will be redirected to the hosts in the specified tables. The configuration directives that are valid in this context are described below. .Bl -tag -width Ds .It Ic backup table Ar name Specify the table to switch to when all hosts in the main table are seen as down or disabled. .It Ic disable Set the service initially disabled. It can be later enabled through .Xr hoststatectl 8 . .It Ic sticky-address This has the same effect than specifying sticky-address for a rdr rule in .Xr pf.conf 5 . It will ensure that multiple connections from the same source are mapped to the same redirection address. .It Ic table Ar name Specify the main table to be used. This is mandatory. .It Ic tag Ar name Automatically tag packets passing through the .Xr pf 4 rdr rule with the name supplied. This allows simpler filter rules. .It Ic virtual ip Ar address Ic port Ar port Specify an .Ar address and a .Ar port that will be used to redirect requests to the hosts in the main or backup table. Optionally an interface name can be given as follows, to specify which interface the rdr rule will be enabled on: .Bd -literal -offset indent interface ``ifname'' .Ed .El .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 load balancing 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 look up a private key in .Pa /etc/ssl/private/address.key and a public certificate in .Pa /etc/ssl/address.crt , 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 fed into the hash by looking at HTTP headers and GET variables; see the .Sx PROTOCOLS section below. .El .Pp The optional host retry option will be used as a tolerance for failed host connections, the connection will be retried for .Ar number more times, see the .Sx TABLES section for details about host entries. .It Ic nat lookup When redirecting connections with an .Ar rdr 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 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 setting 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 Xo .Ar action .Op Ic log .Xc Define an action for the selected entity. The .Ic log keyword will log the entity name and the value. The optional .Ic url keyword will look up the entity as a GET variable in the URL instead of an HTTP header value when using the .Ic http protocol. .Bl -tag -width Ds .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 an 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 load balancing hash to select the target host. See the .Ic table keyword in the .Sx RELAYS section above. .It Xo .Op Ic url .Ic log Ar key .Xc Log the name and the value of the entity. .El .It Ic tcp Ar option Enable or disable the specified TCP option; see .Xr tcp 4 for details about TCP 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 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. .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 ciphers Ar string Set the string defining the SSL cipher suite. If not specified, the default value .Ar HIGH:!ADH will be used (strong crypto cipher suites without anonymous DH). See the .Sx CIPHERS section of .Xr openssl 1 for information about SSL cipher suites and preference lists. .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 .El .Pp The .Ar value strings of the .Ic append and .Ic change directives 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 $TIMEOUT The configured session timeout of the relay. .El .Sh FILES .Bl -tag -width "/etc/ssl/private/address.keyXX" -compact .It Pa /etc/hoststated.conf .Xr hoststated 8 configuration file. .Pp .It Pa /etc/services Service name database. .Pp .It Pa /etc/ssl/address.crt .It Pa /etc/ssl/private/address.key Location of the relay SSL server certificates, where .Ar address is the configured IP address of the relay. .El .Sh EXAMPLES This configuration file would create a 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 phphosts { timeout 300 real port 8080 check http "/" digest 630aa3c2f... host $www1 host $www2 host $www3 host $www4 } table sorryhost { check icmp disable timeout 300 real port 8080 host sorryhost.private.example.com } service www { virtual ip www.example.com port 8080 interface trunk0 virtual ip www6.example.com port 80 interface trunk0 tag HOSTSTATED table phphosts 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 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 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" ssl { sslv2, ciphers "MEDIUM:HIGH" } } 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 myssh { tcp { nodelay, socket buffer 65536 } } relay sshforward { protocol myssh listen on www.example.com port 2222 forward to shell.example.com port 22 } .Ed .Sh SEE ALSO .Xr hoststatectl 8 , .Xr hoststated 8 , .Xr ssl 8 .Sh HISTORY The .Nm program first appeared in .Ox 4.1 . .Sh AUTHORS .An -nosplit The .Nm program was written by .An Pierre-Yves Ritschard Aq pyr@openbsd.org and .An Reyk Floeter Aq reyk@openbsd.org .