Bug 815680

Summary: Update of man page to reflect new thinp functionality
Product: Red Hat Enterprise Linux 6 Reporter: Nenad Peric <nperic>
Component: lvm2Assignee: LVM and device-mapper development team <lvm-team>
lvm2 sub component: Manual pages and Documentation (RHEL6) QA Contact: Cluster QE <mspqa-list>
Status: CLOSED ERRATA Docs Contact:
Severity: low    
Priority: high CC: agk, cmarthal, dwysocha, heinzm, jbrassow, jchaloup, msnitzer, ovasik, prajnoha, prockai, pschiffe, thornber, zkabelac
Version: 6.3Keywords: ManPageChange
Target Milestone: rc   
Target Release: ---   
Hardware: Unspecified   
OS: Unspecified   
Whiteboard:
Fixed In Version: lvm2-2.02.107-2.el6 Doc Type: Enhancement
Doc Text:
Man pages have been added to cover the LVM topics of thin-provisioning and caching (i.e. "tiered storage"). The new man pages are 'lvmthin(7)' and 'lvmcache(7)'.
Story Points: ---
Clone Of: Environment:
Last Closed: 2014-10-14 08:22:54 UTC Type: Bug
Regression: --- Mount Type: ---
Documentation: --- CRM:
Verified Versions: Category: ---
oVirt Team: --- RHEL 7.3 requirements from Atomic Host:
Cloudforms Team: --- Target Upstream Version:
Embargoed:
Bug Depends On:    
Bug Blocks: 1119576    

Description Nenad Peric 2012-04-24 09:02:02 UTC
Description of problem:

The current man pages are not descriptive enough to cover all the functionality and intricacies of thin provisioning. 

A suggested man page update was proposed in Bug #773507 which would provide for more space and better explanation of the new functionality. 


A copy of comment #17 follows:

-------

I've discussed some variations of man page part for thinp with Nate and we came
up with a suggestion on how to make things much clearer in MAN of lvcreate:
It will make the whole thinp idea more coherent and will avoid "chicken and the
egg" confusion some people who dive right in might experience. 


-T, --thin, --thinpool ThinPoolLogicalVolume{Name|Path}
    Creates  thin  pool or thin logical volume or both. See THIN PROVISIONING.




...

THIN PROVISIONING

Thin provisioning allows for the creation of logical volumes larger than
available extents.  First create a pool then create a volume in the pool.

To create a thin pool ...
    Options, examples, interaction with other LVM options

To create a logical volume in the thin pool...
    Options, examples, interaction with other LVM options 

To create a thin logical volume and pool at the same time... 
    Options, examples, interaction with other LVM options

Comment 2 Zdenek Kabelac 2012-04-24 11:24:22 UTC
Hmm - it doesn't fit current layout of lvcreate man page - since we don't have separate section for mirrors/raids, snapshot.

I'd still prefer to keep things described rather with option itself.
Otherwise the man-page might start to look probably even less readable than it's today i.e. having multiple example sections...

Would there be also proposal to preserve current layout ?

(Since there might be in future some tool to generate man page from set of options)

Comment 3 Nenad Peric 2012-04-24 12:50:35 UTC
The layout with a separate section was just a suggestion for making the description of thin provisioning works separate actually from the options themselves, to try and maybe avoid some cluttering of text. 

Any kind of more detailed description of what the options do, how they combine  and what is the idea behind lvm thin provisioning (possibly with a few nice examples) would be all-right I suppose.

Comment 4 RHEL Program Management 2012-05-03 05:22:07 UTC
Since RHEL 6.3 External Beta has begun, and this bug remains
unresolved, it has been rejected as it is not proposed as
exception or blocker.

Red Hat invites you to ask your support representative to
propose this request, if appropriate and relevant, in the
next release of Red Hat Enterprise Linux.

Comment 6 RHEL Program Management 2012-07-10 08:25:17 UTC
This request was not resolved in time for the current release.
Red Hat invites you to ask your support representative to
propose this request, if still desired, for consideration in
the next release of Red Hat Enterprise Linux.

Comment 7 RHEL Program Management 2012-07-10 23:57:44 UTC
This request was erroneously removed from consideration in Red Hat Enterprise Linux 6.4, which is currently under development.  This request will be evaluated for inclusion in Red Hat Enterprise Linux 6.4.

Comment 12 Zdenek Kabelac 2014-06-09 11:35:10 UTC
Latest release of  lvm2  provides:

man  lvmthin

and same will apply to cache support:

man lvmcache


These pages will provide more in-depth description of thin and cache functionality with another set of examples.

Comment 23 Nenad Peric 2014-07-22 12:46:46 UTC
Detailed man pages of lvm thin provisioning and lvm caching have been created as lvmcaache and lvmthin.
They are referred to at the end of the following man pages as well:

/usr/share/man/man8/lvm.8.gz
/usr/share/man/man8/lvconvert.8.gz
/usr/share/man/man8/lvchange.8.gz
/usr/share/man/man8/lvcreate.8.gz

and the main man pages:

/usr/share/man/man7/lvmcache.7.gz
/usr/share/man/man7/lvmthin.7.gz

Marking VERIFIED with:

lvm2-2.02.107-2.el6    BUILT: Fri Jul 11 15:47:33 CEST 2014
lvm2-libs-2.02.107-2.el6    BUILT: Fri Jul 11 15:47:33 CEST 2014
lvm2-cluster-2.02.107-2.el6    BUILT: Fri Jul 11 15:47:33 CEST 2014
udev-147-2.56.el6    BUILT: Fri Jul 11 16:53:07 CEST 2014
device-mapper-1.02.86-2.el6    BUILT: Fri Jul 11 15:47:33 CEST 2014
device-mapper-libs-1.02.86-2.el6    BUILT: Fri Jul 11 15:47:33 CEST 2014
device-mapper-event-1.02.86-2.el6    BUILT: Fri Jul 11 15:47:33 CEST 2014
device-mapper-event-libs-1.02.86-2.el6    BUILT: Fri Jul 11 15:47:33 CEST 2014
device-mapper-persistent-data-0.3.2-1.el6    BUILT: Fri Apr  4 15:43:06 CEST 2014
cmirror-2.02.107-2.el6    BUILT: Fri Jul 11 15:47:33 CEST 2014

Comment 25 errata-xmlrpc 2014-10-14 08:22:54 UTC
Since the problem described in this bug report should be
resolved in a recent advisory, it has been closed with a
resolution of ERRATA.

For information on the advisory, and where to find the updated
files, follow the link below.

If the solution does not work for you, open a new bug report.

http://rhn.redhat.com/errata/RHBA-2014-1387.html