1.\" Copyright (c) 2010 The FreeBSD Foundation 2.\" All rights reserved. 3.\" 4.\" This software was developed by Pawel Jakub Dawidek under sponsorship from 5.\" the FreeBSD Foundation. 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 10.\" 1. Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer. 12.\" 2. Redistributions in binary form must reproduce the above copyright 13.\" notice, this list of conditions and the following disclaimer in the 14.\" documentation and/or other materials provided with the distribution. 15.\" 16.\" THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS IS'' AND 17.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 18.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 19.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE 20.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 21.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 22.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 23.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 24.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 25.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 26.\" SUCH DAMAGE. 27.\" 28.\" $FreeBSD$ 29.\" 30.Dd August 5, 2010 31.Dt HAST.CONF 5 32.Os 33.Sh NAME 34.Nm hast.conf 35.Nd configuration file for the 36.Xr hastd 8 37daemon and the 38.Xr hastctl 8 39utility. 40.Sh DESCRIPTION 41The 42.Nm 43file is used by both 44.Xr hastd 8 45daemon 46and 47.Xr hastctl 8 48control utility. 49Configuration file is designed in a way that exactly the same file can be 50(and should be) used on both HAST nodes. 51Every line starting with # is treated as comment and ignored. 52.Sh CONFIGURATION FILE SYNTAX 53General syntax of the 54.Nm 55file is following: 56.Bd -literal -offset indent 57# Global section 58control <addr> 59listen <addr> 60replication <mode> 61timeout <seconds> 62 63on <node> { 64 # Node section 65 control <addr> 66 listen <addr> 67} 68 69on <node> { 70 # Node section 71 control <addr> 72 listen <addr> 73} 74 75resource <name> { 76 # Resource section 77 replication <mode> 78 name <name> 79 local <path> 80 timeout <seconds> 81 82 on <node> { 83 # Resource-node section 84 name <name> 85 # Required 86 local <path> 87 # Required 88 remote <addr> 89 } 90 on <node> { 91 # Resource-node section 92 name <name> 93 # Required 94 local <path> 95 # Required 96 remote <addr> 97 } 98} 99.Ed 100.Pp 101Most of the various available configuration parameters are optional. 102If parameter is not defined in the particular section, it will be 103inherited from the parent section. 104For example, if the 105.Ic listen 106parameter is not defined in the node section, it will be inherited from 107the global section. 108In case the global section does not define the 109.Ic listen 110parameter at all, the default value will be used. 111.Sh CONFIGURATION FILE DESCRIPTION 112The 113.Aq node 114argument can be replaced either by a full hostname as obtained by 115.Xr gethostname 3 , 116only first part of the hostname, or by node's UUID as found in the 117.Va kern.hostuuid 118.Xr sysctl 8 119variable. 120.Pp 121The following statements are available: 122.Bl -tag -width ".Ic xxxx" 123.It Ic control Aq addr 124.Pp 125Address for communication with 126.Xr hastctl 8 . 127Each of the following examples defines the same control address: 128.Bd -literal -offset indent 129uds:///var/run/hastctl 130unix:///var/run/hastctl 131/var/run/hastctl 132.Ed 133.Pp 134The default value is 135.Pa uds:///var/run/hastctl . 136.It Ic listen Aq addr 137.Pp 138Address to listen on in form of: 139.Bd -literal -offset indent 140protocol://protocol-specific-address 141.Ed 142.Pp 143Each of the following examples defines the same listen address: 144.Bd -literal -offset indent 1450.0.0.0 1460.0.0.0:8457 147tcp://0.0.0.0 148tcp://0.0.0.0:8457 149tcp4://0.0.0.0 150tcp4://0.0.0.0:8457 151.Ed 152.Pp 153The default value is 154.Pa tcp4://0.0.0.0:8457 . 155.It Ic replication Aq mode 156.Pp 157Replication mode should be one of the following: 158.Bl -tag -width ".Ic xxxx" 159.It Ic memsync 160.Pp 161Report the write operation as completed when local write completes and 162when the remote node acknowledges the data receipt, but before it 163actually stores the data. 164The data on remote node will be stored directly after sending 165acknowledgement. 166This mode is intended to reduce latency, but still provides a very good 167reliability. 168The only situation where some small amount of data could be lost is when 169the data is stored on primary node and sent to the secondary. 170Secondary node then acknowledges data receipt and primary reports 171success to an application. 172However, it may happen that the secondary goes down before the received 173data is really stored locally. 174Before secondary node returns, primary node dies entirely. 175When the secondary node comes back to life it becomes the new primary. 176Unfortunately some small amount of data which was confirmed to be stored 177to the application was lost. 178The risk of such a situation is very small. 179The 180.Ic memsync 181replication mode is currently not implemented. 182.It Ic fullsync 183.Pp 184Mark the write operation as completed when local as well as remote 185write completes. 186This is the safest and the slowest replication mode. 187The 188.Ic fullsync 189replication mode is the default. 190.It Ic async 191.Pp 192The write operation is reported as complete right after the local write 193completes. 194This is the fastest and the most dangerous replication mode. 195This mode should be used when replicating to a distant node where 196latency is too high for other modes. 197The 198.Ic async 199replication mode is currently not implemented. 200.El 201.It Ic timeout Aq seconds 202.Pp 203Connection timeout in seconds. 204The default value is 205.Va 5 . 206.It Ic name Aq name 207.Pp 208GEOM provider name that will appear as 209.Pa /dev/hast/<name> . 210If name is not defined, resource name will be used as provider name. 211.It Ic local Aq path 212.Pp 213Path to the local component which will be used as backend provider for 214the resource. 215This can be either GEOM provider or regular file. 216.It Ic remote Aq addr 217.Pp 218Address of the remote 219.Nm hastd 220daemon. 221Format is the same as for the 222.Ic listen 223statement. 224When operating as a primary node this address will be used to connect to 225the secondary node. 226When operating as a secondary node only connections from this address 227will be accepted. 228.Pp 229A special value of 230.Va none 231can be used when the remote address is not yet known (eg. the other node is not 232set up yet). 233.El 234.Sh FILES 235.Bl -tag -width ".Pa /var/run/hastctl" -compact 236.It Pa /etc/hast.conf 237The default 238.Nm 239configuration file. 240.It Pa /var/run/hastctl 241Control socket used by the 242.Xr hastctl 8 243control utility to communicate with the 244.Xr hastd 8 245daemon. 246.El 247.Sh EXAMPLES 248The example configuration file can look as follows: 249.Bd -literal -offset indent 250resource shared { 251 local /dev/da0 252 253 on hasta { 254 remote tcp4://10.0.0.2 255 } 256 on hastb { 257 remote tcp4://10.0.0.1 258 } 259} 260resource tank { 261 on hasta { 262 local /dev/mirror/tanka 263 remote tcp4://10.0.0.2 264 } 265 on hastb { 266 local /dev/mirror/tankb 267 remote tcp4://10.0.0.1 268 } 269} 270.Ed 271.Sh SEE ALSO 272.Xr gethostname 3 , 273.Xr geom 4 , 274.Xr hastctl 8 , 275.Xr hastd 8 . 276.Sh AUTHORS 277The 278.Nm 279was written by 280.An Pawel Jakub Dawidek Aq pjd@FreeBSD.org 281under sponsorship of the FreeBSD Foundation. 282