gmirror(8)

NAME

gmirror - control utility for mirrored devices

SYNOPSIS

gmirror label [-hnv] [-b balance] [-s slice] name prov ...
gmirror clear [-v] prov ...
gmirror configure [-adhnv] [-b balance] [-s slice] name
gmirror rebuild [-v] name prov ...
gmirror insert [-hiv] [-p priority] name prov ...
gmirror remove [-v] name prov ...
gmirror activate [-v] name prov ...
gmirror deactivate [-v] name prov ...
gmirror forget [-v] name ...
gmirror stop [-fv] name ...
gmirror clear [-v] prov ...
gmirror dump prov ...
gmirror list
gmirror status
gmirror load
gmirror unload

DESCRIPTION

The gmirror utility is used for mirror (RAID1) configura

tions. After a
mirror's creation, all components are detected and config

ured automatically. All operations like failure detection, stale compo

nent detection,
rebuild of stale components, etc. are also done automatical

ly. The
gmirror 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.

The first argument to gmirror indicates an action to be per

formed:

label Create a mirror. The order of components is

important,

because a component's priority is based on

its position
(starting from 0). The component with the

biggest priority is used by the prefer balance algorithm

and is also
used as a master component when resynchro

nization is
needed, e.g. after a power failure when the

device was
open for writing.

Additional options include:

-b balance Specifies balance algo

rithm to use, one

of:

load Read from

the compo

nent with

the lowest
load.

prefer Read from

the compo

nent with

the biggest
priority.

round-robin Use

round-robin algo

rithm

when choosing
component

to read.

split Split

read requests,

which are

bigger than
or equal

to slice size
on N

pieces, where N
is the

number of
active

components.
This is

the default
balance

algorithm.

-h Hardcode providers' names

in metadata.

-n Turn off autosynchroniza

tion of stale

components.

-s slice When using the split bal

ance 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 com

ponents.
Defaults to 4096 bytes.

clear Clear metadata on the given providers.

configure Configure the given device.

Additional options include:

-a Turn on autosynchroniza

tion of stale

components.

-b balance Specifies balance algo

rithm to use.

-d Do not hardcode providers'

names in

metadata.

-h Hardcode providers' names

in metadata.

-n Turn off autosynchroniza

tion of stale

components.

-s slice Specifies slice size for

split balance

algorithm.

rebuild Rebuild the given mirror components

forcibly. If

autosynchronization was not turned off for

the given
device, this command should be unnecessary.

insert Add the given component(s) to the existing

mirror.

Additional options include:

-h Hardcode providers' names

in metadata.

-i Mark component(s) as in

active immedi

ately after insertion.

-p priority Specifies priority of the

given compo

nent(s).

remove Remove the given component(s) from the mir

ror and clear

metadata on it.

activate Activate the given component(s), which were

marked as

inactive before.

deactivate Mark the given component(s) as inactive, so

it will not

be automatically connected to the mirror.

forget Forget about components which are not con

nected. This

command is useful when a disk has failed and

cannot be
reconnected, preventing the remove command

from being
used to remove it.

stop Stop the given mirror.

Additional options include:

-f Stop the given mirror even if it is

opened.

dump Dump metadata stored on the given providers.

list See geom(8).

status See geom(8).

load See geom(8).

unload See geom(8).

Additional options include:

-v Be more verbose.

EXIT STATUS

Exit status is 0 on success, and 1 if the command fails.

EXAMPLES

Use 3 disks to setup a mirror. Choose split balance algo

rithm, split
only requests which are bigger than or equal to 2kB. Create

file system,
mount it, then unmount it and stop device:

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

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:

gmirror label -v -b round-robin data da0
gmirror insert data da1

Create a mirror, but do not use automatic synchronization

feature. Add
another disk and rebuild it:

gmirror label -v -n -b load data da0 da1
gmirror insert data da2
gmirror rebuild data da2

One disk failed. Replace it with a brand new one:

gmirror forget data
gmirror insert data da1

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):

gmirror label data da0 da1
gmirror deactivate data da1
dd if=/dev/da1 of=/backup/data.img bs=1m
gmirror activate data da1

NOTES

Doing kernel dumps to gmirror providers.

This is possible, but some conditions have to be met. First

of all, a
kernel dump will go only to one component and gmirror always

chooses the
component with the highest priority. Reading a dump from

the mirror on
boot will only work if the prefer balance algorithm is used

(that way
gmirror will read only from the component with the highest

priority). If
you use a different balance algorithm, you should add:

gmirror configure -b prefer data

to the /etc/rc.early script and:

gmirror configure -b round-robin data

to the /etc/rc.local script. The decision which component

to choose for
dumping is made when 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 savecore(8) will find nothing.

If on the next
boot a component with the highest priority will be synchro

nized, the prefer balance algorithm will read from the next one, thus will

find nothing
there.

SEE ALSO

geom(4), dumpon(8), geom(8), mount(8), newfs(8),

savecore(8), umount(8),
vinum(8)

HISTORY

The gmirror utility appeared in FreeBSD 5.3.

AUTHORS

Pawel Jakub Dawidek <pjd@FreeBSD.org>

BUGS

There should be a way to change a component's priority in

side a running
mirror.

There should be a section with an implementation descrip

tion.

Documentation for sysctls kern.geom.mirror.* is missing.

BSD March 8, 2006

BSD