e4b0a90e77
Rather then combining hardlink creation for the geom(8) binary with shared library build, move libraries to src/lib/geom so they are built and installed normally. Create a common Makefile.classes which is included by both lib/geom/Makefile and sbin/geom/Makefile so the symlink and libraries stay in sync. The relocation of libraries allows libraries to be build for 32-bit compat. This also reduces the number of non-standard builds in the system. This commit is not sufficent to run a 32-bit /sbin/geom on a 64-bit system out of the box as it will look in the wrong place for libraries unless GEOM_LIBRARY_PATH is set appropriatly in the environment. Reviewed by: bdrewery Sponsored by: DARPA, AFRL Differential Revision: https://reviews.freebsd.org/D15360
437 lines
12 KiB
Groff
437 lines
12 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 November 30, 2017
|
|
.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 create
|
|
.Op Fl Fnv
|
|
.Op Fl b Ar balance
|
|
.Op Fl s Ar slice
|
|
.Ar name
|
|
.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 create
|
|
Similar to
|
|
.Cm label ,
|
|
but creates mirror without storing on-disk metadata in last sector.
|
|
This special "manual" operation mode assumes some external control to manage
|
|
mirror detection after reboot, device hot-plug and other external events.
|
|
.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 SYSCTL VARIABLES
|
|
The following
|
|
.Xr sysctl 8
|
|
variables can be used to configure behavior for all mirrors.
|
|
.Bl -tag -width indent
|
|
.It Va kern.geom.mirror.debug
|
|
Control the verbosity of kernel logging related to mirrors.
|
|
A value larger than 0 will enable debug logging.
|
|
.It Va kern.geom.mirror.timeout
|
|
The amount of time, in seconds, to wait for all copies of a mirror to
|
|
appear before starting the mirror.
|
|
Disks that appear after the mirror has been started are not automatically
|
|
added to the mirror.
|
|
.It Va kern.geom.mirror.idletime
|
|
The amount of time, in seconds, which must elapse after the last write to
|
|
a mirror before that mirror is marked clean.
|
|
Clean mirrors do not need to be synchronized after a power failure or
|
|
system crash.
|
|
A small value may result in frequent overwrites of the disks' metadata
|
|
sectors, and thus may reduce the longevity of the disks.
|
|
.It Va kern.geom.mirror.disconnect_on_failure
|
|
Determine whether a disk is automatically removed from its mirror when an
|
|
I/O request to that disk fails.
|
|
.It Va kern.geom.mirror.sync_requests
|
|
The number of parallel I/O requests used while synchronizing a mirror.
|
|
This parameter may only be configured as a
|
|
.Xr loader.conf 5
|
|
tunable.
|
|
.It Va kern.geom.mirror.sync_update_period
|
|
The period, in seconds, at which a synchronizing mirror's metadata is
|
|
updated.
|
|
Periodic updates are used to record a synchronization's progress so that
|
|
an interrupted synchronization may be resumed starting at the recorded
|
|
offset, rather than at the beginning.
|
|
A smaller value results in more accurate progress tracking, but also
|
|
increases the number of non-sequential writes to the disk being synchronized.
|
|
If the sysctl value is 0, no updates are performed until the synchronization
|
|
is complete.
|
|
.El
|
|
.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 sysctl 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.
|