Copyright (c) 2010-2011 Pawel Jakub Dawidek <pawel@dawidek.net>
All rights reserved.
This software was developed by Pawel Jakub Dawidek under sponsorship from
the FreeBSD Foundation.
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the distribution.
THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS IS'' AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
SUCH DAMAGE.
$FreeBSD: head/sbin/hastd/hast.conf.5 219351 2011-03-06 22:56:14Z pjd $
.Dd August 30, 2010 .Dt HAST.CONF 5 .Os .Sh NAME .Nm hast.conf .Nd configuration file for the .Xr hastd 8 daemon and the .Xr hastctl 8 utility. .Sh DESCRIPTION The .Nm file is used by both .Xr hastd 8 daemon and .Xr 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. .Sh CONFIGURATION FILE SYNTAX General syntax of the .Nm file is following: d -literal -offset indent # Global section control <addr> listen <addr> replication <mode> checksum <algorithm> timeout <seconds> exec <path> on <node> { # Node section control <addr> listen <addr> } on <node> { # Node section control <addr> listen <addr> } resource <name> { # Resource section replication <mode> checksum <algorithm> name <name> local <path> timeout <seconds> exec <path> on <node> { # Resource-node section name <name> # Required local <path> # Required remote <addr> } on <node> { # Resource-node section name <name> # Required local <path> # Required remote <addr> } } .Ed
p 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 c 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 c listen parameter at all, the default value will be used. .Sh CONFIGURATION FILE DESCRIPTION The .Aq node argument can be replaced either by a full hostname as obtained by .Xr gethostname 3 , only first part of the hostname, or by node's UUID as found in the .Va kern.hostuuid .Xr sysctl 8 variable.
p The following statements are available: l -tag -width ".Ic xxxx" t Ic control Aq addr
p Address for communication with .Xr hastctl 8 . Each of the following examples defines the same control address: d -literal -offset indent uds:///var/run/hastctl unix:///var/run/hastctl /var/run/hastctl .Ed
p The default value is
a uds:///var/run/hastctl . t Ic listen Aq addr
p Address to listen on in form of: d -literal -offset indent protocol://protocol-specific-address .Ed
p Each of the following examples defines the same listen address: d -literal -offset indent 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 .Ed
p The default value is
a tcp4://0.0.0.0:8457 . t Ic replication Aq mode
p Replication mode should be one of the following: l -tag -width ".Ic xxxx" t Ic memsync
p 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 c memsync replication mode is currently not implemented. t Ic fullsync
p Mark the write operation as completed when local as well as remote write completes. This is the safest and the slowest replication mode. The c fullsync replication mode is the default. t Ic async
p 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. The c async replication mode is currently not implemented. .El t Ic checksum Aq algorithm
p Checksum algorithm should be one of the following: l -tag -width ".Ic sha256" t Ic none No checksum will be calculated for the data being send over the network. This is the default setting. t Ic crc32 CRC32 checksum will be calculated. t Ic sha256 SHA256 checksum will be calculated. .El t Ic timeout Aq seconds
p Connection timeout in seconds. The default value is .Va 5 . t Ic exec Aq path
p Execute the given program on various HAST events. Below is the list of currently implemented events and arguments the given program is executed with: l -tag -width ".Ic xxxx" t Ic "<path> role <resource> <oldrole> <newrole>"
p Executed on both primary and secondary nodes when resource role is changed.
p t Ic "<path> connect <resource>"
p Executed on both primary and secondary nodes when connection for the given resource between the nodes is established.
p t Ic "<path> disconnect <resource>"
p Executed on both primary and secondary nodes when connection for the given resource between the nodes is lost.
p t Ic "<path> syncstart <resource>"
p Executed on primary node when synchronization process of secondary node is started.
p t Ic "<path> syncdone <resource>"
p Executed on primary node when synchronization process of secondary node is completed successfully.
p t Ic "<path> syncintr <resource>"
p 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.
p t Ic "<path> split-brain <resource>"
p Executed on both primary and secondary nodes when split-brain condition is detected.
p .El The .Aq path argument should contain full path to executable program. If the given program exits with code different than .Va 0 , .Nm hastd will log it as an error.
p The .Aq resource argument is resource name from the configuration file.
p The .Aq oldrole argument is previous resource role (before the change). It can be one of: .Ar init , .Ar secondary , .Ar primary .
p The .Aq newrole argument is current resource role (after the change). It can be one of: .Ar init , .Ar secondary , .Ar primary .
p t Ic name Aq name
p GEOM provider name that will appear as
a /dev/hast/<name> . If name is not defined, resource name will be used as provider name. t Ic local Aq path
p Path to the local component which will be used as backend provider for the resource. This can be either GEOM provider or regular file. t Ic remote Aq addr
p Address of the remote .Nm hastd daemon. Format is the same as for the c 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.
p A special value of .Va none can be used when the remote address is not yet known (eg. the other node is not set up yet). .El .Sh FILES l -tag -width ".Pa /var/run/hastctl" -compact t Pa /etc/hast.conf The default .Nm configuration file. t Pa /var/run/hastctl Control socket used by the .Xr hastctl 8 control utility to communicate with the .Xr hastd 8 daemon. .El .Sh EXAMPLES The example configuration file can look as follows: d -literal -offset indent resource shared { local /dev/da0 on hasta { remote tcp4://10.0.0.2 } on hastb { remote tcp4://10.0.0.1 } } resource tank { on hasta { local /dev/mirror/tanka remote tcp4://10.0.0.2 } on hastb { local /dev/mirror/tankb remote tcp4://10.0.0.1 } } .Ed .Sh SEE ALSO .Xr gethostname 3 , .Xr geom 4 , .Xr hastctl 8 , .Xr hastd 8 . .Sh AUTHORS The .Nm was written by .An Pawel Jakub Dawidek Aq pjd@FreeBSD.org under sponsorship of the FreeBSD Foundation.