RHEL Engineering is moving the tracking of its product development work on RHEL 6 through RHEL 9 to Red Hat Jira (issues.redhat.com). If you're a Red Hat customer, please continue to file support cases via the Red Hat customer portal. If you're not, please head to the "RHEL project" in Red Hat Jira and file new tickets here. Individual Bugzilla bugs in the statuses "NEW", "ASSIGNED", and "POST" are being migrated throughout September 2023. Bugs of Red Hat partners with an assigned Engineering Partner Manager (EPM) are migrated in late September as per pre-agreed dates. Bugs against components "kernel", "kernel-rt", and "kpatch" are only migrated if still in "NEW" or "ASSIGNED". If you cannot log in to RH Jira, please consult article #7032570. That failing, please send an e-mail to the RH Jira admins at rh-issues@redhat.com to troubleshoot your issue as a user management inquiry. The email creates a ServiceNow ticket with Red Hat. Individual Bugzilla bugs that are migrated will be moved to status "CLOSED", resolution "MIGRATED", and set with "MigratedToJIRA" in "Keywords". The link to the successor Jira issue will be found under "Links", have a little "two-footprint" icon next to it, and direct you to the "RHEL project" in Red Hat Jira (issue links are of type "https://issues.redhat.com/browse/RHEL-XXXX", where "X" is a digit). This same link will be available in a blue banner at the top of the page informing you that that bug has been migrated.
Bug 1218769 - Document LVM Selection Criteria
Summary: Document LVM Selection Criteria
Keywords:
Status: CLOSED CURRENTRELEASE
Alias: None
Product: Red Hat Enterprise Linux 7
Classification: Red Hat
Component: doc-Logical_Volume_Manager
Version: 7.2
Hardware: Unspecified
OS: Unspecified
medium
unspecified
Target Milestone: rc
: ---
Assignee: Steven J. Levine
QA Contact: ecs-bugs
URL:
Whiteboard:
Depends On: 1181842
Blocks: 1273152
TreeView+ depends on / blocked
 
Reported: 2015-05-05 20:04 UTC by Steven J. Levine
Modified: 2019-03-06 02:36 UTC (History)
7 users (show)

Fixed In Version:
Doc Type: Bug Fix
Doc Text:
Clone Of: 1181842
: 1273152 (view as bug list)
Environment:
Last Closed: 2015-11-24 21:07:10 UTC
Target Upstream Version:
Embargoed:


Attachments (Terms of Use)

Description Steven J. Levine 2015-05-05 20:04:41 UTC
Cloning this for RHEL 7.

+++ This bug was initially created as a clone of Bug #1181842 +++

For the RHEL 6.7 LVM manual, we need to document support of selection criteria. Information about selection criteria can be found under the SELECTION CRITERIA heading in the lvm.8 man page.

--- Additional comment from Steven J. Levine on 2015-03-16 17:16:53 EDT ---

Just to put this information here, to incorporate into the document:

Many commands take the -S or --select SELECTION option:
For  reporting  commands, display only rows that match selection
criteria.  All rows are displayed with the additional "selected"
column  (-o selected) showing 1 if the row matches the Selection
and 0 otherwise. For non-reporting commands  which  process  LVM
entities,  the  selection can be used to match items to process.
See SELECTION CRITERIA section of this man page for more  infor-
mation about the way the selection criteria are constructed.

SELECTION CRITERIA
       The selection criteria are a set of statements combined by logical  and
       grouping  operators.  The statement consists of column name for which a
       set of valid values is defined using comparison operators. For complete
       list  of  column  names (fields) that can be used in selection, see the
       output of <lvm reporting command> -S help.

       Comparison operators (cmp_op):

              =~ — Matching regular expression.

              !~ — Not matching regular expression.

              =  — Equal to.

              != — Not equal to.

              >= — Greater than or equal to.

              >  — Greater than

              <= — Less than or equal to.

       Binary logical operators (cmp_log):

              && — All fields must match

              ,  — All fields must match

              || — At least one field must match

              #  — At least one field must match

       Unary logical operators:

              !  — Logical negation

       Grouping operators:

              (  — Left parenthesis

              )  — Right parenthesis

              [  — List start

       Informal grammar specification:

              STATEMENT = column cmp_op VALUE | STATEMENT log_op  STATEMENT  |
              (STATEMENT) | !(STATEMENT)

              VALUE = [VALUE log_op VALUE]
              For  list-based types: string list. The log_op must always be of
              one type within the whole list value.

              VALUE = value
              For scalar types: number (integer), size (floating point  number
              with  size  unit suffix), percent (floating point number with or
              without % suffix), string.

--- Additional comment from Steven J. Levine on 2015-03-24 17:04:49 EDT ---

Sent to lvm-team on 3-24:

For the RHEL 6.7 version of the LVM manual, brassow has asked me to document selection criteria for LVM commands -- pointing me to the SELECTION CRITERIA section of the LVM man page for basic information.

I was wondering if anybody here can provide me with examples that use the -S option, and what the output looks like?  That could help me figure out how to approach this in the documentation. Although I think that just a few key examples will probably be enough.

I could play around on a test system, but I'm not really sure where to start. Does anybody have any examples of when they have used this option on a command that might be suitable for the documentation?

Thanks,

Steven

--- Additional comment from Steven J. Levine on 2015-03-30 15:36:08 EDT ---

From Peter Rajnoha on 3/25:
On 03/24/2015 10:03 PM, slevine wrote:
> For the RHEL 6.7 version of the LVM manual, brassow has asked me to
> document selection criteria for LVM commands -- pointing me to the
> SELECTION CRITERIA section of the LVM man page for basic information.
>
> I was wondering if anybody here can provide me with examples that use
> the -S option, and what the output looks like?  That could help me
> figure out how to approach this in the documentation. Although I think
> that just a few key examples will probably be enough.
>

Hi!

There are two groups of commands where users can make use of
the -S/--select for selection. It's either:

  - reporting (pvs, vgs, lvs, pvdisplay, vgdisplay, lvdisplay, lvm devtypes, dmsetup info -c)

  - processing (pvchange, vgchange, lvchange, vgimport, vgexport, vgremove, lvremove)


Maybe important thing to note is that the selection is a property of
reporting infrastructure that is part of libdevmapper (the dm_report*
properties and functions exposed via libdevmapper.h). So that's why we
can support selection in LVM commands as well as in dmsetup. Also,
other libdevmapper users can make use of it, of course - simply, this
feature is not bound to LVM only.

Now, back to those two groups mentioned above:

Reporting commands - the outcome of selection is that only the lines that
satisfy selection criteria are reported.

Processing commands - the outcome of selection is that only the items that
satisfy selection criteria are processed. Here, an internal in-memory report
is done automatically, so we can compare the actual field values with
selection criteria, but this internal report is not visible to users - they
just see the outcome - selected items get processed.


As for the selection criteria - they're a set of statements with field
names (colum names) for which we define valid values using operators
(the exact set of allowed operators is listed in lvm man page in that
SELECTION_CRITERIA section).

Users can take a peek at the quick help by using "help" keyword as
selection criteria in which case full set of fields and possible
operators is reported:

  <lvm_reporting_command> -S/--select help
  (for example, lvs -S help)

The help line for each field also contains exact type of that field
enclosed in [ ], for example:

lv_name              - Name.  LVs created for internal use are enclosed in brackets. [string]
lv_role              - LV role. [string list]
raid_mismatch_count  - For RAID, number of mismatches found or repaired. [number]
copy_percent         - For RAID, mirrors and pvmove, current percentage in-sync. [percent]
lv_size              - Size of LV in current units. [size]

Those are all possible field types we recognize now: string, string_list, number, percent, size.
Those types are also briefly explained in "-S help" under "Selection operands".

There's no requirement for the field which is in the selection criteria
to be displayed (so selection criteria can contain one set of fields
while the output can contain completely different set of fields).
We can handle this.

The values are either concrete values of that type OR there can be reserved
values - for example -1, unknown, undefined, undef are all keywords to denote
"undefined" value (all listed values are synonyms).

A few of the field values have synonyms too (in constrast to the global
one for the undefined value), so, for example, for the lv_permissions field
which normally displays "read-only" or "writeable", synonyms are recognized
as well like "rw" and "read-write" for "writeable". Then "r" and "ro" for
"read-only". These synonyms can be used in selection criteria as well for
values just like their original values. This is not yet properly documented
in <lvm command> -S help, but I have a patch lying somewhere which just needs
finishing for these per-field synonyms to appear in that help...
Also I'd like to make the lvm_command -S help a bit better and more comprendious
and separate help for each field, so "<lvm command> -S help <field_name>"
would show all details and possible values for that field - this is not
yet done, but I have that on my TODO list.


There are special fields:

  - "help" - displays help (e.g. "lvs -S help", "dmsetup info -c -S help")

  - "selected" - this field is automatically recognized for all dm report
     users (so LVM and dmsetup and anyone else using libdevmapper reporting
     infrastructure with selection). If used, all fields are displayed as
     usual (without selection), but the "selected" field displays either
     "0" or "1" based on whether the line is selected or not with the
     selection criteria (this may come in handy in scripts).

As for the operators, the "-S help" also shows what field types can be
used with an operator, for example:

  =  - Equal to. [number, size, percent, string, string list]
  (meaning it can go with fields of type: number, size, percent,string or string list)

  <  - Less than. [number, size, percent]
  (meaning it can go with fields of type: number, size, percent)

  and so on...


We can use regular expressions as well ("=~" operator) - regular
expressions can be used with any fields of "string" type
(the regular expressions are of the same syntax as, for example,
already used in lvm.conf's "filter" setting).

The logical operators are quite clear, maybe we should mention
that there "&&" is synonym to "," and "||" is synonym to "#"
(I prefer && and || because I'm programmer  But someone may
prefer the one-character ones).

And yes, as for the grouping operators, we have 3 types:

  "( )" - used for grouping statements
  "[ ]" - used to group strings into a string list (exact match)
  "{ }" - used to group strings into a string list too (subset match)



So that's about the theory around. Now, a few examples to get the idea
about how it works in real (for documentation, we could probably select
better set of commands/LVs, the example below are just for the idea...):

I have:

[0] f21/~ # lvs -a -o+layout,role
  LV              VG     Attr       LSize   Pool Origin Data%  Meta%  Layout      Role                        
  root            fedora -wi-ao----   9.01g                           linear      public                      
  swap            fedora -wi-ao---- 512.00m                           linear      public                      
  [lvol0_pmspare] vg     ewi-------   4.00m                           linear      private,pool,spare          
  lvol1           vg     Vwi-a-tz--   1.00g pool        0.00          thin,sparse public                      
  lvol2           vg     Vwi-a-tz--   1.00g pool        0.00          thin,sparse public,origin,thinorigin    
  lvol3           vg     Vwi---tz-k   1.00g pool lvol2                thin,sparse public,snapshot,thinsnapshot
  pool            vg     twi-aotz-- 100.00m             0.00   1.07   thin,pool   private                     
  [pool_tdata]    vg     Twi-ao---- 100.00m                           linear      private,thin,pool,data      
  [pool_tmeta]    vg     ewi-ao----   4.00m                           linear      private,thin,pool,metadata  


- I want to select all LVs having "lvol[13]" in name:
  (so I'll use regex)

[0] f21/~ # lvs -a -o+layout,role -S 'lv_name=~lvol[13]'
  LV    VG   Attr       LSize Pool Origin Data%  Layout      Role                        
  lvol1 vg   Vwi-a-tz-- 1.00g pool        0.00   thin,sparse public                      
  lvol3 vg   Vwi---tz-k 1.00g pool lvol2         thin,sparse public,snapshot,thinsnapshot


- I want to select all LVs having more than 500m in size:

[0] f21/~ # lvs -a -o+layout,role -S 'lv_size>500m'
  LV    VG     Attr       LSize   Pool Origin Data%  Layout      Role                        
  root  fedora -wi-ao----   9.01g                    linear      public                      
  swap  fedora -wi-ao---- 512.00m                    linear      public                      
  lvol1 vg     Vwi-a-tz--   1.00g pool        0.00   thin,sparse public                      
  lvol2 vg     Vwi-a-tz--   1.00g pool        0.00   thin,sparse public,origin,thinorigin    
  lvol3 vg     Vwi---tz-k   1.00g pool lvol2         thin,sparse public,snapshot,thinsnapshot


- I want to select all LVs which have a role on constructing thins:
  (see the use of {} for the subset!)

[0] f21/~ # lvs -a -o+layout,role -S 'lv_role={thin}'
  LV           VG   Attr       LSize   Layout     Role                      
  [pool_tdata] vg   Twi-ao---- 100.00m linear     private,thin,pool,data    
  [pool_tmeta] vg   ewi-ao----   4.00m linear     private,thin,pool,metadata


- I want to select all "usable" top-level LVs (simply, the ones which are "public"):
  (if you don't use {} for string list, it's assumed by default, so lv_role=public is equal to lv_role={public})

[0] f21/~ # lvs -a -o+layout,role -S 'lv_role=public'   
  LV    VG     Attr       LSize   Pool Origin Data%  Layout      Role                        
  root  fedora -wi-ao----   9.01g                    linear      public                      
  swap  fedora -wi-ao---- 512.00m                    linear      public                      
  lvol1 vg     Vwi-a-tz--   1.00g pool        0.00   thin,sparse public                      
  lvol2 vg     Vwi-a-tz--   1.00g pool        0.00   thin,sparse public,origin,thinorigin    
  lvol3 vg     Vwi---tz-k   1.00g pool lvol2         thin,sparse public,snapshot,thinsnapshot


- I want to select all LVs with thin layout:

[0] f21/~ # lvs -a -o+layout,role -S 'lv_layout={thin}'
  LV    VG   Attr       LSize   Pool Origin Data%  Meta%  Layout      Role                        
  lvol1 vg   Vwi-a-tz--   1.00g pool        0.00          thin,sparse public                      
  lvol2 vg   Vwi-a-tz--   1.00g pool        0.00          thin,sparse public,origin,thinorigin    
  lvol3 vg   Vwi---tz-k   1.00g pool lvol2                thin,sparse public,snapshot,thinsnapshot
  pool  vg   twi-aotz-- 100.00m             0.00   1.07   thin,pool   private     


- I want to select thin sparse LVs exactly:
  (see the use of [] for exact match, also see that you don't need to specify the
   string list member in order for the match to be positive!)

[0] f21/~ # lvs -a -o+layout,role -S 'lv_layout=[sparse,thin]'
  LV    VG   Attr       LSize Pool Origin Data%  Layout      Role                        
  lvol1 vg   Vwi-a-tz-- 1.00g pool        0.00   thin,sparse public                      
  lvol2 vg   Vwi-a-tz-- 1.00g pool        0.00   thin,sparse public,origin,thinorigin    
  lvol3 vg   Vwi---tz-k 1.00g pool lvol2         thin,sparse public,snapshot,thinsnapshot


- I want just LV names which are thin sparse LVs:
  (the list of fields used in selection don't need to be equal/subset of the list
   of fields we display)

[0] f21/~ # lvs -a -o lv_name -S 'lv_layout=[sparse,thin]'
  LV   
  lvol1
  lvol2
  lvol3


Now, the processing - thin snapshots have "skip activation" flag set by default.
Let's change this flag in one go for all thin snapshots (I've added one more
LV lvol4 which is linear and has that flag set too so you can see it works):

[0] f21/~ # lvs -o name,skip_activation,layout,role
  LV    SkipAct         Layout      Role                        
  root                  linear      public                      
  swap                  linear      public                      
  lvol1                 thin,sparse public                      
  lvol2                 thin,sparse public,origin,thinorigin    
  lvol3 skip activation thin,sparse public,snapshot,thinsnapshot
  lvol4 skip activation linear      public                      
  pool                  thin,pool   private   

[0] f21/~ # lvchange --setactivationskip n -S 'role=thinsnapshot'
  Logical volume "lvol3" changed.

[0] f21/~ # lvs -o name,active,skip_activation,layout,role
  LV    Active SkipAct         Layout      Role                        
  root  active                 linear      public                      
  swap  active                 linear      public                      
  lvol1 active                 thin,sparse public                      
  lvol2 active                 thin,sparse public,origin,thinorigin    
  lvol3                        thin,sparse public,snapshot,thinsnapshot
  lvol4 active skip activation linear      public                      
  pool  active                 thin,pool   private 


Now I've created one more thin origin/snapshot to see the difference in
subsequent example, so we have:

[0] f21/~ # lvs -o name,active,skip_activation,origin,layout,role
  LV    Active SkipAct         Origin Layout      Role                        
  root  active                        linear      public                      
  swap  active                        linear      public                      
  lvol1 active                        thin,sparse public                      
  lvol2 active                        thin,sparse public,origin,thinorigin    
  lvol3                        lvol2  thin,sparse public,snapshot,thinsnapshot
  lvol4 active skip activation        linear      public                      
  lvol5 active                        thin,sparse public,origin,thinorigin    
  lvol6                        lvol5  thin,sparse public,snapshot,thinsnapshot
  pool  active                        thin,pool   private  


Now, let's activate thin snapshot volumes which have lvol2 as origin
[0] f21/~ # lvchange -ay -S 'lv_role=thinsnapshot && origin=lvol2'

[0] f21/~ # lvs -o name,active,skip_activation,origin,layout,role
  LV    Active SkipAct         Origin Layout      Role                        
  root  active                        linear      public                      
  swap  active                        linear      public                      
  lvol1 active                        thin,sparse public                      
  lvol2 active                        thin,sparse public,origin,thinorigin    
  lvol3 active                 lvol2  thin,sparse public,snapshot,thinsnapshot
  lvol4 active skip activation        linear      public                      
  lvol5 active                        thin,sparse public,origin,thinorigin    
  lvol6                        lvol5  thin,sparse public,snapshot,thinsnapshot
  pool  active                        thin,pool   private     


If you're processing a whole while selection criteria matches an
item from that whole, the whole is processed then - for example,
when you're changing whole volume group, but selection matches
one (or more items) from that volume group, the whole volume
group is then selected:

[0] f21/~/ # lvs -o name,vg_name
  LV    VG    
  root  fedora
  swap  fedora
  lvol1 vg    
  lvol2 vg    
  lvol3 vg    
  lvol4 vg    
  lvol5 vg    
  lvol6 vg    
  pool  vg 


[0] f21/~ # vgchange -ay -S 'lv_name=lvol1'
  7 logical volume(s) in volume group "vg" now active


An exmaple of more complex selection criteria statement:
(tag me all LVs with "mytag" which have a role of origin and at the same time they're named lvol[456] OR the lv_size is more that 5 gigs)

[0] f21/~ # lvchange --addtag mytag -S '(role=origin && lv_name=~lvol[456]) || lv_size > 5g'
  Logical volume "root" changed.
  Logical volume "lvol5" changed.

The possibilities here are endless... 

-- Peter 

On 03/24/2015 10:03 PM, slevine wrote:
> For the RHEL 6.7 version of the LVM manual, brassow has asked me to
> document selection criteria for LVM commands -- pointing me to the
> SELECTION CRITERIA section of the LVM man page for basic information.
>
> I was wondering if anybody here can provide me with examples that use
> the -S option, and what the output looks like?  That could help me
> figure out how to approach this in the documentation. Although I think
> that just a few key examples will probably be enough.
>

Hi!

There are two groups of commands where users can make use of
the -S/--select for selection. It's either:

  - reporting (pvs, vgs, lvs, pvdisplay, vgdisplay, lvdisplay, lvm devtypes, dmsetup info -c)

  - processing (pvchange, vgchange, lvchange, vgimport, vgexport, vgremove, lvremove)


Maybe important thing to note is that the selection is a property of
reporting infrastructure that is part of libdevmapper (the dm_report*
properties and functions exposed via libdevmapper.h). So that's why we
can support selection in LVM commands as well as in dmsetup. Also,
other libdevmapper users can make use of it, of course - simply, this
feature is not bound to LVM only.

Now, back to those two groups mentioned above:

Reporting commands - the outcome of selection is that only the lines that
satisfy selection criteria are reported.

Processing commands - the outcome of selection is that only the items that
satisfy selection criteria are processed. Here, an internal in-memory report
is done automatically, so we can compare the actual field values with
selection criteria, but this internal report is not visible to users - they
just see the outcome - selected items get processed.


As for the selection criteria - they're a set of statements with field
names (colum names) for which we define valid values using operators
(the exact set of allowed operators is listed in lvm man page in that
SELECTION_CRITERIA section).

Users can take a peek at the quick help by using "help" keyword as
selection criteria in which case full set of fields and possible
operators is reported:

  <lvm_reporting_command> -S/--select help
  (for example, lvs -S help)

The help line for each field also contains exact type of that field
enclosed in [ ], for example:

lv_name              - Name.  LVs created for internal use are enclosed in brackets. [string]
lv_role              - LV role. [string list]
raid_mismatch_count  - For RAID, number of mismatches found or repaired. [number]
copy_percent         - For RAID, mirrors and pvmove, current percentage in-sync. [percent]
lv_size              - Size of LV in current units. [size]

Those are all possible field types we recognize now: string, string_list, number, percent, size.
Those types are also briefly explained in "-S help" under "Selection operands".

There's no requirement for the field which is in the selection criteria
to be displayed (so selection criteria can contain one set of fields
while the output can contain completely different set of fields).
We can handle this.

The values are either concrete values of that type OR there can be reserved
values - for example -1, unknown, undefined, undef are all keywords to denote
"undefined" value (all listed values are synonyms).

A few of the field values have synonyms too (in constrast to the global
one for the undefined value), so, for example, for the lv_permissions field
which normally displays "read-only" or "writeable", synonyms are recognized
as well like "rw" and "read-write" for "writeable". Then "r" and "ro" for
"read-only". These synonyms can be used in selection criteria as well for
values just like their original values. This is not yet properly documented
in <lvm command> -S help, but I have a patch lying somewhere which just needs
finishing for these per-field synonyms to appear in that help...
Also I'd like to make the lvm_command -S help a bit better and more comprendious
and separate help for each field, so "<lvm command> -S help <field_name>"
would show all details and possible values for that field - this is not
yet done, but I have that on my TODO list.


There are special fields:

  - "help" - displays help (e.g. "lvs -S help", "dmsetup info -c -S help")

  - "selected" - this field is automatically recognized for all dm report
     users (so LVM and dmsetup and anyone else using libdevmapper reporting
     infrastructure with selection). If used, all fields are displayed as
     usual (without selection), but the "selected" field displays either
     "0" or "1" based on whether the line is selected or not with the
     selection criteria (this may come in handy in scripts).

As for the operators, the "-S help" also shows what field types can be
used with an operator, for example:

  =  - Equal to. [number, size, percent, string, string list]
  (meaning it can go with fields of type: number, size, percent,string or string list)

  <  - Less than. [number, size, percent]
  (meaning it can go with fields of type: number, size, percent)

  and so on...


We can use regular expressions as well ("=~" operator) - regular
expressions can be used with any fields of "string" type
(the regular expressions are of the same syntax as, for example,
already used in lvm.conf's "filter" setting).

The logical operators are quite clear, maybe we should mention
that there "&&" is synonym to "," and "||" is synonym to "#"
(I prefer && and || because I'm programmer  But someone may
prefer the one-character ones).

And yes, as for the grouping operators, we have 3 types:

  "( )" - used for grouping statements
  "[ ]" - used to group strings into a string list (exact match)
  "{ }" - used to group strings into a string list too (subset match)



So that's about the theory around. Now, a few examples to get the idea
about how it works in real (for documentation, we could probably select
better set of commands/LVs, the example below are just for the idea...):

I have:

[0] f21/~ # lvs -a -o+layout,role
  LV              VG     Attr       LSize   Pool Origin Data%  Meta%  Layout      Role                        
  root            fedora -wi-ao----   9.01g                           linear      public                      
  swap            fedora -wi-ao---- 512.00m                           linear      public                      
  [lvol0_pmspare] vg     ewi-------   4.00m                           linear      private,pool,spare          
  lvol1           vg     Vwi-a-tz--   1.00g pool        0.00          thin,sparse public                      
  lvol2           vg     Vwi-a-tz--   1.00g pool        0.00          thin,sparse public,origin,thinorigin    
  lvol3           vg     Vwi---tz-k   1.00g pool lvol2                thin,sparse public,snapshot,thinsnapshot
  pool            vg     twi-aotz-- 100.00m             0.00   1.07   thin,pool   private                     
  [pool_tdata]    vg     Twi-ao---- 100.00m                           linear      private,thin,pool,data      
  [pool_tmeta]    vg     ewi-ao----   4.00m                           linear      private,thin,pool,metadata  


- I want to select all LVs having "lvol[13]" in name:
  (so I'll use regex)

[0] f21/~ # lvs -a -o+layout,role -S 'lv_name=~lvol[13]'
  LV    VG   Attr       LSize Pool Origin Data%  Layout      Role                        
  lvol1 vg   Vwi-a-tz-- 1.00g pool        0.00   thin,sparse public                      
  lvol3 vg   Vwi---tz-k 1.00g pool lvol2         thin,sparse public,snapshot,thinsnapshot


- I want to select all LVs having more than 500m in size:

[0] f21/~ # lvs -a -o+layout,role -S 'lv_size>500m'
  LV    VG     Attr       LSize   Pool Origin Data%  Layout      Role                        
  root  fedora -wi-ao----   9.01g                    linear      public                      
  swap  fedora -wi-ao---- 512.00m                    linear      public                      
  lvol1 vg     Vwi-a-tz--   1.00g pool        0.00   thin,sparse public                      
  lvol2 vg     Vwi-a-tz--   1.00g pool        0.00   thin,sparse public,origin,thinorigin    
  lvol3 vg     Vwi---tz-k   1.00g pool lvol2         thin,sparse public,snapshot,thinsnapshot


- I want to select all LVs which have a role on constructing thins:
  (see the use of {} for the subset!)

[0] f21/~ # lvs -a -o+layout,role -S 'lv_role={thin}'
  LV           VG   Attr       LSize   Layout     Role                      
  [pool_tdata] vg   Twi-ao---- 100.00m linear     private,thin,pool,data    
  [pool_tmeta] vg   ewi-ao----   4.00m linear     private,thin,pool,metadata


- I want to select all "usable" top-level LVs (simply, the ones which are "public"):
  (if you don't use {} for string list, it's assumed by default, so lv_role=public is equal to lv_role={public})

[0] f21/~ # lvs -a -o+layout,role -S 'lv_role=public'   
  LV    VG     Attr       LSize   Pool Origin Data%  Layout      Role                        
  root  fedora -wi-ao----   9.01g                    linear      public                      
  swap  fedora -wi-ao---- 512.00m                    linear      public                      
  lvol1 vg     Vwi-a-tz--   1.00g pool        0.00   thin,sparse public                      
  lvol2 vg     Vwi-a-tz--   1.00g pool        0.00   thin,sparse public,origin,thinorigin    
  lvol3 vg     Vwi---tz-k   1.00g pool lvol2         thin,sparse public,snapshot,thinsnapshot


- I want to select all LVs with thin layout:

[0] f21/~ # lvs -a -o+layout,role -S 'lv_layout={thin}'
  LV    VG   Attr       LSize   Pool Origin Data%  Meta%  Layout      Role                        
  lvol1 vg   Vwi-a-tz--   1.00g pool        0.00          thin,sparse public                      
  lvol2 vg   Vwi-a-tz--   1.00g pool        0.00          thin,sparse public,origin,thinorigin    
  lvol3 vg   Vwi---tz-k   1.00g pool lvol2                thin,sparse public,snapshot,thinsnapshot
  pool  vg   twi-aotz-- 100.00m             0.00   1.07   thin,pool   private     


- I want to select thin sparse LVs exactly:
  (see the use of [] for exact match, also see that you don't need to specify the
   string list member in order for the match to be positive!)

[0] f21/~ # lvs -a -o+layout,role -S 'lv_layout=[sparse,thin]'
  LV    VG   Attr       LSize Pool Origin Data%  Layout      Role                        
  lvol1 vg   Vwi-a-tz-- 1.00g pool        0.00   thin,sparse public                      
  lvol2 vg   Vwi-a-tz-- 1.00g pool        0.00   thin,sparse public,origin,thinorigin    
  lvol3 vg   Vwi---tz-k 1.00g pool lvol2         thin,sparse public,snapshot,thinsnapshot


- I want just LV names which are thin sparse LVs:
  (the list of fields used in selection don't need to be equal/subset of the list
   of fields we display)

[0] f21/~ # lvs -a -o lv_name -S 'lv_layout=[sparse,thin]'
  LV   
  lvol1
  lvol2
  lvol3


Now, the processing - thin snapshots have "skip activation" flag set by default.
Let's change this flag in one go for all thin snapshots (I've added one more
LV lvol4 which is linear and has that flag set too so you can see it works):

[0] f21/~ # lvs -o name,skip_activation,layout,role
  LV    SkipAct         Layout      Role                        
  root                  linear      public                      
  swap                  linear      public                      
  lvol1                 thin,sparse public                      
  lvol2                 thin,sparse public,origin,thinorigin    
  lvol3 skip activation thin,sparse public,snapshot,thinsnapshot
  lvol4 skip activation linear      public                      
  pool                  thin,pool   private   

[0] f21/~ # lvchange --setactivationskip n -S 'role=thinsnapshot'
  Logical volume "lvol3" changed.

[0] f21/~ # lvs -o name,active,skip_activation,layout,role
  LV    Active SkipAct         Layout      Role                        
  root  active                 linear      public                      
  swap  active                 linear      public                      
  lvol1 active                 thin,sparse public                      
  lvol2 active                 thin,sparse public,origin,thinorigin    
  lvol3                        thin,sparse public,snapshot,thinsnapshot
  lvol4 active skip activation linear      public                      
  pool  active                 thin,pool   private 


Now I've created one more thin origin/snapshot to see the difference in
subsequent example, so we have:

[0] f21/~ # lvs -o name,active,skip_activation,origin,layout,role
  LV    Active SkipAct         Origin Layout      Role                        
  root  active                        linear      public                      
  swap  active                        linear      public                      
  lvol1 active                        thin,sparse public                      
  lvol2 active                        thin,sparse public,origin,thinorigin    
  lvol3                        lvol2  thin,sparse public,snapshot,thinsnapshot
  lvol4 active skip activation        linear      public                      
  lvol5 active                        thin,sparse public,origin,thinorigin    
  lvol6                        lvol5  thin,sparse public,snapshot,thinsnapshot
  pool  active                        thin,pool   private  


Now, let's activate thin snapshot volumes which have lvol2 as origin
[0] f21/~ # lvchange -ay -S 'lv_role=thinsnapshot && origin=lvol2'

[0] f21/~ # lvs -o name,active,skip_activation,origin,layout,role
  LV    Active SkipAct         Origin Layout      Role                        
  root  active                        linear      public                      
  swap  active                        linear      public                      
  lvol1 active                        thin,sparse public                      
  lvol2 active                        thin,sparse public,origin,thinorigin    
  lvol3 active                 lvol2  thin,sparse public,snapshot,thinsnapshot
  lvol4 active skip activation        linear      public                      
  lvol5 active                        thin,sparse public,origin,thinorigin    
  lvol6                        lvol5  thin,sparse public,snapshot,thinsnapshot
  pool  active                        thin,pool   private     


If you're processing a whole while selection criteria matches an
item from that whole, the whole is processed then - for example,
when you're changing whole volume group, but selection matches
one (or more items) from that volume group, the whole volume
group is then selected:

[0] f21/~/ # lvs -o name,vg_name
  LV    VG    
  root  fedora
  swap  fedora
  lvol1 vg    
  lvol2 vg    
  lvol3 vg    
  lvol4 vg    
  lvol5 vg    
  lvol6 vg    
  pool  vg 


[0] f21/~ # vgchange -ay -S 'lv_name=lvol1'
  7 logical volume(s) in volume group "vg" now active


An exmaple of more complex selection criteria statement:
(tag me all LVs with "mytag" which have a role of origin and at the same time they're named lvol[456] OR the lv_size is more that 5 gigs)

[0] f21/~ # lvchange --addtag mytag -S '(role=origin && lv_name=~lvol[456]) || lv_size > 5g'
  Logical volume "root" changed.
  Logical volume "lvol5" changed.

The possibilities here are endless... 

-- Peter

--- Additional comment from Steven J. Levine on 2015-04-07 17:16:23 EDT ---

Peter:

I have written a draft of a new appendix in the LVM manual about this feature -- which is pretty extensive. It doens't have the info about per-field synonyms, so I can add that when it's ready.

Could you review this new information?  It is here:

https://documentation-devel.engineering.redhat.com/site/documentation/en-US/Red_Hat_Enterprise_Linux/6/html/Logical_Volume_Manager_Administration/selection_criteria.html

Steven

--- Additional comment from Peter Rajnoha on 2015-04-08 06:45:05 EDT ---

(In reply to Steven J. Levine from comment #4)
> https://documentation-devel.engineering.redhat.com/site/documentation/en-US/
> Red_Hat_Enterprise_Linux/6/html/Logical_Volume_Manager_Administration/
> selection_criteria.html

Yup, I think we could go with that.


A few things to add/edit:

Table C.1. Selection Criteria Field Types
  - string list 	Strings enclosed by [ ] or { } and elements delimited by either "all items must match" or "at least one item must match" operator. 
  (...added "... or { } ...")

C.3. Selection Criteria Fields
  - lv_attr displays both LV device info as well as LV status - it's in separate
    combined group called "Logical Volume Device Info and Status Combined Fields",
    I would probably mention that just like we mention other groups (as we may
    add more fields in that combined group later on...)

  - lv_allocation_policy -- lost formatting

Table C.13. Selection Criteria Synonyms
  - there are some values which are binary - see the ones with 0/1 synonyms (there's also a special "--binary" switch for reporting tools which, if used, causes all these binary fields to display 0 or 1 instead of "some text" or "". The "" below denotes blank string - it can be matches by -S 'field_name=""')

  - complete list of synonyms (I have in plan to patch "-S help" to display these synonyms, but it's not ready yet):


For all fields of type "number" and for undefined value these synonyms: -1, unknown, undefined, undef

Field                    Field Value          Synonyms

pv_allocatable           allocatable          1
pv_allocatable           ""                   0

pv_exported              exported             1
pv_exported              ""                   0

pv_missing               missing              1
pv_missing               ""                   0


vg_extendable            extendable           1
vg_extendable            ""                   0

vg_exported              exported             1
vg_exported              ""                   0


vg_partial               partial              1
vg_partial               ""                   0

vg_clustered             clustered            1
vg_clustered             ""                   0

vg_permissions           writeable            rw, read-write
vg_permissions           read-only            r, ro

vg_mda_copies            unmanaged            unknown, undefined, undef, -1


lv_initial_image_sync    initial image sync   sync, 1
lv_initial_image_sync    ""                   0

lv_image_synced          image synced         synced, 1
lv_image_synce           ""                   0

lv_merging               merging              1
lv_merging               ""                   0

lv_converting            converting           1
lv_converting            ""                   0

lv_allocation_locked     allocation locked    locked, 1
lv_allocation_locked     ""                   0

lv_fixed_minor           fixed minor          fixed, 1
lv_fixed_minor           ""                   0

lv_active_locally        active locally       active, locally, 1
lv_active_locally        ""                   0

lv_active_remotely       active remotely      active, remotely, 1
lv_active_remotely       ""                   0

lv_active_exclusively    active exclusively   active, exclusively, 1
lv_active_exclusively    ""                   0

lv_merge_failed          merge failed         failed, 1
lv_merge_failed          ""                   0

lv_snapshot_invalid      snapshot invalid     invalid, 1
lv_snapshot_invalid      ""                   0

lv_suspended             suspended            1
lv_suspended             ""                   0

lv_live_table            live table present   live table, live, 1
lv_live_table            ""                   0

lv_inactive_table        inactive table present    inactive table, inactive, 1
lv_inactive_table        ""                   0

lv_device_open           open                 1
lv_device_open           ""                   0

lv_skip_activation       skip activation      skip, 1
lv_skip_activation       ""                   0

zero                     zero                 1
zero                     ""                   0

lv_permissions           writeable            rw, read-write
lv_permissions           read-only            r, ro
lv_permissions           read-only-override   ro-override, r-override, R

lv_when_full             error                error when full, error if no space
lv_when_full             queue                queue when full, queue if no space
lv_when_full             ""                   undefined

cache_policy             ""                   undefined
seg_monitor              ""                   undefined
lv_health_status         ""                   undefined


C.4. Selection Criteria Display Examples
  - can we switch off text wrapping? (or do we need examples with output not that wide?)

  - The following command displays all logical volumes with a layout field that
    matches "sparse,thin" exactly. Not that it is not necessary to specify the
    string list member for the match to be positive. 

    -- should be "... Note that is is not necessary to specify the string list
       members in exact order for the match to be positive."

--- Additional comment from Steven J. Levine on 2015-04-08 18:49:33 EDT ---

I have updated the document according to the input in Comment 5 and replaced the table of synonyms with the table of synonyms provided.

I have to figure out what to do about the wrapping display -- the output has changed. I may have to reformat so it is at least more readable.

I will rebuild the document and then send the new synonym table/section back to Peter R. for his review.

--- Additional comment from Steven J. Levine on 2015-04-09 14:26:49 EDT ---

Peter:

I have made the updates noted in your comment. Could you look over the new sections? They are basically these:

https://documentation-devel.engineering.redhat.com/site/documentation/en-US/Red_Hat_Enterprise_Linux/6/html/Logical_Volume_Manager_Administration/selection_fields.html

- Table C.6 (a new table just for lv_attr) has a typo of "Stauts" in the title. That is fixed in the current draft.

- Table C.14 (and the intro paragraphs to that table), Selection Criteria Synonyms

Plus here:

https://documentation-devel.engineering.redhat.com/site/documentation/en-US/Red_Hat_Enterprise_Linux/6/html/Logical_Volume_Manager_Administration/selection_display_examples.html

For Section C.4, I had to do some fudging around to prevent line wraps and this is what I came up with. It's not quite literally what the display would looik like, but I think it's clearer than the wrapped lines. So far I have found no way to fix the wrap-line display for too-long code/output examples. Does this look ok?

Thanks,

Steven

--- Additional comment from Steven J. Levine on 2015-04-09 15:52:31 EDT ---

Peter:  And another question (by way of Corey):

"...in the logical volume fields table, you have three metadata fields (lv_metadata_size,metadata_percent,metadata_lv) and then define them as "For thin pools, ..." however cache pools also use all three of those fields as well. Should cache be added to that defination, or are cache pools technically a type of "thin pool"?"


-Steven

--- Additional comment from Peter Rajnoha on 2015-04-10 08:25:34 EDT ---

(In reply to Steven J. Levine from comment #7)
> https://documentation-devel.engineering.redhat.com/site/documentation/en-US/
> Red_Hat_Enterprise_Linux/6/html/Logical_Volume_Manager_Administration/
> selection_fields.html
> 
> - Table C.6 (a new table just for lv_attr) has a typo of "Stauts" in the
> title. That is fixed in the current draft.
> 

OK

> - Table C.14 (and the intro paragraphs to that table), Selection Criteria
> Synonyms

OK

> 
> Plus here:
> 
> https://documentation-devel.engineering.redhat.com/site/documentation/en-US/
> Red_Hat_Enterprise_Linux/6/html/Logical_Volume_Manager_Administration/
> selection_display_examples.html
> 
> For Section C.4, I had to do some fudging around to prevent line wraps and
> this is what I came up with. It's not quite literally what the display would
> looik like, but I think it's clearer than the wrapped lines. So far I have
> found no way to fix the wrap-line display for too-long code/output examples.
> Does this look ok?

Yup, looks much better now!

--- Additional comment from Peter Rajnoha on 2015-04-10 08:58:21 EDT ---

(In reply to Steven J. Levine from comment #8)
> Peter:  And another question (by way of Corey):
> 
> "...in the logical volume fields table, you have three metadata fields
> (lv_metadata_size,metadata_percent,metadata_lv) and then define them as "For
> thin pools, ..." however cache pools also use all three of those fields as
> well. Should cache be added to that defination, or are cache pools
> technically a type of "thin pool"?"

Yeah, indeed, you're right, I've fixed the comments in the help string:

https://git.fedorahosted.org/cgit/lvm2.git/commit/?id=394250ef6759243e59de41dd6cfced544c041c76

(Only for lv_metadata_size, data_lv and metadata_lv fields. The metadata_percent does not report values for cache pools... yet.)

--- Additional comment from Steven J. Levine on 2015-04-10 15:05:07 EDT ---

The latest draft, with updates as per the comments, is now on the review server.

https://documentation-devel.engineering.redhat.com/site/documentation/en-US/Red_Hat_Enterprise_Linux/6/html/Logical_Volume_Manager_Administration/selection_criteria.html

--- Additional comment from Steven J. Levine on 2015-04-24 11:34:25 EDT ---

Related feature bug is BZ#1215059

Comment 2 Steven J. Levine 2015-05-18 21:55:34 UTC
The Selection Criteria chapter from the RHEL 6.7 beta version of this document has been added to the draft for the 7.2 version.

Comment 3 Peter Rajnoha 2015-10-15 09:05:48 UTC
Note: there are recent extensions to selection/reporting which we have in 7.2 which are worth to mention:

bug #1085684 (possibility to use -S|--select with some non-reporting lvm cmds)

bug #1240538 (extended support for time reporting fields and improved way to do selection on time fields)

Comment 4 Steven J. Levine 2015-10-15 21:26:30 UTC
I had already added the new info on using selection criteria with non-reporting lvm commands, as this was added to 6.7 as well and I used that info.

I have updated the selection criteria appendix with information about time reporting fields -- a few changes throughout and an entire new section. I used info from the feature bug combined with info from the help screens. When this finishes building on Brew I will send it to Peter for review.

Red_Hat_Enterprise_Linux-Logical_Volume_Manager_Administration-7-web-en-US-0.3-3.el6eng


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