unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

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



voldisk(8)							   voldisk(8)



NAME

  voldisk - Defines and	manages	Logical	Storage	Manager	disks

SYNOPSIS

  /sbin/voldisk	[-f] init accessname [attribute...]

  /sbin/voldisk	[-f] define accessname [attribute...]

  /sbin/voldisk	offline	accessname...

  /sbin/voldisk	online accessname...

  /sbin/voldisk	[-a] online

  /sbin/voldisk	rm accessname...

  /sbin/voldisk	[-g diskgroup] [-qs] list [disk...]

  /sbin/voldisk	clearimport accessname...

  /sbin/voldisk	[-g diskgroup] check disk...

  /sbin/voldisk	[-g diskgroup] set  disk [attribute...]

  /sbin/voldisk	moddb accessname [attribute...]

OPTIONS

  The following	options	are recognized:

  -f  Forces an	operation that would normally fail.

  -a  Specifies	all online disks that are not currently	in an imported disk
      group.

  -g diskgroup
      Specifies	the disk group for the operation.

  -q  Suppresses the listing of	output field labels.

  -s  Specifies	the listing of detailed	information from the disk header,
      including	the disk ID, host ID, disk group ID and	disk group name.

DESCRIPTION

  The voldisk utility performs basic administrative operations on disks.
  Operations include initializing and replacing	disks, as well as taking care
  of some bookkeeping necessary	for the	disk model presented by	the Logical
  Storage Manager.


  The voldisk operations that take an accessname argument accept only disk
  access names,	which are system-specific names	that relate to disk
  addresses. On	Tru64 UNIX systems, disk access	names are usually of the form
  dsknp, where dsk is the device mnemonic for disk devices, n is the sequence
  number of the	disk, and p is the partition identifier	(in the	range a	to
  h). Special devices, such as internal	RAM disks, may use different forms
  for disk access names. Disk access names relate directly to device node
  names	in the /dev/disk directory.

  The voldisk operations that take a disk argument can take disk access	names
  or disk media	names (for example, disk01). For such operations, a disk
  group	can be specified with -g to distinguish	disk media names that are
  used in more than one	disk group.

  Physical disks in the	Logical	Storage	Manager	are presumed to	be movable,
  and are usually identified by	a unique disk ID stored	on the physical	disk,
  rather than by a disk	device node. This allows disks to be moved to dif-
  ferent SCSI target IDs without affecting correct operation.

  The Logical Storage Manager maintains	known disk device address information
  in a set of disk access records, which are stored in the rootdg disk group
  configuration. The names of these records are	based on the disk access
  name.	These disk access records are normally used solely to identify which
  physical disks exist,	based on disk IDs stored on the	disks themselves.
  All voldisk operations except	init and define	require	specification of
  defined disk access records.

  Private Region Data Structures


  Physical disks contain public	regions, which are used	for allocating sub-
  disks. They can also contain private regions,	which are used for storing
  private Logical Storage Manager information. Private regions are structured
  regions, and are maintained entirely by the Logical Storage Manager.

  Private regions contain the following	structures:

    +  Disk header

       Each private region contains exactly two	copies of a disk header,
       which defines the unique	disk ID, disk geometry information, and	disk
       group association information. Two copies are created so	that one copy
       can be lost (due	to I/O failures) without causing use of	the disk to
       be lost.	The primary copy of the	disk header is stored in block 0 of
       the private region. The alternate copy is stored	within the first 256
       sectors.	If the primary copy is unreadable or unusable, the Logical
       Storage Manager will search the first 256 sectors of the	private
       region for the alternate	copy.

    +  Table of	contents

       A linked	list of	blocks,	pointed	to by the disk header, that define
       additional structures in	the private and	public regions.	The table of
       contents	blocks define disk group configuration copy locations, log
       copy locations, and reserved regions carved from	the public region.
       Each link block in the table of contents	is replicated at the begin-
       ning and	end of the private region.  If the primary copy	of any one
       link block is unreadable	or unusable, the alternate copy	of that	link
       is used.

    +  Configuration copies

       A disk contains 0, 1, or	2 disk group configuration copies, depending
       on the number specified when the	disk was initialized using the vol-
       disk init operation (explained later). When a disk is added to a	disk
       group, the disk group's persistent configuration	records	are written
       to each copy. For disks that are	not associated with a disk group, the
       space allocated for configuration copies	is unused.

       Each disk group requires	at least one usable configuration copy.
       Preferably there	should be at least four	copies,	allocated between at
       least two disks.	 This allows one disk to be lost totally, while	still
       preserving sufficient redundancy	for recovering from simple read
       failures.

    +  Disk group log copies

       A disk contains 0, 1, or	2 disk group log copies. The number of log
       copies is set to	the same as the	number of configuration	copies for
       the disk	(as explained in the Configuration copies section above).

       These logs are written by the kernel when certain types of actions are
       performed: transaction commits, plex detaches resulting from I/O
       failures, total dirty region log	(DRL) failures,	the first write	to a
       volume, and volume close. After a crash or a clean reboot, this log
       information is used to recover the state	of a disk group	just prior to
       the crash or reboot.

       Each disk group requires	at least one usable disk group log copy. As
       with configuration copies, it is	preferable to have at least four log
       copies, allocated between at least two disks.

  For a	single disk, the disk header and the table of contents blocks are
  critical data	structures. At least one copy of the disk header, and at
  least	one copy of each table of contents block, must be readable and
  usable, or else the disk itself is unusable and will have to be reinitial-
  ized.

  Within disk groups, disk group configuration and log copies are critical
  data structures. At least one	complete configuration copy and	log copy must
  be readable and usable, or the disk group is unusable	and will have to be
  reinitialized	from scratch.

  All disk group association information is stored in the disk header within
  private regions. This	information consists of	a disk group name, disk	group
  unique ID, and a host	ID. When the system boots, the Logical Storage
  Manager scans	for disks that are stamped with	the system's host ID. Each
  represented disk group is imported automatically. Disks with a non-matching
  host ID are not imported automatically, and cannot be	used until the host
  ID is	cleared	with the clearimport operation.

  Disk Types


  On Tru64 UNIX	systems, three disk types are provided with the	base Logical
  Storage Manager: nopriv, simple, and sliced. The default is simple for a
  disk access name that	specifies a partition (dsknp), and sliced for a	disk
  access name that specifies the entire	disk (dskn).

  The simplest disk type is nopriv, which defines a disk that has no private
  region, and that consists only of space for allocating subdisks. Configura-
  tion and log copies cannot be	stored on nopriv disks,	so they	are not
  self-identifying, and	the Logical Storage Manager cannot track their move-
  ment on a SCSI chain or between controllers.

  The nopriv disk type is mainly used for encapsulation	of existing data, or
  for defining special devices that you	wish to	use with the Logical Storage
  Manager, but that cannot store private regions (for example, RAM disks).

  Initializing a nopriv	device with voldisk init creates a disk	access record
  in the rootdg	configuration, but does	not write to the disk. The disk	ID
  for nopriv devices is	stored in the disk access record in the	rootdg
  configuration.

  The disk label fstype	tag for	a nopriv partition is LSMnopriv.



				     Note

       Do not use the type=nopriv attribute to initialize a new	disk with no
       configuration database. Instead,	use the	nconfig=0 attribute setting.

  A simple disk	has both a public and a	private	region,	which are stored on a
  single disk partition, with the public region	following the private region.

  The disk label fstype	tag for	a simple partition is LSMsimp.

  A sliced disk	has both a public and a	private	region,	which are stored on
  different disk partitions.

  The disk label for a sliced disk has the fstype field	set to LSMpubl for
  the partition	with the public	region and LSMpriv for the partition with the
  private region.

  Autoconfigured Disks


  On Tru64 UNIX	systems, the Logical Storage Manager can get a list of known
  disk device addresses	from the operating system. Any disks marked for	use
  by LSM are automatically configured into LSM when vold is started. Disks
  that are not configured for LSM use appear as	type sliced, with a status of
  UNKNOWN.

  LSM disks that are not associated with a disk	group can be removed from LSM
  use, if necessary, using voldisk rm. The next	invocation of voldisk list
  displays those devices as UNKNOWN, the same as if they had never been	in
  use by LSM. If you reinitialize a disk for LSM use, the next invocation of
  voldisk list reflects	its changed status as an LSM disk. Disks are listed
  as either in use by LSM or unknown, but not both.

  Autoconfigured devices can be	disabled and reenabled using the offline and
  online operations. However, the offline state	is not stored persistently.
  If you need to persistently offline a	device at a particular address,	you
  will need to convert the address to use an explicit device record. To	do
  this,	remove the autoconfigured device, and use voldisk define to create an
  explicitly-configured	device.

KEYWORDS AND ATTRIBUTES

  The behavior of the voldisk utility depends upon the keyword specified as
  the first operand. Any attribute operands override default values assigned
  for various disk attributes. Supported keywords and attributes are:

  init
      Initializes regions of a disk for	use by the Logical Storage Manager.
      This involves installing a disk header and writing an empty configura-
      tion on the disk.	The accessname operand identifies the disk.

      Normally,	this command fails if the disk already contains	an apparently
      valid disk header. The -f	option can be used to override this and	to
      force initialization of the disk.	A disk that is a member	of an
      imported disk group cannot be initialized.

      The voldisk init operation creates a disk	access record for a disk (if
      one does not already exist), and sets its	state to online. If the	root
      configuration is disabled	when a disk is initialized, the	disk header
      is initialized, but the disk is not added	to the permanent list of
      known disks until	the root configuration is enabled.

      Attributes that can be used with voldisk init are:

      type=disk_type
	  Specifies the	disk device access type, which is a system-specific
	  name identifying a class of strategies for accessing disks and for
	  managing private and public regions. For Tru64 UNIX, the valid
	  disk_type names are: nopriv, simple, and sliced. See the Disk	Types
	  section for details.

      offline
	  Specifies that the device will be left in the	offline	state, ini-
	  tially. This is used only if this operation is defining a new	disk
	  access record.

      publen=length or len=length
	  For the nopriv device	type, this attribute specifies the usable
	  length of the	device.	This is	required if there is no	system-
	  defined procedure for	determining the	disk length; otherwise,	a
	  suitable default is computed.

	  For the simple or sliced device type,	this attribute specifies the
	  length of the	public region. If this is not specified, the length
	  of the public	region is computed from	available disk label informa-
	  tion.	If no such information is available, a public region length
	  must be specified. The default public	region length is adjusted to
	  account for the private region, or for any specified public or
	  private region offsets.

      puboffset=offset or offset=offset
	  Specifies the	offset from the	beginning of the partition containing
	  the public region to the beginning of	the public region. This	can
	  be used if it	is necessary to	skip over some region reserved by the
	  operating system. This attribute does	not apply to nopriv disks.
	  For simple disks, use	the privoffset attribute.

	  This attribute defaults to 0.	For sliced disks, an offset of 16 or
	  greater is a reasonable value. If the	disk is	a hardware stripe
	  set, you can use a different offset to maintain stripe alignment.

      volatile
	  If this attribute is specified, the disk is considered to have
	  volatile contents (that is, the disk contents	are not	expected to
	  remain consistent across a system reboot).  Subdisks and plexes
	  defined on disks with	the volatile attribute will inherit that
	  attribute. The volume	start operation	interprets volatile plexes as
	  requiring a complete resynchronization from other plexes in the
	  same volume.

	  This attribute can be	used only for the nopriv device	type.

      pubslice=num or slice=num
	  Defines the partition	to use for the public partition. The value of
	  num can be 0-7 (corresponding	to partitions a-h). This attribute
	  can be used only for the sliced device type.

      privslice=num
	  Defines the partition	to use for the private partition. The value
	  of num can be	0-7 (corresponding to partitions a-h). This attribute
	  can be used only for the sliced device type.

      The following attributes can be used with	voldisk	init only for the
      simple or	sliced device type:

      privoffset=offset
	  Specifies the	offset from the	beginning of the partition containing
	  the private region to	the beginning of the private region. The
	  default is 0.

	  For a	simple disk that occupies a partition that begins at block 0
	  (for example,	when you initialize the	disk specifying	the a or c
	  partition), you should set the privoffset to 16. For a simple	disk
	  that occupies	a partition that does not begin	at block 0 (for	exam-
	  ple, when you	initialize the disk specifying the b or	d partition),
	  the default of 0 is appropriate.

	  By default, the private region of a sliced disk is at	the end	of
	  the disk (the	h partition) and needs no offset.  Therefore the
	  privoffset default of	0 is appropriate.

      privlen=length
	  Specifies the	length of the private region. If this is not speci-
	  fied,	a default is chosen. For the sliced type, the default is com-
	  puted	from available disk label information. For the simple type,
	  the default size is 4096 blocks. With	the sliced type, if no parti-
	  tion information is available, a private region length must be
	  specified in this command.

      nconfig=count
	  Specifies the	number of configuration	copies to store	on the disk.
	  The number of	configuration copies will be the same as the number
	  of log regions.  This	defaults to 1. The nconfig attribute can be
	  set to 0 to specify that no configuration copies be stored on	the
	  disk.	A setting of 1 is reasonable for disk groups that contain
	  three	or more	disks. This allows either more configuration records
	  or a smaller reserved	private	region.

      configlen=length
	  Specifies the	size of	the reserved space for each copy of the	con-
	  figuration stored on the disk. The default size is based on the
	  size of the private area and the number of configuration copies
	  requested, along with	some free space	for uses other than the	con-
	  figuration copies.

      loglen=length
	  Specifies the	size of	the reserved space in the private region for
	  each log region. This	size limits the	number of kernel-initiated
	  detach operations that can be	logged against the disk	group. The
	  default is about 15% of the size of the configuration	copies.	It is
	  advised that the log sizes be	kept as	15% of the configuration copy
	  size.

  define
      Defines a	disk access record without initializing	the disk. The Logical
      Storage Manager cannot scan a disk unless	a disk access record is
      defined for the disk. Thus, to see what is on a new disk or to move one
      or more disks that comprise a valid disk group from one system to
      another, you must	first use voldisk define to make the disks accessi-
      ble. Then	you can	use voldisk list to see	what is	on the disks, or
      voldg import to import a disk group that is on those disks.

      Normally,	a define operation fails if the	specified disk device is
      invalid (for example, if the disk	is currently nonexistent).  The	-f
      option can be used to force the definition of an unusable	disk. This
      can be useful in situations such as preparing the	disk device for	use
      after a reboot. For example, if you intend to add	a new controller and
      move some	existing disks to the new controller, you may need to define
      the new disk device addresses, even though they will not be usable
      until you	shutdown and reconfigure your disks.

      Attributes that can be used with voldisk define are:

      type=disk_type
	  See the init keyword description for details.

      offline
	  Specifies that the disk be created in	the offline state.

      publen=length or len=length
	  See the init keyword description for details.

      puboffset=offset or offset=offset
	  See the init keyword description for details.

      volatile
	  See the init keyword description for details.

      diskid=newdiskid
	  Sets the disk	ID to the newdiskid value in the disk access record
	  for the nopriv disk.

      pubslice=num or slice=num
	  See the init keyword description for details.

      privslice=num
	  See the init keyword description for details.

      privoffset=offset
	  See the init keyword description for details.

  offline
      Declares the disk	devices	named by the accessname	arguments to be	in
      the offline state. This disables checking	of the disk when searching
      for particular disk IDs, or for the set of disks in a particular disk
      group.  This operation cannot be applied to disks	that are members of
      an imported disk group.

      A	disk should be placed offline if the disk is not currently accessi-
      ble, and if accessing the	disk could have	a negative impact on the sys-
      tem. For example,	disk drivers on	a few operating	systems	can cause
      system panics or hangs if	an attempt is made to access disks that	are
      not accessible. In other operating systems, attempts to access inacces-
      sible drives may take several seconds or minutes before returning	a
      failure.

  online
      Clears the offline state for a disk device. This reenables checking of
      the disk when searching for disk IDs, or for members of a	disk group.
      This can be used for disks that are already in the online	state, pro-
      vided that they are not in imported disk groups. All internal informa-
      tion for an already online state disk is regenerated from	the disk's
      private region.

      The -a can be specified to place on line all online disks	that are not
      currently	in an imported disk group. This	can be used to force the
      volume manager to	rescan all disk	headers, or to adapt to	changes	in a
      disk's partitioning.

  rm  Removes the specified disk access	records, by disk access	name.

  list
      Lists detailed disk information on the specified disks.

      If no disk arguments are specified, a one-line summary is	printed	for
      all disk access records known to the system.

      If disk arguments	are specified, a full description of the contents of
      the disk header and of the table of contents is printed for each named
      disk.

      If no disk arguments are specified, but a	disk group is specified	with
      -g, voldisk lists	only those disks belonging to the specified disk
      group.

      If the -s	option is specified, information from the disk header is
      listed, including	the disk ID, the host ID (if the disk is or was
      imported), and the disk group ID and disk	group name (if the disk	is a
      member of	a disk group). With -s,	the output format is the same whether
      or not accessname	arguments are specified.

      If the -q	option is specified, no	header is printed describing output
      fields. This option has no effect	with the long formats generated	with
      -s or with accessname arguments.

  clearimport
      Clears the host-specific import information stored on the	indicated
      disks, and in the	configurations stored on those disks. This command
      may be necessary in cases	where import information stored	for a disk
      group becomes unusable, due to host failures, or due to a	disk group
      being moved from one machine to another.

      This operation cannot be applied to disks	that are in imported disk
      groups.

  check
      Validates	the usability of the given disks. A disk is considered usable
      if the Logical Storage Manager can write and read	back at	least one of
      the disk headers that are	stored on the disk. If a disk in a disk	group
      is found to be unusable, it is detached from its disk group and all
      subdisks stored on the disk become invalid until the physical disk is
      replaced or the disk media record	is reassigned to a different physical
      disk.


				       Note

	 Since a nopriv	disk does not contain a	disk header, the check key-
	 word might incorrectly	report a failed	nopriv disk as okay and
	 usable.

  set Changes some attributes for a disk. The attributes are either simple
      names (used to turn an attribute on or off), or can be of	the form
      attrname=value, to indicate a value for a	particular attribute.

      The set functionality is not currently implemented for any of the
      existing disk types.

  moddb
      Used with	nconfig=count to change	the number of configuration copies
      and log copies for the disk device specified by the accessname argu-
      ment. See	the init keyword description for details on the	nconfig
      attribute.

      The size of the private region is	fixed. If there	are two	copies of the
      configuration database on	a disk,	each is	limited	to half	the space in
      the private region. By decreasing	the number of configuration copies
      and log copies on	a disk,	the space available for	the remaining confi-
      guration database	on that	disk will be increased.

      Refer to the Logical Storage Manager manual for more information about
      when to use this option.



SEE ALSO

  volintro(8), vold(8),	voldg(8), volume(8)