.\"	$OpenBSD: hoststated.conf.5,v 1.54 2007/10/22 15:45:40 jmc Exp $
.\"
.\" Copyright (c) 2006, 2007 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: October 22 2007 $
.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.
.Pp
Comments can be put anywhere in the file using a hash mark
.Pq Sq # ,
and extend to the end of the current line.
.Pp
Additional configuration files can be included with the
.Ic include
keyword, for example:
.Bd -literal -offset indent
include "/etc/hoststated.conf.local"
.Ed
.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 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 target host.
.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 a content whose SHA1 digest is
.Ar digest .
If
.Ar hostname
is specified, it is used as the
.Dq Host:
header to query a specific hostname at target host.
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
.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 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 script Ar path
Execute an external program to check the host state.
The program will be executed for each host by specifing the host name
on the command line:
.Bd -literal -offset indent
/usr/local/bin/checkload.pl front-www1.private.example.com
.Ed
.Pp
.Xr hoststated 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 _hoststated
user and terminated after
.Ar timeout
milliseconds.
.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.
.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.
If this parameter is not specified,
.Xr hoststated 8
will create a template table which inherits the port from the
referencing service or relay.
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.
.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 host 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 Xo
.Ic forward to Ar address Ic port Ar port
.Op Ic retry Ar number
.Xc
Specify the address and port of the target host to connect to.
.It Xo
.Ic service Ar name
.Op Ic retry Ar number
.Xc
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 Xo
.Ic nat lookup
.Op Ic retry Ar number
.Xc
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 TCP 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
.Pp
.Xr hoststated 8
also supports relaying of UDP 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.
The supported UDP protocols are:
.Pp
.Bl -tag -width http -offset indent -compact
.It Ic dns
Domain Name System (DNS) protocol.
The request IDs in the DNS header will be used to match the state.
.Xr hoststated 8
will replace these IDs with random values to compensate for
predictable values generated by some hosts.
.El
.It Xo
.Op Ar direction
.Op Ar type
.Ar action
.Op Ic log
.Xc
Define an action for the selected entity.
The optional
.Ic log
keyword will log the entity name and the value.
The actions are depending on the underlying application
.Ic protocol .
.Pp
The following directions are allowed for the specified action:
.Bl -tag -width Ds
.It Ic request
Handle the data stream from the client to the relay, like HTTP
requests.
This is the default if the direction directive is omitted.
.It Ic response
Handle the data stream from the target host to the relay, like
HTTP server replies.
.El
.Pp
The following entity types for the actions are available:
.Bl -tag -width Ds
.It Ic cookie
Look up the entity as a value in the Cookie header when using the
.Ic http
protocol.
This type is only available with the direction
.Ic request .
.It Ic header
Look up the entity in the application protocol headers, like HTTP
headers in
.Ic http
mode.
.It Ic path
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 .
.It Ic url
Look up the entity as a GET variable in the URL when using the
.Ic http
protocol.
This type is only available with the direction
.Ic request .
.El
.Pp
The following actions are available:
.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.
If
.Ar key
does not exist in the request, it will be created with the value
set to
.Ar value .
.It Ic change Ar key Ic to Ar value
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 value
set to
.Ar value .
.It Ic remove Ar key
Remove the entity with the selected name.
.It Ic expect Ar value Ic from Ar key
Expect an entity with the specified value.
If the entity is not present or the value doesn't match, the connection
will be dropped.
.It Ic filter Ar value Ic from Ar key
Like the
.Ic expect
directive above, but drop any connections with the specified entity
and value.
.It Ic hash Ar key
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 Ic log Ar key
Log the name and the value of the entity.
.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 3682.
.It Ic ip ttl
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.
.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 host www.example.com port 8080 interface trunk0
	virtual host 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
	header append "$REMOTE_ADDR" to "X-Forwarded-For"
	header append "$SERVER_ADDR:$SERVER_PORT" to "X-Forwarded-By"
	header change "Keep-Alive" to "$TIMEOUT"
	url hash "sessid"
	cookie hash "sessid"
	path filter "*command=*" from "/cgi-bin/index.cgi"

	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
file format first appeared in
.Ox 4.1 .
.Sh AUTHORS
.An -nosplit
The
.Xr hoststated 8
program was written by
.An Pierre-Yves Ritschard Aq pyr@openbsd.org
and
.An Reyk Floeter Aq reyk@openbsd.org .