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 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.  This parameter is mandatory.  Main and backup
             tables 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
             Specify the address and port of the target host to connect to.

     service name
             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
             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:

             header  Look up the entity in the application protocol headers,
                     like HTTP headers in http mode.

             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.

             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.

             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 option; see tcp(4) for de-
             tails about TCP 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.

             [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"

                   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 program first appeared in OpenBSD 4.1.

AUTHORS
     The hoststated.conf program was written by Pierre-Yves Ritschard
     <pyr@openbsd.org> and Reyk Floeter <reyk@openbsd.org>.

OpenBSD 4.1                    November 1, 2006                              8
