sbin/hastd/hast.conf.5

   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 May 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
  38 daemon and the
  39 .Xr hastctl 8
  40 utility.
  41 .Sh DESCRIPTION
  42 The
  43 .Nm
  44 file is used by both
  45 .Xr hastd 8
  46 daemon
  47 and
  48 .Xr hastctl 8
  49 control utility.
  50 Configuration file is designed in a way that exactly the same file can be
  51 (and should be) used on both HAST nodes.
  52 Every line starting with # is treated as comment and ignored.
  53 .Sh CONFIGURATION FILE SYNTAX
  54 General syntax of the
  55 .Nm
  56 file is following:
  57 .Bd -literal -offset indent
  58 # Global section
  59 control <addr>
  60 listen <addr>
  61 replication <mode>
  62 checksum <algorithm>
  63 compression <algorithm>
  64 timeout <seconds>
  65 exec <path>
  66
  67 on <node> {
  68         # Node section
  69         control <addr>
  70         listen <addr>
  71 }
  72
  73 on <node> {
  74         # Node section
  75         control <addr>
  76         listen <addr>
  77 }
  78
  79 resource <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
 110 Most of the various available configuration parameters are optional.
 111 If parameter is not defined in the particular section, it will be
 112 inherited from the parent section.
 113 For example, if the
 114 .Ic listen
 115 parameter is not defined in the node section, it will be inherited from
 116 the global section.
 117 In case the global section does not define the
 118 .Ic listen
 119 parameter at all, the default value will be used.
 120 .Sh CONFIGURATION FILE DESCRIPTION
 121 The
 122 .Aq node
 123 argument can be replaced either by a full hostname as obtained by
 124 .Xr gethostname 3 ,
 125 only first part of the hostname, or by node's UUID as found in the
 126 .Va kern.hostuuid
 127 .Xr sysctl 8
 128 variable.
 129 .Pp
 130 The following statements are available:
 131 .Bl -tag -width ".Ic xxxx"
 132 .It Ic control Aq addr
 133 .Pp
 134 Address for communication with
 135 .Xr hastctl 8 .
 136 Each of the following examples defines the same control address:
 137 .Bd -literal -offset indent
 138 uds:///var/run/hastctl
 139 unix:///var/run/hastctl
 140 /var/run/hastctl
 141 .Ed
 142 .Pp
 143 The default value is
 144 .Pa uds:///var/run/hastctl .
 145 .It Ic listen Aq addr
 146 .Pp
 147 Address to listen on in form of:
 148 .Bd -literal -offset indent
 149 protocol://protocol-specific-address
 150 .Ed
 151 .Pp
 152 Each of the following examples defines the same listen address:
 153 .Bd -literal -offset indent
 154 0.0.0.0
 155 0.0.0.0:8457
 156 tcp://0.0.0.0
 157 tcp://0.0.0.0:8457
 158 tcp4://0.0.0.0
 159 tcp4://0.0.0.0:8457
 160 .Ed
 161 .Pp
 162 Multiple listen addresses can be specified.
 163 By default
 164 .Nm hastd
 165 listens on
 166 .Pa tcp4://0.0.0.0:8457
 167 and
 168 .Pa tcp6://[::]:8457
 169 if kernel supports IPv4 and IPv6 respectively.
 170 .It Ic replication Aq mode
 171 .Pp
 172 Replication mode should be one of the following:
 173 .Bl -tag -width ".Ic xxxx"
 174 .It Ic memsync
 175 .Pp
 176 Report the write operation as completed when local write completes and
 177 when the remote node acknowledges the data receipt, but before it
 178 actually stores the data.
 179 The data on remote node will be stored directly after sending
 180 acknowledgement.
 181 This mode is intended to reduce latency, but still provides a very good
 182 reliability.
 183 The only situation where some small amount of data could be lost is when
 184 the data is stored on primary node and sent to the secondary.
 185 Secondary node then acknowledges data receipt and primary reports
 186 success to an application.
 187 However, it may happen that the secondary goes down before the received
 188 data is really stored locally.
 189 Before secondary node returns, primary node dies entirely.
 190 When the secondary node comes back to life it becomes the new primary.
 191 Unfortunately some small amount of data which was confirmed to be stored
 192 to the application was lost.
 193 The risk of such a situation is very small.
 194 The
 195 .Ic memsync
 196 replication mode is currently not implemented.
 197 .It Ic fullsync
 198 .Pp
 199 Mark the write operation as completed when local as well as remote
 200 write completes.
 201 This is the safest and the slowest replication mode.
 202 The
 203 .Ic fullsync
 204 replication mode is the default.
 205 .It Ic async
 206 .Pp
 207 The write operation is reported as complete right after the local write
 208 completes.
 209 This is the fastest and the most dangerous replication mode.
 210 This mode should be used when replicating to a distant node where
 211 latency is too high for other modes.
 212 The
 213 .Ic async
 214 replication mode is currently not implemented.
 215 .El
 216 .It Ic checksum Aq algorithm
 217 .Pp
 218 Checksum algorithm should be one of the following:
 219 .Bl -tag -width ".Ic sha256"
 220 .It Ic none
 221 No checksum will be calculated for the data being send over the network.
 222 This is the default setting.
 223 .It Ic crc32
 224 CRC32 checksum will be calculated.
 225 .It Ic sha256
 226 SHA256 checksum will be calculated.
 227 .El
 228 .It Ic compression Aq algorithm
 229 .Pp
 230 Compression algorithm should be one of the following:
 231 .Bl -tag -width ".Ic none"
 232 .It Ic none
 233 Data send over the network will not be compressed.
 234 .It Ic hole
 235 Only blocks that contain all zeros will be compressed.
 236 This is very useful for initial synchronization where potentially many blocks
 237 are still all zeros.
 238 There should be no measurable performance overhead when this algorithm is being
 239 used.
 240 This is the default setting.
 241 .It Ic lzf
 242 The LZF algorithm by Marc Alexander Lehmann will be used to compress the data
 243 send over the network.
 244 LZF is very fast, general purpose compression algorithm.
 245 .El
 246 .It Ic timeout Aq seconds
 247 .Pp
 248 Connection timeout in seconds.
 249 The default value is
 250 .Va 20 .
 251 .It Ic exec Aq path
 252 .Pp
 253 Execute the given program on various HAST events.
 254 Below is the list of currently implemented events and arguments the given
 255 program is executed with:
 256 .Bl -tag -width ".Ic xxxx"
 257 .It Ic "<path> role <resource> <oldrole> <newrole>"
 258 .Pp
 259 Executed on both primary and secondary nodes when resource role is changed.
 260 .Pp
 261 .It Ic "<path> connect <resource>"
 262 .Pp
 263 Executed on both primary and secondary nodes when connection for the given
 264 resource between the nodes is established.
 265 .Pp
 266 .It Ic "<path> disconnect <resource>"
 267 .Pp
 268 Executed on both primary and secondary nodes when connection for the given
 269 resource between the nodes is lost.
 270 .Pp
 271 .It Ic "<path> syncstart <resource>"
 272 .Pp
 273 Executed on primary node when synchronization process of secondary node is
 274 started.
 275 .Pp
 276 .It Ic "<path> syncdone <resource>"
 277 .Pp
 278 Executed on primary node when synchronization process of secondary node is
 279 completed successfully.
 280 .Pp
 281 .It Ic "<path> syncintr <resource>"
 282 .Pp
 283 Executed on primary node when synchronization process of secondary node is
 284 interrupted, most likely due to secondary node outage or connection failure
 285 between the nodes.
 286 .Pp
 287 .It Ic "<path> split-brain <resource>"
 288 .Pp
 289 Executed on both primary and secondary nodes when split-brain condition is
 290 detected.
 291 .Pp
 292 .El
 293 The
 294 .Aq path
 295 argument should contain full path to executable program.
 296 If the given program exits with code different than
 297 .Va 0 ,
 298 .Nm hastd
 299 will log it as an error.
 300 .Pp
 301 The
 302 .Aq resource
 303 argument is resource name from the configuration file.
 304 .Pp
 305 The
 306 .Aq oldrole
 307 argument is previous resource role (before the change).
 308 It can be one of:
 309 .Ar init ,
 310 .Ar secondary ,
 311 .Ar primary .
 312 .Pp
 313 The
 314 .Aq newrole
 315 argument is current resource role (after the change).
 316 It can be one of:
 317 .Ar init ,
 318 .Ar secondary ,
 319 .Ar primary .
 320 .Pp
 321 .It Ic name Aq name
 322 .Pp
 323 GEOM provider name that will appear as
 324 .Pa /dev/hast/<name> .
 325 If name is not defined, resource name will be used as provider name.
 326 .It Ic local Aq path
 327 .Pp
 328 Path to the local component which will be used as backend provider for
 329 the resource.
 330 This can be either GEOM provider or regular file.
 331 .It Ic remote Aq addr
 332 .Pp
 333 Address of the remote
 334 .Nm hastd
 335 daemon.
 336 Format is the same as for the
 337 .Ic listen
 338 statement.
 339 When operating as a primary node this address will be used to connect to
 340 the secondary node.
 341 When operating as a secondary node only connections from this address
 342 will be accepted.
 343 .Pp
 344 A special value of
 345 .Va none
 346 can be used when the remote address is not yet known (eg. the other node is not
 347 set up yet).
 348 .It Ic source Aq addr
 349 .Pp
 350 Local address to bind to before connecting to the remote
 351 .Nm hastd
 352 daemon.
 353 Format is the same as for the
 354 .Ic listen
 355 statement.
 356 .El
 357 .Sh FILES
 358 .Bl -tag -width ".Pa /var/run/hastctl" -compact
 359 .It Pa /etc/hast.conf
 360 The default
 361 .Nm
 362 configuration file.
 363 .It Pa /var/run/hastctl
 364 Control socket used by the
 365 .Xr hastctl 8
 366 control utility to communicate with the
 367 .Xr hastd 8
 368 daemon.
 369 .El
 370 .Sh EXAMPLES
 371 The example configuration file can look as follows:
 372 .Bd -literal -offset indent
 373 listen tcp://0.0.0.0
 374
 375 on hasta {
 376         listen tcp://2001:db8::1/64
 377 }
 378 on hastb {
 379         listen tcp://2001:db8::2/64
 380 }
 381
 382 resource shared {
 383         local /dev/da0
 384
 385         on hasta {
 386                 remote tcp://10.0.0.2
 387         }
 388         on hastb {
 389                 remote tcp://10.0.0.1
 390         }
 391 }
 392 resource tank {
 393         on hasta {
 394                 local /dev/mirror/tanka
 395                 source tcp://10.0.0.1
 396                 remote tcp://10.0.0.2
 397         }
 398         on hastb {
 399                 local /dev/mirror/tankb
 400                 source tcp://10.0.0.2
 401                 remote tcp://10.0.0.1
 402         }
 403 }
 404 .Ed
 405 .Sh SEE ALSO
 406 .Xr gethostname 3 ,
 407 .Xr geom 4 ,
 408 .Xr hastctl 8 ,
 409 .Xr hastd 8 .
 410 .Sh AUTHORS
 411 The
 412 .Nm
 413 was written by
 414 .An Pawel Jakub Dawidek Aq pjd@FreeBSD.org
 415 under sponsorship of the FreeBSD Foundation.