388 lines
9.7 KiB
Groff
388 lines
9.7 KiB
Groff
.\" Copyright (c) 2004-2009 Pawel Jakub Dawidek <pjd@FreeBSD.org>
|
|
.\" All rights reserved.
|
|
.\"
|
|
.\" 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 December 27, 2013
|
|
.Dt GMIRROR 8
|
|
.Os
|
|
.Sh NAME
|
|
.Nm gmirror
|
|
.Nd "control utility for mirrored devices"
|
|
.Sh SYNOPSIS
|
|
.Nm
|
|
.Cm label
|
|
.Op Fl Fhnv
|
|
.Op Fl b Ar balance
|
|
.Op Fl s Ar slice
|
|
.Ar name
|
|
.Ar prov ...
|
|
.Nm
|
|
.Cm clear
|
|
.Op Fl v
|
|
.Ar prov ...
|
|
.Nm
|
|
.Cm configure
|
|
.Op Fl adfFhnv
|
|
.Op Fl b Ar balance
|
|
.Op Fl s Ar slice
|
|
.Ar name
|
|
.Nm
|
|
.Cm configure
|
|
.Op Fl v
|
|
.Fl p Ar priority
|
|
.Ar name
|
|
.Ar prov
|
|
.Nm
|
|
.Cm rebuild
|
|
.Op Fl v
|
|
.Ar name
|
|
.Ar prov ...
|
|
.Nm
|
|
.Cm resize
|
|
.Op Fl v
|
|
.Op Fl s Ar size
|
|
.Ar name
|
|
.Nm
|
|
.Cm insert
|
|
.Op Fl hiv
|
|
.Op Fl p Ar priority
|
|
.Ar name
|
|
.Ar prov ...
|
|
.Nm
|
|
.Cm remove
|
|
.Op Fl v
|
|
.Ar name
|
|
.Ar prov ...
|
|
.Nm
|
|
.Cm activate
|
|
.Op Fl v
|
|
.Ar name
|
|
.Ar prov ...
|
|
.Nm
|
|
.Cm deactivate
|
|
.Op Fl v
|
|
.Ar name
|
|
.Ar prov ...
|
|
.Nm
|
|
.Cm destroy
|
|
.Op Fl fv
|
|
.Ar name ...
|
|
.Nm
|
|
.Cm forget
|
|
.Op Fl v
|
|
.Ar name ...
|
|
.Nm
|
|
.Cm stop
|
|
.Op Fl fv
|
|
.Ar name ...
|
|
.Nm
|
|
.Cm dump
|
|
.Ar prov ...
|
|
.Nm
|
|
.Cm list
|
|
.Nm
|
|
.Cm status
|
|
.Nm
|
|
.Cm load
|
|
.Nm
|
|
.Cm unload
|
|
.Sh DESCRIPTION
|
|
The
|
|
.Nm
|
|
utility is used for mirror (RAID1) configurations.
|
|
After a mirror's creation, all components are detected and configured
|
|
automatically.
|
|
All operations like failure detection, stale component detection, rebuild
|
|
of stale components, etc.\& are also done automatically.
|
|
The
|
|
.Nm
|
|
utility uses on-disk metadata (stored in the provider's last sector) to store all needed
|
|
information.
|
|
Since the last sector is used for this purpose, it is possible to place a root
|
|
file system on a mirror.
|
|
.Pp
|
|
The first argument to
|
|
.Nm
|
|
indicates an action to be performed:
|
|
.Bl -tag -width ".Cm deactivate"
|
|
.It Cm label
|
|
Create a mirror.
|
|
The order of components is important, because a component's priority is based on its position
|
|
(starting from 0 to 255).
|
|
The component with the biggest priority is used by the
|
|
.Cm prefer
|
|
balance algorithm
|
|
and is also used as a master component when resynchronization is needed,
|
|
e.g.\& after a power failure when the device was open for writing.
|
|
.Pp
|
|
Additional options include:
|
|
.Bl -tag -width ".Fl b Ar balance"
|
|
.It Fl b Ar balance
|
|
Specifies balance algorithm to use, one of:
|
|
.Bl -tag -width ".Cm round-robin"
|
|
.It Cm load
|
|
Read from the component with the lowest load.
|
|
This is the default balance algorithm.
|
|
.It Cm prefer
|
|
Read from the component with the biggest priority.
|
|
.It Cm round-robin
|
|
Use round-robin algorithm when choosing component to read.
|
|
.It Cm split
|
|
Split read requests, which are bigger than or equal to slice size on N pieces,
|
|
where N is the number of active components.
|
|
.El
|
|
.It Fl F
|
|
Do not synchronize after a power failure or system crash.
|
|
Assumes device is in consistent state.
|
|
.It Fl h
|
|
Hardcode providers' names in metadata.
|
|
.It Fl n
|
|
Turn off autosynchronization of stale components.
|
|
.It Fl s Ar slice
|
|
When using the
|
|
.Cm split
|
|
balance algorithm and an I/O READ request is bigger than or equal to this value,
|
|
the I/O request will be split into N pieces, where N is the number of active
|
|
components.
|
|
Defaults to 4096 bytes.
|
|
.El
|
|
.It Cm clear
|
|
Clear metadata on the given providers.
|
|
.It Cm configure
|
|
Configure the given device.
|
|
.Pp
|
|
Additional options include:
|
|
.Bl -tag -width ".Fl p Ar priority"
|
|
.It Fl a
|
|
Turn on autosynchronization of stale components.
|
|
.It Fl b Ar balance
|
|
Specifies balance algorithm to use.
|
|
.It Fl d
|
|
Do not hardcode providers' names in metadata.
|
|
.It Fl f
|
|
Synchronize device after a power failure or system crash.
|
|
.It Fl F
|
|
Do not synchronize after a power failure or system crash.
|
|
Assumes device is in consistent state.
|
|
.It Fl h
|
|
Hardcode providers' names in metadata.
|
|
.It Fl n
|
|
Turn off autosynchronization of stale components.
|
|
.It Fl p Ar priority
|
|
Specifies priority for the given component
|
|
.Ar prov .
|
|
.It Fl s Ar slice
|
|
Specifies slice size for
|
|
.Cm split
|
|
balance algorithm.
|
|
.El
|
|
.It Cm rebuild
|
|
Rebuild the given mirror components forcibly.
|
|
If autosynchronization was not turned off for the given device, this command
|
|
should be unnecessary.
|
|
.It Cm resize
|
|
Change the size of the given mirror.
|
|
.Pp
|
|
Additional options include:
|
|
.Bl -tag -width ".Fl s Ar size"
|
|
.It Fl s Ar size
|
|
New size of the mirror is expressed in logical block numbers.
|
|
This option can be omitted, then it will be automatically calculated to
|
|
maximum available size.
|
|
.El
|
|
.It Cm insert
|
|
Add the given component(s) to the existing mirror.
|
|
.Pp
|
|
Additional options include:
|
|
.Bl -tag -width ".Fl p Ar priority"
|
|
.It Fl h
|
|
Hardcode providers' names in metadata.
|
|
.It Fl i
|
|
Mark component(s) as inactive immediately after insertion.
|
|
.It Fl p Ar priority
|
|
Specifies priority of the given component(s).
|
|
.El
|
|
.It Cm remove
|
|
Remove the given component(s) from the mirror and clear metadata on it.
|
|
.It Cm activate
|
|
Activate the given component(s), which were marked as inactive before.
|
|
.It Cm deactivate
|
|
Mark the given component(s) as inactive, so it will not be automatically
|
|
connected to the mirror.
|
|
.It Cm destroy
|
|
Stop the given mirror and clear metadata on all its components.
|
|
.Pp
|
|
Additional options include:
|
|
.Bl -tag -width ".Fl f"
|
|
.It Fl f
|
|
Stop the given mirror even if it is opened.
|
|
.El
|
|
.It Cm forget
|
|
Forget about components which are not connected.
|
|
This command is useful when a disk has failed and cannot be reconnected, preventing the
|
|
.Cm remove
|
|
command from being used to remove it.
|
|
.It Cm stop
|
|
Stop the given mirror.
|
|
.Pp
|
|
Additional options include:
|
|
.Bl -tag -width ".Fl f"
|
|
.It Fl f
|
|
Stop the given mirror even if it is opened.
|
|
.El
|
|
.It Cm dump
|
|
Dump metadata stored on the given providers.
|
|
.It Cm list
|
|
See
|
|
.Xr geom 8 .
|
|
.It Cm status
|
|
See
|
|
.Xr geom 8 .
|
|
.It Cm load
|
|
See
|
|
.Xr geom 8 .
|
|
.It Cm unload
|
|
See
|
|
.Xr geom 8 .
|
|
.El
|
|
.Pp
|
|
Additional options include:
|
|
.Bl -tag -width ".Fl v"
|
|
.It Fl v
|
|
Be more verbose.
|
|
.El
|
|
.Sh EXIT STATUS
|
|
Exit status is 0 on success, and 1 if the command fails.
|
|
.Sh EXAMPLES
|
|
Use 3 disks to setup a mirror.
|
|
Choose split balance algorithm, split only
|
|
requests which are bigger than or equal to 2kB.
|
|
Create file system,
|
|
mount it, then unmount it and stop device:
|
|
.Bd -literal -offset indent
|
|
gmirror label -v -b split -s 2048 data da0 da1 da2
|
|
newfs /dev/mirror/data
|
|
mount /dev/mirror/data /mnt
|
|
\&...
|
|
umount /mnt
|
|
gmirror stop data
|
|
gmirror unload
|
|
.Ed
|
|
.Pp
|
|
Create a mirror on disk with valid data (note that the last sector of the disk
|
|
will be overwritten).
|
|
Add another disk to this mirror,
|
|
so it will be synchronized with existing disk:
|
|
.Bd -literal -offset indent
|
|
gmirror label -v -b round-robin data da0
|
|
gmirror insert data da1
|
|
.Ed
|
|
.Pp
|
|
Create a mirror, but do not use automatic synchronization feature.
|
|
Add another disk and rebuild it:
|
|
.Bd -literal -offset indent
|
|
gmirror label -v -n -b load data da0 da1
|
|
gmirror insert data da2
|
|
gmirror rebuild data da2
|
|
.Ed
|
|
.Pp
|
|
One disk failed.
|
|
Replace it with a brand new one:
|
|
.Bd -literal -offset indent
|
|
gmirror forget data
|
|
gmirror insert data da1
|
|
.Ed
|
|
.Pp
|
|
Create a mirror, deactivate one component, do the backup and connect it again.
|
|
It will not be resynchronized, if there is no need to do so (there were no writes in
|
|
the meantime):
|
|
.Bd -literal -offset indent
|
|
gmirror label data da0 da1
|
|
gmirror deactivate data da1
|
|
dd if=/dev/da1 of=/backup/data.img bs=1m
|
|
gmirror activate data da1
|
|
.Ed
|
|
.Sh NOTES
|
|
Doing kernel dumps to
|
|
.Nm
|
|
providers is possible, but some conditions have to be met.
|
|
First of all, a kernel dump will go only to one component and
|
|
.Nm
|
|
always chooses the component with the highest priority.
|
|
Reading a dump from the mirror on boot will only work if the
|
|
.Cm prefer
|
|
balance algorithm is used (that way
|
|
.Nm
|
|
will read only from the component with the highest priority).
|
|
If you use a different balance algorithm, you should add:
|
|
.Bd -literal -offset indent
|
|
gmirror configure -b prefer data
|
|
.Ed
|
|
.Pp
|
|
to the
|
|
.Pa /etc/rc.early
|
|
script and:
|
|
.Bd -literal -offset indent
|
|
gmirror configure -b round-robin data
|
|
.Ed
|
|
.Pp
|
|
to the
|
|
.Pa /etc/rc.local
|
|
script.
|
|
The decision which component to choose for dumping is made when
|
|
.Xr dumpon 8
|
|
is called.
|
|
If on the next boot a component with a higher priority will be available,
|
|
the prefer algorithm will choose to read from it and
|
|
.Xr savecore 8
|
|
will find nothing.
|
|
If on the next boot a component with the highest priority will be synchronized,
|
|
the prefer balance algorithm will read from the next one, thus will find nothing
|
|
there.
|
|
.Sh SEE ALSO
|
|
.Xr geom 4 ,
|
|
.Xr dumpon 8 ,
|
|
.Xr geom 8 ,
|
|
.Xr gvinum 8 ,
|
|
.Xr mount 8 ,
|
|
.Xr newfs 8 ,
|
|
.Xr savecore 8 ,
|
|
.Xr umount 8
|
|
.Sh HISTORY
|
|
The
|
|
.Nm
|
|
utility appeared in
|
|
.Fx 5.3 .
|
|
.Sh AUTHORS
|
|
.An Pawel Jakub Dawidek Aq Mt pjd@FreeBSD.org
|
|
.Sh BUGS
|
|
There should be a way to change a component's priority inside a running mirror.
|
|
.Pp
|
|
There should be a section with an implementation description.
|
|
.Pp
|
|
Documentation for sysctls
|
|
.Va kern.geom.mirror.*
|
|
is missing.
|