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 September 8, 2016 31.Dt HASTCTL 8 32.Os 33.Sh NAME 34.Nm hastctl 35.Nd "Highly Available Storage control utility" 36.Sh SYNOPSIS 37.Nm 38.Cm create 39.Op Fl d 40.Op Fl c Ar config 41.Op Fl e Ar extentsize 42.Op Fl k Ar keepdirty 43.Op Fl m Ar mediasize 44.Ar name ... 45.Nm 46.Cm role 47.Op Fl d 48.Op Fl c Ar config 49.Aq init | primary | secondary 50.Ar all | name ... 51.Nm 52.Cm list 53.Op Fl d 54.Op Fl c Ar config 55.Op Ar all | name ... 56.Nm 57.Cm status 58.Op Fl d 59.Op Fl c Ar config 60.Op Ar all | name ... 61.Nm 62.Cm dump 63.Op Fl d 64.Op Fl c Ar config 65.Op Ar all | name ... 66.Sh DESCRIPTION 67The 68.Nm 69utility is used to control the behaviour of the 70.Xr hastd 8 71daemon. 72.Pp 73This utility should be used by HA software like 74.Nm heartbeat 75or 76.Nm ucarp 77to setup HAST resources role when changing from primary mode to 78secondary or vice versa. 79Be aware that if a file system like UFS exists on HAST provider and 80primary node dies, file system has to be checked for inconsistencies 81with the 82.Xr fsck 8 83utility after switching secondary node to primary role. 84.Pp 85The first argument to 86.Nm 87indicates an action to be performed: 88.Bl -tag -width ".Cm create" 89.It Cm create 90Initialize local provider configured for the given resource. 91Additional options include: 92.Bl -tag -width ".Fl e Ar extentsize" 93.It Fl e Ar extentsize 94Size of an extent. 95Extent is a block which is used for synchronization. 96.Xr hastd 8 97maintains a map of dirty extents and extent is the smallest region that 98can be marked as dirty. 99If any part of an extent is modified, entire extent will be synchronized 100when nodes connect. 101If extent size is too small, there will be too much disk activity 102related to dirty map updates, which will degrade performance of the 103given resource. 104If extent size is too large, synchronization, even in case of short 105outage, can take a long time increasing the risk of losing up-to-date 106node before synchronization process is completed. 107The default extent size is 108.Va 2MB . 109.It Fl k Ar keepdirty 110Maximum number of dirty extents to keep dirty all the time. 111Most recently used extents are kept dirty to reduce number of metadata 112updates. 113The default number of most recently used extents which will be kept 114dirty is 115.Va 64 . 116.It Fl m Ar mediasize 117Size of the smaller provider used as backend storage on both nodes. 118This option can be omitted if node providers have the same size on both 119sides. 120.El 121.Pp 122If size is suffixed with a k, M, G or T, it is taken as a kilobyte, 123megabyte, gigabyte or terabyte measurement respectively. 124.It Cm role 125Change role of the given resource. 126The role can be one of: 127.Bl -tag -width ".Cm secondary" 128.It Cm init 129Resource is turned off. 130.It Cm primary 131Local 132.Xr hastd 8 133daemon will act as primary node for the given resource. 134System on which resource role is set to primary can use 135.Pa /dev/hast/<name> 136GEOM provider. 137.It Cm secondary 138Local 139.Xr hastd 8 140daemon will act as secondary node for the given resource - it will wait 141for connection from the primary node and will handle I/O requests 142received from it. 143GEOM provider 144.Pa /dev/hast/<name> 145will not be created on secondary node. 146.El 147.It Cm list 148Present verbose status of the configured resources. 149.It Cm status 150Present terse (and more easy machine-parseable) status of the configured 151resources. 152.It Cm dump 153Dump metadata stored on local component for the configured resources. 154.El 155.Pp 156In addition, every subcommand can be followed by the following options: 157.Bl -tag -width ".Fl c Ar config" 158.It Fl c Ar config 159Specify alternative location of the configuration file. 160The default location is 161.Pa /etc/hast.conf . 162.It Fl d 163Print debugging information. 164This option can be specified multiple times to raise the verbosity 165level. 166.El 167.Sh FILES 168.Bl -tag -width ".Pa /var/run/hastctl" -compact 169.It Pa /etc/hast.conf 170Configuration file for 171.Nm 172and 173.Xr hastd 8 . 174.It Pa /var/run/hastctl 175Control socket used by 176.Nm 177to communicate with the 178.Xr hastd 8 179daemon. 180.El 181.Sh EXIT STATUS 182Exit status is 0 on success, or one of the values described in 183.Xr sysexits 3 184on failure. 185.Sh EXAMPLES 186Initialize HAST provider, create file system on it and mount it. 187.Bd -literal -offset indent 188nodeB# hastctl create shared 189nodeB# hastd 190nodeB# hastctl role secondary shared 191 192nodeA# hastctl create shared 193nodeA# hastd 194nodeA# hastctl role primary shared 195nodeA# newfs -U /dev/hast/shared 196nodeA# mount -o noatime /dev/hast/shared /shared 197nodeA# application_start 198.Ed 199.Pp 200Switch roles for the 201.Nm shared 202HAST resource. 203.Bd -literal -offset indent 204nodeA# application_stop 205nodeA# umount -f /shared 206nodeA# hastctl role secondary shared 207 208nodeB# hastctl role primary shared 209nodeB# fsck -t ufs /dev/hast/shared 210nodeB# mount -o noatime /dev/hast/shared /shared 211nodeB# application_start 212.Ed 213.Sh SEE ALSO 214.Xr sysexits 3 , 215.Xr geom 4 , 216.Xr hast.conf 5 , 217.Xr fsck 8 , 218.Xr ggatec 8 , 219.Xr ggatel 8 , 220.Xr hastd 8 , 221.Xr mount 8 , 222.Xr newfs 8 223.Sh HISTORY 224The 225.Nm 226utility appeared in 227.Fx 8.1 . 228.Sh AUTHORS 229The 230.Nm 231was developed by 232.An Pawel Jakub Dawidek Aq Mt pjd@FreeBSD.org 233under sponsorship of the FreeBSD Foundation. 234