1.\" Copyright (c) 2010 The FreeBSD Foundation 2.\" Copyright (c) 2010-2011 Pawel Jakub Dawidek <pawel@dawidek.net> 3.\" All rights reserved. 4.\" 5.\" This software was developed by Pawel Jakub Dawidek under sponsorship from 6.\" the FreeBSD Foundation. 7.\" 8.\" Redistribution and use in source and binary forms, with or without 9.\" modification, are permitted provided that the following conditions 10.\" are met: 11.\" 1. Redistributions of source code must retain the above copyright 12.\" notice, this list of conditions and the following disclaimer. 13.\" 2. Redistributions in binary form must reproduce the above copyright 14.\" notice, this list of conditions and the following disclaimer in the 15.\" documentation and/or other materials provided with the distribution. 16.\" 17.\" THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS IS'' AND 18.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 19.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 20.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE 21.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 22.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 23.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 24.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 25.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 26.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 27.\" SUCH DAMAGE. 28.\" 29.\" $FreeBSD$ 30.\" 31.Dd March 20, 2011 32.Dt HAST.CONF 5 33.Os 34.Sh NAME 35.Nm hast.conf 36.Nd configuration file for the 37.Xr hastd 8 38daemon and the 39.Xr hastctl 8 40utility. 41.Sh DESCRIPTION 42The 43.Nm 44file is used by both 45.Xr hastd 8 46daemon 47and 48.Xr hastctl 8 49control utility. 50Configuration file is designed in a way that exactly the same file can be 51(and should be) used on both HAST nodes. 52Every line starting with # is treated as comment and ignored. 53.Sh CONFIGURATION FILE SYNTAX 54General syntax of the 55.Nm 56file is following: 57.Bd -literal -offset indent 58# Global section 59control <addr> 60listen <addr> 61replication <mode> 62checksum <algorithm> 63compression <algorithm> 64timeout <seconds> 65exec <path> 66 67on <node> { 68 # Node section 69 control <addr> 70 listen <addr> 71} 72 73on <node> { 74 # Node section 75 control <addr> 76 listen <addr> 77} 78 79resource <name> { 80 # Resource section 81 replication <mode> 82 checksum <algorithm> 83 compression <algorithm> 84 name <name> 85 local <path> 86 timeout <seconds> 87 exec <path> 88 89 on <node> { 90 # Resource-node section 91 name <name> 92 # Required 93 local <path> 94 # Required 95 remote <addr> 96 source <addr> 97 } 98 on <node> { 99 # Resource-node section 100 name <name> 101 # Required 102 local <path> 103 # Required 104 remote <addr> 105 source <addr> 106 } 107} 108.Ed 109.Pp 110Most of the various available configuration parameters are optional. 111If parameter is not defined in the particular section, it will be 112inherited from the parent section. 113For example, if the 114.Ic listen 115parameter is not defined in the node section, it will be inherited from 116the global section. 117In case the global section does not define the 118.Ic listen 119parameter at all, the default value will be used. 120.Sh CONFIGURATION FILE DESCRIPTION 121The 122.Aq node 123argument can be replaced either by a full hostname as obtained by 124.Xr gethostname 3 , 125only first part of the hostname, or by node's UUID as found in the 126.Va kern.hostuuid 127.Xr sysctl 8 128variable. 129.Pp 130The following statements are available: 131.Bl -tag -width ".Ic xxxx" 132.It Ic control Aq addr 133.Pp 134Address for communication with 135.Xr hastctl 8 . 136Each of the following examples defines the same control address: 137.Bd -literal -offset indent 138uds:///var/run/hastctl 139unix:///var/run/hastctl 140/var/run/hastctl 141.Ed 142.Pp 143The default value is 144.Pa uds:///var/run/hastctl . 145.It Ic listen Aq addr 146.Pp 147Address to listen on in form of: 148.Bd -literal -offset indent 149protocol://protocol-specific-address 150.Ed 151.Pp 152Each of the following examples defines the same listen address: 153.Bd -literal -offset indent 1540.0.0.0 1550.0.0.0:8457 156tcp://0.0.0.0 157tcp://0.0.0.0:8457 158tcp4://0.0.0.0 159tcp4://0.0.0.0:8457 160.Ed 161.Pp 162The default value is 163.Pa tcp4://0.0.0.0:8457 . 164.It Ic replication Aq mode 165.Pp 166Replication mode should be one of the following: 167.Bl -tag -width ".Ic xxxx" 168.It Ic memsync 169.Pp 170Report the write operation as completed when local write completes and 171when the remote node acknowledges the data receipt, but before it 172actually stores the data. 173The data on remote node will be stored directly after sending 174acknowledgement. 175This mode is intended to reduce latency, but still provides a very good 176reliability. 177The only situation where some small amount of data could be lost is when 178the data is stored on primary node and sent to the secondary. 179Secondary node then acknowledges data receipt and primary reports 180success to an application. 181However, it may happen that the secondary goes down before the received 182data is really stored locally. 183Before secondary node returns, primary node dies entirely. 184When the secondary node comes back to life it becomes the new primary. 185Unfortunately some small amount of data which was confirmed to be stored 186to the application was lost. 187The risk of such a situation is very small. 188The 189.Ic memsync 190replication mode is currently not implemented. 191.It Ic fullsync 192.Pp 193Mark the write operation as completed when local as well as remote 194write completes. 195This is the safest and the slowest replication mode. 196The 197.Ic fullsync 198replication mode is the default. 199.It Ic async 200.Pp 201The write operation is reported as complete right after the local write 202completes. 203This is the fastest and the most dangerous replication mode. 204This mode should be used when replicating to a distant node where 205latency is too high for other modes. 206The 207.Ic async 208replication mode is currently not implemented. 209.El 210.It Ic checksum Aq algorithm 211.Pp 212Checksum algorithm should be one of the following: 213.Bl -tag -width ".Ic sha256" 214.It Ic none 215No checksum will be calculated for the data being send over the network. 216This is the default setting. 217.It Ic crc32 218CRC32 checksum will be calculated. 219.It Ic sha256 220SHA256 checksum will be calculated. 221.El 222.It Ic compression Aq algorithm 223.Pp 224Compression algorithm should be one of the following: 225.Bl -tag -width ".Ic none" 226.It Ic none 227Data send over the network will not be compressed. 228.It Ic hole 229Only blocks that contain all zeros will be compressed. 230This is very useful for initial synchronization where potentially many blocks 231are still all zeros. 232There should be no measurable performance overhead when this algorithm is being 233used. 234This is the default setting. 235.It Ic lzf 236The LZF algorithm by Marc Alexander Lehmann will be used to compress the data 237send over the network. 238LZF is very fast, general purpose compression algorithm. 239.El 240.It Ic timeout Aq seconds 241.Pp 242Connection timeout in seconds. 243The default value is 244.Va 5 . 245.It Ic exec Aq path 246.Pp 247Execute the given program on various HAST events. 248Below is the list of currently implemented events and arguments the given 249program is executed with: 250.Bl -tag -width ".Ic xxxx" 251.It Ic "<path> role <resource> <oldrole> <newrole>" 252.Pp 253Executed on both primary and secondary nodes when resource role is changed. 254.Pp 255.It Ic "<path> connect <resource>" 256.Pp 257Executed on both primary and secondary nodes when connection for the given 258resource between the nodes is established. 259.Pp 260.It Ic "<path> disconnect <resource>" 261.Pp 262Executed on both primary and secondary nodes when connection for the given 263resource between the nodes is lost. 264.Pp 265.It Ic "<path> syncstart <resource>" 266.Pp 267Executed on primary node when synchronization process of secondary node is 268started. 269.Pp 270.It Ic "<path> syncdone <resource>" 271.Pp 272Executed on primary node when synchronization process of secondary node is 273completed successfully. 274.Pp 275.It Ic "<path> syncintr <resource>" 276.Pp 277Executed on primary node when synchronization process of secondary node is 278interrupted, most likely due to secondary node outage or connection failure 279between the nodes. 280.Pp 281.It Ic "<path> split-brain <resource>" 282.Pp 283Executed on both primary and secondary nodes when split-brain condition is 284detected. 285.Pp 286.El 287The 288.Aq path 289argument should contain full path to executable program. 290If the given program exits with code different than 291.Va 0 , 292.Nm hastd 293will log it as an error. 294.Pp 295The 296.Aq resource 297argument is resource name from the configuration file. 298.Pp 299The 300.Aq oldrole 301argument is previous resource role (before the change). 302It can be one of: 303.Ar init , 304.Ar secondary , 305.Ar primary . 306.Pp 307The 308.Aq newrole 309argument is current resource role (after the change). 310It can be one of: 311.Ar init , 312.Ar secondary , 313.Ar primary . 314.Pp 315.It Ic name Aq name 316.Pp 317GEOM provider name that will appear as 318.Pa /dev/hast/<name> . 319If name is not defined, resource name will be used as provider name. 320.It Ic local Aq path 321.Pp 322Path to the local component which will be used as backend provider for 323the resource. 324This can be either GEOM provider or regular file. 325.It Ic remote Aq addr 326.Pp 327Address of the remote 328.Nm hastd 329daemon. 330Format is the same as for the 331.Ic listen 332statement. 333When operating as a primary node this address will be used to connect to 334the secondary node. 335When operating as a secondary node only connections from this address 336will be accepted. 337.Pp 338A special value of 339.Va none 340can be used when the remote address is not yet known (eg. the other node is not 341set up yet). 342.It Ic source Aq addr 343.Pp 344Local address to bind to before connecting to the remote 345.Nm hastd 346daemon. 347Format is the same as for the 348.Ic listen 349statement. 350.El 351.Sh FILES 352.Bl -tag -width ".Pa /var/run/hastctl" -compact 353.It Pa /etc/hast.conf 354The default 355.Nm 356configuration file. 357.It Pa /var/run/hastctl 358Control socket used by the 359.Xr hastctl 8 360control utility to communicate with the 361.Xr hastd 8 362daemon. 363.El 364.Sh EXAMPLES 365The example configuration file can look as follows: 366.Bd -literal -offset indent 367resource shared { 368 local /dev/da0 369 370 on hasta { 371 remote tcp4://10.0.0.2 372 } 373 on hastb { 374 remote tcp4://10.0.0.1 375 } 376} 377resource tank { 378 on hasta { 379 local /dev/mirror/tanka 380 source tcp4://10.0.0.1 381 remote tcp4://10.0.0.2 382 } 383 on hastb { 384 local /dev/mirror/tankb 385 source tcp4://10.0.0.2 386 remote tcp4://10.0.0.1 387 } 388} 389.Ed 390.Sh SEE ALSO 391.Xr gethostname 3 , 392.Xr geom 4 , 393.Xr hastctl 8 , 394.Xr hastd 8 . 395.Sh AUTHORS 396The 397.Nm 398was written by 399.An Pawel Jakub Dawidek Aq pjd@FreeBSD.org 400under sponsorship of the FreeBSD Foundation. 401