Note: This is a beta release of Red Hat Bugzilla 5.0. The data contained within is a snapshot of the live data so any changes you make will not be reflected in the production Bugzilla. Also email is disabled so feel free to test any aspect of the site that you want. File any problems you find or give feedback here.
Bug 1364399 - lvconvert manpage references to --cachepolicy may be misleading
Summary: lvconvert manpage references to --cachepolicy may be misleading
Keywords:
Status: ASSIGNED
Alias: None
Product: Red Hat Enterprise Linux 7
Classification: Red Hat
Component: lvm2
Version: 7.3
Hardware: x86_64
OS: Linux
unspecified
low
Target Milestone: rc
: ---
Assignee: David Teigland
QA Contact: cluster-qe@redhat.com
URL:
Whiteboard:
Depends On:
Blocks:
TreeView+ depends on / blocked
 
Reported: 2016-08-05 09:32 UTC by Roman Bednář
Modified: 2018-10-26 21:45 UTC (History)
7 users (show)

Fixed In Version:
Doc Type: If docs needed, set a value
Doc Text:
Clone Of:
Environment:
Last Closed:


Attachments (Terms of Use)

Description Roman Bednář 2016-08-05 09:32:37 UTC
lvconvert manpage still contains several references to --cachepolicy option even though it has been removed recently.
Changes are related to BZ #1353759 and #1344120.

# lvs -a -o lvname,lvattr,pool_lv,cache_policy
  LV                 Attr       Pool         CachePolicy
  root               -wi-ao----                         
  swap               -wi-ao----                         
  [cache_pool]       Cwi---C---              cleaner    
  [cache_pool_cdata] Cwi-ao----                         
  [cache_pool_cmeta] ewi-ao----                         
  cachelv            Cwi-a-C--- [cache_pool] cleaner    
  [cachelv_corig]    owi-aoC---                         
  [lvol0_pmspare]    ewi-------                         
  [lvol0_pmspare]    ewi-------   
    
No longer supported:
# lvconvert --cachepolicy smq vg/cachelv
  Operation not permitted on cache LV vg/cachelv.
  Operations permitted on a cache LV are:
  --splitcache
  --uncache
  --splitmirrors (operates on mirror or raid sub LV)
  --type thin-pool

Recommended:
# lvchange --cachepolicy smq vg/cachelv
    Logical volume vg/cachelv changed.



3.10.0-481.el7.x86_64

lvm2-2.02.162-1.el7    BUILT: Fri Jul 29 09:26:36 CEST 2016
lvm2-libs-2.02.162-1.el7    BUILT: Fri Jul 29 09:26:36 CEST 2016
lvm2-cluster-2.02.162-1.el7    BUILT: Fri Jul 29 09:26:36 CEST 2016
device-mapper-1.02.132-1.el7    BUILT: Fri Jul 29 09:26:36 CEST 2016
device-mapper-libs-1.02.132-1.el7    BUILT: Fri Jul 29 09:26:36 CEST 2016
device-mapper-event-1.02.132-1.el7    BUILT: Fri Jul 29 09:26:36 CEST 2016
device-mapper-event-libs-1.02.132-1.el7    BUILT: Fri Jul 29 09:26:36 CEST 2016
device-mapper-persistent-data-0.6.3-1.el7    BUILT: Fri Jul 22 12:29:13 CEST 2016
cmirror-2.02.162-1.el7    BUILT: Fri Jul 29 09:26:36 CEST 2016

Comment 2 Zdenek Kabelac 2016-08-05 20:46:29 UTC
When the volumes are converted to  cachepool - user can specify  --cachepolicy.
ATM you just can't 'change' it for existing cachepool - that's  'lvchange' operation.

So the title of BZ is misleading - lvconvert clearly needs to document '--cachepolicy' option.

Future version of lvconvert might possibly route 'change' operation implicitly.

Comment 3 Alasdair Kergon 2016-08-17 17:49:14 UTC
The current man page states:

       lvconvert --type cache VG/StripedLV
       · Convert StripedLV to type cache.
       · Requires --cachepool to specify the cache pool to use.
       · Options --cachepolicy, --cachesettings.

       lvconvert --type cache VG/RaidLV
       · Convert RaidLV to type cache.
       · Requires --cachepool to specify the cache pool to use.
       · Options --cachepolicy, --cachesettings.

       lvconvert --type cache VG/ThinPoolLV
       · Convert the data portion of ThinPoolLV to type cache.
       · Operates on the data sub LV of the thin pool LV.
       · Options --cachepolicy, --cachesettings.

       --cachepolicy Policy
              Specifies the cache policy for a cache LV.  Also see lvmcache(7).

I'm not sure what you're suggesting needs changing, but I find "to type cache" misleading - it's not meant to actually make the LV into a cache, is it, but rather to cache the contents of the LV?  Would it be better to talk about using the cache pool to cache the contents of the LV in question or to make this '--type cached'?

Comment 4 David Teigland 2016-08-17 18:24:05 UTC
> I find "to type
> cache" misleading - it's not meant to actually make the LV into a cache, is
> it, but rather to cache the contents of the LV?  Would it be better to talk
> about using the cache pool to cache the contents of the LV in question or to
> make this '--type cached'?

There's no doubt the nomenclature here is annoying and confusing, but it was carefully discussed and officially defined back in Feb 2014.  That discussion happened when we were going through the initial drafts of the lvmcache(7) man page and defining the terms that we would use throughout the man page.

Actually, I originally suggested the same as you're suggesting above (I used "cached LV" and "CachedLV" terms in first drafts of the man page.)  However, at some point we found a problem with these terms, and I forget exactly what that was.  It might have been that the word "cached" did not match the type name "cache", but I'm not sure any more.

We could of course reopen this discussion and consider changing the term to something different, but this would need to be done carefully, updating as many places together as possible.

Comment 5 Zdenek Kabelac 2016-08-18 07:58:09 UTC
While it probably would be useful to talk about 'cached LV'   the --type  itself is rather derived/associated with kernel target name  (the original meaning of --type).

Hence that's why --type is seen as low-level manipulation option (approaching 'dmsetup' level).

While there is no 'cache-pool' kernel target type and this type rather serves layering support for lvm2 code to allow 1-by-1 construction, the 'cache' type itself is tied to  'cache' target visible in  'dmsetup table'.

Personally I'd prefer to talk about 'cached LV' in man pages - as IMHO I do not see much confusion especially when would stayed with '-H' shortcut with a meaning 'I want to have this LV to be cached one'.

But I understand mild level of confusion when we say:
cached LV is build with --type cache  - but it's probably how to explain the connection between 'segment types'  and real user visible LV.

We may possibly add acceptance of 'synonyms' so  --type cached  could be translated to  '--type cache' - but since we then would report segtype
as 'cache' - it doesn't look much helpful either...

The core of  explanation should focus on exposing the fact there
is  'origin LV' (which gets cached -  so we talk about cached LV)
and there is segment type cache - which actually handles caching.

But saying this - we would clearly put a lot of details on a user which in reality doesn't care that much about the 'engine under-deck'

Comment 6 Roman Bednář 2016-08-18 11:23:39 UTC
As mentioned in Comment 2, the title is misleading, I did not realize the --cachepolicy option is still used for conversion.
But what I would like to see in the docs is some better explanation in this section:

--cachepolicy Policy
              Specifies the cache policy for a cache LV.  Also see lvmcache(7).


Since the 'lvconvert --cachepolicy' by itself no longer works, how about adding a sentence like: 'For changing a policy on existing cache LV refer to lvchange(8).'

And the following:

>I'm not sure what you're suggesting needs changing, but I find "to type
>cache" misleading - it's not meant to actually make the LV into a cache, is
>it, but rather to cache the contents of the LV?

Good point. It behaves exactly as you said. So this section is a bit confusing too.
It's also missing the 'Requires' section like it's written with other examples:
'Requires --cachepool to specify the cache pool to use.'


Note You need to log in before you can comment on or make changes to this bug.