EVMS Release 2.1.1
==================

See the INSTALL file for installation instructions.

See the Users-Guide at http://evms.sourceforge.net/users_guide/ for detailed
usage information.

Important notes concerning this release:

1. Move / Replace

   Currently, all "move" and "replace" operations must be performed while the
   volume is offline/unmounted. The necessary kernel support for online moves
   is not yet complete. EVMS will support online move in a future release.

2. Snapshotting

   Snapshot Reset:

   Snapshot volumes can now be reset without deleting and recreating the volume
   on top of the snapshot object. This command will reset the snapshot to the
   current state of the origin volume. It may only be performed if the snapshot
   volume is unmounted.

   Snapshot Rollback:

   Snapshot volumes can now be "rolled-back" onto their origin volume. This
   function copies the saved contents of the snapshot back to the origin. Both
   the snapshot and the origin volume must be unmounted to perform this
   function, and must remain unmounted until the rollback is complete.

   Other snapshot notes:

   Snapshots cannot be taken of compatibility or EVMS volumes that are made
   directly from MD regions or full disks. In order to take a snapshot of a
   volume, the top object in that volume must be a Device-Mapper-managed
   device. This is necessary because that object's mapping must be modified
   to include hooks for copy-on-write to the snapshot device. Since RAID
   objects are handled by the MD kernel driver, and full disks are managed
   by the IDE or SCSI drivers, their "mappings" cannot change.

   For now, the snapshot plugin will simply not give the option of taking
   snapshots of these types of volumes. Future releases of EVMS will try to
   get around this restriction.

   In addition, snapshots currently only work on 2.4 kernels. The snapshot
   module for Device-Mapper has not yet been ported to the 2.5 kernel. If
   you need snapshotting, please use a 2.4 kernel.

3. Software-RAID

   If you have existing Software-RAID devices that you would like to migrate
   to using EVMS, please make sure you are not using RAID auto-detect. EVMS
   requires volume discovery to be done in user-space. Having the kernel
   auto-detect just the RAID arrays will cause some inconsistencies in the
   RAID superblocks.

   If you are using auto-detect, you will need to use fdisk to change the
   partition types from 0xfd to 0x83.

   RAID-1 Reconfigure

   This new function allows a new object to be added as an active member to a
   RAID-1 region. In effect, this allows changing an n-way mirror to an n+1-way
   mirror.

   RAID-1 Resize

   This new function allows a RAID-1 region to be resized if all of its child
   objects can be resized.

   RAID-Linear Resize

   This new function allows a RAID-linear region to be resized in three possible
   ways. The last child object may be resized (if allowed by that object's
   plugin), an entirely new object may be added to the end of the linear region,
   or the last child object may be removed from the linear region.

   Restrictions:

   There is an unfortunate restriction for the three new RAID functions just
   described. To explain this, it's best to start by describing some of the
   core differences between the RAID driver and Device-Mapper (the term MD will
   not be used here to avoid naming confusion with Device-Mapper (DM)).

   A DM device has a mapping to some lower-level device(s). This mapping can be
   changed "online". This is done by temporarily suspending I/O to the device,
   replacing the existing mapping with a new mapping, and resuming the suspended
   I/O. This is the process used, for example, when expanding a volume.

   The RAID driver can also be thought of as having a mapping to lower-level
   devices. However, the RAID driver has no way to change this mapping "online",
   because it has no way to suspend I/O to its device while it changes the map.
   Thus, the only way to change this map (e.g. to expand a RAID or to add a new
   active member) is to deactivate the RAID device, write new superblocks
   indicating the change in the device, and reactivate the RAID device. On the
   surface this doesn't sound too bad. However, the key is knowing that the RAID
   driver will refuse to deactivate a device that is open. This is the case if
   the device is mounted, or the device is in use by a higher level device, 
   which will happen if you have LVM on top of RAID (as is your case).

   Therefore, there will be some restrictions on when raid-reconfig and 
   raid-resize can be used. These functions are allowed on a RAID object that is
   not a volume, or on a RAID object that is a compatibility volume and is not
   mounted. These function are currently NOT allowed on a RAID object that is an
   EVMS volume, or on a RAID object that is consumed by another plugin's
   object (such as LVM), because in these situations the RAID device will have
   a Device-Mapper device on top of it.

   Clearly, this is a pretty horrible restriction, but it is currently due to 
   limitations of the RAID driver. There has been talk of "porting" the RAID 
   driver to use Device-Mapper. However, this work definitely won't begin until
   the 2.7 kernel, which is not much help in the immediate future.

4. Multipath

   A new MD multipath plug-in has been added to EVMS. This plug-in allows you
   to identify multipath devices and create an MD volume that aggregates the
   multipath devices as a single volume. To configure multipath you choose
   Create Region and then choose MD Multipath. The multipath plug-in will
   present a list of storage objects from which you are expected to identify
   the multipath objects. Select all of the multipath devices! During the
   selection process, the multipath plug-in will perform several tests to
   validate the objects selected. If you choose a storage object that does not
   appear to be a multipath, the plug-in will reject the storage object,
   returning an invalid media type error message. After you have chosen all the
   storage objects for your MD multipath region, you have the option of
   configuring the MD volume to support either a Simple Failover or Simple Load
   Balancing I/O policy. Commiting the multipath region will lay down an MD
   super block on the physical device and the MD volume will be activated with
   a START_ARRAY call to the kernel.

   If you choose simple failover, just a single device will be marked active
   and the remaining devices will be marked as spare paths. At runtime, if the
   active path returns an I/O error a spare path will automatically be
   activated and the I/O will be retried on the newly activated path. The path
   on which the I/O failed will be marked faulty. Simple load balancing works
   by marking all the selected objects as active I/O paths with runtime efforts
   to send I/O to the least active path. If an I/O fails in a simple load
   balance configuration it will be retried on one of the remaining active
   paths. Just like simple failover, the path on whch the I/O failed will be
   marked faulty.   

   If a path fails and you rerun the engine it will probably complain that the
   information in the super block is incorrect. The number of devices will be
   wrong for starters because the engine could not read a super block off the
   failed device. When asked if you wish to FIX the information you should
   always decline. Instead ... you should locate the failed path and figure out
   why and fix it. The next time you run the engine it should complain that the
   multipath volume is running degraded because it sees a faulty device listed
   and ... now ... you should go ahead and tell the engine to fix the super
   blocks. It will do so by updating the super blocks and then STOP/START the
   MD raid volume. Currently, this can only be done while the volume is
   unmounted.

