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