sbin/hastd/hastd.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 February 1, 2010
  31 .Dt HASTD 8
  32 .Os
  33 .Sh NAME
  34 .Nm hastd
  35 .Nd "Highly Available Storage daemon"
  36 .Sh SYNOPSIS
  37 .Nm
  38 .Op Fl dFh
  39 .Op Fl c Ar config
  40 .Op Fl P Ar pidfile
  41 .Sh DESCRIPTION
  42 The
  43 .Nm
  44 daemon is responsible for managing highly available GEOM providers.
  45 .Pp
  46 .Nm
  47 allows to transparently store data on two physically separated machines
  48 connected over the TCP/IP network.
  49 Only one machine (cluster node) can actively use storage provided by
  50 .Nm .
  51 This machine is called primary.
  52 The
  53 .Nm
  54 daemon operates on block level, which makes it transparent for file
  55 systems and applications.
  56 .Pp
  57 There is one main
  58 .Nm
  59 daemon which starts new worker process as soon as a role for the given
  60 resource is changed to primary or as soon as a role for the given
  61 resource is changed to secondary and remote (primary) node will
  62 successfully connect to it.
  63 Every worker process gets a new process title (see
  64 .Xr setproctitle 3 ) ,
  65 which describes its role and resource it controls.
  66 The exact format is:
  67 .Bd -literal -offset indent
  68 hastd: <resource name> (<role>)
  69 .Ed
  70 .Pp
  71 When (and only when)
  72 .Nm
  73 operates in primary role for the given resource, corresponding
  74 .Pa /dev/hast/<name>
  75 disk-like device (GEOM provider) is created.
  76 File systems and applications can use this provider to send I/O
  77 requests to.
  78 Every write, delete and flush operation
  79 .Dv ( BIO_WRITE , BIO_DELETE , BIO_FLUSH )
  80 is send to local component and synchronously replicated
  81 to the remote (secondary) node if it is available.
  82 Read operations
  83 .Dv ( BIO_READ )
  84 are handled locally unless I/O error occurs or local version of the data
  85 is not up-to-date yet (synchronization is in progress).
  86 .Pp
  87 The
  88 .Nm
  89 daemon uses the GEOM Gate class to receive I/O requests from the
  90 in-kernel GEOM infrastructure.
  91 The
  92 .Nm geom_gate.ko
  93 module is loaded automatically if the kernel was not compiled with the
  94 following option:
  95 .Bd -ragged -offset indent
  96 .Cd "options GEOM_GATE"
  97 .Ed
  98 .Pp
  99 The connection between two
 100 .Nm
 101 daemons is always initiated from the one running as primary to the one
 102 running as secondary.
 103 When primary
 104 .Nm
 105 is unable to connect or connection fails, it will try to re-establish
 106 connection every few seconds.
 107 Once connection is established, primary
 108 .Nm
 109 will synchronize every extent that was modified during connection outage
 110 to the secondary
 111 .Nm .
 112 .Pp
 113 It is possible that in case of connection outage between the nodes
 114 .Nm
 115 primary role for the given resource will be configured on both nodes.
 116 This in turn leads to incompatible data modifications.
 117 Such condition is called split-brain and cannot be automatically
 118 resolved by the
 119 .Nm
 120 daemon as this will lead most likely to data corruption or lost of
 121 important changes.
 122 Even though it cannot be fixed by
 123 .Nm
 124 itself, it will be detected and further connection between independently
 125 modified nodes will not be possible.
 126 Once this situation is manually resolved by an administrator, resource
 127 on one of the nodes can be initialized (erasing local data), which makes
 128 connection to the remote node possible again.
 129 Connection of freshly initialized component will trigger full resource
 130 synchronization.
 131 .Pp
 132 The
 133 .Nm
 134 daemon itself never picks his role up automatically.
 135 The role has to be configured with the
 136 .Xr hastctl 8
 137 control utility by additional software like
 138 .Nm ucarp
 139 or
 140 .Nm heartbeat
 141 that can reliably manage role separation and switch secondary node to
 142 primary role in case of original primary failure.
 143 .Pp
 144 The
 145 .Nm
 146 daemon can be started with the following command line arguments:
 147 .Bl -tag -width ".Fl P Ar pidfile"
 148 .It Fl c Ar config
 149 Specify alternative location of the configuration file.
 150 The default location is
 151 .Pa /etc/hast.conf .
 152 .It Fl d
 153 Print or log debugging information.
 154 This option can be specified multiple times to raise the verbosity
 155 level.
 156 .It Fl F
 157 Start the
 158 .Nm
 159 daemon in the foreground.
 160 By default
 161 .Nm
 162 starts in the background.
 163 .It Fl h
 164 Print the
 165 .Nm
 166 usage message.
 167 .It Fl P Ar pidfile
 168 Specify alternative location of a file where main process PID will be
 169 stored.
 170 The default location is
 171 .Pa /var/run/hastd.pid .
 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 Launch
 179 .Nm
 180 on both nodes.
 181 Set role for resource
 182 .Nm shared
 183 to primary on
 184 .Nm nodeA
 185 and to secondary on
 186 .Nm nodeB .
 187 Create file system on
 188 .Pa /dev/hast/shared
 189 provider and mount it.
 190 .Bd -literal -offset indent
 191 nodeB# hastd
 192 nodeB# hastctl role secondary shared
 193
 194 nodeA# hastd
 195 nodeA# hastctl role primary shared
 196 nodeA# newfs -U /dev/hast/shared
 197 nodeA# mount -o noatime /dev/hast/shared /shared
 198 .Ed
 199 .Sh FILES
 200 .Bl -tag -width ".Pa /var/run/hastctl" -compact
 201 .It Pa /etc/hast.conf
 202 The configuration file for
 203 .Nm
 204 and
 205 .Xr hastctl 8 .
 206 .It Pa /var/run/hastctl
 207 Control socket used by the
 208 .Xr hastctl 8
 209 control utility to communicate with
 210 .Nm .
 211 .It Pa /var/run/hastd.pid
 212 The default location of the
 213 .Nm
 214 PID file.
 215 .El
 216 .Sh SEE ALSO
 217 .Xr sysexits 3 ,
 218 .Xr geom 4 ,
 219 .Xr hast.conf 5 ,
 220 .Xr ggatec 8 ,
 221 .Xr ggated 8 ,
 222 .Xr ggatel 8 ,
 223 .Xr hastctl 8 ,
 224 .Xr mount 8 ,
 225 .Xr newfs 8 ,
 226 .Xr g_bio 9 .
 227 .Sh AUTHORS
 228 The
 229 .Nm
 230 was developed by
 231 .An Pawel Jakub Dawidek Aq pjd@FreeBSD.org
 232 under sponsorship of the FreeBSD Foundation.