Enterprise Volume Management System (EVMS) HOWTO

Kevin Corry


corryk at us.ibm.com

Joy Yokley Goodreau


joyg at us.ibm.com

2001-09-14
Revision History                                                           
Revision 1.4             2002-03-27            Revised by: JYG             
Updated version. Ready for 1.0.0 release                                   
Revision 1.3             2002-03-21            Revised by: JYG             
Added MD plug-in description, BBR plug-in description, CLI description, and
reviewer edits.                                                            
Revision 1.2             2002-03-11            Revised by: JYG             
Improved readability                                                       
Revision 1.1             2002-03-01            Revised by: JYG             
General edits and corrections                                              
Revision 1.0             2002-01-17            Revised by: JYG             
Added information on Snapshot Feature Plug-in                              
Revision 0.9             2002-01-08            Revised by: KMC             
Added information on adding EVMS support to an init-ramdisk.               



EVMS provides flexibility and extensibility in managing storage. EVMS is a
new approach to logical volume management. The EVMS architecture introduces
a plug-in model that allows for easy expansion or customization of various
levels of volume management. This HOWTO provides a basic explanation of
EVMS, as well as instructions for installing and using EVMS.

---------------------------------------------------------------------------
---------------------------------------------------------------------------

Copyright Notice and Disclaimer

Copyright 2001, 2002 IBM Corporation

This document may be reproduced or distributed in any form without prior
permission provided the copyright notice is retained on all copies.
Modified versions of this document may be freely distributed, provided that
they are clearly identified as such, and this copyright is included intact.

This document is provided "AS IS," with no express or implied warranties.
Use the information in this document at your own risk.

Special Notices

The following terms are registered trademarks of International Business
Machines Corporation in the United States and/or other countries: AIX and
OS/2. A full list of U.S. trademarks owned by IBM may be found at http://
www.ibm.com/legal/copytrade.shtml. Intel is a trademark or registered
trademark of Intel Corporation or its subsidiaries in the United States and
other countries. Linux is a trademark of Linus Torvalds. Other company,
product, and service names may be trademarks or service marks of others.
---------------------------------------------------------------------------

Introduction

The Enterprise Volume Management System (EVMS) is a new approach to logical
volume management. The EVMS architecture introduces a plug-in model that
allows for easy expansion or customization of various levels of volume
management.
---------------------------------------------------------------------------

Current Versions

The current version of EVMS is 1.0.0. EVMS is designed to work with the 2.4
and 2.5 series of Linux kernels. This release contains patches against
most kernel versions up to 2.4.18 and 2.5.5. Please see The Linux Kernel
Archives for the Linux kernel source

The latest version of this document is available on the EVMS web site.
---------------------------------------------------------------------------

Mailing List and Feedback

To follow discussions about EVMS development, please subscribe to our
mailing list, evms-devel@list.sourceforge.net. Subscription information and
archives are available on the EVMS website.

As EVMS developers, we rely on our users to let us know how useful EVMS is.
If you have any suggestions or comments about the features and capabilities
of EVMS or this HOWTO, please send your comments to our mailing list.

To submit bugs, patches, and support requests to the project, use the
Tracker tool on the EVMS website.
---------------------------------------------------------------------------

EVMS Major Components

EVMS uses a layered, plug-in model to provide flexibility and extensibility
for managing storage. This way of managing storage allows for easy
expansion or customization of various levels of volume management.
---------------------------------------------------------------------------

Runtime

The EVMS Runtime refers to the in-kernel portion of the system. The Runtime
has three primary purposes:

  * determines the system's logical volumes at boot time and provides the
    necessary block devices to represent those volumes in user-space. Each
    plug-in determines the portion of the volumes that it is responsible
    for and passes new information up to the next layer.
   
  * handles I/O to the volumes. Each plug-in is responsible for translating
    I/O requests as appropriate for its volumes into I/O requests for the
    layer below.
   
  * provides an ioctl interface so communication can take place between the
    kernel and user-space.
   

EVMS kernel plug-ins are built as Linux block device drivers that interact
with the EVMS kernel runtime code. These plug-ins are built as part of the
Linux kernel build process and require core EVMS support in the kernel.
Plug-ins add functionality to the Runtime by providing support for features
for logical volumes. An example of a plug-in that provides such
functionality is bad block relocation (BBR). BBR is a feature that can be
applied to a logical volume. The support for this feature comes from the
BBR plug-in.
---------------------------------------------------------------------------

Engine

The EVMS Engine is the core of the user-space administration tools. The
EVMS Engine is responsible for providing the following services:

  * A front-end API set for creating user interface tools.
   
  * A back-end API set for plug-in writers.
   
  * Managing the discovery and modification of logical volumes.
   
  * Management of the loading of plug-ins and the interaction between them.
   

Each plug-in inside the Runtime has a corresponding plug-in inside the EVMS
Engine. These plug-ins provide administration capabilities for various
kinds of logical volumes. For example, the DriveLinking plug-in inside the
Runtime is responsible for I/O through DriveLink devices, and the
corresponding DriveLinking plug-in inside the Engine handles creation,
modification, and maintenance of DriveLink volumes.

Plug-ins are built as shared libraries. The EVMS Engine loads these
libraries when it is opened. Therefore, new features and functions can be
added to the user-space by simply writing a new plug-in, instead of
modifying the core EVMS Engine.
---------------------------------------------------------------------------

User Interfaces

Because the EVMS Engine provides a programatic interface instead of a
direct user interface, multiple user interfaces can be written or tailored
to a particular style or group of tasks. Currently, four different user
interfaces under development:

  * A general command line for supporting all EVMS capabilities.
   
  * A graphical user interface (GUI) for easy administration using a GUI
    desktop.
   
  * A text-mode, ncurses-based interface.
   
  * A set of command line utilities for emulating the Linux LVM (logical
    volume management) command set.
   

   
    NOTE: The user interface for command line utilities that emulate Linux
    LVM (logical volume management) is one example of how the Engine
    application programming interface (API) can be used to create a
    tailored user interface.

---------------------------------------------------------------------------

EVMS Terminology

Because of the different terms used to describe volume management on
operating systems, we developed a set of terms specific to EVMS. This
section defines some general terms used in EVMS and defines the different
layers used with EVMS.
---------------------------------------------------------------------------

General Terms

The following list defines volume management terms as they relate
specifically to EVMS.

Sector
    The lowest level of addressability on a block device. This definition
    is in keeping with the standard meaning found in other management
    systems.
   
Storage Object
    Any memory structure in EVMS that is capable of being a block device.
   
Logical Disk
    The ordered set of contiguous sectors that comprises or represents a
    physical device.
   
Disk Segment
    An ordered set of physically contiguous sectors residing on a logical
    disk or other disk segment. The general analogy for a disk segment is
    to a traditional disk partition, such as DOS or OS/2
   
Storage Region
    An ordered set of logically contiguous sectors (not necessarily
    physically contiguous). The underlying mapping can be to logical disks,
    disk segments, or other storage regions.

Feature Object
    A logically contiguous address space created from one or more disks,
    segments, regions, or other feature objects through the use of an EVMS
    native feature.
   
EVMS Logical Volume
    A mountable storage object.
   
Compatibility Logical Volume
    A mountable storage object that does not contain any EVMS Feature
    Objects. Many plug-ins in EVMS provide support for the capabilities of
    other volume management schemes. Volumes that are designated as
    "compatibility" are insured to be backwards compatible to that
    particular scheme because they do not contain any EVMS native metadata.
   
Storage Container
    A collection of storage objects. Storage containers provide a
    re-mapping of the collection into a new set of storage objects that the
    storage container exports. The appropriate analogy for a storage
    container is to other volume groups, such as AIX and Linux LVM.
   
---------------------------------------------------------------------------

Layer Definitions

EVMS defines a layered architecture where plug-ins in each layer create
abstractions of the layer(s) below. EVMS also allows plug-ins to create
abstractions of objects within the same layer. The following list defines
these layers from the bottom up.


Defining the Layers

Logical Device Managers
    The first layer is the logical device managers. These plug-ins
    communicate with the hardware device drivers to create the first EVMS
    objects. Currently, all local devices (most IDE and SCSI disks) are
    handled by a single plug-in. Future releases of EVMS might have
    additional device managers to do network device management, such as for
    disks on a storage area network (SAN).
   
Segment Managers
    The second layer is the segment managers. In general, these plug-ins
    handle the segmenting, or partitioning, of disk drives. These engine
    components can replace programs, such as fdisk and disk druid, and the
    kernel component can replace the in-kernel disk partitioning code.
    Segment managers can also be "stacked," meaning that one segment
    manager can take input from another segment manager.
   
    Currently, the only plug-in in this layer is the Default Segment
    Manager. This plug-in handles the DOS partitioning scheme. This scheme
    is traditionally used by Linux. The plug-in also handles some special
    cases that arise when using OS/2 partitions. In the future, additional
    segment managers may handle additional partitioning schemes.
   
Region Managers
    The third layer is the region managers. This layer is intended to
    provide a place for plug-ins that ensures compatibility with existing
    volume management schemes in Linux or other operating systems. Region
    managers are intended to model systems that provide a logical
    abstraction above disks or partitions.
   
    Like the segment managers, region managers can also be stacked.
    Therefore, the input object to a region manager can be a disk, a
    segment, or another region.
   
    There are currently four region manager plug-ins in EVMS. The first is
    the LVM plug-in that provides compatibility with the Linux LVM and
    allows the creation of volume groups or containers and logical volumes
    or regions.
   
    Two more plug-ins are the AIX and OS/2 region managers. The AIX LVM is
    very similar in functionality to the Linux LVM because it uses volume
    groups and logical volumes. Currently there is only kernel support for
    the AIX plug-in. The OS/2 plug-in provides compatibility with volumes
    created under OS/2. Unlike the Linux and AIX LVMs, the OS/2 LVM is
    based on the linear linking of disk partitions.
   
    The fourth region manager plug-in is the Multi-Disk (MD) plug-in for
    RAID. This plug-in provides RAID levels linear, 0, 1, 1+0, 4, and 5 in
    software. The ability to stack region managers allows combinations of
    RAID and LVM. For instance, a stripe set (RAID 0) could be used as a PV
    in LVM, or two LVM LVs could be mirrored using RAID 1.
   

---------------------------------------------------------------------------

Installation

Downloading EVMS

You can download the current version of EVMS (1.0.0) from the EVMS homepage
. Download the file evms-1.0.0.tar.gz. This file contains patches for the
Linux kernel and all necessary user-space administration tools.

After downloading the file, untar it in the appropriate place, using the
following command:
cd /usr/src 
tar xvzf evms-1.0.0.tar.gz
   
   
    NOTE: The command above assumes the file is untarred in /usr/src. You
    can also use other directories.

---------------------------------------------------------------------------

Adding EVMS Support to the Kernel

Obtaining Linux Kernel Source

Currently, EVMS support is not included in the main Linux kernel. EVMS
patches for the kernel source are included in the package you untarred in
the previous step. The current EVMS package contains a patch against both
the 2.4 and 2.5 kernel series.
   
   
    NOTE: EVMS will not work with 2.3, 2.2, or earlier kernel series.


If you do not have a Linux kernel source tree, you can obtain one from The
Linux Kernel Archives . For instructions on configuring and compiling a
Linux kernel, please see The Kernel HOWTO.
---------------------------------------------------------------------------

Patching the Kernel

You must apply two patches to your kernel tree to include EVMS support. The
first patch is specific to your version of the kernel; the second patch
includes all the EVMS specific source code.

To apply patches to the kernel, complete the following steps:

 1. Determine which kernel version you are using.
   
 2. Find the appropriate patch in the kernel directory of the EVMS package.
    For this example we will assume you are running 2.4.18.
   
 3. Patch your kernel tree with EVMS by typing the following commands:
    cd /usr/src/linux
    patch -p1 < /usr/src/evms-1.0.0/kernel/evms-linux-2.4.18-common-files.patch
       
        NOTE: If the path to the kernel source on your machine is different
        than /usr/src/linux, substitute the path to the kernel source on
        your machine for /usr/src/linux
   
 4. Type the following command from inside the same directory you used in
    the previous step to apply the patch to any 2.4 kernel tree:
    patch -p1 < /usr/src/evms-1.0.0/kernel/evms-1.0.0-linux-2.4.patch
   
    If you are running a 2.5 kernel, substitute the
    evms-1.0.0-linux-2.5.patch in the command above.

    Linux Kernel 2.5 Users: Not all EVMS plug-ins have been ported to the
    2.5 kernel. The plug-ins for MD, BBR, AIX, and OS/2 have not been
    converted to use the latest I/O path changes in 2.5. Therefore, you
    should not enable these plug-ins in the kernel or in the EVMS Engine.
   
In addition, there is a third patch that should be applied if you are
planning on using snapshots on journaled filesystems. Extra code is needed
in the VFS layer to force journaled filesystems to sync their journals to
disk at the time a snapshot is created. This allows the filesystem to appear
clean from the snapshot's point of view.

Find the appropriate VFS-lock patch file for the kernel you are running, and
apply it as follows (from the same directory as above):

    patch -p1 < /usr/src/evms-1.0.0/kernel/linux-2.4.18-VFS-lock.patch

   
The EVMS kernel patch has not been tested with kernels from Red Hat or
SuSE. These distributions make modifications to the Linux kernel that might
not be compatible with the code in EVMS. If you are patching a kernel from
one of these distributions, and the above command produces errors, you will
need to start with a clean kernel from kernel.org.
---------------------------------------------------------------------------

Configuring the Kernel

Once you have patched the kernel, you will need to configure the kernel. To
configure the kernel, complete the following steps:

 1. Type the following command:
    make xconfig
       
        NOTE: You can also use config or menuconfig.
   
 2. To enable EVMS support, select Main Menu->Enterprise Volume Management
    System.
   
 3. Toggle the following options:
    EVMS kernel runtime               <y>
    EVMS local device manager plugin  <y>
    EVMS DOS partition manager plugin <y>
   
    The options listed above are the bare minimum required with EVMS. The
    remaining options add additional capabilities to EVMS.
       
        NOTE: EVMS has many capabilities. Certain packages allow EVMS to be
        compatible with logical volumes, such as Linux LVM, AIX LVM, and OS
        /2 LVM, as well as Linux MD/Software RAID. There are also three new
        features specific to EVMS: snapshotting, drive linking, and
        bad-block relocation. If you do not know which capabilities you
        want to use, turn on kernel support for all the options. You can
        decide which ones to actually use after the Engine and user-space
        administration tools are installed.
       
        MD Support: If you choose to turn on EVMS MD support, do not enable
        native MD support (in the Multi-device Support menu). MD rewrites
        its metadata from within the kernel, and if both systems recognize
        the same volume, there may be inconsistencies.
       
        EVMS Linux LVM: If you choose to turn on EVMS Linux LVM support,
        you may enable native Linux LVM support. However, do not mount the
        same volume through both systems at the same time. Also, if you use
        one system to make a change to a volume or group configuration, you
        may need to reboot for the other system to recognize the changes.
       
        Linux Kernel 2.5 Users: The new 2.5 kernel series makes a number of
        changes to the I/O path. EVMS is still being updated for these
        changes. As of this release, only the following plug-ins will work
        under 2.5: local device manager, DOS partition manager, SnapShot,
        DriveLink, and Linux LVM.
   
 4. Turn on the remaining options you have chosen by selecting Main Menu->
    Enterprise Volume Management System. Toggle the following options:
    EVMS SnapShot Feature                   <y>
    EVMS DriveLink Feature                  <y>
    EVMS Bad Block Relocation (BBR) Feature <y>
    EVMS Linux LVM Package                  <y>
    EVMS Linux MD Package                   <y>
      EVMS MD Linear (append) mode          <y>
      EVMS MD RAID-0 (stripe) mode          <y>
      EVMS MD RAID-1 (mirroring) mode       <y>
      EVMS MD RAID-4/RAID-5 mode            <y>
    EVMS AIX LVM Package                    <y>
    EVMS OS/2 LVM Package                   <y>
   

You have the option of building EVMS as kernel modules instead of compiling
directly into the kernel. However, if you choose this method, EVMS will not
automatically perform discovery at kernel boot time. You will need to load
the necessary kernel modules from user-space using insmod or modprobe.
Next, use the evms_rediscover utility to tell EVMS to discover the logical
volumes. See the kernel configuration help on each EVMS plug-in for the
names of the kernel modules to be loaded.

If you decide to build EVMS as kernel modules, and you want your root-file
system on an EVMS volume, use an init-ramdisk during boot. Instructions on
adding EVMS support to your init-ramdisk can be found in the section called
Using EVMS with an Init-Ramdisk. If you are not currently running an
init-ramdisk and want root on EVMS, you should compile all EVMS plug-ins
directly into the kernel.
   
   
    NOTE: If you choose to build EVMS as kernel modules, you will need to
    compile all EVMS plug-ins as modules. If you compile some plug-ins as
    modules and some plug-ins directly into the kernel, the plug-ins that
    are in the kernel will perform automatic boot-time discovery, without
    the remaining plug-ins being active. This inconsistency could produce
    incorrect volumes.


Continue configuring your kernel as required for your system and hardware.
When you have finished configuring your kernel, choose Save and Exit to
quit the kernel configuration.
---------------------------------------------------------------------------

Building and Installing the New Kernel

Once you have configured the kernel, you will need to build the kernel.

 1. Type the following command:
    make dep && make clean && make bzImage modules modules_install
   
 2. Copy the new kernel to the appropriate location.
       
        NOTE: Use the arch/i386/boot/bzImage file on Intel machines.
   
 3. Run lilo to install the new kernel image.
   
 4. Re-boot your machine to start the new kernel with EVMS support enabled.
   

---------------------------------------------------------------------------

Installing the Engine

The EVMS Engine consists of all the user-space administration tools and
libraries for EVMS. The Engine also contains a stand-alone library, dlist,
that the Engine uses for linked-list management.

 1. To build and install the Engine, type the following commands:
    cd /usr/src/evms-1.0.0/engine
    autoconf
    ./configure [--options]
       
        NOTE: The command autoconf is only necessary for code taken
        directly from CVS; however, using this command will not affect the
        install or build if your code is not taken directly from CVS.
   
 2. Select the appropriate options for your configuration:
   
    -prefix=dir
        The default install path is /usr/local.
       
    -with-kernel=dir
        If your kernel source (with the EVMS patch) is not in /usr/src/
        linux, you must set this option.
       
    -with-evmslib_dir=dir
        This is the path to install the engine core library.
       
    -with-evmsheaders_dir=dir
        This is the path to install the engine header files.
       
    -with-plugins=<list>
        This option specifies which plug-ins to compile. The default is
        all. Other choices are none, localdskmgr, defsegmgr, lvmregmgr,
        bbr, drivelink, and snapshot
       
    -with-interfaces=<list>
        This option specifies which user interfaces to compile. The default
        is all. Other choices are none, CommandLine, evmsgui, and LvmUtils
       
    -with-debug=level
        The options are none, basic, or paranoid.
       
    -with-efence
        This links with the ElectricFence memory-debugging library.
       
   
 3. Type the following commands:
    make
    make install
    ldconfig
   
    Unless you specified other directories, the following list describes
    where files will be installed on your system:
   
      + The core Engine library will be installed in /usr/local/lib.
       
      + All plug-in libraries will be installed in /usr/local/lib/evms.
       
      + All user interface binaries will be installed in /usr/local/sbin.
       
   
 4. Add the Engine library path to your LD_LIBRARY_PATH or /etc/ld.so.conf.
    Do not add the plug-in library path to these files because the Engine
    will dynamically load these libraries directly.
   

---------------------------------------------------------------------------

Installing the Engine RPM

You can download an RPM with the latest compiled Engine binaries and
libraries. This RPM is available on the project web site along with the
source code package. The RPM is a generic i386 RPM, so it should install on
any system that uses the Red Hat Package Manager.

If you install the EVMS RPM, you will still need to patch your kernel with
EVMS support. Follow the steps the section called Adding EVMS Support to
the Kernel.
---------------------------------------------------------------------------

Using EVMS

Device Files and the EVMS Namespace

In order for user-space programs to access EVMS volumes, device files are
created in the /dev/evms directory for each exported volume. Device files
are created every time the Engine commits changes, so you can always see
the the current state of the volume configuration in the /dev/evms
directory.

A variety of namespaces exist within the /dev/evms directory. Each plug-in
defines and maintains its own namespace. The most common names will be
those of DOS segments. On a non-EVMS Linux system, disk drives and drive
partitions appear as files in /dev. These same names are maintained in EVMS
by the local device manager and the DOS segment manager. Corresponding
device files are created in /dev/evms. An example of the naming convention
follows:
/dev/hda  -> /dev/evms/hda
/dev/hda1 -> /dev/evms/hda1
/dev/sdb  -> /dev/evms/sdb
/dev/sdb5 -> /dev/evms/sdb5

EVMS features create logical volumes with persistent names. The names of
these volumes are used to create the appropriate device file in /dev/evms.
For example, if an EVMS snapshot was created and named "Thursday_Snapshot,"
it would appear as /dev/evms/Thursday_Snapshot.

The Linux LVM plug-in is an example of a plug-in specific namespace that
uses the directory /dev/evms/lvm. In this directory, additional directories
are created for each active volume group. Device files representing the LVM
logical volumes are created in the appropriate group directory, as
demonstrated in the following example:
/dev/Group1/Volume1 -> /dev/evms/lvm/Group1/Volume1

Namespaces exist for other plug-ins. Currently the OS/2 LVM is in /dev/evms
/os2 and the AIX LVM is in /dev/evms/aix.
---------------------------------------------------------------------------

devfs

As of version 0.2.2, EVMS supports the kernel device file system (devfs).
If you have devfs enabled in the kernel and mounted in your file system
tree, you will see the device files for your volumes immediately upon boot.
devfs is the preferred method for running EVMS because it ensures that the
minor numbers EVMS dynamically assigns to compatibility volumes will never
be out of sync with the minor numbers of the device files for those
volumes.
---------------------------------------------------------------------------

Fixing EVMS Device Nodes

On systems that are not running devfs, the device nodes in the /dev/evms
directory may become out of sync with the volumes that are exported by the
EVMS kernel. The following list details potential problems that could occur
if you do not use devfs:

  * Nodes might not exist for volumes that are exported.
   
  * Nodes might have the wrong minor number associated with them.
   
  * Nodes might exist for volumes that are no longer exported by the EVMS
    kernel.
   

Using a user interface could alleviate many of the problems listed above.
If you use the user interfaces and commit changes, the EVMS Engine will
update the device nodes in the /dev/evms so that the nodes agree with the
volumes that are exported by the EVMS kernel.

The evms_devnnode_fixup program provides an alternative means of fixing the
device nodes in the /dev/evms directory by updating the device nodes
without the overhead of starting a user interface.

evms_devnode_fixup can be run as a daemon by specifying the -d option. In
daemon mode, evms_devnode_fixup will first fix the device nodes in the /dev
/evms directory. It then loops, waiting for notifications of volume changes
from the EVMS Runtime. On each notification, evms_devnode_fixup fixes the
device nodes in the /dev/evms directory.
---------------------------------------------------------------------------

Using EVMS with an Init-Ramdisk

To build your EVMS kernel plug-ins as modules and mount your root file
system on an EVMS volume, add EVMS support to your init-ramdisk. If you do
not have an init-ramdisk, general instructions for creating one are in the
kernel source tree in the file Documentation/initrd.txt. Some distributions
include utilities for creating init-ramdisks. (See your distribution for
details.) If you do not want to use an init-ramdisk, you should compile all
EVMS support directly into the kernel.

To modify your init-ramdisk, decompress it using gunzip and mount it
through a loopback device. The following steps walk you through modifying
your init-ramdisk. The following commands are based on the assumption that
the init-ramdisk is mounted on /mnt/loop.

 1. Once the init-ramdisk is mounted, copy the EVMS kernel modules to it.
    mkdir -p /mnt/loop/lib/modules/x.y.z/kernel/drivers/evms
    cp /lib/modules/x.y.z/kernel/drivers/evms/*.o \
       /mnt/loop/lib/modules/x.y.z/kernel/drivers/evms
       
        NOTE: In the previous code, x.y.z is the version of your kernel.
   
 2. Copy the evms_rediscover utility to the init-ramdisk. If you are not
    using devfs, copy the evms_devnode_fixup utility as well.
    cp /usr/local/sbin/evms_rediscover /mnt/loop/bin
    cp /usr/local/sbin/evms_devnode_fixup /mnt/loop/bin
       
        NOTE: evms_rediscover and evms_devnode_fixup are compiled
        statically and will not need any additional dynamic libraries added
        to the init-ramdisk.
   
 3. Edit the linuxrc script on your init-ramdisk so that it loads all of the
    EVMS kernel modules.
   
 4. Call a kernel rediscover, followed by evms_ devnode_fixup (if you are
    not running devfs).
   
 5. Add the following lines to the linuxrc script. These lines should be
    added to the linuxrc script before the root file system is mounted, so
    the root volume will be discovered and available.
    insmod evms
    insmod evms_passthru
    insmod ldev_mgr
    insmod dos_part
    # Add insmod commands for all EVMS modules copied in the step above.
    evms_rediscover
    evms_devnode_fixup  # If not running devfs
   

If you have built the plug-ins as modules, and do not wish to mount your
root file system using EVMS, simply add entries in your init scripts to
load all the necessary EVMS modules. Once you have edited the scripts, run
the evms_rediscover utility. You should run the rediscover early in the
boot scripts before the /etc/fstab file is processed.
---------------------------------------------------------------------------

EVMS GUI

The EVMS GUI provides you with a flexible and easy-to-use interface to
administer volumes and storage objects. The EVMS GUI makes extensive use of
the Engine API that is available to front-end interfaces. The EVMS Engine
is explained in greater detail in the section called Engine. Because the
Engine API offers up abstractions, the EVMS GUI can accommodate new
plug-ins and features without requiring code changes.

Many users will find the EVMS GUI easy to use because it checks which
storage objects, actions, and plug-ins are acceptable for each task. At
times, the EVMS GUI may appear restrictive, but the controls that are in
place make the EVMS GUI easier to use than the command line and help
generate safer results.
---------------------------------------------------------------------------

Using the GUI to Complete Tasks

In the EVMS GUI you can accomplish most tasks in one of two ways: context
sensitive menus and the Actions menu.

Context sensitive menus are available from any of the main "views." Each
view corresponds to a page in a notebook widget located on the EVMS GUI
main window. These views are made up of different trees or lists that
visually represent the organization of different object types, such as
volumes, feature objects, regions, or containers.

You can view the context sensitive menu for an object by right-clicking on
that object. The actions that are available for that object will appear on
the screen. The GUI will only present actions that are acceptable for that
object at that point in the process.

To use the Actions menu choose Main Menu->Action-><the action you want to
accomplish>. The Actions option provides a more guided path to completing a
task than context sensitive menus do. The Actions option is similar to the
popular wizard or druid approach used by many GUI applications.

All of the operations you need to perform as an administrator are available
through the Actions menu.
---------------------------------------------------------------------------

Examples of Using the EVMS GUI

The following sections demonstrate how to perform some of the most common
tasks using the EVMS GUI, such as creating segments, creating containers,
creating regions, creating volumes, and committing changes.
   
   
    NOTE: Although not part of the examples, you can combine two regions
    with drive linking and then create a volume from the DriveLink feature
    object.

---------------------------------------------------------------------------

Creating a Segment

To create a segment, follow the steps below:

 1. Select Actions->Create->Segment to see a list of segment manager
    plug-ins. Currently this list contains only the Default Storage Segment
    Manager.
   
 2. Select Default Storage Segment Manager. Click Next.
   
    The next dialog window lists the free space storage objects suitable
    for creating a new segment.
   
 3. Select one of the free space storage objects. Click Next.
   
    The last dialog window presents the free space object you selected as
    well as the available configuration options for that object.
   
 4. Enter or select the appropriate values for the fields. Required fields
    are denoted by the "*" in front of the field description. The Default
    Segment Manager provides default values, but you may want to change
    some of these values.
       
        NOTE: By placing the mouse pointer over a field description, you
        can get more information about that field.
   
    Once you have filled in information for all the required fields, the
    Create button becomes available.
   
 5. Click the Create button. A window that displays the outcome appears. If
    the operation failed, close the window. Try adjusting one or more of
    the values from the step above, and Click the Create button again.
   


Once you have successfully created a segment, you can create another
segment if you have free space available.
---------------------------------------------------------------------------

Creating a Container

To create a container, follow the steps below:

 1. Select Actions->Create->Container to see a list of region manager
    plug-ins that support container creation.
   
 2. Select the LVM Region Manager. Click Next.
   
    The next dialog window contains a list of storage objects that the LVM
    Region Manager can use to create a container.
   
 3. Select one or more of the segments you created earlier. Click Next
   
 4. Enter a name for the container and any special size requirements you may
    have.
   
 5. Click the Create button. A window that displays the outcome appears. If
    the operation failed, close the window. Try adjusting one or more of
    the values from the step above. Click the Create again.
   


Once you have successfully created a container, you can create another
container if you have free space available.
---------------------------------------------------------------------------

Creating a Region

To create a region, follow the steps below:

 1. Select Actions->Create->Region to see a list of region manager plug-ins.
   
 2. Select the LVM Region Manager. Click Next.
       
        NOTE: You may see additional region managers that were not in the
        selection list when you were creating the storage container. You
        may not see the region managers because not all region managers are
        required to support containers.
   
 3. Select the free space region from the container you created in section
    the section called Creating a Container. The container should have a
    name similar to lvm/yourvg/Freespace. Click Next.
   
    The fields in the next window are required for the LVM Region Manager
    plug-in.
   
 4. Fill in the region/lv name and change any preset fields to customize the
    region.
   
 5. Click the Create button to complete the operation. A window that
    displays the outcome appears. If the operation failed, close the
    window. Try adjusting one or more of the values from the step above.
    Click the Create button again.
   

---------------------------------------------------------------------------

Creating a Volume

You can create volumes by selecting Action->Create->EVMS Volume. However,
in order to demonstrate using the context sensitive menus, this section
shows you how to create a volume using these menus.

 1. Click the Region tab to view the regions.
   
 2. Right-click on the newly created region. It should be the one with the
    "Dirty" check box marked.
   
 3. Select Create EVMS Volume.
   
 4. Enter a name for the volume. Click the Create button.
   
 5. Click the volumes tab, your newly created volume should appear on this
    list.
   

---------------------------------------------------------------------------

Creating a Compatibility Volume

The volume that was created in the section called Creating a Volume is now
an EVMS-native volume, so it contains EVMS-specific information to identify
the name and minor number. Once this volume information is applied, the
volume is no longer fully backwards compatible with existing volume types.

In the example we have been using, we created a disk partition (segment),
an LVM volume group (container), and an LVM volume (region). Instead of
adding EVMS system data to this region, we can tell EVMS to make it
directly available as a volume. The new volume is known as a compatibility
volume. The same process can be done with segments, or with regions from
other region managers. Using this method, the final product is fully
backwards-compatible with the desired system.
   
   
    NOTE: If you wanted to make the volume you created in the section
    called Creating a Volume a compatibility volume, you would need to
    remove the volume from the storage object.


To create a compatibility volume, follow the steps below:

 1. Right-click on the LVM region, and select Create Compatibility Volume
    menu item.
   
 2. Click the Create button.
   
 3. Click on the Volume tab in the GUI to see a volume with the same name as
    the region that you created above. This is your compatibility volume.
   

---------------------------------------------------------------------------

Committing the Changes

All changes you make while in the EVMS GUI are only in memory until you
commit or save the changes. In order to make your changes permanent, you
must save all changes before exiting. If you forget to save the changes and
decide to exit or close the EVMS GUI, you will be reminded about saving any
pending changes.

To explicitly commit all changes you made to files, select Action->Commit
Changes and click the Commit button.
---------------------------------------------------------------------------

EVMS Ncurses Interface

The EVMS Ncurses (evmsn) user interface provides you with a menu driven
interface with similar characteristics to the EVMS GUI. Like the EVMS GUI,
evmsn can accommodate new plug-ins and features without requiring any code
changes.

The availability of an EVMS Ncurses user interface allows you to manage
volumes on systems that do not have the X and GTK+ libraries that are
required by the EVMS GUI.
---------------------------------------------------------------------------

Navigating through EVMS Ncurses

The EVMS Ncurses user interface initially displays a list of logical
volumes similar to the logical volumes view in the EVMS GUI.

A general guide to navigating through the layout of the Ncurses screen is
listed below:

  * A menu of function keys-to-action mappings is listed at the bottom of
    the screen.
   
  * The F2 key returns you to the volumes view.
   
  * The F4 key displays a menu of other views you could switch to.
   
  * The F5 key saves changes made during an evmsn session.
   
  * Status messages and user prompts appear on a line located between the
    window frame for the current view and the action function keys menu
    line.
   
  * You can select which actions to perform by using the up and down arrow
    keys to highlight an object within the current view. Once the correct
    item is highlighted, press the Enter key. Ncurses will typically
    provide a context sensitive submenu of available actions.
   
  * When navigating from one menu to another, the ESC (escape) key will
    return you to the previous menu.
   

Ncurses allows you to create new objects based on your current view. For
example, a container can be created in the Storage Containers view by
selecting any container. If the view is empty, you can still create a
container by pressing the Enter key on the "No Storage Containers found"
row.

In order to change or set an option value within the configuration options
menu, use the spacebar key to select the value. Typically, you must press
spacebar once again to actually get a prompt to enter a new value. Press
Enter when you are finished. In order to complete most operations you must
press Enter.
---------------------------------------------------------------------------

Examples of Using the Ncurses Interface

The following sections demonstrate how to perform some of the most common
tasks using the EVMS Ncurses. These tasks include creating segments,
creating containers, creating regions, creating volumes, and committing
changes.
---------------------------------------------------------------------------

Creating a Segment

To create a segment, follow the steps below:

 1. Press the F4 or 4 key to switch views.
   
 2. Scroll down using the down arrow key until Disk Segments is highlighted.
    Press the Enter key.
   
 3. Press the Enter key again to display a sub menu on the current
    selection.
   
 4. Select Create a New Segment. Press the Enter key. You should see a list
    of segment manager plug-ins. Currently this list contains only the
    Default Storage Segment Manager.
   
 5. Select Default Storage Segment Manager. Press the Enter key.
   
    The next dialog window will present a list of free space storage
    objects suitable for creating a new segment.
   
 6. Select one of the objects by moving to it with the arrow keys and then
    using the spacebar key to select it. Once the storage object is
    selected (it is marked by a X). Press the Enter key.
   
    The last dialog window displays the selected free space object and
    configuration options available from the plug-in manager. Required
    fields are denoted by the "*" in front of the field description. The
    default segment manager provides default values, but you may want to
    change some of these values.
   
 7. Select a field value by highlighting the field and pressing the spacebar
    key.
   
 8. Change the value of the field by pressing the spacebar key once more and
    entering a new value if a "::" prompt is displayed.
   
 9. Once all required values have been completed, press the Enter key and a
    results status message will be displayed.
   

Once you have successfully created a segment you can create another segment
if you have free space still available.
---------------------------------------------------------------------------

Creating a Container

To create a container, follow the steps below:

 1. Press the F4 or 4 key to switch views.
   
 2. Scroll down the list using the down arrow key to the Storage Containers.
    Press the Enter key.
   
 3. Press the Enter key again to display a sub menu.
   
 4. Press the Enter key when Create a New Container is highlighted. You
    should see a list of plug-ins that support container creation.
   
 5. Select LVM Region Manager. Press the Enter key.
   
    The next sub menu will contain a list of storage objects, such as
    segments, disks, or regions the LVM Region Manager finds acceptable to
    use for the creation of a container.
   
 6. Use the spacebar to select one or more of the segments you created
    earlier from the list. Press Enter when you are satisfied with your
    selections.
   
 7. Press the spacebar key to select the field for the container name.
   
 8. Press the spacebar key once more, and type in the container name at the
    "::" prompt.
   
 9. Press the Enter key after typing in the container name.
   
10. Press the Enter key to complete the operation.
   

---------------------------------------------------------------------------

Creating a Region

To create a region, follow the steps below:

 1. Press the F4 or 4 key to switch views.
   
 2. Scroll down the list using the down arrow key until Storage Regions is
    highlighted. Press the Enter key.
   
 3. Press the Enter key again to display a submenu.
   
 4. Press the Enter key when Create a New Region is highlighted. You will be
    presented with a list of region manager plug-ins.
   
 5. Select the LVM Region Manager. Press the Enter key.
       
        NOTE: You might see additional region managers that were not in the
        selection list when you created the storage container. This absence
        of visible region managers occurs because not all region managers
        are required to support containers.
   
 6. Select the free space region from the container you created earlier in
    section the section called Creating a Container. The container should
    be named something similar to lvm&solyourvg&solFreespace. Use the
    spacebar key to select it. Press the Enter key to continue. The
    configuration options submenu should appear.
   
 7. Fill in the region/lv name and make any other changes you need to make.
    Press Enter to complete the operation.
   

---------------------------------------------------------------------------

Creating a Volume

To create a volume, follow the steps below:

 1. Highlight the newly created region in the Storage Regions view. Press
    the Enter key.
   
 2. Select Create EVMS Volume from the Region. Press the Enter key.
   
 3. Confirm the creation of the volume.
   
 4. Enter a name for the volume. Press the Enter key to complete the
    operation.
   


If you look at the volumes view (F2), you should see your new volume.
---------------------------------------------------------------------------

Creating a Compatibility Volume

The volume that was created in the section called Creating a Volume, is an
EVMS-native volume. An EVMS-native volume means that the volume contains
EVMS-specific information to identify the name and minor number. Once this
volume information is applied, the volume is no longer fully backwards
compatible with existing volume types.

In the previous sections, you created a disk partition (segment), an LVM
volume group (container), and an LVM volume (region). Instead of adding
EVMS system data to this region, we can tell EVMS to make it directly
available as a volume. This type of volume is known as a compatibility
volume. The same can be done with segments, or with regions from other
region managers. Using this method, the final product is fully
backwards-compatible with the desired system.

To create a compatibility volume, follow the steps below:

 1. Highlight the region you created in the Storage Regions view. Press the
    Enter key. You will not be asked to provide a volume name because one
    is automatically assigned.
   
 2. Select Create Compatibility Volume from the Region. Press the Enter key.
       
        NOTE: If the volume was already an EVMS volume, you must use the
        Remove Volume from Storage Object option before you can make it a
        compatibility volume.
   
 3. Confirm the creation of the volume.
   

If you switch to the Volume view by pressing the F2 key, you will see a
volume with the same name as the region that you created in the section
called Creating a Region.
---------------------------------------------------------------------------

Committing Your Changes

All changes you make while in the EVMS Ncurses are only in memory until you
commit or save the changes. In order to make your changes permanent, you
must save all changes before exiting. If you forget to save the changes and
decide to exit or close the EVMS Ncurses, you will be reminded about saving
any pending changes.

To explicitly commit all changes you made to files, press the F5 key and
confirm that you want to save changes.
---------------------------------------------------------------------------

EVMS Command Line Interpreter

The EVMS Command Line Interpreter (EVMS CLI) provides a command-driven user
interface for EVMS. The EVMS CLI is designed to help automate volume
management tasks. For situations where the EVMS GUI is not available, the
EVMS CLI provides an interactive mode.

Because the EVMS CLI is an interpreter, it operates differently than
command line utilities from the operating system. For the EVMS CLI, you can
only specify options on the command line you use to invoke the EVMS CLI.
These options control how the EVMS CLI operates, such as where the EVMS CLI
should go for commands to interpret, how often the EVMS CLI should commit
changes to disk, and how verbose the EVMS CLI should be in reporting its
activities. The EVMS CLI options are not volume management commands and can
only be specified when the interpreter is invoked. Once invoked, the EVMS
CLI prompts for commands unless it was invoked with the -f filename option.
If the CLI was invoked with the -f option, it gets commands from the
specified file.

The volume management commands the EVMS CLI understands are specified in
the grammar.ps file that accompanies the EVMS package. These commands are
described in detail in the EVMS man page, and help on these commands is
available from the EVMS CLI itself.
---------------------------------------------------------------------------

Using the EVMS CLI to Complete Tasks

Use the evms command to start the EVMS CLI. If you do not enter an option
with evms, the EVMS CLI will start in interactive mode. In interactive
mode, the EVMS CLI prompts you for commands. The results of each command
are committed to disk immediately. The EVMS CLI will exit when you enter an
empty command line. You can modify this behavior by using the following
options with evms:

-c
    This option commits changes to disk only when EVMS CLI exits, not after
    each command.
   
-f filename
    This option tells the EVMS CLI to use filename as the source of
    commands. The EVMS CLI will exit, when it reaches the end of filename.
   
-p
    This option parses commands only, which means that the commands are not
    actually executed. When combined with the -f option, the -p option can
    be used to catch syntax errors in command files.
   
-h
    This option displays help information for options used with the evms
    command.
   

   
    NOTE: The remaining options are less commonly used. Information on the
    remaining options is available in the EVMS man page.


Once the EVMS CLI has been invoked, it processes the commands or command
file you provided. A full listing of the commands is documented in the EVMS
man page.

The following sections examine some common tasks and the commands you can
use to complete these tasks.
---------------------------------------------------------------------------

Assigning a Segment Manager to a New Disk

When a new disk is added to a system, the disk usually contains no data and
has not been partitioned. Initially this disk shows up in EVMS as a
compatibility volume because EVMS cannot tell if the disk is being used as
a volume. Using a disk as a volume is common with RAID hardware. RAID
hardware combines multiple physical disks into one virtual disk. The
virtual disk is divided into partitions, with each partition appearing as a
physical disk to the rest of the system. These disks are then used as
volumes.

The system displays the physical disks it sees as volumes. You must tell
EVMS that the new disk is not being used as a volume. Use the Revert
command to accomplish this. The following example demonstrates this
process.
   
   
    Example: Assume that you have added a new disk to the system that EVMS
    sees as sde. This disk contains no data and has not been subdivided in
    any way (no partitions). EVMS assumes that this disk is a compatibility
    volume known as /dev/evms/sde. Tell EVMS that this disk is not a volume
    and is available for use by entering the following command:

Revert:/dev/evms/sde

Once EVMS knows that the disk is available, you can assign a segment
manager to the disk. The segment manager allows you to divide the disk into
segments (partitions). The following example demonstrates this process.
   
   
    Example: Assign the Default Segment Manager to the disk, sde, by typing
    the following command:

Assign:DefaultSegMgr={},sde

The command above assigns the Default Segment Manager to sde. The Default
Segment Manager will create two segments on the disk: a metadata segment
known as sde_mbr, and a segment to represent the available space on the
drive, sde_freespace1. This freespace segment (sde_freespace1) can be
divided into other segments because it represents space on the drive which
is not in use.
---------------------------------------------------------------------------

Creating a Segment

Data segments represent disk space used to construct volumes. Metadata
segments represent storage space on a disk that is consumed by the segment
manager managing the disk. Freespace segments represent unused disk space.
Data segments are created from freespace segments by allocating some, or
all, of the freespace in the freespace segment to the data segment.
Whenever the segment manager assiged to a disk needs more storage space,
that segment manager creates metadata segments from the freespace segments.

To create a data segment from a freespace segment, use the Allocate command
as demonstrated in the following example.
   
   
    Example: Create a 100 MB segment from the freespace segment
    sde_freespace1. This freespace segment lies on a drive controlled by
    the Default Segment Manager.


To complete the example above, use the Allocate command. The Allocate
command takes the following arguments: the name of the freespace segment to
allocate from and a list of options to pass to the segment manager. In our
example, the Default Segment Manager uses the size option to specify how
large a data segment to create from the freespace segment. The command to
accomplish this is:
Allocate: sde_freespace1,size=100MB

You can also complete the example above by using the Create command. The
arguments the Create command accepts vary depending on what is being
created. The first argument to the Create command indicates what is to be
created, which in the above example is a segment. The remaining arguments
are the freespace segment to allocate from and a list of options to pass to
the segment manager. The command to accomplish this is:
Create: Segment,sde_freespace1, size=100MB
---------------------------------------------------------------------------

Creating a Container

Segments and disks may be combined to form a container. Containers allow
you to combine storage objects and then subdivide those combined storage
objects into new storage objects. You can combine storage objects to
implement the volume group concept as found in the AIX and Linux LVM Volume
Managers.
   
   
    Example: Given a system with three available disk drives (sdc, sdd,
    hdc), use the EVMS LVM Region Manager to combine these disk drives into
    a container called "Sample Container" with a PE size of 16 KB.


The Create command is used to create containers. The first argument in the
Create command is the type of object to produce, in this case a container.
The Create command then accepts the following arguments: the region manager
to use along with any parameters it may need, and the segments or disks to
create the container from. The command to complete the example above is:
Create:Container,LvmRegMgr={name="Sample
                        Container",pe_size=16KB},sdc, sdd,
                        hdc

The command above specifies that the LVM Region Manager should be used to
combine sdc, sdd, and hdc into a container. The LVM Region Manager supports
the name and pe_size options. These options provide the name for the
container and the pe_size for the container.
---------------------------------------------------------------------------

Creating a Region

Regions are typically created from containers, but they can also be created
from segments and disks. Most region managers that support containers will
create one or more freespace regions to represent the freespace within the
container. This function is analogous to the way a segment manager creates
a freespace segment to represent unused disk space. Data Regions can be
created from these freespace regions using the Allocate command as
demonstrated in the following example:
   
   
    Example: Given the container "Sample Container," which has a single
    freespace region of 8799 MB in size, create a data region 1000 MB in
    size.


The LVM Region Manager supports many options for creating regions. To see
the available options for creating regions and containers, use the Query
command as follows:
query:plugins,plugin=LvmRegMgr,list options
Use these options to create the region in the above example. The Allocate
command takes the following arguments: the freespace region to allocate
from, and the options to pass to the region manager which controls the
freespace region you are allocating from. The LVM Region Manager options
you need are name and size. You may use other options, but these are the
minimum required. To complete the example, type the following command:
Allocate:"lvm/Sample Container/Freespace",name="Sample Region",size=1000MB

Regions that are created by combining segments and disks or regions do not
use the Allocate command. These regions use the Create command. Arguments
to the Create command are the following: keyword Region, the name of the
region manager to use, the region managers options, and the segments,
disks, and regions that are to be combined to form the new region. The form
of this command is:
Create:region, Region Manager Name = {Region Manager Options}, Segment/Disk/Region,Segment/Disk/Region ...
---------------------------------------------------------------------------

Creating a Storage Object

Storage objects are created from segments, regions, disks, or other storage
objects. Storage objects are typically used when an EVMS specific feature
is desired on a volume, such as Bad Block Relocation (BBR). Storage objects
are created using the Create command. In this case, the arguments to the
Create command are the keyword Object followed by the name of the EVMS
feature to use along with its options, and the segments, disks, regions,
and storage objects to use to create the new storage object.
   
   
    Example: Given the region lvm/Sample Container/Sample Region, create a
    storage object called BBR_Region using the EVMS Bad Block Relocation
    feature.


Because the BBR feature supports only one option, name, the command to
complete this example is:
Create:Object,BBR={name=BBR_Region},"lvm/Sample Container/Sample Region"
   
   
    NOTE: The EVMS CLI ignores spaces. Any name containing spaces must
    appear in quotation marks.

---------------------------------------------------------------------------

Creating a Volume

Volumes are created from disks, segments, regions, or storage objects.
Volumes are either EVMS native volumes or compatibility volumes.
Compatibility volumes are intended to be compatible with a volume manager
other than EVMS, such as the Linux LVM. Compatibility volumes may have
restrictions on what EVMS can do with them. EVMS native volumes have no
such restrictions, but they can only be used by an EVMS equipped system.
   
   
    Native Volume Example: Create an EVMS native volume from the region
    called BBR_Region that was created in the example in the section called
    Creating a Storage Object.


The command to complete the example is:
Create: Volume, BBR_Region, Name = "Sample EVMS Native Volume"
   
   
    Compatibility Volume Example: Given a region created by the LVM Region
    Manager that has not become part of any other region or storage object,
    and is called lvm/Sample Container/My LVM Volume, create a volume
    compatible with the Linux LVM.


Because the region lvm/Sample Container/My LVM Volume was created by the
LVM Region Manager and has had nothing else done to it, it is in a format
that the Linux LVM can understand. Turn the volume into a compatibility
volume by typing the following command:
Create:Volume,"lvm/Sample Container/My LVM Volume",compatibility
---------------------------------------------------------------------------

Notes on Commands and Command Files

The EVMS CLI allows multiple commands to appear on a command line. When
using multiple commands on a single command line, the commands must be
separated by a colon, which is the command separator. This is important for
command files because the EVMS CLI sees a command file as a single long
command line. The EVMS CLI has no concept of lines in the file and ignores
spaces. These features allow a command in a command file to span several
lines and use whatever indentation, or margins that are convenient. The
only requirement is that the command separator appear between commands.

The EVMS CLI ignores spaces unless the spaces appear within quote marks.
Any name that contains spaces or other non-printable or control characters
should be placed in quotation marks. If the name contains a quotation mark
as part of the name, the quotation mark must be "doubled" as in the
following example:
"This is a name containing ""embedded"" quote marks."

EVMS CLI keywords are case insensitive, and EVMS names are case sensitive.

Finally, C programming language style comments are supported by the EVMS
CLI. Comments may begin and end anywhere except within a quoted string, as
in the following example:
/* This is a comment */
Create:Vo/*This is a silly place for a comment, but it is
allowed.*/lume,"lvm/Sample Container/My LVM
Volume",compatibility
---------------------------------------------------------------------------

LVM Utilities

The Linux LVM is based on the concept of volume groups. A volume group (VG)
is a collection of physical volumes (PVs). All PVs in one group have their
storage space subdivided into small, fixed-sized sections called physical
extents (PEs). The default size for a PE is 4 MB. Logical volumes (LVs) are
created by allocating one or more PEs to the new LV. When I/O requests come
in for a volume, the LVM code determines which PV and which PE the request
lies on, and passes the request down the stack to the appropriate device.

You may be familiar with the Linux LVM, and you might have existing LVM
volumes that you wish to use under EVMS. In this case you are probably
already familiar with the LVM command set and with separate commands to
perform each specific task, such as creating a volume group or creating a
logical volume.

In addition to the kernel and user-space plug-ins in EVMS that recognize
and administer LVM volumes, a set of command line utilities has been
written to emulate the LVM command set, using the EVMS Engine APIs.

Currently, the following commands are available in the command line
utilities. The options are generally identical to those available from the
LVM commands. Use the "--help" option for each command to learn more about
that command.

evms_vgcreate
    Creates a new LVM volume group with the given list of PVs. VG commands
    no longer require the user to prepare objects with evms_pvcreate. Any
    available object in EVMS can now be used directly by these commands.
    Similarly, the evms_pvremove command is no longer necessary to release
    PVs back to available EVMS objects.
   
evms_vgremove
    Deletes an existing volume group.
   
evms_vgextend
    Adds new PVs to an existing volume group.
   
evms_vgreduce
    Takes PVs out of an existing volume group.
   
evms_lvcreate
    Creates a new LVM logical volume. evms_lvcreate supports creating
    normal (linear) LVs as well as striped LVs. Linear LVs can be specified
    as being contiguous. The LVM plug-in defines contiguous to mean the LV
    must reside on a single PV in a contiguous run of PEs. This command
    also supports creating snapshot LVs of existing LVs in the same VG and
    allows you to specify the underlying PVs for any non-snapshot LV.
   
evms_lvremove
    Deletes an LVM logical volume. Deleting LVs that are snapshotted is not
    allowed.
   
evms_lvextend
    Expands an existing LV by adding extents. You must expand the file
    system after expanding the LV. This command currently does not support
    expanding snapshots or snapshot originals.
   
evms_lvreduce
    Shrinks an existing LV by removing extents. You must shrink the file
    system before shrinking the LV. Do not shrink the LV first, or you will
    risk losing data from the file system. This command does not currently
    support shrinking snapshots or snapshot originals.
   
evms_pvscan
    Lists all current LVM PVs. This command also lists all other EVMS
    disks, segments, and regions, and marks each as "available" or
    "unavailable." Available objects can be used directly to create or
    extend volume groups.
   
evms_vgscan
    Lists all current LVM VGs. This command also contains a new option (-c)
    to force a commit, and the creation of all necessary device files in /
    dev. This creation of files is necessary for existing LVM setups that
    have not created any new LVs using the EVMS tools (unless devfs is
    enabled). The same results can also be accomplished by using the EVMS
    GUI and performing a commit.
   
evms_lvscan
    Lists all current LVM LVs. When an LV is listed as inactive that LV
    does not appear as a compatibility volume in EVMS, and it is not
    available for use through EVMS. The only way this can occur is if the
    LV was created in the EVMS GUI and a compatibility volume was not
    added. Use the GUI to perform the task of adding a compatibility volume
    to an inactive LV.
   
evms_pvdisplay
    Displays extra information about the specified PV.
   
evms_vgdisplay
    Displays extra information about the specified VG.
   
evms_lvdisplay
    Displays extra information about the specified LV.
   


Two commands have been removed from the set of LVM utilities. evms_pvcreate
and evms_pvremove are no longer necessary. The evms_pvscan command will now
display all LVM PVs as well as all other disks, segments, and regions in
EVMS, and label them as available or unavailable. Objects that are marked
as available can be used by evms_vgcreate without needing to call
evms_pvcreate.

As noted in the section called General Terms, EVMS uses different terms
than those used in LVM. However, the two sets of terms are comparable.
Volume groups (VGs) from LVM are called containers in EVMS. Because the LVM
plug-in is an EVMS Region Manager, its output objects (LVs in LVM) are
called regions. The input objects (PVs in LVM) are called segments, even
though region managers can actually take disks and other regions as inputs
as well. These command line utilities will often use the LVM and EVMS
terminology interchangeably, so these simple rules will hopefully prevent
confusion.

The options for each of the commands listed above should be the same as the
options from the related LVM commands. However, some options now have
slightly different meanings. For instance, the verbose option (-v) displays
additional information about the command to the user, but also opens the
Engine with DEBUG level messaging, so that additional information is
written to the Engine log (/var/log/evmsEngine.log). The debug option (-d)
displays the same amount of info to the user as the verbose option, but
opens the Engine with ENTRY_EXIT level messaging, which causes very
detailed trace information to be written to the Engine log. Also, some
options are currently silently ignored, because their functionality has not
been implemented yet, or because that functionality is not necessary in
EVMS. For instance, the auto-backup option (-A) is ignored because the LVM
plug-in does not yet make metadata backups.
---------------------------------------------------------------------------

Descriptions of EVMS Plug-Ins

The following sections explain the plug-ins available for EVMS.
---------------------------------------------------------------------------

Bad Block Replacement Feature Plug-In

Bad blocks are disk sectors that are unusable because any attempt to access
them will fail with an I/O error. The bad block replacement (BBR) feature
detects and corrects a bad block by remapping the sector to another sector
on the same disk. Disk sectors that are set aside for this mapping are
called replacement blocks because they are used by BBR to replace the bad
blocks. Once a bad block is remapped by BBR to a replacement block, a disk
access will not produce I/O errors.

When you configure a BBR storage object, an area on the disk is reserved by
the plug-in so that a supply of replacement blocks is guaranteed. BBR
consumes this supply of replacement blocks as it remaps bad blocks until no
more replacement blocks are available. When no more replacement blocks are
available, I/O to any new bad block will fail because the plug-in has no
replacement blocks to use for remapping the bad block.

You can create a BBR storage object by selecting an existing object and
providing a name for the new BBR storage object. The number of replacement
blocks and their location on disk are configured automatically by the BBR
plug-in. The number of replacement blocks is typically no more than a track
in size. When resizing a volume or storage object, a BBR storage object can
never become the shrink or expand point, so there are no resizing options
for this plug-in.
---------------------------------------------------------------------------

Default Segment Manager Plug-In

The Default Segment Manager plug-in is a disk partition manager that is
responsible for discovering and managing the following:

  * msdos disk partitions
   
  * embedded unixware slices
   
  * OS/2 partitions and dlat sectors
   
  * embedded bsd slices
   
  * embedded solarisx86 slices
   


A disk partition is an area on a disk with a starting address and size.
There are various types of partitions. Information about partitions is kept
in a structure called a partition record. Partition records are gathered in
structures called partition tables. These tables are stored on the disk so
that the disk partitions can be found by firmware, operating systems, and
disk partitioning tools.

The Default Segment Manager plug-in creates the segment storage objects
that map to disk partitions. When you create, destroy, or resize segment
storage objects, the Default Segment Manager reconstructs the disk
partition tables to reflect the changes and writes the new tables out to
disk when called to commit changes. The Default Segment Manager updates
msdos partition tables, embedded partition tables, and OS/2 dlat sectors.

When creating a segment storage object, you must choose from a list of
acceptable freespace segment objects. Freespace segment objects are used to
represent areas on the disk that are not being used by partitions or
partition tables. As segment storage objects are created, the available
sectors within the freespace are allocated to new partitions and partition
tables. Selecting a freespace storage object determines where the new
partition is created on the disk. After choosing a freespace segment, you
will need to make choices baced on the following configurations:

  * size - Value is sector count. Must be in cylinder size amounts.
   
  * offset - Value is sector count. This value allows you to offset the
    start of the new partition.
   
  * type - Value is an integer. This determines what kind of partition to
    create, defaults to Linux 0x83.
   
  * bootable - Value is YES or NO. Choose YES if you wish the partition to
    be marked active.
   
  * primary - Value is YES or NO. Choose YES if you wish to create a
    primary partition.
   


If you are creating a segment storage object on an OS/2 disk there are
three additional fields:

  * partition name - Value is a string. OS/2 partitions have names. There
    is a maximum of 20 characters
   
  * volume name - Value is a string. OS/2 logical volumes have a name.
    There is a maximum 20 characters.
   
  * drive letter - Value is of type char. OS/2 compatibility volumes have
    drive letters (A-Z).
   


When resizing a volume or storage object, a segment storage object may
become the shrink or expand point. When shrinking a segment storage object,
there is only one acceptable object, and it is the segment object itself. A
segment storage object can only be expanded if there are unused sectors
immediately following that object on the disk. These unused sectors are
called freespace. The system contains a freespace segment storage object
that maps unused sectors. When expanding a segment storage object, the only
acceptable object to expand is the freespace storage object that maps the
unused sectors immediately following the segment storage object.

Once you choose the acceptable object, for resizing the segment storage
object, you need to specify how many sectors you wish to expand or shrink
the segment object by. Since disk partitions fall on cylinder boundaries,
you will always be expanding or shrinking in cylinder size amounts to
preserve the ending cylinder boundary requirement.
---------------------------------------------------------------------------

DriveLinking Feature Plug-In

The DriveLinking plug-in is an aggregating plug-in. It produces a storage
object by binding together several smaller storage objects. The resulting
aggregate storage object is called a drive link storage object. The smaller
objects, that are consumed by the drive link object, are called drive link
child objects. Most EVMS storage objects can be used as child objects, such
as disks, regions and partitions.

A drive link storage object is an ordered collection of child objects. The
order of the collection is maintained by the DriveLink plug-in. When you
first create the drive link storage object, the order in which you pick the
child storage objects determines the order of the collection. The order is
preserved by saving a copy of the information on every child object. The
ordering information allows the plug-in to reassemble the child objects in
the same sequence every time. The ordering information also ensures that a
disk access will map to exactly the same disk sectors each and every time.

You can create a drive link storage object by selecting child objects for
the drive link and providing a name for the new drive link storage object.
When resizing a volume or storage object, a drive link storage object might
become the expand or shrink point. You can resize the volume or storage
object by selecting the expand or shrink objects and resizing that object.
   
   
    NOTE: A drive link storage object will only resize by adding or
    removing child objects at the end of the existing drive link. This
    limitation prevents any disruption with the ordering of child objects.


To expand the volume or storage object, select several objects from the
list of acceptable storage objects and these objects will be added at the
end of the existing drive link storage object. When shrinking a volume or
storage object, you can select several storage objects to remove from the
end of the drive link. A drive link storage object can only be shrunk by
removing the last child object in the drive link. If you are selecting
several child objects to shrink a drive link storage object, the order in
which you choose the objects is important. You must first choose the last
child object in the drive link. Next, choose the second to last child
object.
---------------------------------------------------------------------------

Multi-Disk Plug-In

The EVMS Multi-Disk (MD) plug-in provides support for Linux software RAID
volumes. The EVMS MD plug-in reads disks written by the native Linux MD
driver and writes the meta data for new RAID devices in the same format so
that the native Linux MD driver can read it.

The EVMS MD plug-in provides support for the linear, RAID0, RAID1, RAID4,
and RAID5 personalities of MD.

  * Linear support links a number of devices consecutively and makes them
    appear as one large device.
   
  * RAID0 provides striping across a number of devices.
   
  * RAID1 provides n-way mirroring. N-way mirroring means that each device
    contains a copy of the same data.
   
  * RAID4 and RAID5 provide striping with parity. Having the parity allows
    the data to be retrieved even if a device in the RAID fails. RAID4
    keeps all the parity on one device. RAID5 distributes the parity among
    the devices in one of four different algorithms.
   


The EVMS MD plug-in allows you to add or remove spare disks in RAID1,
RAID4, and RAID5 while RAID is running. The plug-in allows you to add or
remove devices in a RAID0 n-way mirror, while RAID is running. The plug-in
also allows you to remove devices from a RAID4 or RAID5 array while the
system us running as long as there is a spare device available to replace
the one you removed.

If you choose to use the EVMS MD plug-in, you should not use the Linux
native MD driver at the same time. Having two drivers manage your MD
devices can lead to data corruption.
---------------------------------------------------------------------------

SnapShot Feature Plug-In

Snapshots are "frozen" images of volumes. This means that they take an
image of a volume at a given instance in time and allow access to that
static instance even while the original volume is mounted and undergoing
modifications. The static image can be mounted as a different volume and
used for such processes such as backups.

In addition to the static capabilities, the EVMS SnapShot Plug-in allows
for snapshots to be created as read/write. This addition is, in essence, a
fork of the original volume. The new volume is a virtual copy of the
original that can be written to without affecting the original volume.
Snapshots can be created in any EVMS volume. It should be noted that the
actual start of the snapshotting does not occur until the snapshot object
is made into a volume. Also, reverting a snapshot volume disables the
snapshot and causes it to be reset. This behavior can be useful for a
volume that you regularly snapshot and backup.