1 .\" Copyright (c) 2010 The FreeBSD Foundation
2 .\" Copyright (c) 2010-2012 Pawel Jakub Dawidek <pawel@dawidek.net>
3 .\" All rights reserved.
5 .\" This documentation was written 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>
87 compression <algorithm>
95 # Resource-node section
105 # Resource-node section
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.
122 parameter is not defined in the node section, it will be inherited from
124 In case the global section does not define the
126 parameter at all, the default value will be used.
127 .Sh CONFIGURATION FILE DESCRIPTION
130 argument can be replaced either by a full hostname as obtained by
132 only first part of the hostname, by node's UUID as found in the
136 or by node's hostid as found in the
141 The following statements are available:
142 .Bl -tag -width ".Ic xxxx"
143 .It Ic control Aq addr
145 Address for communication with
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
155 .Pa uds:///var/run/hastctl .
156 .It Ic pidfile Aq path
158 File in which to store the process ID of the main
163 .Pa /var/run/hastd.pid .
164 .It Ic listen Aq addr
166 Address to listen on in form of:
167 .Bd -literal -offset indent
168 protocol://protocol-specific-address
171 Each of the following examples defines the same listen address:
172 .Bd -literal -offset indent
181 Multiple listen addresses can be specified.
185 .Pa tcp4://0.0.0.0:8457
188 if kernel supports IPv4 and IPv6 respectively.
189 .It Ic replication Aq mode
191 Replication mode should be one of the following:
192 .Bl -tag -width ".Ic xxxx"
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
200 This mode is intended to reduce latency, but still provides a very good
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.
215 replication mode is the default.
218 Mark the write operation as completed when local as well as remote
220 This is the safest and the slowest replication mode.
223 The write operation is reported as complete right after the local write
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.
229 .It Ic checksum Aq algorithm
231 Checksum algorithm should be one of the following:
232 .Bl -tag -width ".Ic sha256"
234 No checksum will be calculated for the data being send over the network.
235 This is the default setting.
237 CRC32 checksum will be calculated.
239 SHA256 checksum will be calculated.
241 .It Ic compression Aq algorithm
243 Compression algorithm should be one of the following:
244 .Bl -tag -width ".Ic none"
246 Data send over the network will not be compressed.
248 Only blocks that contain all zeros will be compressed.
249 This is very useful for initial synchronization where potentially many blocks
251 There should be no measurable performance overhead when this algorithm is being
253 This is the default setting.
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.
259 .It Ic timeout Aq seconds
261 Connection timeout in seconds.
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>"
272 Executed on both primary and secondary nodes when resource role is changed.
273 .It Ic "<path> connect <resource>"
275 Executed on both primary and secondary nodes when connection for the given
276 resource between the nodes is established.
277 .It Ic "<path> disconnect <resource>"
279 Executed on both primary and secondary nodes when connection for the given
280 resource between the nodes is lost.
281 .It Ic "<path> syncstart <resource>"
283 Executed on primary node when synchronization process of secondary node is
285 .It Ic "<path> syncdone <resource>"
287 Executed on primary node when synchronization process of secondary node is
288 completed successfully.
289 .It Ic "<path> syncintr <resource>"
291 Executed on primary node when synchronization process of secondary node is
292 interrupted, most likely due to secondary node outage or connection failure
294 .It Ic "<path> split-brain <resource>"
296 Executed on both primary and secondary nodes when split-brain condition is
302 argument should contain full path to executable program.
303 If the given program exits with code different than
306 will log it as an error.
310 argument is resource name from the configuration file.
314 argument is previous resource role (before the change).
322 argument is current resource role (after the change).
327 .It Ic metaflush on | off
331 flush write cache of the local provider after every metadata (activemap) update.
332 Flushing write cache ensures that provider will not reorder writes and that
333 metadata will be properly updated before real data is stored.
334 If the local provider does not support flushing write cache (it returns
347 GEOM provider name that will appear as
348 .Pa /dev/hast/<name> .
349 If name is not defined, resource name will be used as provider name.
352 Path to the local component which will be used as backend provider for
354 This can be either GEOM provider or regular file.
355 .It Ic remote Aq addr
357 Address of the remote
360 Format is the same as for the
363 When operating as a primary node this address will be used to connect to
365 When operating as a secondary node only connections from this address
370 can be used when the remote address is not yet known (eg. the other node is not
372 .It Ic source Aq addr
374 Local address to bind to before connecting to the remote
377 Format is the same as for the
382 .Bl -tag -width ".Pa /var/run/hastctl" -compact
383 .It Pa /etc/hast.conf
389 .It Pa /var/run/hastctl
390 Control socket used by the
392 control utility to communicate with the
397 The example configuration file can look as follows:
398 .Bd -literal -offset indent
402 listen tcp://2001:db8::1/64
405 listen tcp://2001:db8::2/64
412 remote tcp://10.0.0.2
415 remote tcp://10.0.0.1
420 local /dev/mirror/tanka
421 source tcp://10.0.0.1
422 remote tcp://10.0.0.2
425 local /dev/mirror/tankb
426 source tcp://10.0.0.2
427 remote tcp://10.0.0.1
440 .An Pawel Jakub Dawidek Aq Mt pjd@FreeBSD.org
441 under sponsorship of the FreeBSD Foundation.