Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
GMIRROR(8)		  BSD System Manager's Manual		    GMIRROR(8)

     gmirror --	control	utility	for mirrored devices

     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 list
     gmirror status
     gmirror load
     gmirror unload

     The gmirror utility is used for mirror (RAID1) configurations.  After a
     mirror's creation,	all components are detected and	configured automati-
     cally.  All operations like failure detection, stale component detection,
     rebuild of	stale components, etc. are also	done automatically.  The
     gmirror utility uses on-disk metadata (stored in the provider's last sec-
     tor) 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 performed:

     label	 Create	a mirror.  The order of	components is important, be-
		 cause a component's priority is based on its position (start-
		 ing from 0).  The component with the biggest priority is used
		 by the	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.

		 Additional options include:

		 -b balance  Specifies balance algorithm to use, one of:

			     load	  Read from the	component with the
					  lowest load.

			     prefer	  Read from the	component with the
					  biggest priority.

			     round-robin  Use round-robin algorithm when
					  choosing component to	read.

			     split	  Split	read requests, which are big-
					  ger than or equal to slice size on N
					  pieces, where	N is the number	of ac-
					  tive components.

		 -h	     Hardcode providers' names in metadata.

		 -n	     Turn off autosynchronization of stale components.

		 -s slice    When using	the 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 compo-

     clear	 Clear metadata	on the given providers.

     configure	 Configure the given device.

		 Additional options include:

		 -a	     Turn on autosynchronization of stale components.

		 -b balance  Specifies balance algorithm to use.

		 -d	     Do	not hardcode providers'	names in metadata.

		 -h	     Hardcode providers' names in metadata.

		 -n	     Turn off autosynchronization of stale components.

		 -s slice    Specifies slice size for split balance algorithm.

     rebuild	 Rebuild the given mirror components forcibly.	If autosyn-
		 chronization 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 inactive immediately	after

		 -p priority  Specifies	priority of the	given component(s).

     remove	 Remove	the given component(s) from the	mirror and clear meta-
		 data on it.

     activate	 Activate the given component(s), which	were marked as inac-
		 tive 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 connected.  This	com-
		 mand is useful	when a disk has	failed and cannot be recon-
		 nected, preventing the	remove command from being used to re-
		 move it.

     stop	 Stop the given	mirror.

		 Additional options include:

		 -f  Stop the given mirror even	if it is opened.

     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 is 0 on success, and 1	if the command fails.

     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:

	   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.  Add another disk	to this	mir-
     ror, 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

     geom(4), geom(8), mount(8), newfs(8), umount(8), vinum(8)

     The gmirror utility appeared in FreeBSD 5.3.

     Pawel Jakub Dawidek <>

     There should be a way to change a component's priority inside a running

     There should be a section with an implementation description.

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

BSD				 July 9, 2004				   BSD


Want to link to this manual page? Use this URL:

home | help