1 .\" Copyright (c) 2010 The FreeBSD Foundation
2 .\" Copyright (c) 2010 Pawel Jakub Dawidek <pjd@FreeBSD.org>
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
86 # Resource-node section
94 # Resource-node section
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.
109 parameter is not defined in the node section, it will be inherited from
111 In case the global section does not define the
113 parameter at all, the default value will be used.
114 .Sh CONFIGURATION FILE DESCRIPTION
117 argument can be replaced either by a full hostname as obtained by
119 only first part of the hostname, or by node's UUID as found in the
124 The following statements are available:
125 .Bl -tag -width ".Ic xxxx"
126 .It Ic control Aq addr
128 Address for communication with
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
138 .Pa uds:///var/run/hastctl .
139 .It Ic listen Aq addr
141 Address to listen on in form of:
142 .Bd -literal -offset indent
143 protocol://protocol-specific-address
146 Each of the following examples defines the same listen address:
147 .Bd -literal -offset indent
157 .Pa tcp4://0.0.0.0:8457 .
158 .It Ic replication Aq mode
160 Replication mode should be one of the following:
161 .Bl -tag -width ".Ic xxxx"
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
169 This mode is intended to reduce latency, but still provides a very good
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.
184 replication mode is currently not implemented.
187 Mark the write operation as completed when local as well as remote
189 This is the safest and the slowest replication mode.
192 replication mode is the default.
195 The write operation is reported as complete right after the local write
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.
202 replication mode is currently not implemented.
204 .It Ic timeout Aq seconds
206 Connection timeout in seconds.
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>"
217 Executed on both primary and secondary nodes when resource role is changed.
219 .It Ic "<path> connect <resource>"
221 Executed on both primary and secondary nodes when connection for the given
222 resource between the nodes is established.
224 .It Ic "<path> disconnect <resource>"
226 Executed on both primary and secondary nodes when connection for the given
227 resource between the nodes is lost.
229 .It Ic "<path> syncstart <resource>"
231 Executed on primary node when synchronization process of secondary node is
234 .It Ic "<path> syncdone <resource>"
236 Executed on primary node when synchronization process of secondary node is
237 completed successfully.
239 .It Ic "<path> syncintr <resource>"
241 Executed on primary node when synchronization process of secondary node is
242 interrupted, most likely due to secondary node outage or connection failure
245 .It Ic "<path> split-brain <resource>"
247 Executed on both primary and secondary nodes when split-brain condition is
253 argument should contain full path to executable program.
254 If the given program exits with code different than
257 will log it as an error.
261 argument is resource name from the configuration file.
265 argument is previous resource role (before the change).
273 argument is current resource role (after the change).
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.
286 Path to the local component which will be used as backend provider for
288 This can be either GEOM provider or regular file.
289 .It Ic remote Aq addr
291 Address of the remote
294 Format is the same as for the
297 When operating as a primary node this address will be used to connect to
299 When operating as a secondary node only connections from this address
304 can be used when the remote address is not yet known (eg. the other node is not
308 .Bl -tag -width ".Pa /var/run/hastctl" -compact
309 .It Pa /etc/hast.conf
313 .It Pa /var/run/hastctl
314 Control socket used by the
316 control utility to communicate with the
321 The example configuration file can look as follows:
322 .Bd -literal -offset indent
327 remote tcp4://10.0.0.2
330 remote tcp4://10.0.0.1
335 local /dev/mirror/tanka
336 remote tcp4://10.0.0.2
339 local /dev/mirror/tankb
340 remote tcp4://10.0.0.1
353 .An Pawel Jakub Dawidek Aq pjd@FreeBSD.org
354 under sponsorship of the FreeBSD Foundation.