sbin/hastd/hast.conf.5

   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
  37 deamon and the
  38 .Xr hastctl 8
  39 utility.
  40 .Sh DESCRIPTION
  41 The
  42 .Nm
  43 file is used by both
  44 .Xr hastd 8
  45 daemon
  46 and
  47 .Xr hastctl 8
  48 control utility.
  49 Configuration file is designed in a way that exactly the same file can be
  50 (and should be) used on both HAST nodes.
  51 Every line starting with # is treated as comment and ignored.
  52 .Sh CONFIGURATION FILE SYNTAX
  53 General syntax of the
  54 .Nm
  55 file is following:
  56 .Bd -literal -offset indent
  57 # Global section
  58 control <addr>
  59 listen <addr>
  60 replication <mode>
  61 timeout <seconds>
  62
  63 on <node> {
  64         # Node section
  65         control <addr>
  66         listen <addr>
  67 }
  68
  69 on <node> {
  70         # Node section
  71         control <addr>
  72         listen <addr>
  73 }
  74
  75 resource <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
 101 Most of the various available configuration parameters are optional.
 102 If parameter is not defined in the particular section, it will be
 103 inherited from the parent section.
 104 For example, if the
 105 .Ic listen
 106 parameter is not defined in the node section, it will be inherited from
 107 the global section.
 108 In case the global section does not define the
 109 .Ic listen
 110 parameter at all, the default value will be used.
 111 .Sh CONFIGURATION FILE DESCRIPTION
 112 The
 113 .Aq node
 114 argument can be replaced either by a full hostname as obtained by
 115 .Xr gethostname 3 ,
 116 only first part of the hostname, or by node's UUID as found in the
 117 .Va kern.hostuuid
 118 .Xr sysctl 8
 119 variable.
 120 .Pp
 121 The following statements are available:
 122 .Bl -tag -width ".Ic xxxx"
 123 .It Ic control Aq addr
 124 .Pp
 125 Address for communication with
 126 .Xr hastctl 8 .
 127 Each of the following examples defines the same control address:
 128 .Bd -literal -offset indent
 129 uds:///var/run/hastctl
 130 unix:///var/run/hastctl
 131 /var/run/hastctl
 132 .Ed
 133 .Pp
 134 The default value is
 135 .Pa uds:///var/run/hastctl .
 136 .It Ic listen Aq addr
 137 .Pp
 138 Address to listen on in form of:
 139 .Bd -literal -offset indent
 140 protocol://protocol-specific-address
 141 .Ed
 142 .Pp
 143 Each of the following examples defines the same listen address:
 144 .Bd -literal -offset indent
 145 0.0.0.0
 146 0.0.0.0:8457
 147 tcp://0.0.0.0
 148 tcp://0.0.0.0:8457
 149 tcp4://0.0.0.0
 150 tcp4://0.0.0.0:8457
 151 .Ed
 152 .Pp
 153 The default value is
 154 .Pa tcp4://0.0.0.0:8457 .
 155 .It Ic replication Aq mode
 156 .Pp
 157 Replication mode should be one of the following:
 158 .Bl -tag -width ".Ic xxxx"
 159 .It Ic memsync
 160 .Pp
 161 Report the write operation as completed when local write completes and
 162 when the remote node acknowledges the data receipt, but before it
 163 actually stores the data.
 164 The data on remote node will be stored directly after sending
 165 acknowledgement.
 166 This mode is intended to reduce latency, but still provides a very good
 167 reliability.
 168 The only situation where some small amount of data could be lost is when
 169 the data is stored on primary node and sent to the secondary.
 170 Secondary node then acknowledges data receipt and primary reports
 171 success to an application.
 172 However, it may happen that the seconderay goes down before the received
 173 data is really stored locally.
 174 Before secondary node returns, primary node dies entirely.
 175 When the secondary node comes back to life it becomes the new primary.
 176 Unfortunately some small amount of data which was confirmed to be stored
 177 to the application was lost.
 178 The risk of such a situation is very small, which is the reason for this
 179 mode to be the default.
 180 .It Ic fullsync
 181 .Pp
 182 Mark the write operation as completed when local as well as remote
 183 write completes.
 184 This is the safest and the slowest replication mode.
 185 The
 186 .Ic fullsync
 187 replication mode is currently not implemented.
 188 .It Ic async
 189 .Pp
 190 The write operation is reported as complete right after the local write
 191 completes.
 192 This is the fastest and the most dangerous replication mode.
 193 This mode should be used when replicating to a distant node where
 194 latency is too high for other modes.
 195 The
 196 .Ic async
 197 replication mode is currently not implemented.
 198 .El
 199 .It Ic timeout Aq seconds
 200 .Pp
 201 Connection timeout in seconds.
 202 The default value is
 203 .Va 5 .
 204 .It Ic name Aq name
 205 .Pp
 206 GEOM provider name that will appear as
 207 .Pa /dev/hast/<name> .
 208 If name is not defined, resource name will be used as provider name.
 209 .It Ic local Aq path
 210 .Pp
 211 Path to the local component which will be used as backend provider for
 212 the resource.
 213 This can be either GEOM provider or regular file.
 214 .It Ic remote Aq addr
 215 .Pp
 216 Address of the remote
 217 .Nm hastd
 218 daemon.
 219 Format is the same as for the
 220 .Ic listen
 221 statement.
 222 When operating as a primary node this address will be used to connect to
 223 the secondary node.
 224 When operating as a secondary node only connections from this address
 225 will be accepted.
 226 .El
 227 .Sh EXAMPLES
 228 The example configuration file can look as follows:
 229 .Bd -literal -offset indent
 230 resource shared {
 231         local /dev/da0
 232
 233         on hasta {
 234                 remote tcp4://10.0.0.2
 235         }
 236         on hastb {
 237                 remote tcp4://10.0.0.1
 238         }
 239 }
 240 resource tank {
 241         on hasta {
 242                 local /dev/mirror/tanka
 243                 remote tcp4://10.0.0.2
 244         }
 245         on hastb {
 246                 local /dev/mirror/tankb
 247                 remote tcp4://10.0.0.1
 248         }
 249 }
 250 .Ed
 251 .Sh FILES
 252 .Bl -tag -width ".Pa /var/run/hastctl" -compact
 253 .It Pa /etc/hast.conf
 254 The default
 255 .Nm
 256 configuration file.
 257 .It Pa /var/run/hastctl
 258 Control socket used by the
 259 .Xr hastctl 8
 260 control utility to communicate with the
 261 .Xr hastd 8
 262 daemon.
 263 .El
 264 .Sh SEE ALSO
 265 .Xr gethostname 3 ,
 266 .Xr geom 4 ,
 267 .Xr hastctl 8 ,
 268 .Xr hastd 8 .
 269 .Sh AUTHORS
 270 The
 271 .Nm
 272 was written by
 273 .An Pawel Jakub Dawidek Aq pjd@FreeBSD.org
 274 under sponsorship of the FreeBSD Foundation.