HOSTSTATED.CONF(5) OpenBSD Programmer's Manual HOSTSTATED.CONF(5)
NAME
hoststated.conf - Host Status daemon configuration file
DESCRIPTION
hoststated.conf is the configuration file for the Host Status Daemon,
hoststated(8).
SECTIONS
hoststated.conf is divided into six main sections:
Macros
User-defined variables may be defined and used later, simplifying
the configuration file.
Global Configuration
Global settings for hoststated(8).
Tables
Table definitions describe the content of a pf(4) table and the
method used for checking the health of the hosts they contain.
Services
Services will be translated to pf(4) rdr rules if their table or
backup table have content.
Relays
Relays allow layer 7 load balancing, SSL acceleration, and general
purpose TCP proxying.
Protocols
Protocols are predefined protocol handlers and settings for relays.
Within the sections, a host address can be either specified by IPv4 ad-
dress, IPv6 address, or DNS host name. A port can be either specified by
number or by name. The port name to number mappings are found in the
file /etc/services; see services(5) for details.
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 un-
derscores. Macro names may not be reserved words (for example, table,
service, or timeout). Macros are not expanded inside quotes.
For example:
www1="10.0.0.1"
www2="10.0.0.2"
table webhosts {
check tcp
timeout 300
real port 80
host $www1
host $www2
}
GLOBAL CONFIGURATION
Here are the settings that can be set globally:
demote group
Enable the global 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 infor-
mation on interface groups, see the group keyword in ifconfig(8).
interval number
Set the interval in seconds at which the hosts will be checked.
The default interval is 10 seconds.
log (updates|all)
Log state notifications after completed host checks. Either only
log the updates to new states or log all state notifications,
even if the state didn't change. The host state can be up (the
health check completed successfully), down (the host is down or
didn't match the check criteria), or unknown (the host is dis-
abled or has not been checked yet).
prefork number
When using relays, run the specified number of processes to han-
dle relayed connections. This will increase the performance and
prevents delays when connecting to a relay. hoststated(8) will
run 5 relay processes by default and every process will handle
all configured relays.
timeout number
Set the global timeout in milliseconds for checks. This can be
overriden by the timeout value in the table definitions. The de-
fault interval is 200 milliseconds and it must not exceed the
global interval.
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.
check http path code number
For each host in the table, verify that retrieving the URL path
gives the HTTP return code number.
check https path code number
This has the same effect as above but wraps the HTTP request in
SSL.
check http path digest string
For each host in the table, verify that retrieving the URL path
produces a content whose SHA1 digest is digest. The digest does
not take the HTTP headers into account. To compute the digest,
use this simple command:
ftp -o - http://host[:port]/path | sha1
This gives a digest that can be used as is in a digest statement:
a9993e36476816aba3e25717850c26c9cd0d89d
check https path digest string
This has the same effect as above but wraps the HTTP request in
SSL.
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.
check send data expect pattern [ssl]
For each host in the table, a TCP connection is established on
the port specified, then data is sent. Incoming data is then
read and is expected to match against pattern using shell glob-
bing rules. If data is an empty string or 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 ssl keyword is present, the transaction will occur
in an SSL tunnel.
check script 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:
/usr/local/bin/checkload.pl front-www1.private.example.com
hoststated(8) expects a positive return value on success and zero
on failure. Note that the script will be executed with the priv-
ileges of the "_hoststated" user and terminated after timeout
milliseconds.
check ssl
Perform a complete SSL handshake with each host to check their
availability.
check tcp
Use a simple TCP connect to check that hosts are up.
demote group
Enable the per-table carp(4) demotion option. This will incre-
ment the carp demotion counter for the specified interface group
if all hosts in the table are down. For more information on in-
terface groups, see the group keyword in ifconfig(8).
disable
Start the table disabled - no hosts will be checked in this
table. The table can be later enabled through hoststatectl(8).
host address [retry number]
Add the host whose address is 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 number more times before setting
the host state to down.
real port port
When using the TCP or HTTP checking methods, use this port to
connect to hosts. If this parameter is not specified,
hoststated(8) will create a template table which inherits the
port from the referencing service or relay. Main and backup ta-
bles need to have the same real port.
timeout number
Set the timeout in milliseconds for each host that is checked us-
ing TCP as the transport. This will override the global timeout,
which is 200 milliseconds by default.
SERVICES
Services represent a pf(4) rdr rule. They are used to specify which ad-
dresses will be redirected to the hosts in the specified tables. The
configuration directives that are valid in this context are described be-
low.
backup table name
Specify the table to switch to when all hosts in the main table
are seen as down or disabled.
disable
Set the service initially disabled. It can be later enabled
through hoststatectl(8).
sticky-address
This has the same effect than specifying sticky-address for a rdr
rule in pf.conf(5). It will ensure that multiple connections
from the same source are mapped to the same redirection address.
table name
Specify the main table to be used. This is mandatory.
tag name
Automatically tag packets passing through the pf(4) rdr rule with
the name supplied. This allows simpler filter rules.
virtual host address port port
Specify an address and a port that will be used to redirect re-
quests to the hosts in the main or backup table. Optionally an
interface name can be given as follows, to specify which inter-
face the rdr rule will be enabled on:
interface ``ifname''
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 be-
tween the target host and the remote client. A relay is also called an
application layer or layer 7 proxy.
The main purpose of a relay is to provide advanced load balancing func-
tionality based on specified protocol characteristics, such as HTTP head-
ers, to provide SSL acceleration functionality and to allow basic han-
dling of the underlying application protocol.
The relay configuration directives are described below.
listen on address port port [ssl]
Specify the address and port for the relay to listen on. The re-
lay will accept incoming connections to the specified address.
If the ssl keyword is present, the relay will accept connections
using the encrypted SSL protocol. The relay will look up a pri-
vate key in /etc/ssl/private/address.key and a public certificate
in /etc/ssl/address.crt, where address is the specified IP ad-
dress of the relay to listen on. See ssl(8) for details about
SSL server certificates.
forward to address port port [retry number]
Specify the address and port of the target host to connect to.
service name [retry number]
Use the first virtual IP address and port from the specified ser-
vice as the target host to connect to. This is exclusive to the
forward to and table directives.
table name mode [no check]
Get the target host from the specified table. The following
modes are available to select a host from the specified table:
roundrobin Distributes the outgoing connections using a
round-robin scheduler through all active
hosts.
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.
hash Like the loadbalance mode, but without includ-
ing the source and destination addresses and
ports. Additional input can be fed into the
hash by looking at HTTP headers and GET vari-
ables; see the PROTOCOLS section below.
The optional host retry option will be used as a tolerance for
failed host connections; the connection will be retried for
number more times. See the TABLES section for details about host
entries.
nat lookup [retry number]
When redirecting connections with an rdr rule in pf.conf(5) to a
relay listening on localhost, this directive will look up the re-
al destination address of the intended target host, allowing the
relay to be run as a transparent proxy. If either the forward
to, service, or table directive is present, it will be used as a
backup if the NAT lookup failed.
timeout seconds
Specify the timeout in seconds for accepted sessions. The de-
fault timeout is 600 seconds (10 minutes).
disable
Start the relay but immediately close any accepted connections.
protocol name
Use the specified protocol definition for the relay. The generic
TCP protocol options will be used by default; see the PROTOCOLS
section below.
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.
The protocol configuration directives are described below.
protocol type
Enable special handling of the specified application layer proto-
col. The supported protocols are:
http Handle the Hypertext Transfer Protocol (HTTP or
"HTTPS" if encapsulated in a SSL tunnel).
tcp Generic handler for TCP-based protocols.
[direction] [type] action [log]
Define an action for the selected entity. The optional log key-
word will log the entity name and the value. The actions are de-
pending on the underlying application protocol.
The following directions are allowed for the specified action:
request
Handle the data stream from the client to the relay, like
HTTP requests. This is the default if the direction di-
rective is omitted.
response
Handle the data stream from the target host to the relay,
like HTTP server replies.
The following entity types for the actions are available:
cookie Look up the entity as a value in the Cookie header when
using the http protocol. This type is only available
with the direction request.
header Look up the entity in the application protocol headers,
like HTTP headers in http mode.
path Look up the entity as a value in the URL path when using
the http protocol. This type is only available with the
direction request.
url Look up the entity as a GET variable in the URL when us-
ing the http protocol. This type is only available with
the direction request.
The following actions are available:
append value to key
Append the specified value to a protocol entity with the
selected name. When using the http protocol, key will
indicate a specified HTTP header. If key does not exist
in the request, it will be created with the value set to
value.
change key to value
Like the append directive above, but change the contents
of the specified entity. If key does not exist in the
request, it will be created with the value set to value.
remove key
Remove the entity with the selected name.
expect value from 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.
filter value from key
Like the expect directive above, but drop any connections
with the specified entity and value.
hash key
Feed the value of the selected entity into the load bal-
ancing hash to select the target host. See the table
keyword in the RELAYS section above.
log key
Log the name and the value of the entity.
tcp option
Enable or disable the specified TCP/IP options; see tcp(4) and
ip(4) for more information about the options. Valid options are:
backlog 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 kern.somaxconn sysctl(8) variable.
ip minttl 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 Generalized TTL
Security Mechanism (GTSM) according to RFC 3682.
ip ttl Change the default time-to-live value in the IP headers.
[no] nodelay
Enable the TCP NODELAY option for this connection. This
is recommended to avoid delays in the relayed data
stream, e.g. for SSH connections.
[no] sack
Use selective acknowledgements for this connection.
socket buffer number
Set the socket-level buffer size for input and output for
this connection. This will affect the TCP window size.
ssl option
Set the SSL options and session settings. This is only used if
SSL is enabled in the relay. Valid options are:
ciphers string
Set the string defining the SSL cipher suite. If not
specified, the default value HIGH:!ADH will be used
(strong crypto cipher suites without anonymous DH). See
the CIPHERS section of openssl(1) for information about
SSL cipher suites and preference lists.
session cache value
Set the maximum size of the SSL session cache. If the
value is zero, the default size defined by the SSL li-
brary will be used. A positive number will set the maxi-
mum size in bytes and the keyword disable will disable
the SSL session cache.
[no] sslv2
Enable the SSLv2 protocol; disabled by default.
[no] sslv3
Disable the SSLv3 protocol; enabled by default.
[no] tlsv1
Disable the TLSv1/SSLv3.1 protocol; enabled by default.
The value strings of the append and change directives may contain prede-
fined macros that will be expanded at runtime:
$REMOTE_ADDR The IP address of the connected client.
$REMOTE_PORT The TCP source port of the connected client.
$SERVER_ADDR The configured IP address of the relay.
$SERVER_PORT The configured TCP server port of the relay.
$TIMEOUT The configured session timeout of the relay.
FILES
/etc/hoststated.conf hoststated(8) configuration file.
/etc/services Service name database.
/etc/ssl/address.crt
/etc/ssl/private/address.key Location of the relay SSL server certifi-
cates, where address is the configured IP
address of the relay.
EXAMPLES
This configuration file would create a service ``www'' which load bal-
ances four hosts and falls back to one host containing a ``sorry page'':
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
}
The following configuration would add a relay to forward secure HTTPS
connections to a pool of HTTP webservers using the loadbalance protocol
(SSL acceleration and layer 7 load balancing). The HTTP protocol defini-
tion will add two HTTP headers containing address information of the
client and the server, set the ``Keep-Alive'' header value to the config-
ured session timeout, and include the ``sessid'' variable in the hash to
calculate the target host:
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
}
The second relay example will accept incoming connections to port 2222
and forward them to a remote SSH server. The TCP nodelay option will al-
low a ``smooth'' SSH session without delays between keystrokes or dis-
played output on the terminal:
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
}
SEE ALSO
hoststatectl(8), hoststated(8), ssl(8)
HISTORY
The hoststated.conf file format first appeared in OpenBSD 4.1.
AUTHORS
The hoststated(8) program was written by Pierre-Yves Ritschard
<pyr@openbsd.org> and Reyk Floeter <reyk@openbsd.org>.
OpenBSD 4.2 July 24, 2007 9