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 February 1, 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 37deamon 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 seconderay 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, which is the reason for this 179mode to be the default. 180.It Ic fullsync 181.Pp 182Mark the write operation as completed when local as well as remote 183write completes. 184This is the safest and the slowest replication mode. 185The 186.Ic fullsync 187replication mode is currently not implemented. 188.It Ic async 189.Pp 190The write operation is reported as complete right after the local write 191completes. 192This is the fastest and the most dangerous replication mode. 193This mode should be used when replicating to a distant node where 194latency is too high for other modes. 195The 196.Ic async 197replication mode is currently not implemented. 198.El 199.It Ic timeout Aq seconds 200.Pp 201Connection timeout in seconds. 202The default value is 203.Va 5 . 204.It Ic name Aq name 205.Pp 206GEOM provider name that will appear as 207.Pa /dev/hast/<name> . 208If name is not defined, resource name will be used as provider name. 209.It Ic local Aq path 210.Pp 211Path to the local component which will be used as backend provider for 212the resource. 213This can be either GEOM provider or regular file. 214.It Ic remote Aq addr 215.Pp 216Address of the remote 217.Nm hastd 218daemon. 219Format is the same as for the 220.Ic listen 221statement. 222When operating as a primary node this address will be used to connect to 223the secondary node. 224When operating as a secondary node only connections from this address 225will be accepted. 226.El 227.Sh FILES 228.Bl -tag -width ".Pa /var/run/hastctl" -compact 229.It Pa /etc/hast.conf 230The default 231.Nm 232configuration file. 233.It Pa /var/run/hastctl 234Control socket used by the 235.Xr hastctl 8 236control utility to communicate with the 237.Xr hastd 8 238daemon. 239.El 240.Sh EXAMPLES 241The example configuration file can look as follows: 242.Bd -literal -offset indent 243resource shared { 244 local /dev/da0 245 246 on hasta { 247 remote tcp4://10.0.0.2 248 } 249 on hastb { 250 remote tcp4://10.0.0.1 251 } 252} 253resource tank { 254 on hasta { 255 local /dev/mirror/tanka 256 remote tcp4://10.0.0.2 257 } 258 on hastb { 259 local /dev/mirror/tankb 260 remote tcp4://10.0.0.1 261 } 262} 263.Ed 264.Sh SEE ALSO 265.Xr gethostname 3 , 266.Xr geom 4 , 267.Xr hastctl 8 , 268.Xr hastd 8 . 269.Sh AUTHORS 270The 271.Nm 272was written by 273.An Pawel Jakub Dawidek Aq pjd@FreeBSD.org 274under sponsorship of the FreeBSD Foundation. 275