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