.\"	$OpenBSD: hoststated.conf.5,v 1.17 2007/02/07 15:17:46 reyk Exp $
.\"
.\" Copyright (c) 2006 Pierre-Yves Ritschard <pyr@spootnik.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 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 four 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.
.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 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 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 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 check ssl
This has the same effect as above but also implies
.Ic use ssl .
.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 Ic host Ar address
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.
.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 EXAMPLE
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
.Sh FILES
.Bl -tag -width "/etc/hoststated.conf" -compact
.It Pa /etc/hoststated.conf
.Xr hoststated 8
configuration file
.It Pa /etc/services
Service name database
.El
.Sh SEE ALSO
.Xr hoststatectl 8 ,
.Xr hoststated 8