1c1e2e8b71
HAST allows to transparently store data on two physically separated machines connected over the TCP/IP network. HAST works in Primary-Secondary (Master-Backup, Master-Slave) configuration, which means that only one of the cluster nodes can be active at any given time. Only Primary node is able to handle I/O requests to HAST-managed devices. Currently HAST is limited to two cluster nodes in total. HAST operates on block level - it provides disk-like devices in /dev/hast/ directory for use by file systems and/or applications. Working on block level makes it transparent for file systems and applications. There in no difference between using HAST-provided device and raw disk, partition, etc. All of them are just regular GEOM providers in FreeBSD. For more information please consult hastd(8), hastctl(8) and hast.conf(5) manual pages, as well as http://wiki.FreeBSD.org/HAST. Sponsored by: FreeBSD Foundation Sponsored by: OMCnet Internet Service GmbH Sponsored by: TransIP BV
268 lines
6.9 KiB
Groff
268 lines
6.9 KiB
Groff
.\" Copyright (c) 2010 The FreeBSD Foundation
|
|
.\" All rights reserved.
|
|
.\"
|
|
.\" This software was developed by Pawel Jakub Dawidek under sponsorship from
|
|
.\" the FreeBSD Foundation.
|
|
.\"
|
|
.\" Redistribution and use in source and binary forms, with or without
|
|
.\" modification, are permitted provided that the following conditions
|
|
.\" are met:
|
|
.\" 1. Redistributions of source code must retain the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer.
|
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer in the
|
|
.\" documentation and/or other materials provided with the distribution.
|
|
.\"
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS IS'' AND
|
|
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
|
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
|
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE
|
|
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
|
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
|
|
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
|
|
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
|
|
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
|
|
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
|
|
.\" SUCH DAMAGE.
|
|
.\"
|
|
.\" $FreeBSD$
|
|
.\"
|
|
.Dd February 1, 2010
|
|
.Dt HAST.CONF 5
|
|
.Os
|
|
.Sh NAME
|
|
.Nm hast.conf
|
|
.Nd configuration file for the
|
|
.Xr hastd 8
|
|
deamon and the
|
|
.Xr hastctl 8
|
|
utility.
|
|
.Sh DESCRIPTION
|
|
The
|
|
.Nm
|
|
file is used by both
|
|
.Xr hastd 8
|
|
daemon
|
|
and
|
|
.Xr hastctl 8
|
|
control utility.
|
|
Configuration file is designed in a way that exactly the same file can be
|
|
(and should be) used on both HAST nodes.
|
|
Every line starting with # is treated as comment and ignored.
|
|
.Sh CONFIGURATION FILE SYNTAX
|
|
General syntax of the
|
|
.Nm
|
|
file is following:
|
|
.Bd -literal -offset indent
|
|
# Global section
|
|
control <addr>
|
|
listen <addr>
|
|
replication <mode>
|
|
|
|
on <node> {
|
|
# Node section
|
|
control <addr>
|
|
listen <addr>
|
|
}
|
|
|
|
on <node> {
|
|
# Node section
|
|
control <addr>
|
|
listen <addr>
|
|
}
|
|
|
|
resource <name> {
|
|
# Resource section
|
|
replication <mode>
|
|
name <name>
|
|
local <path>
|
|
|
|
on <node> {
|
|
# Resource-node section
|
|
name <name>
|
|
# Required
|
|
local <path>
|
|
# Required
|
|
remote <addr>
|
|
}
|
|
on <node> {
|
|
# Resource-node section
|
|
name <name>
|
|
# Required
|
|
local <path>
|
|
# Required
|
|
remote <addr>
|
|
}
|
|
}
|
|
.Ed
|
|
.Pp
|
|
Most of the various available configuration parameters are optional.
|
|
If parameter is not defined in the particular section, it will be
|
|
inherited from the parent section.
|
|
For example, if the
|
|
.Ic listen
|
|
parameter is not defined in the node section, it will be inherited from
|
|
the global section.
|
|
In case the global section does not define the
|
|
.Ic listen
|
|
parameter at all, the default value will be used.
|
|
.Sh CONFIGURATION FILE DESCRIPTION
|
|
The
|
|
.Aq node
|
|
argument can be replaced either by a full hostname as obtained by
|
|
.Xr gethostname 3 ,
|
|
only first part of the hostname, or by node's UUID as found in the
|
|
.Va kern.hostuuid
|
|
.Xr sysctl 8
|
|
variable.
|
|
.Pp
|
|
The following statements are available:
|
|
.Bl -tag -width ".Ic xxxx"
|
|
.It Ic control Aq addr
|
|
.Pp
|
|
Address for communication with
|
|
.Xr hastctl 8 .
|
|
Each of the following examples defines the same control address:
|
|
.Bd -literal -offset indent
|
|
uds:///var/run/hastctl
|
|
unix:///var/run/hastctl
|
|
/var/run/hastctl
|
|
.Ed
|
|
.Pp
|
|
The default value is
|
|
.Pa uds:///var/run/hastctl .
|
|
.It Ic listen Aq addr
|
|
.Pp
|
|
Address to listen on in form of:
|
|
.Bd -literal -offset indent
|
|
protocol://protocol-specific-address
|
|
.Ed
|
|
.Pp
|
|
Each of the following examples defines the same listen address:
|
|
.Bd -literal -offset indent
|
|
0.0.0.0
|
|
0.0.0.0:8457
|
|
tcp://0.0.0.0
|
|
tcp://0.0.0.0:8457
|
|
tcp4://0.0.0.0
|
|
tcp4://0.0.0.0:8457
|
|
.Ed
|
|
.Pp
|
|
The default value is
|
|
.Pa tcp4://0.0.0.0:8457 .
|
|
.It Ic replication Aq mode
|
|
.Pp
|
|
Replication mode should be one of the following:
|
|
.Bl -tag -width ".Ic xxxx"
|
|
.It Ic memsync
|
|
.Pp
|
|
Report the write operation as completed when local write completes and
|
|
when the remote node acknowledges the data receipt, but before it
|
|
actually stores the data.
|
|
The data on remote node will be stored directly after sending
|
|
acknowledgement.
|
|
This mode is intended to reduce latency, but still provides a very good
|
|
reliability.
|
|
The only situation where some small amount of data could be lost is when
|
|
the data is stored on primary node and sent to the secondary.
|
|
Secondary node then acknowledges data receipt and primary reports
|
|
success to an application.
|
|
However, it may happen that the seconderay goes down before the received
|
|
data is really stored locally.
|
|
Before secondary node returns, primary node dies entirely.
|
|
When the secondary node comes back to life it becomes the new primary.
|
|
Unfortunately some small amount of data which was confirmed to be stored
|
|
to the application was lost.
|
|
The risk of such a situation is very small, which is the reason for this
|
|
mode to be the default.
|
|
.It Ic fullsync
|
|
.Pp
|
|
Mark the write operation as completed when local as well as remote
|
|
write completes.
|
|
This is the safest and the slowest replication mode.
|
|
The
|
|
.Ic fullsync
|
|
replication mode is currently not implemented.
|
|
.It Ic async
|
|
.Pp
|
|
The write operation is reported as complete right after the local write
|
|
completes.
|
|
This is the fastest and the most dangerous replication mode.
|
|
This mode should be used when replicating to a distant node where
|
|
latency is too high for other modes.
|
|
The
|
|
.Ic async
|
|
replication mode is currently not implemented.
|
|
.El
|
|
.It Ic name Aq name
|
|
.Pp
|
|
GEOM provider name that will appear as
|
|
.Pa /dev/hast/<name> .
|
|
If name is not defined, resource name will be used as provider name.
|
|
.It Ic local Aq path
|
|
.Pp
|
|
Path to the local component which will be used as backend provider for
|
|
the resource.
|
|
This can be either GEOM provider or regular file.
|
|
.It Ic remote Aq addr
|
|
.Pp
|
|
Address of the remote
|
|
.Nm hastd
|
|
daemon.
|
|
Format is the same as for the
|
|
.Ic listen
|
|
statement.
|
|
When operating as a primary node this address will be used to connect to
|
|
the secondary node.
|
|
When operating as a secondary node only connections from this address
|
|
will be accepted.
|
|
.El
|
|
.Sh EXAMPLES
|
|
The example configuration file can look as follows:
|
|
.Bd -literal -offset indent
|
|
resource shared {
|
|
local /dev/da0
|
|
|
|
on hasta {
|
|
remote tcp4://10.0.0.2
|
|
}
|
|
on hastb {
|
|
remote tcp4://10.0.0.1
|
|
}
|
|
}
|
|
resource tank {
|
|
on hasta {
|
|
local /dev/mirror/tanka
|
|
remote tcp4://10.0.0.2
|
|
}
|
|
on hastb {
|
|
local /dev/mirror/tankb
|
|
remote tcp4://10.0.0.1
|
|
}
|
|
}
|
|
.Ed
|
|
.Sh FILES
|
|
.Bl -tag -width ".Pa /var/run/hastctl" -compact
|
|
.It Pa /etc/hast.conf
|
|
The default
|
|
.Nm
|
|
configuration file.
|
|
.It Pa /var/run/hastctl
|
|
Control socket used by the
|
|
.Xr hastctl 8
|
|
control utility to communicate with the
|
|
.Xr hastd 8
|
|
daemon.
|
|
.El
|
|
.Sh SEE ALSO
|
|
.Xr gethostname 3 ,
|
|
.Xr geom 4 ,
|
|
.Xr hastctl 8 ,
|
|
.Xr hastd 8 .
|
|
.Sh AUTHORS
|
|
The
|
|
.Nm
|
|
was written by
|
|
.An Pawel Jakub Dawidek Aq pjd@FreeBSD.org
|
|
under sponsorship of the FreeBSD Foundation.
|