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