sbin/hastd/hast.conf.5

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