xvm(7M)

NAME
     XVM - logical volume manager

SYNOPSIS
     /dev/xvm/*
     /dev/rxvm/*

DESCRIPTION
     XVM devices provide a logical organization to disk storage that is not
     based on disk partitions, enabling the administrator to divide a disk
     into an arbitrary number of slices.

     XVM is cluster-aware, providing a replicated image of the XVM devices
     across all cells in a cluster, and allowing for administration of XVM
     devices from any cell in the cluster.

     There is a kernel driver, referred to as XVM, an api library, and
     administrative commands to interface with the kernel.  The driver is a
     pseudo device, not directly associated with any physical hardware;  its
     function is to map requests on logical volume devices into requests to
     underlying disk devices.

     XVM configuration information is stored on-disk in the form of labels, in
     a reserved area of each XVM disk.

   Terminology
     objects
          XVM objects are divided into three categories:  physical volumes,
          volume elements, and unlabeled disks.

     unlabeled disk
          An unlabeled disk is a disk that either has not been labeled for use
          by xvm, or a disk that has been labeled, but has not had its labels
          read by the XVM driver.

     physvol
          Physical volumes (physvol's) are disks that have been labeled for
          use by XVM.

     ve   Volume elements (ve's) are the building blocks of an XVM device
          topology.  Ve's are further divided into specific ve types.

     topology
          A collection of related ve's arranged in a treelike fashion with
          volume ve's at the root of the tree, and slice ve's at the leaves.

     volume
          A volume is the topmost ve in an XVM topology.  Volumes are used to
          group multiple subvolumes under a single name.

     subvolume
          Subvolumes are the main io and control entry points for an xvm
          topology.  Block and character special files are tied to the
          subvolumes to provide the XVM io and ioctl interface.  Subvolumes
          have only a single child ve.  Associated with a subvolume is a
          subvolume type.  The subvolume type is a number in the range 0-255.
          Types 0-16 are system-defined, and are used to mark a subvolume as
          being a XFS data, log, or rt subvolume.  The remaining system
          subvolume types are reserved for future use.  Types 17-255 are
          available for administrators to tag a subvolume with a generic type.

     System-defined subvolumes must be unique within a volume ie.  you cannot
     have two data subvolumes under the same volume.

     slice
          Slices reside at the bottom of an XVM topology, and represent a
          range of contiguous data blocks on a physvol.

     logical ve's
          Between subvolumes and slices are logical volume elements that are
          used to impose certain characteristics to the subvolume address
          space.  Concat ve's are used to concatenate underlying ve's into a
          larger address space.  Stripe ve's can be used to improve io
          transfer rates by dividing io requests up among its underlying ve's.
          Mirror ve's are for data redundancy by maintaining identical images
          of data on each underlying ve.

     In general, the logical ve's can be stacked arbitrarily, although
          there is a limit of 10 levels to a ve topology from the volume ve
          through a slice.  Mirror ve's also have a limit of 8 children.

     pieces
          The terms piece and child refer to a child of a ve.  All ve's except
          slices can have children.  Volumes are limited to 255 children,
          subvolumes are limited to 1 child, and mirrors are limited to 8
          children.  Other ve's are limited to 65536 children.  Pieces are 0-
          based, meaning piece 0 is the leftmost child of a ve.

   Object Naming
     All XVM objects except slices can have user-supplied names given to them
     (if user names are not supplied, default names will be generated).
     Generally, objects are specified using the object name, with subvolumes
     being an exception.  Subvolume objects must be specified by prefixing the
     subvolume name with its volume name followed by '/'.  For example:
     fred/data.

     Because user-defined names are allowed, it is possible to have
     ambiguities in the XVM object name space.  When an ambiguous name is
     supplied to an XVM command, the command will generate an error.  To
     remove ambiguity, object names may be prefixed with a type followed by a
     '/'.  For example:  concat/concat1.
     The following type prefixes are recognized:

     prefix      object type
     __________________________
     vol         volume ve
     subvol      subvolume ve
     concat      concat ve
     stripe      stripe ve
     mirror      mirror ve
     slice       slice ve
     phys        physvol
     unlabeled   unlabeled disk

     Note that unambiguous subvolumes are a 3-tuple:
     subvol/vol_name/subvol_name.

     XVM volume elements can also be specified using a path-like syntax, where
     the components of the path are ve names or piece numbers under the
     parent.  For example:  vol/fred/data/concat0/physs0 refers to the ve
     physs0, whose parent is concat0, which is the data subvolume of volume
     fred.  Additionally, concat0/0 refers to the zero-th (leftmost) piece of
     the ve concat0.  The piece syntax is helpful when you want to target a ve
     without having to know its name.  A component of .. refers to the parent
     of the object referenced by the path up to that point.  For example,
     concat0/.. would refer to the parent of concat0.  The parent of a volume
     is considered to be the volume itself.  There is no concept of current
     object, so .. can only be used when the preceeding portion of the path
     can be translated into an object.

   Creating Topologies
     XVM topologies can be built top-down, or bottom-up.  It should be noted
     that any tree or subtree that does not end in a slice will not have
     labels written to disk, and therefore will not be persistent across
     reboots.

   Automatic Volume & Subvolume Generation
     When new volume elements are created, they are automaticly associated
     with a volume and data subvolume.  This eliminates the need to explicitly
     create volume and subvolumes for every ve.  By default, the volume name
     will be automaticly named, and the subvolume will be of type data with
     the name data.  The xvm(1M) ve creation commands take options for naming
     the volume explicitly.  Note that if a volume is automaticly named, a
     new, possibly different name is generated when the system reboots.

   Subvolume block/char Path names
     The subvolume block and character special files exist under the following
     paths:

     /dev/xvm/volname_subvolname   (blk-special)
     /dev/rxvm/volname_ubvolname   (chr-special)

     The shorter name volname can optionally be used instead of
     volname_subvolname when referring to the data subvolume.  For example,
     /dev/xvm/fred_data and /dev/xvm/fred both refer to the block-special file
     of the data subvolume under volume fred.

   Administering XVM devices
     Physvols and ve's are created and manipulated with the xvm(1M) command.

FILES
     /dev/xvm/*
     /dev/rxvm/*

SEE ALSO
     xvm(1M).