Add manual page for gmirror(8). --- class/mirror/Makefile Sat Jul 31 01:13:44 2004 +++ sbin/geom/class/mirror/Makefile Wed Aug 18 17:48:18 2004 @@ -1,10 +1,9 @@ -# $FreeBSD: src/sbin/geom/class/mirror/Makefile,v 1.1 2004/07/30 23:13:44 pjd Exp $ +# $FreeBSD: src/sbin/geom/class/mirror/Makefile,v 1.2 2004/08/18 15:48:18 pjd Exp $ .PATH: ${.CURDIR}/../../misc CLASS= mirror -NOMAN= notyet DPADD= ${LIBMD} LDADD= -lmd --- /dev/null Wed Sep 8 19:11:00 2004 +++ sbin/geom/class/mirror/gmirror.8 Wed Aug 18 18:38:16 2004 @@ -0,0 +1,292 @@ +.\" Copyright (c) 2004 Pawel Jakub Dawidek +.\" 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: src/sbin/geom/class/mirror/gmirror.8,v 1.3 2004/08/18 16:14:24 pjd Exp $ +.\" +.Dd Jul 9, 2004 +.Dt GMIRROR 8 +.Os +.Sh NAME +.Nm gmirror +.Nd "control utility for mirrored devices" +.Sh SYNOPSIS +.Nm +.Cm label +.Op Fl hnv +.Op Fl b Ar balance +.Op Fl s Ar slice +.Ar name +.Ar prov +.Op Ar prov Op Ar ... +.Nm +.Cm clear +.Op Fl v +.Ar prov +.Op Ar prov Op Ar ... +.Nm +.Cm configure +.Op Fl adhnv +.Op Fl b Ar balance +.Op Fl s Ar slice +.Ar name +.Nm +.Cm rebuild +.Op Fl v +.Ar name +.Ar prov +.Op Ar prov Op Ar ... +.Nm +.Cm insert +.Op Fl hipv +.Ar name +.Ar prov +.Op Ar prov Op Ar ... +.Nm +.Cm remove +.Op Fl v +.Ar name +.Ar prov +.Op Ar prov Op Ar ... +.Nm +.Cm activate +.Op Fl v +.Ar name +.Ar prov +.Op Ar prov Op Ar ... +.Nm +.Cm deactivate +.Op Fl v +.Ar name +.Ar prov +.Op Ar prov Op Ar ... +.Nm +.Cm forget +.Op Fl v +.Ar name +.Op Ar name Op Ar ... +.Nm +.Cm stop +.Op Fl fv +.Ar name +.Op Ar name Op Ar ... +.Nm +.Cm list +.Op Ar name Op Ar ... +.Nm +.Cm load +.Op Fl v +.Nm +.Cm unload +.Op Fl v +.Sh DESCRIPTION +The +.Nm +utility is used for mirrors (RAID1) configuration. +After a mirror creation, all components are detected and configured +automatically. +All operations like failure detection, stale components detection, rebuild +of stale components etc.\& are done automatically as well. +The +.Nm +utility uses on-disk metadata (the last provider's 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. +Components order is important, because priority is based on its position +(starting from 0). +Component with the biggest priority is used by prefer balance algorithm +and also is used as a master component when resynchronization is needed +after, e.g. a power failure if 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 "round-robin" +.It load +Read from the component with the lowest load. +.It prefer +Read from the component with the biggest priority. +.It round-robin +Use round-robin algorithm when choosing component to read. +.It 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 h +Hardcode providers' names in metadata. +.It Fl n +Turn off autosynchronization of stale components. +.It Fl s Ar slice +When using +.Nm split +balance algorithm and I/O READ request is bigger than or equal to this value, +I/O request will be split into N pieces, where N is the number of active +component. +.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 b Ar balance" +.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 h +Hardcode providers' names in metadata. +.It Fl n +Turn off autosynchronization of stale components. +.It Fl s Ar slice +Specifies slice size for +.Nm split +balance algorithm. +.El +.It Cm rebuild +Rebuild the given mirror components forcibly. +If autosynchronization wasn't turn off for the given device, this command +hopefully will not be used. +.It Cm insert +Add the given component(s) to the existing mirror. +.Pp +Additional options include: +.Bl -tag -width ".Fl h" +.It Fl h +Hardcode providers' names in metadata. +.It Fl i +Mark component(s) as inacitve immediatelly after insertion. +.It Fl p +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 forget +Forget about components which are not connected. +This command is useful when disk failed and can't be reconnected, so +.Cm remove +command can't be 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 list +List every currently configured devices, if a list of devices is passed as a +parameter then only those devices will be shown. +.It Cm load +Load +.Pa geom_mirror.ko +kernel module. +.It Cm unload +Unload +.Pa geom_mirror.ko +kernel module. +.El +.Pp +Additional options include: +.Bl -tag -width ".Fl v" +.It Fl v +Be more verbose. +.El +.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. 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 sunchronization 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 (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 DIAGNOSTICS +Exit status is 0 on success, and 1 if the command fails. +.Sh SEE ALSO +.Xr geom 4 , +.Xr geom 8 , +.Xr mount 8 , +.Xr newfs 8 , +.Xr umount 8 , +.Xr vinum 8 +.Sh HISTORY +The +.Nm +utility appeared in +.Fx 5.3 . +.Sh AUTHORS +.An Pawel Jakub Dawidek Aq pjd@FreeBSD.org +.Sh BUGS +There should be a way to change component's priority inside a running mirror.