1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
|
.\" Copyright (c) 2010 The FreeBSD Foundation
.\" All rights reserved.
.\"
.\" This software was developed by Pawel Jakub Dawidek under sponsorship from
.\" the FreeBSD Foundation.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\" notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\" notice, this list of conditions and the following disclaimer in the
.\" documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\" $FreeBSD$
.\"
.Dd February 1, 2010
.Dt HASTCTL 8
.Os
.Sh NAME
.Nm hastctl
.Nd "Highly Available Storage control utility"
.Sh SYNOPSIS
.Nm
.Cm create
.Op Fl d
.Op Fl c Ar config
.Op Fl e Ar extentsize
.Op Fl k Ar keepdirty
.Op Fl m Ar mediasize
.Ar name ...
.Nm
.Cm role
.Op Fl d
.Op Fl c Ar config
.Aq init | primary | secondary
.Ar all | name ...
.Nm
.Cm status
.Op Fl d
.Op Fl c Ar config
.Op Ar all | name ...
.Nm
.Cm dump
.Op Fl d
.Op Fl c Ar config
.Op Ar all | name ...
.Sh DESCRIPTION
The
.Nm
utility is used to control the behaviour of the
.Xr hastd 8
daemon.
.Pp
This utility should be used by HA software like
.Nm heartbeat
or
.Nm ucarp
to setup HAST resources role when changing from primary mode to
secondary or vice versa.
Be aware that if a file system like UFS exists on HAST provider and
primary node dies, file system has to be checked for inconsistencies
with the
.Xr fsck 8
utility after switching secondary node to primary role.
.Pp
The first argument to
.Nm
indicates an action to be performed:
.Bl -tag -width ".Cm create"
.It Cm create
Initialize local provider configured for the given resource.
Additional options include:
.Bl -tag -width ".Fl e Ar extentsize"
.It Fl e Ar extentsize
Size of an extent.
Extent is a block which is used for synchronization.
.Nm
maintains a map of dirty extents and extent is the smallest region that
can be marked as dirty.
If any part of an extent is modified, entire extent will be synchronized
when nodes connect.
If extent size is too small, there will be too much disk activity
related to dirty map updates, which will degrade performance of the
given resource.
If extent size is too large, synchronization, even in case of short
outage, can take a long time increasing the risk of loosing up-to-date
node before synchronization process is completed.
The default extent size is
.Va 2MB .
.It Fl k Ar keepdirty
Maximum number of dirty extents to keep dirty all the time.
Most recently used extents are kept dirty to reduce number of metadata
updates.
The default numer of most recently used extents which will be kept
dirty is
.Va 64 .
.It Fl m Ar mediasize
Size of the smaller provider used as backend storage on both nodes.
This option can be omitted if node providers have the same size on both
sides.
.El
.It Cm role
Change role of the given resource.
The role can be one of:
.Bl -tag -width ".Cm secondary"
.It Cm init
Resource is turned off.
.It Cm primary
Local
.Xr hastd 8
daemon will act as primary node for the given resource.
System on which resource role is set to primary can use
.Pa /dev/hast/<name>
GEOM provider.
.It Cm secondary
Local
.Xr hastd 8
daemon will act as secondary node for the given resource - it will wait
for connection from the primary node and will handle I/O requests
received from it.
GEOM provider
.Pa /dev/hast/<name>
will not be created on secondary node.
.El
.It Cm status
Present status of the configured resources.
.It Cm dump
Dump metadata stored on local component for the configured resources.
.El
.Pp
In addition, every subcommand can be followed by the following options:
.Bl -tag -width ".Fl c Ar config"
.It Fl c Ar config
Specify alternative location of the configuration file.
The default location is
.Pa /etc/hast.conf .
.It Fl d
Print debugging information.
This option can be specified multiple times to raise the verbosity
level.
.El
.Sh FILES
.Bl -tag -width ".Pa /var/run/hastctl" -compact
.It Pa /etc/hast.conf
Configuration file for
.Nm
and
.Xr hastd 8 .
.It Pa /var/run/hastctl
Control socket used by
.Nm
to communicate with the
.Xr hastd 8
daemon.
.El
.Sh EXIT STATUS
Exit status is 0 on success, or one of the values described in
.Xr sysexits 3
on failure.
.Sh EXAMPLES
Initialize HAST provider, create file system on it and mount it.
.Bd -literal -offset indent
nodeB# hastctl create shared
nodeB# hastd
nodeB# hastctl role secondary shared
nodeB# hastctl create shared
nodeA# hastd
nodeA# hastctl role primary shared
nodeA# newfs -U /dev/hast/shared
nodeA# mount -o noatime /dev/hast/shared /shared
nodeA# application_start
.Ed
.Pp
Switch roles for the
.Nm shared
HAST resource.
.Bd -literal -offset indent
nodeA# application_stop
nodeA# umount -f /shared
nodeA# hastctl role secondary shared
nodeB# hastctl role primary shared
nodeB# fsck -t ufs /dev/hast/shared
nodeB# mount -o noatime /dev/hast/shared /shared
nodeB# application_start
.Ed
.Sh SEE ALSO
.Xr sysexits 3 ,
.Xr geom 4 ,
.Xr hast.conf 5 ,
.Xr fsck 8 ,
.Xr ggatec 8 ,
.Xr ggatel 8 ,
.Xr hastd 8 ,
.Xr mount 8 ,
.Xr newfs 8 .
.Sh AUTHORS
The
.Nm
was developed by
.An Pawel Jakub Dawidek Aq pjd@FreeBSD.org
under sponsorship of the FreeBSD Foundation.
|