Skip site navigation (1)Skip section navigation (2)

FreeBSD Man Pages

Man Page or Keyword Search:
Man Architecture
Apropos Keyword Search (all sections) Output format
home | help
HAST.CONF(5)              FreeBSD File Formats Manual             HAST.CONF(5)

NAME
     hast.conf - configuration file for the hastd(8) daemon and the hastctl(8)
     utility

DESCRIPTION
     The hast.conf file is used by both hastd(8) daemon and hastctl(8) control
     utility.  Configuration file is designed in a way that exactly the same
     file can be (and should be) used on both HAST nodes.  Every line starting
     with # is treated as comment and ignored.

CONFIGURATION FILE SYNTAX
     General syntax of the hast.conf file is following:

           # Global section
           control <addr>
           listen <addr>
           replication <mode>
           checksum <algorithm>
           compression <algorithm>
           timeout <seconds>
           exec <path>
           metaflush "on" | "off"
           pidfile <path>

           on <node> {
                   # Node section
                   control <addr>
                   listen <addr>
                   pidfile <path>
           }

           on <node> {
                   # Node section
                   control <addr>
                   listen <addr>
                   pidfile <path>
           }

           resource <name> {
                   # Resource section
                   replication <mode>
                   checksum <algorithm>
                   compression <algorithm>
                   name <name>
                   local <path>
                   timeout <seconds>
                   exec <path>
                   metaflush "on" | "off"

                   on <node> {
                           # Resource-node section
                           name <name>
                           # Required
                           local <path>
                           metaflush "on" | "off"
                           # Required
                           remote <addr>
                           source <addr>
                   }
                   on <node> {
                           # Resource-node section
                           name <name>
                           # Required
                           local <path>
                           metaflush "on" | "off"
                           # Required
                           remote <addr>
                           source <addr>
                   }
           }

     Most of the various available configuration parameters are optional.  If
     parameter is not defined in the particular section, it will be inherited
     from the parent section.  For example, if the listen parameter is not
     defined in the node section, it will be inherited from the global
     section.  In case the global section does not define the listen parameter
     at all, the default value will be used.

CONFIGURATION FILE DESCRIPTION
     The <node> argument can be replaced either by a full hostname as obtained
     by gethostname(3), only first part of the hostname, or by node's UUID as
     found in the kern.hostuuid sysctl(8) variable.

     The following statements are available:

     control <addr>

               Address for communication with hastctl(8).  Each of the
               following examples defines the same control address:

                     uds:///var/run/hastctl
                     unix:///var/run/hastctl
                     /var/run/hastctl

               The default value is uds:///var/run/hastctl.

     pidfile <path>

               File in which to store the process ID of the main hastd(8)
               process.

               The default value is /var/run/hastd.pid.

     listen <addr>

               Address to listen on in form of:

                     protocol://protocol-specific-address

               Each of the following examples defines the same listen address:

                     0.0.0.0
                     0.0.0.0:8457
                     tcp://0.0.0.0
                     tcp://0.0.0.0:8457
                     tcp4://0.0.0.0
                     tcp4://0.0.0.0:8457

               Multiple listen addresses can be specified.  By default hastd
               listens on tcp4://0.0.0.0:8457 and tcp6://[::]:8457 if kernel
               supports IPv4 and IPv6 respectively.

     replication <mode>

               Replication mode should be one of the following:

               memsync

                         Report the write operation as completed when local
                         write completes and when the remote node acknowledges
                         the data receipt, but before it actually stores the
                         data.  The data on remote node will be stored
                         directly after sending acknowledgement.  This mode is
                         intended to reduce latency, but still provides a very
                         good reliability.  The only situation where some
                         small amount of data could be lost is when the data
                         is stored on primary node and sent to the secondary.
                         Secondary node then acknowledges data receipt and
                         primary reports success to an application.  However,
                         it may happen that the secondary goes down before the
                         received data is really stored locally.  Before
                         secondary node returns, primary node dies entirely.
                         When the secondary node comes back to life it becomes
                         the new primary.  Unfortunately some small amount of
                         data which was confirmed to be stored to the
                         application was lost.  The risk of such a situation
                         is very small.  The memsync replication mode is
                         currently not implemented.

               fullsync

                         Mark the write operation as completed when local as
                         well as remote write completes.  This is the safest
                         and the slowest replication mode.  The fullsync
                         replication mode is the default.

               async

                         The write operation is reported as complete right
                         after the local write completes.  This is the fastest
                         and the most dangerous replication mode.  This mode
                         should be used when replicating to a distant node
                         where latency is too high for other modes.

     checksum <algorithm>

               Checksum algorithm should be one of the following:

               none        No checksum will be calculated for the data being
                           send over the network.  This is the default
                           setting.

               crc32       CRC32 checksum will be calculated.

               sha256      SHA256 checksum will be calculated.

     compression <algorithm>

               Compression algorithm should be one of the following:

               none      Data send over the network will not be compressed.

               hole      Only blocks that contain all zeros will be
                         compressed.  This is very useful for initial
                         synchronization where potentially many blocks are
                         still all zeros.  There should be no measurable
                         performance overhead when this algorithm is being
                         used.  This is the default setting.

               lzf       The LZF algorithm by Marc Alexander Lehmann will be
                         used to compress the data send over the network.  LZF
                         is very fast, general purpose compression algorithm.

     timeout <seconds>

               Connection timeout in seconds.  The default value is 20.

     exec <path>

               Execute the given program on various HAST events.  Below is the
               list of currently implemented events and arguments the given
               program is executed with:

               <path> role <resource> <oldrole> <newrole>

                         Executed on both primary and secondary nodes when
                         resource role is changed.

               <path> connect <resource>

                         Executed on both primary and secondary nodes when
                         connection for the given resource between the nodes
                         is established.

               <path> disconnect <resource>

                         Executed on both primary and secondary nodes when
                         connection for the given resource between the nodes
                         is lost.

               <path> syncstart <resource>

                         Executed on primary node when synchronization process
                         of secondary node is started.

               <path> syncdone <resource>

                         Executed on primary node when synchronization process
                         of secondary node is completed successfully.

               <path> syncintr <resource>

                         Executed on primary node when synchronization process
                         of secondary node is interrupted, most likely due to
                         secondary node outage or connection failure between
                         the nodes.

               <path> split-brain <resource>

                         Executed on both primary and secondary nodes when
                         split-brain condition is detected.

               The <path> argument should contain full path to executable
               program.  If the given program exits with code different than
               0, hastd will log it as an error.

               The <resource> argument is resource name from the configuration
               file.

               The <oldrole> argument is previous resource role (before the
               change).  It can be one of: init, secondary, primary.

               The <newrole> argument is current resource role (after the
               change).  It can be one of: init, secondary, primary.

     metaflush on | off

               When set to on, flush write cache of the local provider after
               every metadata (activemap) update.  Flushing write cache
               ensures that provider will not reorder writes and that metadata
               will be properly updated before real data is stored.  If the
               local provider does not support flushing write cache (it
               returns EOPNOTSUPP on the BIO_FLUSH request), hastd will
               disable metaflush automatically.  The default value is on.

     name <name>

               GEOM provider name that will appear as /dev/hast/_name_.  If
               name is not defined, resource name will be used as provider
               name.

     local <path>

               Path to the local component which will be used as backend
               provider for the resource.  This can be either GEOM provider or
               regular file.

     remote <addr>

               Address of the remote hastd daemon.  Format is the same as for
               the listen statement.  When operating as a primary node this
               address will be used to connect to the secondary node.  When
               operating as a secondary node only connections from this
               address will be accepted.

               A special value of none can be used when the remote address is
               not yet known (eg. the other node is not set up yet).

     source <addr>

               Local address to bind to before connecting to the remote hastd
               daemon.  Format is the same as for the listen statement.

FILES
     /etc/hast.conf        The default hastctl(8) and hastd(8) configuration
                           file.
     /var/run/hastctl      Control socket used by the hastctl(8) control
                           utility to communicate with the hastd(8) daemon.

EXAMPLES
     The example configuration file can look as follows:

           listen tcp://0.0.0.0

           on hasta {
                   listen tcp://2001:db8::1/64
           }
           on hastb {
                   listen tcp://2001:db8::2/64
           }

           resource shared {
                   local /dev/da0

                   on hasta {
                           remote tcp://10.0.0.2
                   }
                   on hastb {
                           remote tcp://10.0.0.1
                   }
           }
           resource tank {
                   on hasta {
                           local /dev/mirror/tanka
                           source tcp://10.0.0.1
                           remote tcp://10.0.0.2
                   }
                   on hastb {
                           local /dev/mirror/tankb
                           source tcp://10.0.0.2
                           remote tcp://10.0.0.1
                   }
           }

SEE ALSO
     gethostname(3), geom(4), hastctl(8), hastd(8)

AUTHORS
     The hast.conf was written by Pawel Jakub Dawidek <pjd@FreeBSD.org> under
     sponsorship of the FreeBSD Foundation.

FreeBSD 11.0-PRERELEASE        January 25, 2012        FreeBSD 11.0-PRERELEASE

NAME | DESCRIPTION | CONFIGURATION FILE SYNTAX | CONFIGURATION FILE DESCRIPTION | FILES | EXAMPLES | SEE ALSO | AUTHORS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=hast.conf&sektion=5&manpath=FreeBSD+9.1-RELEASE>

home | help