unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (OSF1-V5.1-alpha)
Page:
Section:
Apropos / Subsearch:
optional field



voldg(8)							     voldg(8)



NAME

  voldg	- Manages Logical Storage Manager disk groups

SYNOPSIS

  /sbin/voldg init groupname {medianame=accessname} [nconfig=config-copies |
  all |	default] [minor=base-minor]

  /sbin/voldg [-g diskgroup] [-f] reminor [diskgroup] new-base-minor

  /sbin/voldg [-tfC] [-n newname] [-o shared | private]	[-o convert_old]
  import diskgroup

  /sbin/voldg [-n newname] [-h newhostid] deport diskgroup...

  /sbin/voldg [-g diskgroup] [-k] adddisk {medianame=accessname}

  /sbin/voldg [-g diskgroup] [-k] rmdisk {medianame...}

  /sbin/voldg [-q] list	[diskgroup...]

  /sbin/voldg [-g diskgroup] [-qa] free	[medianame...]

  /sbin/voldg [-g diskgroup] [-q] spare	[medianame...]

  /sbin/voldg flush [diskgroup...]

  /sbin/voldg [-g diskgroup] [-k] repldisk unassoc-medianame=spare-
  medianame...

OPTIONS

  -g diskgroup
      Specifies	the disk group for the operation, either by name or by disk
      group ID.	If no disk group is specified, the rootdg disk group is
      implied.

  -C  Clears the previous name of the specified	disk group.

  -f  Forces an	operation that the Logical Storage Manager (LSM) considers
      potentially dangerous or of questionable use. This permits a limited
      set of operations	that would otherwise be	disallowed.  Some operations
      might be disallowed even with this option.

  -k  Keeps (when used with rmdisk or repldisk)	or reapplies (when used	with
      adddisk) the previous LSM	disk media records for the named disk.	Typi-
      cally used when replacing	a failed disk to keep the LSM structure	of
      the affected volume or disk group	intact.	This option sets any plexes
      requiring	recovery to STALE.

  -h newhostid
      Assigns a	new host name to the disk group.

  -n newname
      Assigns a	new name to the	disk group.

  -o shared or -o private
      Used with	import.	 Converts the disk group's configuration databases
      and kernel change	logs as	appropriate for	the system on which the	disk
      group is being imported. When manually importing a disk group to a
      cluster from a standalone	system,	use -o shared. When manually import-
      ing a disk group to a standalone system from a cluster, use -o private.

  -o convert_old
      Used with	import to import disk groups deported before upgrading the
      LSM software from	pre-Version 5.0	to Version 5.0 or higher.  This
      option upgrades the disk group's metadata	to the current format and
      examines all volumes to determine	if they	use Block Change Logging
      (BCL). If	such volumes are found,	LSM displays a message instructing
      you to use the vollogcnvt	utility	to convert BCLs	to Dirty Region	Logs
      (DRLs). The disk group is	imported but logging is	disabled on volumes
      that use BCL. The	volume is usable and data continues to be written to
      all mirrors, but if a disk in the	volume fails or	the system crashes,
      the entire volume	will be	resynchronized to recover the data.

  -q  Suppresses headers in output fields. If used with	diskgroup, this
      option is	ignored.

  -a  Displays information about space on spare	disks (which is	not really
      allocatable) in addition to regular free space in	the disk group.	Nor-
      mally, spare disk	information is not displayed.

  -t  Performs the operation temporarily.

      When used	with import, the disk group will not be	reimported on reboot.
      Normally,	an imported disk group will be reimported automatically	when
      the system is rebooted, if at least some of the disks in the disk	group
      remain accessible	and usable. If you do not want the disk	group to be
      reimported when the system reboots, import it with the -t	option.

      Can be used with -n newname to temporarily assign	a new minor number or
      name to a	volume or disk group, respectively. When used with -n newname
      when importing a disk group, the disk group's stored name	is retained,
      but the disk group is known to the new host as newname.  This allows
      the disk group to	be reimported on the original host with	its former
      name.

KEYWORDS

  init
      Defines a	new disk group composed	of the disks identified	by disk
      access names. This operation assigns an internal unique ID to the
      group, stores a reference	to the group on	all of the named disks that
      have a disk header, and stores a disk group record in the	disk group's
      configuration database. At least one of the disks	specified must have
      space allocated for a configuration copy.

      If a medianame is	specified for use with a particular disk, that medi-
      aname will name the disk media record used to reference the disk within
      the disk group (for operations such as rmdisk and	subdisk	creations).
      If no medianame is specified, the	disk media name	defaults to
      accessname. See voldisk(8) for more information on defining and ini-
      tializing	disk access records.

      The init operation can be	used to	initialize a root disk group confi-
      guration,	which is identified by the special name	rootdg.	Disks should
      be initialized and added to the disk group right after rootdg is
      created.

      If the autoconfiguration functionality of	LSM is disabled, add the
      names of disks that have copies of the rootdg configuration database to
      the /etc/vol/volboot bootstrap file. See voldctl(8).

      The nconfig attribute can	be used	to specify the number of
      configuration database copies and	kernel log copies that are maintained
      for a disk group.

      The value	of config-copies can be	one of the following:

      default or 0 (the	default	value)
	      LSM maintains the	copies and their number	and distribution
	      throughout the disks and controllers in the disk group.

      all or -1
	      All configuration	and kernel log copies on all disks in the
	      disk group are maintained.

	      This policy places extra overhead	on the system, because every
	      copy of the configuration	database must be updated with every
	      configuration change.

      Positive integer
	      The specified number of copies is	maintained (or all copies, if
	      the number you specify is	larger than the	number of available
	      copies on	all disks).

      When a specific number (or default) is requested,	configuration copies
      are scattered approximately evenly through the disk controllers in the
      disk group. If SCSI disks	with multiple disks per	target are found,
      each such	target is treated similarly to a controller (that is, confi-
      guration copies are evenly distributed among such	targets). With the
      default policy, one configuration	and log	copy is	maintained for each
      controller, and one configuration	and log	copy is	also maintained	for
      each SCSI	target that has	multiple disks;	if this	does not result	in
      allocating at least four copies, additional copies are spread through
      the controllers and targets.


				       Note

	 If a policy other than	all is used, some disks	will not have up-to-
	 date, online configuration and	log copies. As a result, it is possi-
	 ble that some number of disk failures will leave a disk group unus-
	 able, even if some disks in the disk group remain usable. However,
	 the default policy allocates a	sufficient number of copies, in	a
	 sufficient spread of locations, so that such a	scenario is very
	 unlikely to occur. The	default	policy is the recommended policy.

      Refer to voldisk(8) for more information on configuration	and log
      copies and for information on how	to create them.

  minor=base-minor
      Because disk groups can be moved between systems,	LSM lets you allocate
      volume device numbers in separate	ranges for each	disk group.  That
      way, you can choose ranges such that all disk groups in a	group of
      machines can be moved without causing device number collisions. Colli-
      sions may	occur because LSM stores device	numbers	in disk	group confi-
      gurations, so that the same numbers can be used after a reboot (which
      is necessary for use with	NFS, which requires persistency	of device
      numbers).	If two systems use the same device numbers for a set of
      volumes, and if a	disk group from	one machine is moved to	the other,
      LSM can be forced	to temporarily remap some devices.

      A	base volume device minor number	can be set for a disk group with the
      minor operand. Volume device numbers for a disk group are	chosen to
      have minor numbers starting at this base minor number. On	Tru64 UNIX
      systems, minor numbers can range up through 1048576. If no more than
      1000 volumes would ever be created in any	one disk group,	then 1048
      different	ranges of minor	numbers	are available for different disk
      groups. A	reasonably sized range should be left at the end for
      temporary	device number remappings (in the event that two	device
      numbers still conflict).

      If the minor attribute is	not specified on the init command line,	LSM
      chooses a	random number of at least 1000 that is a multiple of 1000 and
      yields a usable range of 1000 device numbers.  This default number is
      chosen such that it does not overlap within a range of 1000 of any
      currently	imported disk groups and does not overlap any currently	allo-
      cated volume device numbers.


				       Note

	 The default policy is likely to ensure	that a small number of disk
	 groups	can be merged successfully between a set of machines. How-
	 ever, in cases	where disk groups will be merged automatically using
	 fail-over mechanisms, you should select ranges	that avoid overlap.

  reminor
      Changes the base minor number for	a disk group, and renumbers all	dev-
      ices in the disk group to	a range	starting at that number. If the	dev-
      ice for a	volume is open,	the old	device number will remain in effect
      until the	system is rebooted or until the	disk group is deported and
      reimported. Also,	if you close an	open volume, you can execute voldg
      reminor again to cause the renumbering to	take effect without rebooting
      or reimporting.

      A	new device number can also overlap with	a temporary renumbering	for a
      volume device, which will	also require a reboot or reimport for the new
      device numbering to take effect. A temporary renumbering can happen in
      the following situations:

	+  When	two volumes (for example, volumes in two different disk
	   groups) share the same permanently assigned device number, in
	   which case one of the volumes is renumbered temporarily to use an
	   alternate device number

	+  When	the persistent device number for a volume is changed, but the
	   active device number	cannot be changed to match
  The active number can	be left	unchanged after	a persistent device number
  change either	because	the volume device was open or because the new number
  was in use as	the active device number for another volume.

      The voldg	reminor	operation will fail if you try to use a	range of
      numbers currently	in use as a persistent (not a temporary) device
      number. You can force use	of the number range with the -f	option.	With
      the -f option, some device renumberings might not	take effect until a
      reboot or	a reimport (just as with open volumes).	 Also, if you force
      volumes in two disk groups to use	the same device	number,	one of the
      volumes will be temporarily renumbered on	the next reboot. The volume
      device to	be renumbered is selected at random, except that device
      numberings in the	rootdg disk group take precedence over all others.

      The -f option should be used only	when swapping the device number
      ranges used by two or more disk groups. See EXAMPLES for more informa-
      tion.

  import
      Imports a	disk group to make the specified disk group available on the
      local machine. This makes	any configuration information stored with the
      disk group accessible, including any disk	and volume configurations.
      You specify the disk group to import with	the diskgroup argument,	which
      can be either the	administrative disk group name or the disk group's
      unique ID.

      Normally,	a disk group is	not imported if	some disks in the disk group
      cannot be	found by the local host. You can force the import with the -f
      option if, for example, one of the disks is currently unusable or	inac-
      cessible.


				       Note

	 Take care when	using the -f option, because it	can cause the same
	 disk group to be imported twice from disjointed sets of disks,	caus-
	 ing the disk group to become inconsistent.

      When a disk group	is imported, all disks in the disk group are stamped
      with the host's ID, which	is usually the host name. Normally, a disk
      group cannot be imported if any of its disks are stamped with a non-
      matching host ID.	This provides a	check in cases where disks can be
      accessed from more than one host.

      If you are certain that a	disk is	not in use by another host (such as
      because a	disk group was not cleanly deported), use the -C option	to
      clear the	existing host ID on all	disks in the disk group	as part	of
      the import. You can also clear a host ID using the voldisk clearimport
      command.

      You can rename a disk group on import using the -n newname option. If
      you do not want the name change to be permanent, use the -n option with
      the -t option. This retains the original name of the disk	group but
      presents the disk	group to the importing host under the new name.

  deport
      Disables access to the specified disk group. You cannot deport a disk
      group if any volumes in the disk group are open. When you	deport a disk
      group, the host ID, which	is usually the host name, is cleared on	all
      disks in the disk	group unless you specify a new host ID using the -h
      option. This is to prevent automatically importing the disk group	when
      the system reboots.

      You can rename a disk group when you deport it with the -n newname
      option. You can also assign the disk group to an alternate host by
      specifying the host ID (voldctl(8)) of the alternate host	with the -h
      newhostid	option.	 This allows the disk group to be automatically
      imported when the	alternate host reboots.	See EXAMPLES.

  adddisk
      Adds the specified disk or disks to a disk group (rootdg by default).
      The disk must not	already	be part	of an imported disk group. The
      accessname component to a	disk specification argument names a disk
      access record (a device address specification) used to access the	disk.
      If a medianame component is specified, it	names the disk media record
      used to define the disk within the disk group. If	no medianame com-
      ponent is	specified, the disk media record will have the same name as
      the disk access record.

      Adding a disk to a disk group causes the disk group's configuration to
      be copied	onto the disk (if the disk has regions for configuration
      copies).	Also, the disk is stamped with the system's host ID, which is
      usually the host name, as	defined	in the /etc/vol/volboot	file.

  rmdisk
      Removes the specified disk or disks from a disk group (rootdg by
      default).	The last disk cannot be	removed	from its disk group. It	is
      not possible to remove the last disk containing a	valid disk group con-
      figuration or log	copy from its disk group.

      Normally,	the rmdisk operation fails if subdisk records point to the
      named disk media records.	However, if the	-k option is specified,	the
      disk media records will be kept, although	in a removed state, and	the
      subdisk records will still point to them.	 The subdisks, and any plexes
      that refer to them, are unusable until the disk is again added using
      the -k option to the adddisk operation. Any volumes that become unus-
      able, because all	plexes become unusable,	are disabled.


				       Note

	 Use extra care	with the -k option because this	option can disable
	 active	volumes.

  list
      Lists the	contents of disk groups. If no diskgroup argument is speci-
      fied, all	disk groups are	listed in an abbreviated one-line format. If
      a	diskgroup argument is specified, a longer format is displayed indi-
      cating the status	and configuration of the disk group and	a listing of
      the disks	that contain copies of its configuration database and kernel
      log.

  free
      Lists free space that can	be used	for allocating subdisks. If a disk
      group is specified, the output is	limited	to the indicated disk group;
      otherwise, space is listed from all disk groups. If disks	are specified
      by disk media name, the output is	restricted to the indicated disks.

      A	region of free space is	identified by disk media name, a physical
      device tag, an offset relative to	the beginning of the public region
      for the media, and a length.

      The physical device tag is a reference that indicates which physical
      device defines the disk media. It	appears	as a truncated disk access
      name.  If	a particular physical device is	split into several Logical
      Storage Manager disk objects, the	device tag for each disk object	will
      be the same. Device tags can be compared to identify space that is on
      the same or on different physical	disks.

  spare
      Lists spare space	that can be used for relocating	subdisks during
      recovery.	If a disk group	is specified, the output is limited to the
      indicated	disk group; otherwise, spare space from	all disk groups	is
      listed. If disks are specified by	disk media name, the output is res-
      tricted to the indicated disks.

      A	region of spare	space is identified by disk media name,	a physical
      device tag, an offset relative to	the beginning of the public region
      for the media, and a length.

      The physical device tag is a reference that indicates which physical
      device defines the disk media. It	appears	as a truncated disk access
      name.

  flush
      Rewrites all on-disk structures managed by the Logical Storage Manager
      for the named disk groups.  This rewrites	all disk headers, configura-
      tion copies, and kernel log copies.  Also, if any	configuration copies
      were disabled (for example as a result of	I/O failures), this will
      rewrite those configuration copies and attempt to	enable them.

  repldisk
      Dissociates the disk access record from the disk media record named by
      spare-medianame and reassociates it with the unassociated	disk media
      record named by unassoc-medianame. Both unassoc-medianame	and spare-
      medianame	must be	members	of the disk group named	by the diskgroup
      argument (rootdg by default). However, if	the -k option is specified,
      the disk media records for the spare-medianame will be kept, although
      in a removed state.

DESCRIPTION

  The voldg utility performs basic administrative operations on	disk groups.
  Operations include the creation of disk groups, the addition of disks	to a
  disk group, and disk group imports and deports. The behavior of the voldg
  utility depends upon the keyword specified as	the first operand.

  A groupname argument must be a disk group name.

  A diskgroup argument can be either a disk group name or a disk group ID.

  An accessname	argument refers	to a disk access name (also referred to	as a
  disk device name), as	stored in the root configuration by the	voldisk	util-
  ity (for example, dsk5).  A medianame	argument is an administrative name
  used to define a disk	within a disk group (for example, disk01).

EXAMPLES

   1.  To swap the number ranges for two disk groups, use the -f option	when
       renumbering the first disk group	to use the range of the	second disk
       group. Renumbering the second disk group	to the first range does	not
       require the -f option:


	    # voldg -f reminor dg-1 dg2-base-minor
	    # voldg reminor dg-2 dg1-base-minor

   2.  To move a rootdg	disk group from	one host to a second host (for exam-
       ple, so you can make repairs to the root	volume)	and then move the
       disk group back to the originating host,	which can then be rebooted on
       the repaired disk group,	do the following:

	a.  Identify the disk group ID for the rootdg disk group with voldisk
	    -s list.

	b.  On the other host, use that	disk group ID to import	that rootdg
	    using -C to	clear import locks, -t for a temporary import, and -n
	    to specify an alternate name (to avoid collision with the rootdg
	    disk group on the second host):


		 # voldg -tC -n	tempname import	rootdg_id

	c.  After repair, deport the disk group	using -h to restore the	first
	    host ID:


		 # voldg -h orig_host_id deport	tempname



   3.  To deport a disk	group to be used as the	rootdg disk group for a	new
       machine:

	a.  Deport the disk group, renaming it rootdg and assigning the	new
	    host ID:
		 # voldg -n rootdg -h newhostid	deport diskgroup

	b.  Connect the	disks to the new host.

	c.  Boot the new host. The system finds	the configuration automati-
	    cally and imports the new rootdg disk group.

   4.  To import disk groups deported from a pre-Version 5.0 version of	LSM
       onto a system running Version 5.0 or higher and upgrade their metadata
       format, enter:
	    # voldg -o convert_old  import diskgroup

       If the disk group contains volumes that use BCL,	the following message
       is displayed:


	    lsm:voldg:WARNING:Logging disabled on volume. Need to convert to DRL.
	    lsm:voldg:WARNING:Run the vollogcnvt command to automatically convert logging.



SEE ALSO

  Commands: vold(8), voldisk(8), vollogcnvt(8),	volplex(8), volume(8)

  Other: volintro(8)