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 [prov [...]]
     gmirror clear [-v]	prov [prov [...]]
     gmirror configure [-adhnv]	[-b balance] [-s slice]	name
     gmirror rebuild [-v] name prov [prov [...]]
     gmirror insert [-hiv] [-p priority] name prov [prov [...]]
     gmirror remove [-v] name prov [prov [...]]
     gmirror activate [-v] name	prov [prov [...]]
     gmirror deactivate	[-v] name prov [prov [...]]
     gmirror forget [-v] name [name [...]]
     gmirror stop [-fv]	name [name [...]]
     gmirror list [name	[...]]
     gmirror load [-v]
     gmirror unload [-v]

     The gmirror utility is used for mirrors (RAID1) configuration.  After a
     mirror creation, all components are detected and configured automati-
     cally.  All operations like failure detection, stale components detec-
     tion, rebuild of stale components etc. are	done automatically as well.
     The gmirror 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.

     The first argument	to gmirror indicates an	action to be performed:

     label	 Create	a mirror.  Components order is important, because pri-
		 ority 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

		 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	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.

     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 wasn't turn off for the given device, this com-
		 mand hopefully	will not be used.

     insert	 Add the given component(s) to the existing mirror.

		 Additional options include:

		 -h	      Hardcode providers' names	in metadata.

		 -i	      Mark component(s)	as inacitve immediatelly 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 disk failed and can't be reconnected, so
		 remove	command	can't be used to remove	it.

     stop	 Stop the given	mirror.

		 Additional options include:

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

     list	 List every currently configured devices, if a list of devices
		 is passed as a	parameter then only those devices will be

     load	 Load geom_mirror.ko kernel module.

     unload	 Unload	geom_mirror.ko kernel module.

     Additional	options	include:

     -v	 Be more verbose.

     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 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 sunchronization 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 (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

     If	you are	using swap-on-mirror configuration be sure to put:


     into your /etc/rc.conf and	use shutdown(8)	command	to reboot/shutdown
     your system.

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

     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 component's priority inside a running

     There should be a section with implementation description.

BSD				  Jul 9, 2004				   BSD


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

home | help