1 .\" Copyright (c) 2010 The FreeBSD Foundation
2 .\" Copyright (c) 2010-2011 Pawel Jakub Dawidek <pawel@dawidek.net>
3 .\" All rights reserved.
5 .\" This software was developed by Pawel Jakub Dawidek under sponsorship from
6 .\" the FreeBSD Foundation.
8 .\" Redistribution and use in source and binary forms, with or without
9 .\" modification, are permitted provided that the following conditions
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.
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
36 .Nd configuration file for the
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
57 .Bd -literal -offset indent
63 compression <algorithm>
83 compression <algorithm>
90 # Resource-node section
99 # Resource-node section
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.
115 parameter is not defined in the node section, it will be inherited from
117 In case the global section does not define the
119 parameter at all, the default value will be used.
120 .Sh CONFIGURATION FILE DESCRIPTION
123 argument can be replaced either by a full hostname as obtained by
125 only first part of the hostname, or by node's UUID as found in the
130 The following statements are available:
131 .Bl -tag -width ".Ic xxxx"
132 .It Ic control Aq addr
134 Address for communication with
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
144 .Pa uds:///var/run/hastctl .
145 .It Ic listen Aq addr
147 Address to listen on in form of:
148 .Bd -literal -offset indent
149 protocol://protocol-specific-address
152 Each of the following examples defines the same listen address:
153 .Bd -literal -offset indent
163 .Pa tcp4://0.0.0.0:8457 .
164 .It Ic replication Aq mode
166 Replication mode should be one of the following:
167 .Bl -tag -width ".Ic xxxx"
170 Report the write operation as completed when local write completes and
171 when the remote node acknowledges the data receipt, but before it
172 actually stores the data.
173 The data on remote node will be stored directly after sending
175 This mode is intended to reduce latency, but still provides a very good
177 The only situation where some small amount of data could be lost is when
178 the data is stored on primary node and sent to the secondary.
179 Secondary node then acknowledges data receipt and primary reports
180 success to an application.
181 However, it may happen that the secondary goes down before the received
182 data is really stored locally.
183 Before secondary node returns, primary node dies entirely.
184 When the secondary node comes back to life it becomes the new primary.
185 Unfortunately some small amount of data which was confirmed to be stored
186 to the application was lost.
187 The risk of such a situation is very small.
190 replication mode is currently not implemented.
193 Mark the write operation as completed when local as well as remote
195 This is the safest and the slowest replication mode.
198 replication mode is the default.
201 The write operation is reported as complete right after the local write
203 This is the fastest and the most dangerous replication mode.
204 This mode should be used when replicating to a distant node where
205 latency is too high for other modes.
208 replication mode is currently not implemented.
210 .It Ic checksum Aq algorithm
212 Checksum algorithm should be one of the following:
213 .Bl -tag -width ".Ic sha256"
215 No checksum will be calculated for the data being send over the network.
216 This is the default setting.
218 CRC32 checksum will be calculated.
220 SHA256 checksum will be calculated.
222 .It Ic compression Aq algorithm
224 Compression algorithm should be one of the following:
225 .Bl -tag -width ".Ic none"
227 Data send over the network will not be compressed.
229 Only blocks that contain all zeros will be compressed.
230 This is very useful for initial synchronization where potentially many blocks
232 There should be no measurable performance overhead when this algorithm is being
234 This is the default setting.
236 The LZF algorithm by Marc Alexander Lehmann will be used to compress the data
237 send over the network.
238 LZF is very fast, general purpose compression algorithm.
240 .It Ic timeout Aq seconds
242 Connection timeout in seconds.
247 Execute the given program on various HAST events.
248 Below is the list of currently implemented events and arguments the given
249 program is executed with:
250 .Bl -tag -width ".Ic xxxx"
251 .It Ic "<path> role <resource> <oldrole> <newrole>"
253 Executed on both primary and secondary nodes when resource role is changed.
255 .It Ic "<path> connect <resource>"
257 Executed on both primary and secondary nodes when connection for the given
258 resource between the nodes is established.
260 .It Ic "<path> disconnect <resource>"
262 Executed on both primary and secondary nodes when connection for the given
263 resource between the nodes is lost.
265 .It Ic "<path> syncstart <resource>"
267 Executed on primary node when synchronization process of secondary node is
270 .It Ic "<path> syncdone <resource>"
272 Executed on primary node when synchronization process of secondary node is
273 completed successfully.
275 .It Ic "<path> syncintr <resource>"
277 Executed on primary node when synchronization process of secondary node is
278 interrupted, most likely due to secondary node outage or connection failure
281 .It Ic "<path> split-brain <resource>"
283 Executed on both primary and secondary nodes when split-brain condition is
289 argument should contain full path to executable program.
290 If the given program exits with code different than
293 will log it as an error.
297 argument is resource name from the configuration file.
301 argument is previous resource role (before the change).
309 argument is current resource role (after the change).
317 GEOM provider name that will appear as
318 .Pa /dev/hast/<name> .
319 If name is not defined, resource name will be used as provider name.
322 Path to the local component which will be used as backend provider for
324 This can be either GEOM provider or regular file.
325 .It Ic remote Aq addr
327 Address of the remote
330 Format is the same as for the
333 When operating as a primary node this address will be used to connect to
335 When operating as a secondary node only connections from this address
340 can be used when the remote address is not yet known (eg. the other node is not
342 .It Ic source Aq addr
344 Local address to bind to before connecting to the remote
347 Format is the same as for the
352 .Bl -tag -width ".Pa /var/run/hastctl" -compact
353 .It Pa /etc/hast.conf
357 .It Pa /var/run/hastctl
358 Control socket used by the
360 control utility to communicate with the
365 The example configuration file can look as follows:
366 .Bd -literal -offset indent
371 remote tcp4://10.0.0.2
374 remote tcp4://10.0.0.1
379 local /dev/mirror/tanka
380 source tcp4://10.0.0.1
381 remote tcp4://10.0.0.2
384 local /dev/mirror/tankb
385 source tcp4://10.0.0.2
386 remote tcp4://10.0.0.1
399 .An Pawel Jakub Dawidek Aq pjd@FreeBSD.org
400 under sponsorship of the FreeBSD Foundation.