sbin/hastctl/hastctl.8

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