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 sec-
     tion.  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, by node's UUID	as
     found in the kern.hostuuid	sysctl(8) variable or by node's	hostid as
     found in the kern.hostid 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 lis-
	   tens	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 com-
		 pletes	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 acknowl-
		 edgement.  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 suc-
		 cess to an application.  However, it may happen that the sec-
		 ondary	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 the default.

	   fullsync

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

	   async

		 The write operation is	reported as complete right after the
		 local write completes.	 This is the fastest and the most dan-
		 gerous	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 measur-
		 able 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	pro-
	   gram	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 sec-
		 ondary	node is	started.

	   <path> syncdone <resource>

		 Executed on primary node when synchronization process of sec-
		 ondary	node is	completed successfully.

	   <path> syncintr <resource>

		 Executed on primary node when synchronization process of sec-
		 ondary	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 dae-
	   mon.	 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	9.3		       January 25, 2012			   FreeBSD 9.3

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

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

home | help