Ok, let's try again:

Add manual page for gmirror(8) utility.

1 files changed, 290 insertions, 0 deletions

diff --git a/sbin/geom/class/mirror/gmirror.8 b/sbin/geom/class/mirror/gmirror.8
new file mode 100644
index 0000000..9774427
--- /dev/null
+++ b/sbin/geom/class/mirror/gmirror.8
@@ -0,0 +1,290 @@
+.\" Copyright (c) 2004 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 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.
+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.
+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 da3
+.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.