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

NAME
     gmirror -- control utility for mirrored devices

SYNOPSIS
     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]

DESCRIPTION
     The  gmirror  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 gmirror util-
     ity 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 possi-
     ble 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 prior-
		 ity 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 writ-
		 ing.

		 Additional options include:

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

			     load	  Read from the component with the  low-
					  est load.

			     prefer	  Read	 from  the  component  with  the
					  biggest priority.

			     round-robin  Use round-robin algorithm when  choos-
					  ing 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 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 re-
			     quest 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 autosynchro-
		 nization wasn't turn off for the  given  device,  this  command
		 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
			      insertion.

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

     deactivate  Mark the given component(s) as inactive, so it will not be  au-
		 tomatically connected to the mirror.

     forget	 Forget  about components which are not connected.  This command
		 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 shown.

     load	 Load geom_mirror.ko kernel module.

     unload	 Unload geom_mirror.ko kernel module.

     Additional options include:

     -v  Be more verbose.

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:

	   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 an-
     other 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

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

	   swapoff="YES"

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

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

SEE ALSO
     geom(4), geom(8), mount(8), newfs(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 component's priority inside a running  mir-
     ror.

     There should be a section with implementation description.

FreeBSD 5.3			   Jul 9, 2004			      GMIRROR(8)

home | help