Bug 1269893 - Clarify -l|--extents option in lvcreate man page
Clarify -l|--extents option in lvcreate man page
Status: CLOSED ERRATA
Product: Red Hat Enterprise Linux 7
Classification: Red Hat
Component: lvm2 (Show other bugs)
7.2
x86_64 Linux
unspecified Severity low
: rc
: ---
Assigned To: David Teigland
cluster-qe@redhat.com
:
Depends On:
Blocks: 1295577 1356151
  Show dependency treegraph
 
Reported: 2015-10-08 08:36 EDT by Roman Bednář
Modified: 2016-11-04 00:11 EDT (History)
14 users (show)

See Also:
Fixed In Version: lvm2-2.02.161-1.el7
Doc Type: Enhancement
Doc Text:
Story Points: ---
Clone Of:
: 1356151 (view as bug list)
Environment:
Last Closed: 2016-11-04 00:11:01 EDT
Type: Bug
Regression: ---
Mount Type: ---
Documentation: ---
CRM:
Verified Versions:
Category: ---
oVirt Team: ---
RHEL 7.3 requirements from Atomic Host:
Cloudforms Team: ---


Attachments (Terms of Use)

  None (edit)
Description Roman Bednář 2015-10-08 08:36:58 EDT
Description of problem:

The current behavior of lvcreate does not exactly correspond to the description in man page:

" When expressed  as  a  percentage, the  number  is  treated  as  an approximate upper limit for the
total number of physical  extents  to  be  allocated  (including extents used by any mirrors, for example). "

The requested functionality would enable a user to request the total (maximum) free space in VG in percentage, which the lvcreate will take,
including all the legs, logs and metadata. The percentage requested then, would be the total taken by all the elements needed to assemble the required LV.

This behavior would also be useful for scripting, because it's a more predictable behavior than current one in some cases.
Additionally the new way of creating LVs should never fail even when user requests a 100% of FREE/VG.

 
Expected results (example):
lvcreate -l30%FREE -m1 vg

This should take the 30% of FREE space in total, creating a public LV of ~15% made available to the user, and a mirror leg (private LV) required for it
at around ~15% as well.
Comment 2 mulhern 2016-04-22 11:37:27 EDT
Could you specify what is current behaviour, please?
Comment 3 Roman Bednář 2016-04-25 04:52:57 EDT
example:
# vgs
  VG            #PV #LV #SN Attr   VSize  VFree 
  ...
  vg              2   0   0 wz--n- 79.98g 79.98g

# lvcreate -l50%FREE -m1 vg
  Logical volume "lvol0" created.

# vgs
  VG            #PV #LV #SN Attr   VSize  VFree 
  ...
  vg              2   1   0 wz--n- 79.98g     0 

>all space taken even if we would intend taking only 50% of the volume group


With current behaviour we do not have an option to limit the command to 50% of the VG in example above. Moreover this behaviour does not exactly match with man page as I mentioned already.
Comment 4 Zdenek Kabelac 2016-04-25 05:06:37 EDT
The  '--size|-l' option is quite clearly defined as a size of some  user available volume.

Which means in case of 3 legged mirror and  -l50%VG  that expectation that you would see allocates only 50% of VG size for whole WHOLE mirror are clearly wrong.

You commanded lvm2 to create LV with size of 50% of you VG, but and then you want to have 2 extra legs which also should be 50% of VG each  -  and this is the exact meaning and it's the 2nd sentence in man page:  The total number  of  physical  extents  allocated will  be  greater  than this, for example, if the volume is mirrored.

The best lvm2 can do in this case - is to try decreasing size of LV so all 3 legs will fit your VG - but this clearly ends with 100%VG used.

As said we do not yet provide option like i.e.  --totalsize 
where you would be able to control sum of all created LV within a one lvm2 command (and ATM it would be somewhat difficult to implement for all layers)
Comment 5 Roman Bednář 2016-04-25 08:30:48 EDT
I was not trying to question the logic behind this behaviour. I tried to propose having a new option here, but if you believe it would be too difficult to implement and it would not pay off for this use case, we can leave it like this. However I think improving a bit on documentation would be a good idea in either case, to make it more clear for users.

In man lvcreate (section -l, --extents):

1) change the last sentence so it's not logically conflicting with the second sentence:

   "The  total  number  of physical  extents  allocated  will be greater than this, for example, if the volume
    is mirrored." - OK
   ...
   "When expressed as a percentage, the number is treated  as  an  approximate  upper  limit  for  the total
    number of physical extents to be allocated 
    >(including extents used by any mirrors, for example)." - WRONG

2) add some example(s) here or to the "Examples" section in the end of manpage, where combinations of 
   %{VG|FREE|....} and raid/mirrors would be shown.
Comment 6 mulhern 2016-04-25 08:53:14 EDT
Comment #4:
There is no plausible interpretation of the sentence:

" When expressed  as  a  percentage, the  number  is  treated  as  an approximate upper limit for the
total number of physical  extents  to  be  allocated  (including extents used by any mirrors, for example). "

other than to mean,
---
if I say 50% of the VG's free space, then the total number of physical extents to be allocated for the new volume will be bounded by a value which is 50% of the VG's free space. Consequently, if the new volume is a 2-way mirror, then the number of logical extents in the volume, will be less than 1/2 * 50% of the free space in the VG, i.e, 25% of the free space in the VG.
---

AFAICT, that is how both Roman and I have interpreted it.

If that is not what is intended, or what it was designed to do, then the description definitely needs to be clarified.

What makes this even more confusing is that the other lv* commands that use --extents options seem to be in transition from the old way, which works more or less as you describe lvcreate working to the new way (what the documentation says lvcreate does).

"N.B. In a future release, when expressed as a percentage with PVS, VG or FREE, the number will be treated as an approximate total number of physical extents to be allocated or freed (including extents used by any mirrors, for example).  The code may currently allocate or remove more space than you might otherwise expect." (From lvresize's --extents documentation).
Comment 7 mulhern 2016-05-03 08:55:09 EDT
AFAICT, the current --extents option is always used to specify the number of _logical_ extents in the logical volume to be created, extended, etc.

Since lvm already has a precise vocabulary of physical and logical extents which it uses consistently in documentation, it seems like a better choice than a --totalsize flag, which has a vague meaning, is simply to make two new options,
* --logicalextents - with same actual meaning as --extents and with --extents retained for backward compatibility
* --physicalextents - with the new meaning of "allocate the number of physical extents specified to make the best possible logical volume (according to the defaults set up in the configuration file and wherever else lvm allows for configuration/profile info)".

Each of these would retain the syntax that --extents now has, i.e., an actual count of extents or the various %options.

I feel that this would be a significant benefit for scripted use of lvm, where getting approximately the storage layout desired, but avoiding failure of the script, without having loops or multiple retries to get it right is very important.
Comment 8 Alasdair Kergon 2016-05-03 09:02:55 EDT
Yes, the reason the percent options all lead to setting the number of logical extents desired is because that has a simple implementation whereas what you're asking for with a total physical amount is considerably more complicated to implement and is unlikely to happen any time soon (if ever).
Comment 9 Zdenek Kabelac 2016-05-03 09:03:04 EDT
Before this will go any further - there are plans in this direction:

Add support for --size  suffix 'X|x' meaning 'logical eXtent size'.
(as bskmgetp are already used)

This way any --size argument would also work with logical extent size without the necessity to double number of other '--size' options we already have and provide matching --extents for every one of them.

So -l will remain - but no more similar ones will be added.

Also -L% is supposed to be working then.
Comment 10 Alasdair Kergon 2016-05-03 09:51:23 EDT
Now look at lvresize too and commit b359b86f88642888116d54d4204d367664fbdcf.  We should revisit this and see if we can document the current state more clearly.

    Start to convert percentage size handling in lvresize to the new
    standard.  Note in the man pages that this code is incomplete.
    
    This is what I am aiming for:
    
    -l<extents>
    -l<percent> LV/ORIGIN
        sets or changes the LV size based on the specified quantity
        of logical logical extents (that might be backed by
        a higher number of physical extents)

    -l<percent> PVS/VG/FREE
        sets or changes the LV size so as to allocate or free the
        desired quantity of physical extents (that might amount to a
        lower number of logical extents for the LV concerned)
    
    -l+50%FREE - Use up half the remaining free space in the VG when
        carrying out this operation.
    
    -l50%VG - After this operation, this LV should be using up half the
        space in the VG.
    
    -l200%LV - Double the logical size of this LV.
    
    -l+100%LV - Double the logical size of this LV.
    
    -l-50%LV - Reduce the logical size of this LV by half.
Comment 11 mulhern 2016-05-03 12:59:56 EDT
"We should revisit this and see if we can document the current state more clearly."

I think that would be helpful. Note that this misunderstanding that Roman and I shared also seems to have been shared by the RHEL7 LVM manual documenters:
"""
When you specify a percentage of the space in a volume group to allocate to a logical volume, that includes the total allocation for the logical volume, including any associated metadata volumes such as are required for thin, cache, raid, and mirror volumes.
"""
- from Section 4.4.1: Creating Linear Volumes.

I've looked over the commit message in Comment#10, and I think I understand it.

I believe that it could be made clearer if whether the argument related to the physical or logical size and whether the result related to the physical or logical size could be emphasized very strongly.

The last example, "reduce the logical size of this LV by half" is short for "the final _logical_ size of the LV will be 50% of the initial _logical_ size of the LV". But -l<percent> PVS/VG/FREE means "the _physical_ extents allocated for this lv will be <percent> of the _physical_ extents of the PVS/VG/FREE". 

Probably, '-l<percent> LV/ORIGIN" means "the final _logical_ size of the LV will be <percent> of the _logical_ size of the origin lv' ?

===============================================================================

Are you saying in comment #8 that it will be difficult for lvm to satisfy a request for a precise physical _number_ of extents to form an lv, whereas if the request for physical size is specified in terms of a percentage, and a best effort attempt to approach, but never exceed that percentage, the request is easier to satisfy? Would the documentation ever express some kind of lower bound guarantee? Right now, allocating an lv of size zero would always meet the specification in the man pages, since the only bound mentioned is an upper one.
Comment 14 David Teigland 2016-07-06 12:37:15 EDT
Pushed out this rewording:

       -l|--extents LogicalExtentsNumber[%{VG|PVS|FREE|ORIGIN}]
              The size of the new LV in logical  extents.   The  number  of
              physical  extents  allocated may be different, and depends on
              the LV type, e.g.  mirroring.  The number of logical  extents
              can  also  be expressed as a percentage of the total space in
              the Volume Group with the suffix %VG, as a percentage of  the
              remaining  free  space  in  the  Volume Group with the suffix
              %FREE, as a percentage of the remaining free  space  for  the
              specified  PhysicalVolume(s)  with the suffix %PVS, or (for a
              snapshot) as a percentage of the total space  in  the  Origin
              Logical  Volume with the suffix %ORIGIN (i.e. 100%ORIGIN pro‐
              vides space for the whole origin).  When expressed as a  per‐
              centage, the number is treated as an approximate upper limit,
              and the actual size of the LV (in  logical  extents)  may  be
              less.
Comment 15 mulhern 2016-07-07 13:25:12 EDT
A rewording of the first two sentences:

Specifies the number of logical extents for the new LV. The number of physical extents may be greater, to accomodate metadata and to support features such as redundancy.

Reasons:
1. Most of the entries start with verbs, some even start with "Specifies".
2. I'm guessing that the number of physical extents can be greater than the number of logical extents, but may not be less. If both are possible, then it would probably be best to say so explicitly.
3. There is no LV type called "mirroring", strictly speaking, so it shouldn't be used as an example of an LV type.

The remaining sentences:

An alternate syntax allows one to specify an upper bound on the size of the new LV as a percentage of the size of a related VG, LV, or set of PVs. The new LV will contain the maximum number of logical extents such that their combined size does not exceed the specified upper bound.

The suffix %VG denotes the total size of the VG, the suffix %FREE the remaining free space in the VG, and the suffix %PVS the free space in the specified Physical Volumes. 

For a snapshot, the upper bound can be expressed as a percentage of the total size in the Origin Logical Volume with the suffix %ORIGIN.

Reasons:
*. Too many parentheses and a very long sentence.
*. Snapshots are special.
*. The alternate syntax does not actually specify the number of extents, it specifies a size. So the man page should say that, even if it is cumbersome.
Comment 16 David Teigland 2016-07-07 14:11:39 EDT
Thanks, I've applied some of those suggestions.

       -l|--extents LogicalExtentsNumber[%{VG|PVS|FREE|ORIGIN}]
              Specifies the size of the new LV in logical extents.  The number
              of  physical  extents allocated may be different, and depends on
              the LV type.  Certain LV types require more physical extents for
              data  redundancy  or  metadata.   An alternate syntax allows the
              size to be determined indirectly as a percentage of the size  of
              a  related  VG,  LV,  or set of PVs.  The suffix %VG denotes the
              total size of the VG, the suffix %FREE the remaining free  space
              in  the  VG, and the suffix %PVS the free space in the specified
              Physical Volumes.  For  a  snapshot,  the  upper  bound  can  be
              expressed  as a percentage of the total size of the Origin Logi‐
              cal Volume with the suffix %ORIGIN  (100%ORIGIN  provides  space
              for the whole origin).  When expressed as a percentage, the num‐
              ber is treated as an approximate upper limit, and the final size
              of the LV is not known until the command is complete.
Comment 17 mulhern 2016-07-07 14:59:54 EDT
Thank you for considering the suggestions:

Follow up:

^For a snapshot, the upper bound^For a snapshot, the size

also, for last line:

When expressed as a percentage, the size defines an upper limit for the
number of logical extents in the new LV. The precise number of logical extents in the new LV is not determined until the command has completed.

Reasons:
1. Say logical extents to remind users that they are indirectly specifying logical not physical size.
2. Omit approximate, it makes it sound like the new LV could be larger than the specified limit. But, leave it in if it actually could be larger.
Comment 18 David Teigland 2016-07-07 18:22:12 EDT
       -l|--extents LogicalExtentsNumber[%{VG|PVS|FREE|ORIGIN}]
              Specifies the size of the new LV in logical extents.  The number
              of  physical  extents allocated may be different, and depends on
              the LV type.  Certain LV types require more physical extents for
              data  redundancy  or  metadata.   An alternate syntax allows the
              size to be determined indirectly as a percentage of the size  of
              a  related  VG,  LV,  or set of PVs.  The suffix %VG denotes the
              total size of the VG, the suffix %FREE the remaining free  space
              in  the  VG, and the suffix %PVS the free space in the specified
              Physical Volumes.  For a snapshot, the size can be expressed  as
              a percentage of the total size of the Origin Logical Volume with
              the suffix %ORIGIN (100%ORIGIN provides space for the whole ori‐
              gin).  When expressed as a percentage, the size defines an upper
              limit for the number of logical extents in the new LV. The  pre‐
              cise  number  of logical extents in the new LV is not determined
              until the command has completed.
Comment 20 Roman Bednář 2016-07-13 06:01:10 EDT
Adding QA ack for 7.3.
Comment 22 Corey Marthaler 2016-09-14 19:19:55 EDT
Marking verified in the latest rpms. What was provided in comment #18 is what is in the current lvcreate(8).


3.10.0-501.el7.x86_64
lvm2-2.02.165-2.el7    BUILT: Wed Sep 14 09:01:43 CDT 2016
lvm2-libs-2.02.165-2.el7    BUILT: Wed Sep 14 09:01:43 CDT 2016
lvm2-cluster-2.02.165-2.el7    BUILT: Wed Sep 14 09:01:43 CDT 2016
device-mapper-1.02.134-2.el7    BUILT: Wed Sep 14 09:01:43 CDT 2016
device-mapper-libs-1.02.134-2.el7    BUILT: Wed Sep 14 09:01:43 CDT 2016
device-mapper-event-1.02.134-2.el7    BUILT: Wed Sep 14 09:01:43 CDT 2016
device-mapper-event-libs-1.02.134-2.el7    BUILT: Wed Sep 14 09:01:43 CDT 2016
device-mapper-persistent-data-0.6.3-1.el7    BUILT: Fri Jul 22 05:29:13 CDT 2016
Comment 24 errata-xmlrpc 2016-11-04 00:11:01 EDT
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.

https://rhn.redhat.com/errata/RHBA-2016-1445.html

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