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