sbin/hastd/hast.conf.5

   1 .\" Copyright (c) 2010 The FreeBSD Foundation
   2 .\" Copyright (c) 2010 Pawel Jakub Dawidek <pjd@FreeBSD.org>
   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 August 30, 2010
  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 timeout <seconds>
  63 exec <path>
  64
  65 on <node> {
  66         # Node section
  67         control <addr>
  68         listen <addr>
  69 }
  70
  71 on <node> {
  72         # Node section
  73         control <addr>
  74         listen <addr>
  75 }
  76
  77 resource <name> {
  78         # Resource section
  79         replication <mode>
  80         name <name>
  81         local <path>
  82         timeout <seconds>
  83         exec <path>
  84
  85         on <node> {
  86                 # Resource-node section
  87                 name <name>
  88                 # Required
  89                 local <path>
  90                 # Required
  91                 remote <addr>
  92         }
  93         on <node> {
  94                 # Resource-node section
  95                 name <name>
  96                 # Required
  97                 local <path>
  98                 # Required
  99                 remote <addr>
 100         }
 101 }
 102 .Ed
 103 .Pp
 104 Most of the various available configuration parameters are optional.
 105 If parameter is not defined in the particular section, it will be
 106 inherited from the parent section.
 107 For example, if the
 108 .Ic listen
 109 parameter is not defined in the node section, it will be inherited from
 110 the global section.
 111 In case the global section does not define the
 112 .Ic listen
 113 parameter at all, the default value will be used.
 114 .Sh CONFIGURATION FILE DESCRIPTION
 115 The
 116 .Aq node
 117 argument can be replaced either by a full hostname as obtained by
 118 .Xr gethostname 3 ,
 119 only first part of the hostname, or by node's UUID as found in the
 120 .Va kern.hostuuid
 121 .Xr sysctl 8
 122 variable.
 123 .Pp
 124 The following statements are available:
 125 .Bl -tag -width ".Ic xxxx"
 126 .It Ic control Aq addr
 127 .Pp
 128 Address for communication with
 129 .Xr hastctl 8 .
 130 Each of the following examples defines the same control address:
 131 .Bd -literal -offset indent
 132 uds:///var/run/hastctl
 133 unix:///var/run/hastctl
 134 /var/run/hastctl
 135 .Ed
 136 .Pp
 137 The default value is
 138 .Pa uds:///var/run/hastctl .
 139 .It Ic listen Aq addr
 140 .Pp
 141 Address to listen on in form of:
 142 .Bd -literal -offset indent
 143 protocol://protocol-specific-address
 144 .Ed
 145 .Pp
 146 Each of the following examples defines the same listen address:
 147 .Bd -literal -offset indent
 148 0.0.0.0
 149 0.0.0.0:8457
 150 tcp://0.0.0.0
 151 tcp://0.0.0.0:8457
 152 tcp4://0.0.0.0
 153 tcp4://0.0.0.0:8457
 154 .Ed
 155 .Pp
 156 The default value is
 157 .Pa tcp4://0.0.0.0:8457 .
 158 .It Ic replication Aq mode
 159 .Pp
 160 Replication mode should be one of the following:
 161 .Bl -tag -width ".Ic xxxx"
 162 .It Ic memsync
 163 .Pp
 164 Report the write operation as completed when local write completes and
 165 when the remote node acknowledges the data receipt, but before it
 166 actually stores the data.
 167 The data on remote node will be stored directly after sending
 168 acknowledgement.
 169 This mode is intended to reduce latency, but still provides a very good
 170 reliability.
 171 The only situation where some small amount of data could be lost is when
 172 the data is stored on primary node and sent to the secondary.
 173 Secondary node then acknowledges data receipt and primary reports
 174 success to an application.
 175 However, it may happen that the secondary goes down before the received
 176 data is really stored locally.
 177 Before secondary node returns, primary node dies entirely.
 178 When the secondary node comes back to life it becomes the new primary.
 179 Unfortunately some small amount of data which was confirmed to be stored
 180 to the application was lost.
 181 The risk of such a situation is very small.
 182 The
 183 .Ic memsync
 184 replication mode is currently not implemented.
 185 .It Ic fullsync
 186 .Pp
 187 Mark the write operation as completed when local as well as remote
 188 write completes.
 189 This is the safest and the slowest replication mode.
 190 The
 191 .Ic fullsync
 192 replication mode is the default.
 193 .It Ic async
 194 .Pp
 195 The write operation is reported as complete right after the local write
 196 completes.
 197 This is the fastest and the most dangerous replication mode.
 198 This mode should be used when replicating to a distant node where
 199 latency is too high for other modes.
 200 The
 201 .Ic async
 202 replication mode is currently not implemented.
 203 .El
 204 .It Ic timeout Aq seconds
 205 .Pp
 206 Connection timeout in seconds.
 207 The default value is
 208 .Va 5 .
 209 .It Ic exec Aq path
 210 .Pp
 211 Execute the given program on various HAST events.
 212 Below is the list of currently implemented events and arguments the given
 213 program is executed with:
 214 .Bl -tag -width ".Ic xxxx"
 215 .It Ic "<path> role <resource> <oldrole> <newrole>"
 216 .Pp
 217 Executed on both primary and secondary nodes when resource role is changed.
 218 .Pp
 219 .It Ic "<path> connect <resource>"
 220 .Pp
 221 Executed on both primary and secondary nodes when connection for the given
 222 resource between the nodes is established.
 223 .Pp
 224 .It Ic "<path> disconnect <resource>"
 225 .Pp
 226 Executed on both primary and secondary nodes when connection for the given
 227 resource between the nodes is lost.
 228 .Pp
 229 .It Ic "<path> syncstart <resource>"
 230 .Pp
 231 Executed on primary node when synchronization process of secondary node is
 232 started.
 233 .Pp
 234 .It Ic "<path> syncdone <resource>"
 235 .Pp
 236 Executed on primary node when synchronization process of secondary node is
 237 completed successfully.
 238 .Pp
 239 .It Ic "<path> syncintr <resource>"
 240 .Pp
 241 Executed on primary node when synchronization process of secondary node is
 242 interrupted, most likely due to secondary node outage or connection failure
 243 between the nodes.
 244 .Pp
 245 .It Ic "<path> split-brain <resource>"
 246 .Pp
 247 Executed on both primary and secondary nodes when split-brain condition is
 248 detected.
 249 .Pp
 250 .El
 251 The
 252 .Aq path
 253 argument should contain full path to executable program.
 254 If the given program exits with code different than
 255 .Va 0 ,
 256 .Nm hastd
 257 will log it as an error.
 258 .Pp
 259 The
 260 .Aq resource
 261 argument is resource name from the configuration file.
 262 .Pp
 263 The
 264 .Aq oldrole
 265 argument is previous resource role (before the change).
 266 It can be one of:
 267 .Ar init ,
 268 .Ar secondary ,
 269 .Ar primary .
 270 .Pp
 271 The
 272 .Aq newrole
 273 argument is current resource role (after the change).
 274 It can be one of:
 275 .Ar init ,
 276 .Ar secondary ,
 277 .Ar primary .
 278 .Pp
 279 .It Ic name Aq name
 280 .Pp
 281 GEOM provider name that will appear as
 282 .Pa /dev/hast/<name> .
 283 If name is not defined, resource name will be used as provider name.
 284 .It Ic local Aq path
 285 .Pp
 286 Path to the local component which will be used as backend provider for
 287 the resource.
 288 This can be either GEOM provider or regular file.
 289 .It Ic remote Aq addr
 290 .Pp
 291 Address of the remote
 292 .Nm hastd
 293 daemon.
 294 Format is the same as for the
 295 .Ic listen
 296 statement.
 297 When operating as a primary node this address will be used to connect to
 298 the secondary node.
 299 When operating as a secondary node only connections from this address
 300 will be accepted.
 301 .Pp
 302 A special value of
 303 .Va none
 304 can be used when the remote address is not yet known (eg. the other node is not
 305 set up yet).
 306 .El
 307 .Sh FILES
 308 .Bl -tag -width ".Pa /var/run/hastctl" -compact
 309 .It Pa /etc/hast.conf
 310 The default
 311 .Nm
 312 configuration file.
 313 .It Pa /var/run/hastctl
 314 Control socket used by the
 315 .Xr hastctl 8
 316 control utility to communicate with the
 317 .Xr hastd 8
 318 daemon.
 319 .El
 320 .Sh EXAMPLES
 321 The example configuration file can look as follows:
 322 .Bd -literal -offset indent
 323 resource shared {
 324         local /dev/da0
 325
 326         on hasta {
 327                 remote tcp4://10.0.0.2
 328         }
 329         on hastb {
 330                 remote tcp4://10.0.0.1
 331         }
 332 }
 333 resource tank {
 334         on hasta {
 335                 local /dev/mirror/tanka
 336                 remote tcp4://10.0.0.2
 337         }
 338         on hastb {
 339                 local /dev/mirror/tankb
 340                 remote tcp4://10.0.0.1
 341         }
 342 }
 343 .Ed
 344 .Sh SEE ALSO
 345 .Xr gethostname 3 ,
 346 .Xr geom 4 ,
 347 .Xr hastctl 8 ,
 348 .Xr hastd 8 .
 349 .Sh AUTHORS
 350 The
 351 .Nm
 352 was written by
 353 .An Pawel Jakub Dawidek Aq pjd@FreeBSD.org
 354 under sponsorship of the FreeBSD Foundation.