{ "content": [ { "type": "text", "text": "# lvmreport (man)\n\n## NAME\n\nlvmreport — LVM reporting and related features\n\n## DESCRIPTION\n\nLVM uses single reporting infrastructure that sets standard on LVM command's output and it\nprovides wide range of configuration settings and command line options to customize report\nand filter the report's output.\n\n## Sections\n\n- **NAME**\n- **DESCRIPTION** (3 subsections)\n- **Terms** (6 subsections)\n- **Selection** (4 subsections)\n- **EXAMPLES** (8 subsections)\n- **SEE ALSO**\n\nUse structuredContent.sections for detailed options, examples, and full documentation.\n" } ], "structuredContent": { "command": "lvmreport", "section": "", "mode": "man", "summary": "lvmreport — LVM reporting and related features", "synopsis": null, "tldr_summary": null, "tldr_examples": [], "tldr_source": null, "flags": [ { "flag": "-S", "long": null, "arg": null, "description": "nizes these field types in reports: • string for set of characters (for each string field type, you can use either string or regular expression - regex for the value used in selection criteria) • string list for set of strings • number for integer value • size for integer or floating point number with size unit suffix (see also lvcre‐‐ ate(8) man page and description for \"-L--size\" option for the list of recognized suffixes) • percent for floating point number with or without \"%\" suffix (e.g. 50 or 50%) • time for time values When using string list in selection criteria, there are several ways how LVM can match string list fields from report, depending on what list grouping operator is used and what item sepa‐ rator is used within that set of items. Also, note that order of items does not matter here. • matching the set strictly where all items must match - use [ ], e.g. [\"a\",\"b\",\"c\"] • matching a subset of the set - use { } with \",\" or \"&&\" as item delimiter, e.g. {\"a\",\"b\",\"c\"} • matching an intersection with the set - use { } with \"#\" or \"||\" as item delimiter, e.g. {\"a\" || \"b\" || \"c\"} When using time in your selection criteria, LVM can recognize various time formats using standard, absolute or freeform expressions. For examples demonstrating time expressions in selection criteria, see EXAMPLES section. • Standard time format - date YYYY-MM-DD YYYY-MM, auto DD=1 YYYY, auto MM=01 and DD=01 - time hh:mm:ss hh:mm, auto ss=0 hh, auto mm=0, auto ss=0 - timezone +hh:mm or -hh:mm +hh or -hh The full date/time specification is YYYY-MM-DD hh:mm:ss. Users are able to leave date/time parts from right to left. Whenever these parts are left out, a range is assumed automatically with second granularity. For example: \"2015-07-07 9:51\" means range of \"2015-07-07 9:51:00\" - \"2015-07-07 9:51:59\". \"2015-07\" means range of \"2015-07-01 0:00:00\" - \"2015-07-31 23:59:59\" \"2015\" means range of \"2015-01-01 0:00:00\" - \"2015-12-31 23:59:59\" • Absolute time format Absolute time is defined as number of seconds since the Epoch (1970:01:01 00:00 +00:00). - @seconds • Freeform time format - weekday names (\"Sunday\" - \"Saturday\" or abbreviated as \"Sun\" - \"Sat\") - labels for points in time (\"noon\", \"midnight\") - labels for a day relative to current day (\"today\", \"yesterday\") - points back in time with relative offset from today (N is a number) \"N\" \"seconds\" / \"minutes\" / \"hours\" / \"days\" / \"weeks\" / \"years\" \"ago\" \"N\" \"secs\" / \"mins\" / \"hrs\" ... \"ago\" \"N\" \"s\" / \"m\" / \"h\" ... \"ago\" - time specification either in hh:mm:ss format or with AM/PM suffixes - month names (\"January\" - \"December\" or abbreviated as \"Jan\" - \"Dec\")" } ], "examples": [ "We start our examples with default configuration - lvmconfig(8) is helpful command to display", "configuration settings which are currently used, including all configuration related to re‐", "porting. We will use it throughout examples below to display current configuration.", "# lvmconfig --type full global/units global/suffix \\", "report/outputformat report/compactoutput \\", "report/compactoutputcols report/aligned \\", "report/headings report/separator \\", "report/listitemseparator report/prefixes \\", "report/quoted report/columnsasrows \\", "report/binaryvaluesasnumeric report/timeformat \\", "report/markhiddendevices report/twowordunknowndevice \\", "report/buffered", "units=\"h\"", "suffix=1", "outputformat=\"basic\"", "compactoutput=0", "compactoutputcols=\"\"", "aligned=1", "headings=1", "separator=\" \"", "listitemseparator=\",\"", "prefixes=0", "quoted=1", "columnsasrows=0", "binaryvaluesasnumeric=0", "timeformat=\"%Y-%m-%d %T %z\"", "markhiddendevices=1", "twowordunknowndevice=0", "buffered=1", "Also, we start with simple LVM layout with two PVs (/dev/sda, /dev/sdb), VG (vg) and two LVs", "(lvol0 and lvol1) in the VG. We display all possible reports as single commands here, see", "also pvs(8), vgs(8), lvs(8) man pages for more information. The field set for each report", "type is configured with configuration settings as we already mentioned in main report", "specifics section in this man page.", "# lvmconfig --type full report/pvscols report/pvssort \\", "report/pvsegscols report/pvsegssort report/vgscols \\", "report/vgssort report/lvscols report/lvssort \\", "report/segscols report/segssort", "pvscols=\"pvname,vgname,pvfmt,pvattr,pvsize,pvfree\"", "pvssort=\"pvname\"", "pvsegscols=\"pvname,vgname,pvfmt,pvattr,pvsize,pvfree,", "pvsegstart,pvsegsize\"", "pvsegssort=\"pvname,pvsegstart\"", "vgscols=\"vgname,pvcount,lvcount,snapcount,vgattr,vgsize,vgfree\"", "vgssort=\"vgname\"", "lvscols=\"lvname,vgname,lvattr,lvsize,poollv,origin,movepv,", "mirrorlog,copypercent,convertlv\"", "lvssort=\"vgname,lvname\"", "segscols=\"lvname,vgname,lvattr,stripes,segtype,segsize\"", "segssort=\"vgname,lvname,segstart\"", "# pvs", "PV VG Fmt Attr PSize PFree", "/dev/sda vg lvm2 a-- 100.00m 88.00m", "/dev/sdb vg lvm2 a-- 100.00m 92.00m", "# pvs --segments", "PV VG Fmt Attr PSize PFree Start SSize", "/dev/sda vg lvm2 a-- 100.00m 88.00m 0 1", "/dev/sda vg lvm2 a-- 100.00m 88.00m 1 1", "/dev/sda vg lvm2 a-- 100.00m 88.00m 2 1", "/dev/sda vg lvm2 a-- 100.00m 88.00m 3 22", "/dev/sdb vg lvm2 a-- 100.00m 92.00m 0 1", "/dev/sdb vg lvm2 a-- 100.00m 92.00m 1 1", "/dev/sdb vg lvm2 a-- 100.00m 92.00m 2 23", "# vgs", "VG #PV #LV #SN Attr VSize VFree", "vg 2 2 0 wz--n- 200.00m 180.00m", "# lvs", "LV VG Attr LSize Pool Origin Move Log Cpy%Sync Convert", "lvol0 vg -wi-a----- 4.00m", "lvol1 vg rwi-a-r--- 4.00m 100.00", "# lvs --segments", "LV VG Attr #Str Type SSize", "lvol0 vg -wi-a----- 1 linear 4.00m", "lvol1 vg rwi-a-r--- 2 raid1 4.00m", "We will use report/lvscols and report/lvssort configuration settings to define our own list", "of fields to use and to sort by that is different from defaults. You can do this for other", "reports in same manner with report/{pvs,pvseg,vgs,seg}{cols,sort} configuration settings.", "Also note that in the example below, we don't display the \"lvtime\" field even though we're", "using it for sorting - this is allowed.", "# lvmconfig --type full report/lvscols report/lvssort", "lvscols=\"lvname,lvsize,origin,poollv,copypercent\"", "lvssort=\"-lvtime\"", "# lvs", "LV LSize Origin Pool Cpy%Sync", "lvol1 4.00m 100.00", "lvol0 4.00m", "You can use -o--options command line option to override current configuration directly on", "command line.", "# lvs -o lvname,lvsize", "LV LSize", "lvol1 4.00m", "lvol0 4.00m", "# lvs -o+lvlayout", "LV LSize Origin Pool Cpy%Sync Layout", "lvol1 4.00m 100.00 raid,raid1", "lvol0 4.00m linear", "# lvs -o-origin", "LV LSize Pool Cpy%Sync", "lvol1 4.00m 100.00", "lvol0 4.00m", "# lvs -o lvname,lvsize,origin -o+lvlayout -o-origin -O lvname", "LV LSize Layout", "lvol0 4.00m linear", "lvol1 4.00m raid,raid1", "You can obtain the same information with single command where all the information about PVs,", "PV segments, LVs and LV segments are obtained per VG under a single VG lock for consistency,", "see also lvm-fullreport(8) man page for more information. The fullreport has its own configu‐", "ration settings to define field sets to use, similar to individual reports as displayed", "above, but configuration settings have \"full\" suffix now. This way, it's possible to con‐", "figure different sets of fields to display and to sort by for individual reports as well as", "the full report.", "# lvmconfig --type full report/pvscolsfull \\", "report/pvssortfull report/pvsegscolsfull \\", "report/pvsegssortfull report/vgscolsfull \\", "report/vgssortfull report/lvscolsfull \\", "report/lvssortfull report/segscolsfull \\", "report/segssortfull", "pvscolsfull=\"pvname,vgname\"", "pvssortfull=\"pvname\"", "pvsegscolsfull=\"pvname,pvsegstart,pvsegsize\"", "pvsegssortfull=\"pvuuid,pvsegstart\"", "vgscolsfull=\"vgname\"", "vgssortfull=\"vgname\"", "lvscolsfull=\"lvname,vgname\"", "lvssortfull=\"vgname,lvname\"", "segscolsfull=\"lvname,segstart,segsize\"", "segssortfull=\"lvuuid,segstart\"", "# lvm fullreport", "VG", "vg", "PV VG", "/dev/sda vg", "/dev/sdb vg", "LV VG", "lvol0 vg", "lvol1 vg", "PV Start SSize", "/dev/sda 0 1", "/dev/sda 1 1", "/dev/sda 2 1", "/dev/sda 3 22", "/dev/sdb 0 1", "/dev/sdb 1 1", "/dev/sdb 2 23", "LV Start SSize", "lvol0 0 4.00m", "lvol1 0 4.00m", "If you look at the lvs output above, you can see that the report also contains fields for", "which there is no information to display (e.g. the columns under \"Origin\" and \"Pool\" heading", "- the \"origin\" and \"poollv\" fields). LVM can automatically compact report output so such", "fields are not included in final output. To enable this feature and to compact all fields,", "use report/compactoutput=1 in your configuration.", "# lvmconfig --type full report/compactoutput", "compactoutput=1", "# lvs", "LV LSize Cpy%Sync", "lvol1 4.00m 100.00", "lvol0 4.00m", "# lvs vg/lvol0", "LV LSize", "lvol0 4.00m", "Alternatively, you can define which fields should be compacted by configuring report/com‐‐", "pactoutputcols configuration setting (or -o--options # command line option).", "# lvmconfig --type full report/compactoutput report/compactoutputcols", "compactoutput=0", "compactoutputcols=\"origin\"", "# lvs", "LV LSize Pool Cpy%Sync", "lvol1 4.00m 100.00", "lvol0 4.00m", "# lvs vg/lvol0", "LV LSize Pool", "lvol0 4.00m", "# lvs -o#poollv", "LV LSize Origin Cpy%Sync", "lvol1 4.00m 100.00", "lvol0 4.00m", "We will use report/compactoutput=1 for subsequent examples.", "By default, LVM displays sizes in reports in human-readable form which means that the most", "suitable unit is used so it's easy to read. You can use report/units configuration setting", "(or --units option directly on command line) and report/suffix configuration setting (or", "--nosuffix command line option) to change this.", "# lvs --units b --nosuffix", "LV LSize Cpy%Sync", "lvol1 4194304 100.00", "lvol0 4194304", "If you want to configure whether report headings are displayed or not, use report/headings", "configuration settings (or --noheadings command line option).", "# lvs --noheadings", "lvol1 4.00m 100.00", "lvol0 4.00m", "In some cases, it may be useful to display report content as key=value pairs where key here", "is actually the field name. Use report/prefixes configuration setting (or --nameprefixes com‐", "mand line option) to switch between standard output and the key=value output. The key=value", "pair is the output that is suitable for use in scripts and for other tools to parse easily.", "Usually, you also don't want to display headings with the output that has these key=value", "pairs.", "# lvs --noheadings --nameprefixes", "LVM2LVNAME='lvol1' LVM2LVSIZE='4.00m' LVM2COPYPERCENT='100.00'", "LVM2LVNAME='lvol0' LVM2LVSIZE='4.00m' LVM2COPYPERCENT=''", "To define whether quotation marks in key=value pairs should be used or not, use report/quoted", "configuration setting (or --unquoted command line option).", "# lvs --noheadings --nameprefixes --unquoted", "LVM2LVNAME=lvol1 LVM2LVSIZE=4.00m LVM2COPYPERCENT=100.00", "LVM2LVNAME=lvol0 LVM2LVSIZE=4.00m LVM2COPYPERCENT=", "For easier parsing, you can even transpose the report so each column now becomes a row in the", "output. This is done with report/outputasrows configuration setting (or --rows command line", "option).", "# lvs --noheadings --nameprefixes --unquoted --rows", "LVM2LVNAME=lvol1 LVM2LVNAME=lvol0", "LVM2LVSIZE=4.00m LVM2LVSIZE=4.00m", "LVM2COPYPERCENT=100.00 LVM2COPYPERCENT=", "Use report/separator configuration setting (or --separator command line option) to define", "your own field separator to use.", "# lvs --noheadings --nameprefixes --unquoted --separator \" | \"", "LVM2LVNAME=lvol1 | LVM2LVSIZE=4.00m | LVM2COPYPERCENT=100.00", "LVM2LVNAME=lvol0 | LVM2LVSIZE=4.00m | LVM2COPYPERCENT=", "If you are using your own separator, the columns in the output are not aligned by default.", "Use report/aligned configuration setting (or --aligned command line option) for LVM to add", "extra spaces in report to align the output properly.", "# lvs --separator \" | \"", "LV | LSize | Cpy%Sync", "lvol1 | 4.00m | 100.00", "lvol0 | 4.00m |", "# lvs --separator \" | \" --aligned", "LV | LSize | Cpy%Sync", "lvol1 | 4.00m | 100.00", "lvol0 | 4.00m |", "Let's display one one more field in addition (\"lvtags\" in this example) for the lvs report", "output.", "# lvs -o+lvtags", "LV LSize Cpy%Sync LV Tags", "lvol1 4.00m 100.00", "lvol0 4.00m tagA,tagB", "The \"LV Tags\" column in the example above displays two list values, separated by \",\" charac‐", "ter for LV lvol0. If you need different list item separator, use report/listitemseparator", "configuration setting its definition.", "# lvmconfig --type full report/listitemseparator", "listitemseparator=\";\"", "# lvs -o+tags", "LV LSize Cpy%Sync LV Tags", "lvol1 4.00m 100.00", "lvol0 4.00m tagA;tagB", "But let's still use the original \",\" character for listitemseparator for subsequent exam‐", "ples.", "Format for any of time values displayed in reports can be configured with report/timeformat", "configuretion setting. By default complete date and time is displayed, including timezone.", "# lvmconfig --type full report/timeformat", "timeformat=\"%Y-%m-%d %T %z\"", "# lvs -o+time", "LV LSize Cpy%Sync CTime", "lvol1 4.00m 100.00 2016-08-29 12:53:36 +0200", "lvol0 4.00m 2016-08-29 10:15:17 +0200", "We can change time format in similar way as we do when using date(1) command or strftime(3)", "function (lvmconfig --type default --withcomments report/timeformat will give you complete", "list of available formatting options). In the example below, we decided to use %s for number", "of seconds since Epoch (1970-01-01 UTC).", "# lvmconfig --type full report/timeformat", "timeformat=\"%s\"", "# lvs", "LV Attr LSize Cpy%Sync LV Tags CTime", "lvol1 rwi-a-r--- 4.00m 100.00 1472468016", "lvol0 -wi-a----- 4.00m tagA,tagB 1472458517", "The lvs does not display hidden LVs by default - to include these LVs in the output, you need", "to use -a--all command line option. Names for these hidden LVs are displayed within square", "brackets.", "# lvs -a", "LV LSize Cpy%Sync", "lvol1 4.00m 100.00", "[lvol1rimage0] 4.00m", "[lvol1rmeta0] 4.00m", "[lvol1rimage1] 4.00m", "[lvol1rmeta1] 4.00m", "lvol0 4.00m", "You can configure LVM to display the square brackets for hidden LVs or not with re‐‐", "port/markhiddendevices configuration setting.", "# lvmconfig --type full report/markhiddendevices", "markhiddendevices=0", "# lvs -a", "LV LSize Cpy%Sync", "lvol1 4.00m 100.00", "lvol1rimage0 4.00m", "lvol1rmeta0 4.00m", "lvol1rimage1 4.00m", "lvol1rmeta1 4.00m", "lvol0 4.00m", "It's not recommended to use LV marks for hidden devices to decide whether the LV is the one", "to use by end users or not. Please, use \"lvrole\" field instead which can report whether the", "LV is \"public\" or \"private\". The private LVs are used by LVM only and they should not be ac‐", "cessed directly by end users.", "# lvs -a -o+lvrole", "LV LSize Cpy%Sync Role", "lvol1 4.00m 100.00 public", "lvol1rimage0 4.00m private,raid,image", "lvol1rmeta0 4.00m private,raid,metadata", "lvol1rimage1 4.00m private,raid,image", "lvol1rmeta1 4.00m private,raid,metadata", "lvol0 4.00m public", "Some of the reporting fields that LVM reports are of binary nature. For such fields, it's ei‐", "ther possible to display word representation of the value (this is used by default) or nu‐", "meric value (0/1 or -1 in case the value is undefined).", "# lvs -o+lvactivelocally", "LV LSize Cpy%Sync ActLocal", "lvol1 4.00m 100.00 active locally", "lvol0 4.00m active locally", "We can change the way how these binary values are displayed with report/binaryvaluesasnu‐‐", "meric configuration setting.", "# lvmconfig --type full report/binaryvaluesasnumeric", "binaryvaluesasnumeric=1", "# lvs -o+lvactivelocally", "LV LSize Cpy%Sync ActLocal", "lvol1 4.00m 100.00 1", "lvol0 4.00m 1", "LVM can output reports in different formats - use report/outputformat configuration setting", "(or --reportformat command line option) to swith the report output format. Currently, LVM", "supports \"basic\" (all the examples we used above used this format) and \"JSON\" output format.", "# lvs -o lvname,lvsize --reportformat json", "\"report\": [", "\"lv\": [", "{\"lvname\":\"lvol1\", \"lvsize\":\"4.00m\"},", "{\"lvname\":\"lvol0\", \"lvsize\":\"4.00m\"}", "Note that some configuration settings and command line options have no effect with certain", "report formats. For example, with JSON output, it doesn't have any meaning to use re‐‐", "port/aligned (--aligned), report/noheadings (--noheadings), report/columnsasrows (--rows)", "or report/buffered (--unbuffered). All these configuration settings and command line options", "are ignored if using the JSON report output format.", "If you need to select only specific rows from report, you can use LVM's report selection fea‐", "ture. If you call -S help, you'll get quick help on selection. The help con‐", "tains list of all fields that LVM can use in reports together with its type enclosed in", "square brackets. The example below contains a line from lvs -S help.", "# lvs -S help", "...", "lvsize - Size of LV in current units. [size]", "...", "This line tells you you that the \"lvsize\" field is of \"size\" type. If you look at the bottom", "of the help output, you can see section about \"Selection operators\" and its \"Comparison oper‐", "ators\".", "# lvs -S help", "...", "Selection operators", "-------------------", "Comparison operators:", "=~ - Matching regular expression. [regex]", "!~ - Not matching regular expression. [regex]", "= - Equal to. [number, size, percent, string, string list, time]", "!= - Not equal to. [number, size, percent, string, stringlist, time]", ">= - Greater than or equal to. [number, size, percent, time]", "> - Greater than. [number, size, percent, time]", "<= - Less than or equal to. [number, size, percent, time]", "< - Less than. [number, size, percent, time]", "since - Since specified time (same as '>='). [time]", "after - After specified time (same as '>'). [time]", "until - Until specified time (same as '<='). [time]", "before - Before specified time (same as '<'). [time]", "...", "Here you can match comparison operators that you may use with the \"lvsize\" field which is of", "type \"size\" - it's =, !=, >=, >, <= and <. You can find applicable comparison operators for", "other fields and other field types the same way.", "To demostrate selection functionality in LVM, we will create more LVs in addition to lvol0", "and lvol1 we used in our previous examples.", "# lvs -o name,size,origin,snappercent,tags,time", "LV LSize Origin Snap% LV Tags CTime", "lvol4 4.00m lvol2 24.61 2016-09-09 16:57:44 +0200", "lvol3 4.00m lvol2 5.08 2016-09-09 16:56:48 +0200", "lvol2 8.00m tagA,tagC,tagD 2016-09-09 16:55:12 +0200", "lvol1 4.00m 2016-08-29 12:53:36 +0200", "lvol0 4.00m tagA,tagB 2016-08-29 10:15:17 +0200", "When selecting size and percent fields, we don't need to use units. For sizes, default \"m\"", "(for MiB) is used - this is the same behaviour as already used for LVM commands when specify‐", "ing sizes (e.g. lvcreate -L). For percent fields, \"%\" is assumed automatically if it's not", "specified. The example below also demonstrates how several criteria can be combined to‐", "gether.", "# lvs -o name,size,snappercent -S 'size=8m'", "LV LSize", "lvol2 8.00m", "# lvs -o name,size,snappercent -S 'size=8'", "LV LSize", "lvol2 8.00m", "# lvs -o name,size,snappercent -S 'size < 5000k'", "LV LSize Snap%", "lvol4 4.00m 24.61", "lvol3 4.00m 5.08", "lvol1 4.00m", "lvol0 4.00m", "# lvs -o name,size,snappercent -S 'size < 5000k && snappercent > 20'", "LV LSize Snap%", "lvol4 4.00m 24.61", "# lvs -o name,size,snappercent \\", "-S '(size < 5000k && snappercent > 20%) || name=lvol2'", "LV LSize Snap%", "lvol4 4.00m 24.61", "lvol2 8.00m", "You can also use selection together with processing-oriented commands.", "# lvchange --addtag test -S 'size < 5000k'", "Logical volume vg/lvol1 changed.", "Logical volume vg/lvol0 changed.", "Logical volume vg/lvol3 changed.", "Logical volume vg/lvol4 changed.", "# lvchange --deltag test -S 'tags = test'", "Logical volume vg/lvol1 changed.", "Logical volume vg/lvol0 changed.", "Logical volume vg/lvol3 changed.", "Logical volume vg/lvol4 changed.", "LVM can recognize more complex values used in selection criteria for string list and time", "field types. For string lists, you can match whole list strictly, its subset or intersection.", "Let's take \"lvtags\" field as an example - we select only rows which contain \"tagA\" within", "tags field. We're using { } to denote that we're interested in subset that matches. If the", "subset has only one item, we can leave out { }.", "# lvs -o name,tags -S 'tags={tagA}'", "LV LV Tags", "lvol2 tagA,tagC,tagD", "lvol0 tagA,tagB", "# lvs -o name,tags -S 'tags=tagA'", "LV LV Tags", "lvol2 tagA,tagC,tagD", "lvol0 tagA,tagB", "Depending on whether we use \"&&\" (or \",\") or \"||\" ( or \"#\") as delimiter for items in the set", "we define in selection criterion for string list, we either match subset (\"&&\" or \",\") or", "even intersection (\"||\" or \"#\").", "# lvs -o name,tags -S 'tags={tagA,tagC,tagD}'", "LV LV Tags", "lvol2 tagA,tagC,tagD", "# lvs -o name,tags -S 'tags={tagA || tagC || tagD}'", "LV LV Tags", "lvol2 tagA,tagC,tagD", "lvol0 tagA,tagB", "To match the complete set, use [ ] with \"&&\" (or \",\") as delimiter for items. Also note that", "the order in which we define items in the set is not relevant.", "# lvs -o name,tags -S 'tags=[tagA]'", "# lvs -o name,tags -S 'tags=[tagB,tagA]'", "LV LV Tags", "lvol0 tagA,tagB", "If you use [ ] with \"||\" (or \"#\"), this is exactly the same as using { }.", "# lvs -o name,tags -S 'tags=[tagA || tagC || tagD]'", "LV LV Tags", "lvol2 tagA,tagC,tagD", "lvol0 tagA,tagB", "To match a set with no items, use \"\" to denote this (note that we have output compaction en‐", "abled so the \"LV Tags\" column is not displayed in the example below because it's blank and so", "it gets compacted).", "# lvs -o name,tags -S 'tags=\"\"'", "LV", "lvol4", "lvol3", "lvol1", "# lvs -o name,tags -S 'tags!=\"\"'", "LV LV Tags", "lvol2 tagA,tagC,tagD", "lvol0 tagA,tagB", "When doing selection based on time fields, we can use either standard, absolute or freeform", "time expressions in selection criteria. Examples below are using standard forms.", "# lvs -o name,time", "LV CTime", "lvol4 2016-09-09 16:57:44 +0200", "lvol3 2016-09-09 16:56:48 +0200", "lvol2 2016-09-09 16:55:12 +0200", "lvol1 2016-08-29 12:53:36 +0200", "lvol0 2016-08-29 10:15:17 +0200", "# lvs -o name,time -S 'time since \"2016-09-01\"'", "LV CTime", "lvol4 2016-09-09 16:57:44 +0200", "lvol3 2016-09-09 16:56:48 +0200", "lvol2 2016-09-09 16:55:12 +0200", "# lvs -o name,time -S 'time since \"2016-09-09 16:56\"'", "LV CTime", "lvol4 2016-09-09 16:57:44 +0200", "lvol3 2016-09-09 16:56:48 +0200", "# lvs -o name,time -S 'time since \"2016-09-09 16:57:30\"'", "LV CTime", "lvol4 2016-09-09 16:57:44 +0200", "# lvs -o name,time \\", "-S 'time since \"2016-08-29\" && time until \"2016-09-09 16:55:12\"'", "LV CTime", "lvol2 2016-09-09 16:55:12 +0200", "lvol1 2016-08-29 12:53:36 +0200", "lvol0 2016-08-29 10:15:17 +0200", "# lvs -o name,time \\", "-S 'time since \"2016-08-29\" && time before \"2016-09-09 16:55:12\"'", "LV CTime", "lvol1 2016-08-29 12:53:36 +0200", "lvol0 2016-08-29 10:15:17 +0200", "Time operators have synonyms: \">=\" for since, \"<=\" for until, \">\" for \"after\" and \"<\" for", "\"before\".", "# lvs -o name,time \\", "-S 'time >= \"2016-08-29\" && time <= \"2016-09-09 16:55:30\"'", "LV CTime", "lvol2 2016-09-09 16:55:12 +0200", "lvol1 2016-08-29 12:53:36 +0200", "lvol0 2016-08-29 10:15:17 +0200", "# lvs -o name,time \\", "-S 'time since \"2016-08-29\" && time < \"2016-09-09 16:55:12\"'", "LV CTime", "lvol1 2016-08-29 12:53:36 +0200", "lvol0 2016-08-29 10:15:17 +0200", "Example below demonstrates using absolute time expression.", "# lvs -o name,time --config report/timeformat=\"%s\"", "LV CTime", "lvol4 1473433064", "lvol3 1473433008", "lvol2 1473432912", "lvol1 1472468016", "lvol0 1472458517", "# lvs -o name,time -S 'time since @1473433008'", "LV CTime", "lvol4 2016-09-09 16:57:44 +0200", "lvol3 2016-09-09 16:56:48 +0200", "Examples below demonstrates using freeform time expressions.", "# lvs -o name,time -S 'time since \"2 weeks ago\"'", "LV CTime", "lvol4 2016-09-09 16:57:44 +0200", "lvol3 2016-09-09 16:56:48 +0200", "lvol2 2016-09-09 16:55:12 +0200", "lvol1 2016-08-29 12:53:36 +0200", "lvol0 2016-08-29 10:15:17 +0200", "# lvs -o name,time -S 'time since \"1 week ago\"'", "LV CTime", "lvol4 2016-09-09 16:57:44 +0200", "lvol3 2016-09-09 16:56:48 +0200", "lvol2 2016-09-09 16:55:12 +0200", "# lvs -o name,time -S 'time since \"2 weeks ago\"'", "LV CTime", "lvol1 2016-08-29 12:53:36 +0200", "lvol0 2016-08-29 10:15:17 +0200", "# lvs -o name,time -S 'time before \"1 week ago\"'", "LV CTime", "lvol1 2016-08-29 12:53:36 +0200", "lvol0 2016-08-29 10:15:17 +0200", "# lvs -o name,time -S 'time since \"68 hours ago\"'", "LV CTime", "lvol4 2016-09-09 16:57:44 +0200", "lvol3 2016-09-09 16:56:48 +0200", "lvol2 2016-09-09 16:55:12 +0200", "# lvs -o name,time -S 'time since \"1 year 3 months ago\"'", "LV CTime", "lvol4 2016-09-09 16:57:44 +0200", "lvol3 2016-09-09 16:56:48 +0200", "lvol2 2016-09-09 16:55:12 +0200", "lvol1 2016-08-29 12:53:36 +0200", "lvol0 2016-08-29 10:15:17 +0200", "As described in categorization based on reporting facility section at the beginning of this", "document, both report-oriented and processing-oriented LVM commands can report the command", "log if this is enabled with log/reportcommandlog configuration setting. Just like any", "other report, we can set the set of fields to display (log/commandlogcols) and to sort by", "(log/commandlogsort) for this report.", "# lvmconfig --type full log/reportcommandlog log/commandlogcols \\", "log/commandlogsort log/commandlogselection", "reportcommandlog=1", "commandlogcols=\"logseqnum,logtype,logcontext,logobjecttype,", "logobjectname,logobjectgroup,logmessage,", "logerrno,logretcode\"", "commandlogsort=\"logseqnum\"", "commandlogselection=\"!(logtype=status && message=success)\"", "# lvs", "Logical Volume", "==============", "LV LSize Cpy%Sync", "lvol1 4.00m 100.00", "lvol0 4.00m", "Command Log", "===========", "Seq LogType Context ObjType ObjName ObjGrp Msg Errno RetCode", "As you can see, the command log is empty (it contains only field names). By default, LVM", "uses selection on the command log report and this case no row matched the selection criteria,", "see also log report specifics section in this document for more information. We're displaying", "complete log report in the example below where we can see that both LVs lvol0 and lvol1 were", "successfully processed as well as the VG vg they are part of.", "# lvmconfig --type full log/commandlogselection", "commandlogselection=\"all\"", "# lvs", "Logical Volume", "==============", "LV LSize Cpy%Sync", "lvol1 4.00m 100.00", "lvol0 4.00m", "Command Log", "===========", "Seq LogType Context ObjType ObjName ObjGrp Msg Errno RetCode", "1 status processing lv lvol0 vg success 0 1", "2 status processing lv lvol1 vg success 0 1", "3 status processing vg vg success 0 1", "# lvchange -an vg/lvol1", "Command Log", "===========", "Seq LogType Context ObjType ObjName ObjGrp Msg Errno RetCode", "1 status processing lv lvol1 vg success 0 1", "2 status processing vg vg success 0 1", "To configure the log report directly on command line, we need to use --configreport option", "before we start any -o--options, -O--sort or -S--select that is targeted for log report.", "# lvs -o lvname,lvsize --configreport log -o logobjecttype, \\", "logobjectname,logmessage,logretcode", "Logical Volume", "==============", "LV LSize", "lvol1 4.00m", "lvol0 4.00m", "Command Log", "===========", "ObjType ObjName Msg RetCode", "lv lvol0 success 1", "lv lvol1 success 1", "vg vg success 1", "The lvm fullreport, with or without log report, consists of several reports - the --configre‐‐", "port is also used to target particular subreport here.", "Below is an extended example with lvm fullreport to illustrate combination of various op‐", "tions. The report output is in JSON format. Also, we configure \"vg\", \"pvseg\", \"seg\" and", "\"log\" subreport to contain only specified fields. For the \"pvseg\" subreport, we're intested", "only in PV names having \"sda\" in their name. For the \"log\" subreport we're intested only in", "log lines related to either \"lvol0\" object or object having \"sda\" in its name. Also, for the", "log subreport we define ordering to be based on \"logobjecttype\" field.", "# lvm fullreport --reportformat json \\", "--configreport vg -o vgname,vgsize \\", "--configreport pvseg -o pvname,pvsegstart \\", "-S 'pvname=~sda' \\", "--configreport seg -o lvname,segstart \\", "--configreport log -o logobjecttype,logobjectname \\", "-O logobjecttype \\", "-S 'logobjectname=lvol0 || \\", "logobjectname=~sda'", "\"report\": [", "\"vg\": [", "{\"vgname\":\"vg\", \"vgsize\":\"200.00m\"}", "\"pv\": [", "{\"pvname\":\"/dev/sda\", \"vgname\":\"vg\"},", "{\"pvname\":\"/dev/sdb\", \"vgname\":\"vg\"}", "\"lv\": [", "{\"lvname\":\"lvol0\", \"vgname\":\"vg\"},", "{\"lvname\":\"lvol1\", \"vgname\":\"vg\"}", "\"pvseg\": [", "{\"pvname\":\"/dev/sda\", \"pvsegstart\":\"0\"},", "{\"pvname\":\"/dev/sda\", \"pvsegstart\":\"1\"},", "{\"pvname\":\"/dev/sda\", \"pvsegstart\":\"2\"},", "{\"pvname\":\"/dev/sda\", \"pvsegstart\":\"3\"}", "\"seg\": [", "{\"lvname\":\"lvol0\", \"segstart\":\"0 \"},", "{\"lvname\":\"lvol1\", \"segstart\":\"0 \"}", "\"log\": [", "{\"logobjecttype\":\"lv\", \"logobjectname\":\"lvol0\"},", "{\"logobjecttype\":\"lv\", \"logobjectname\":\"lvol0\"},", "{\"logobjecttype\":\"pv\", \"logobjectname\":\"/dev/sda\"},", "{\"logobjecttype\":\"pv\", \"logobjectname\":\"/dev/sda\"},", "As already stated in log report coverage paragraph under log report specifics in this docu‐", "mentation, when using LVM shell the log report coverage is wider. There's also special com‐", "mand designed to query last command's log report in the LVM shell - the lastlog command.", "The example below illustrates a situation where we called lvs command. After that, we in‐", "spected the log report with the lastlog, without any selection so all the log report is dis‐", "played on output. Then we called lastlog further, giving various selection criteria. Then we", "ran unknown LVM command \"abc\" for which the log report displays appropriate failure state.", "# lvm", "lvm> lvs", "Logical Volume", "==============", "LV LSize Cpy%Sync", "lvol1 4.00m 100.00", "lvol0 4.00m", "Command Log", "===========", "Seq LogType Context ObjType ObjName ObjGrp Msg Errno RetCode", "1 status processing lv lvol0 vg success 0 1", "2 status processing lv lvol1 vg success 0 1", "3 status processing vg vg success 0 1", "4 status shell cmd lvs success 0 1", "lvm> lastlog", "Command Log", "===========", "Seq LogType Context ObjType ObjName ObjGrp Msg Errno RetCode", "1 status processing lv lvol0 vg success 0 1", "2 status processing lv lvol1 vg success 0 1", "3 status processing vg vg success 0 1", "4 status shell cmd lvs success 0 1", "lvm> lastlog -S logobjecttype=lv", "Command Log", "===========", "Seq LogType Context ObjType ObjName ObjGrp Msg Errno RetCode", "1 status processing lv lvol0 vg success 0 1", "2 status processing lv lvol1 vg success 0 1", "lvm> lastlog -S logcontext=shell", "Command Log", "===========", "Seq LogType Context ObjType ObjName ObjGrp Msg Errno RetCode", "4 status shell cmd lvs success 0 1", "lvm> abc", "Command Log", "===========", "Seq LogType Context ObjType ObjName ObjGrp Msg Errno RetCode", "1 error shell cmd abc No such command 'abc'. Try 'help'. -1 0", "2 status shell cmd abc failure -1 2" ], "see_also": [], "section_outline": [ { "name": "NAME", "lines": 3, "subsections": [] }, { "name": "DESCRIPTION", "lines": 5, "subsections": [ { "name": "Categorization based on reporting facility", "lines": 3 }, { "name": "Report-oriented", "lines": 6 }, { "name": "Processing-oriented", "lines": 15 } ] }, { "name": "Terms", "lines": 8, "subsections": [ { "name": "Common report configuration settings and command line options", "lines": 163 }, { "name": "Main report specifics", "lines": 87 }, { "name": "Log report specifics", "lines": 22 }, { "name": "-S--select", "lines": 6 }, { "name": "Log report coverage", "lines": 39 }, { "name": "Log report content", "lines": 92 } ] }, { "name": "Selection", "lines": 8, "subsections": [ { "name": "List of operators recognized in selection criteria", "lines": 50 }, { "name": "Field types and selection operands", "lines": 2 }, { "name": "-S", "lines": 108, "flag": "-S" }, { "name": "Informal grammar specification", "lines": 15 } ] }, { "name": "EXAMPLES", "lines": 1, "subsections": [ { "name": "Basic usage", "lines": 168 }, { "name": "Automatic output compaction", "lines": 42 }, { "name": "Further formatting options", "lines": 175 }, { "name": "Changing output format", "lines": 23 }, { "name": "Selection", "lines": 264 }, { "name": "Command log reporting", "lines": 58 }, { "name": "Handling multiple reports per single command", "lines": 77 }, { "name": "Report extensions for LVM shell", "lines": 55 } ] }, { "name": "SEE ALSO", "lines": 5, "subsections": [] } ], "sections": { "NAME": { "content": "lvmreport — LVM reporting and related features\n\n", "subsections": [] }, "DESCRIPTION": { "content": "LVM uses single reporting infrastructure that sets standard on LVM command's output and it\nprovides wide range of configuration settings and command line options to customize report\nand filter the report's output.\n\n", "subsections": [ { "name": "Categorization based on reporting facility", "content": "Based on functionality, commands which make use of the reporting infrastructure are divided\nin two groups:\n" }, { "name": "Report-oriented", "content": "These commands inform about current LVM state and their primary role is to display\nthis information in compendious way. To make a distinction, we will name this report\nas main report. The set of report-only commands include: pvs, vgs, lvs, pvdisplay,\nvgdisplay, lvdisplay, lvm devtypes, lvm fullreport. For further information about\nmain report, see main report specifics.\n" }, { "name": "Processing-oriented", "content": "These commands are responsible for changing LVM state and they do not contain any main\nreport as identified for report-oriented commands, they only perform some kind of pro‐\ncessing. The set of processing-oriented commands includes: pvcreate, vgcreate, lvcre‐\nate, pvchange, vgchange, lvchange, pvremove, vgremove, lvremove, pvresize, vgextend,\nvgreduce, lvextend, lvreduce, lvresize, lvrename, pvscan, vgscan, lvscan, pvmove,\nvgcfgbackup, vgck, vgconvert, vgexport, vgimport, vgmknodes.\n\nIf enabled, so called log report is either displayed solely (for processing-oriented com‐\nmands) or in addition to main report (for report-oriented commands). The log report contains\na log of operations, messages and per-object status with complete object identification col‐\nlected during LVM command execution. See log report specifics for more information about this\nreport type.\n\n\n" } ] }, "Terms": { "content": "When describing reporting functionality and features in this text, we will use terms row and\ncolumn. By row we mean series of values reported for single entity (for example single PV, VG\nor LV). Each value from the row then belongs to a column of certain type. The columns have\ncolumn headings which are short descriptions for the columns. The columns are referenced by\ncolumn names. Please note that this text is also using term field interchangeably with the\nterm column. Most of the time the term columns is abbreviated as col in configuration.\n\n", "subsections": [ { "name": "Common report configuration settings and command line options", "content": "There are common configuration settings and command line options which apply to both main re‐‐\nport and log report. Following lists contain all of them, separated into groups based on\ntheir use.\n\nCommon configuration settings:\n\n\n\n• Changing report output format, composition and other output modifiers:\n\n- global/units\n\n- global/suffix\n\n- report/outputformat\n\n- report/compactoutput\n\n- report/compactoutputcols\n\n- report/aligned\n\n- report/headings\n\n- report/separator\n\n- report/listitemseparator\n\n- report/prefixes\n\n- report/quoted\n\n- report/columnsasrows\n\n- report/binaryvaluesasnumeric\n\n- report/timeformat\n\n- report/markhiddendevices\n\n- report/twowordunknowndevice\n\n\n• Special settings\n\n- report/buffered\n\n\n\nThis document does not describe these settings in more detail - if you need detailed informa‐\ntion, including values which are accepted for the settings, please run lvmconfig --type de‐‐\nfault --withcomments . There are more configuration settings in addition to the com‐\nmon set listed above, but they are specific to either main report or log report, see main re‐‐\nport specifics and log report specifics for these settings. Besides configuring reports glob‐\nally by using configuration settings, there are also command line options you can use to ex‐\ntend, override or further specify the report configuration.\n\nCommon command line options:\n\n\n\n• Definition of the set set of fields to use\n\n- --options|-o FieldSet\nField set to use. See main report specifics and log report specifics for\ninformation about field sets configured with global configuratin settings\nthat this option overrides.\n\n- --options|-o+ FieldSet\nFields to include to current field set. See main report specifics and log\nreport specifics for information about field sets configured with global\nconfiguration settings that this option extends.\n\n- --options|-o- FieldSet\nFields to exclude from current field set. See main report specifics and\nlog report specifics for information about field sets configured with\nglobal configuration settings that this option reduces.\n\n- --options|-o# FieldSet\nCompaction of unused fields. Overrides report/compactoutputcols config‐\nuration setting.\n\n\n• Sorting\n\n- --sort|-O+ FieldSet\nFields to sort by in ascending order. See main report specifics and log\nreport specifics for information about field sets configured with global\nconfiguration settings that this option overrides.\n\n- --sort|-O- FieldSet\nFields to sort by in descending order. See main report specifics and log\nreport specifics for information about fields sets configured with global\nconfiguration settings that this options overrides.\n\n\n• Selection\n\n- --select|-S Selection\nDefine selection criteria for report output. For log report, this also\noverrides log/commandlogselection configuration setting, see also log\nreport specifics.\n\n\n• Changing output format and composition\n\n- --reportformat\nOverrides report/outputformat configuration setting.\n\n- --aligned\nOverrides report/aligned configuration setting.\n\n- --binary\nOverrides report/binaryvaluesasnumeric configuration setting.\n\n- --nameprefixes\nOverrides report/prefixes configuration setting.\n\n- --noheadings\nOverrides report/noheadings configuration setting.\n\n- --nosuffix\nOverrides global/suffix configuration setting.\n\n- --rows\nOverrides report/columnsasrows configuration setting.\n\n- --separator\nOverrides report/separator configuration setting.\n\n- --units\nOverrides global/units configuration setting.\n\n- --unquoted\nOverrides report/quoted configuration setting.\n\n\n• Special options\n\n- --configreport ReportName\nThis defines the ReportName for which any subsequent -o--columns,\n-O--sort or -S--select applies to. See also main report specifics and log\nreport specifics for possible ReportName values.\n\n- --logonly\nWhen an LVM command contains both main report and log report, this option\nsuppresses the main report output and it causes the log report output to\nbe displayed only.\n\n- --unbuffered\nOverrides report/bufffered configuration setting.\n\n\n\nThe FieldSet mentioned in the lists above is a set of field names where each field name is\ndelimited by \",\" character. Field set definition, sorting and selection may be repeated on\ncommand line (-o+/-o- includes/excludes fields to/from current list, for all the other re‐\npeatable options, the last value typed for the option on the command line is used). The Se‐‐\nlection is a string with selection criteria, see also Selection paragraph below for more in‐\nformation about constructing these criteria.\n\n\n" }, { "name": "Main report specifics", "content": "The main report currently encompasses these distinct subtypes, referenced by their name - Re‐‐\nportName as listed below. The command in parenthesis is representative command that uses the\nmain report subtype by default. Each subtype has its own configuration setting for global\nfield set definition as well as sort field definition (listed below each individual Report‐‐\nName):\n\n\n\n• pv representing report about Physical Volumes (pvs)\n\n- report/pvscols\n\n- report/pvssort\n\n\n• pvseg representing report about Physical Volume Segments (pvs --segments)\n\n- report/pvsegcols\n\n- report/pvsegsort\n\n\n• vg representing report about Volume Groups (vgs)\n\n- report/vgscols\n\n- report/vgssort\n\n\n• lv representing report about Logical Volumes (lvs)\n\n- report/lvscols\n\n- report/lvssort\n\n\n• seg representing report about Logical Volume Segments (lvs --segments)\n\n- report/segscols\n\n- report/segssort\n\n\n• full representing report combining all of the above as a whole (lvm fullreport)\n\n- report/pvscolsfull\n\n- report/pvssortfull\n\n- report/pvsegscolsfull\n\n- report/pvsegsortfull\n\n- report/vgscolsfull\n\n- report/vgssortfull\n\n- report/lvscolsfull\n\n- report/lvssortfull\n\n- report/segscolsfull\n\n- report/segssortfull\n\n\n• devtype representing report about device types (lvm devtypes)\n\n- report/devtypescols\n\n- report/devtypessort\n\n\nUse pvs, vgs, lvs -o help or lvm devtypes -o help to get complete list of fields that you can\nuse for main report. The list of fields in the help output is separated in groups based on\nwhich report type they belong to. Note that LVM can change final report type used if fields\nfrom different groups are combined together. Some of these combinations are not allowed in\nwhich case LVM will issue an error.\n\nFor all main report subtypes except full, it's not necessary to use --configreport ReportName\nto denote which report any subsequent -o, -O or -S option applies to as they always apply to\nthe single main report type. Currently, lvm fullreport is the only command that includes more\nthan one main report subtype. Therefore, the --configreport is particularly suitable for the\nfull report if you need to configure each of its subreports in a different way.\n\n\n" }, { "name": "Log report specifics", "content": "You can enable log report with log/reportcommandlog configuration setting - this function‐\nality is disabled by default. The log report contains a log collected during LVM command exe‐\ncution and then the log is displayed just like any other report known from main report. There\nis only one log report subtype as shown below together with related configuration settings\nfor fields, sorting and selection:\n\n\n\n• log representing log report\n\n- log/commandlogcols\n\n- log/commandlogsort\n\n- log/commandlogselection\n\n\nYou always need to use --configreport log together with -o--options, -O--sort or -S--selec‐‐\ntion to override configuration settings directly on command line for log report. When com‐\npared to main report, in addition to usual configuration settings for report fields and sort‐\ning, the log report has also configuration option for selection - report/commandlogselec‐‐\ntion. This configuration setting is provided for convenience so it's not necessary to use" }, { "name": "-S--select", "content": "tion criteria to be applied for log report. Default selection criteria used for log report\nare log/commandlogselection=\"!(logtype=status && message=success)\". This means that, by\ndefault, log report doesn't display status messages about successful operation and it dis‐\nplays only rows with error, warning, print-type messages and messages about failure states\n(for more information, see log report content below).\n" }, { "name": "Log report coverage", "content": "Currently, when running LVM commands directly (not in LVM shell), the log report covers com‐\nmand's processing stage which is the moment when LVM entities are iterated and processed one\nby one. It does not cover any command initialization nor command finalization stage. If there\nis any message issued out of log report's coverage range, such message goes directly to out‐\nput, bypassing the log report. By default, that is standard error output for error and warn‐\ning messages and standard output for common print-like messages.\n\nWhen running LVM commands in LVM shell, the log report covers the whole LVM command's execu‐\ntion, including command's processing as well as initialization and finalization stage. So\nfrom this point of view, the log report coverage is complete for executed LVM commands. Note\nthat there are still a few moments when LVM shell needs to initialize itself before it even\nenters the main loop in which it executes LVM commands. Also, there is a moment when LVM\nshell needs to prepare log report properly for next command executed in the shell and then,\nafter the command's run, the shell needs to display the log report for that recently executed\ncommand. If there is a failure or any other message issued during this time, the LVM will by‐\npass log report and display messages on output directly.\n\nFor these reasons and for completeness, it's not possible to rely fully on log report as the\nonly indicator of LVM command's status and the only place where all messages issued during\nLVM command execution are collected. You always need to check whether the command has not\nfailed out of log report's range by checking the non-report output too.\n\nTo help with this, LVM can separate output which you can then redirect to any custom file de‐‐\nscriptor that you prepare before running an LVM command or LVM shell and then you make LVM to\nuse these file descriptors for different kinds of output by defining environment variables\nwith file descriptor numbers. See also LVMOUTFD, LVMERRFD and LVMREPORTFD environment\nvariable description in lvm(8) man page.\n\nAlso note that, by default, reports use the same file descriptor as common print-like mes‐\nsages, which is standard output. If you plan to use log report in your scripts or any exter‐\nnal tool, you should use LVMOUTFD, LVMERRFD and LVMREPORTFD to separate all output\ntypes to different file descriptors. For example, with bash, that would be:\n\nLVMOUTFD=3 LVMERRFD=4 LVMREPORTFD=5 3>outfile 4>errfile 5>re‐\nportfile\n\nWhere the is either direct LVM command or LVM shell. You can collect all three\ntypes of output in particular files then.\n" }, { "name": "Log report content", "content": "Each item in the log report consists of these set of fields providing various information:\n\n\n\n• Basic information (mandatory):\n\n- logseqnum\nItem sequence number. The sequence number is unique for each log item and it in‐\ncreases in the order of the log items as they appeared during LVM command execu‐\ntion.\n\n\n- logtype\nType of log for the item. Currently, these types are used:\n\nstatus for any status information that is logged\n\nprint for any common message printed while the log is collected\n\nerror for any error message printed while the log is collected\n\nwarn for any warning message printed while the log is collected\n\n\n- logcontext\nContext of the log for the item. Currently, two contexts are identified:\n\nshell for the log collected in the outermost code before and after exe‐\ncuting concrete LVM commands\n\nprocessing for the log collected while processing LVM entities during LVM\ncommand execution\n\n\n\n• Message (mandatory):\n\n- logmessage\nAny message associated with current item. For status log type, the message con‐\ntains either success or failure denoting current state. For print, error and\nwarn log types, the message contains the exact message of that type that got is‐\nsued.\n\n\n• Object information (used only if applicable):\n\n- logobjecttype field\nType of the object processed. Currently, these object types are recognized:\n\ncmd for command as a whole\n\norphan for processing group of PVs not in any VG yet\n\npv for PV processing\n\nlabel for direct PV label processing (without VG metadata)\n\nvg for VG processing\n\nlv for LV processing\n\n\n- logobjectname\nName of the object processed.\n\n\n- logobjectid\nID of the object processed.\n\n\n- logobjectgroup\nA group where the processed object belongs to.\n\n\n- logobjectgroupid\nAn ID of a group where the processed object belongs to.\n\n\n• Numeric status (used only if applicable)\n\n- logerrno\nError number associated with current item.\n\n- logretcode\nRreturn code associated with current item.\n\n\n\nYou can also run --configreport log -o help to to display complete list of\nfields that you may use for the log report.\n\n" } ] }, "Selection": { "content": "Selection is used for a report to display only rows that match selection criteria. All rows\nare displayed with the additional selected field (-o selected) displaying 1 if the row\nmatches the Selection and 0 otherwise. The selection criteria are a set of statements com‐\nbined by logical and grouping operators. The statement consists of a field name for which a\nset of valid values is defined using comparison operators. For complete list of fields names\nthat you can use in selection, see the output of -S help. The help output also\ncontains type of values that each field displays enclosed in brackets.\n", "subsections": [ { "name": "List of operators recognized in selection criteria", "content": "• Comparison operators (cmpop)\n\n=~ matching regular expression.\n\n!~ not matching regular expression.\n\n= equal to.\n\n!= not equal to.\n\n>= greater than or equal to.\n\n> greater than\n\n<= less than or equal to.\n\n< less than.\n\n\n• Binary logical operators (cmplog)\n\n&& all fields must match\n\n, all fields must match\n\n|| at least one field must match\n\n# at least one field must match\n\n\n• Unary logical operators\n\n! logical negation\n\n\n• Grouping operators\n\n( left parenthesis\n\n) right parenthesis\n\n[ list start\n\n] list end\n\n{ list subset start\n\n} list subset end\n\n" }, { "name": "Field types and selection operands", "content": "Field type restricts the set of operators and values that you may use with the field when\ndefining selection criteria. You can see field type for each field if you run " }, { "name": "-S", "content": "nizes these field types in reports:\n\n\n• string for set of characters (for each string field type, you can use either string\nor regular expression - regex for the value used in selection criteria)\n\n• string list for set of strings\n\n• number for integer value\n\n• size for integer or floating point number with size unit suffix (see also lvcre‐‐\nate(8) man page and description for \"-L--size\" option for the list of recognized\nsuffixes)\n\n• percent for floating point number with or without \"%\" suffix (e.g. 50 or 50%)\n\n• time for time values\n\nWhen using string list in selection criteria, there are several ways how LVM can match string\nlist fields from report, depending on what list grouping operator is used and what item sepa‐\nrator is used within that set of items. Also, note that order of items does not matter here.\n\n\n• matching the set strictly where all items must match - use [ ], e.g. [\"a\",\"b\",\"c\"]\n\n• matching a subset of the set - use { } with \",\" or \"&&\" as item delimiter, e.g.\n{\"a\",\"b\",\"c\"}\n\n• matching an intersection with the set - use { } with \"#\" or \"||\" as item delimiter,\ne.g. {\"a\" || \"b\" || \"c\"}\n\nWhen using time in your selection criteria, LVM can recognize various time formats using\nstandard, absolute or freeform expressions. For examples demonstrating time expressions in\nselection criteria, see EXAMPLES section.\n\n\n\n• Standard time format\n\n\n- date\n\nYYYY-MM-DD\n\nYYYY-MM, auto DD=1\n\nYYYY, auto MM=01 and DD=01\n\n\n- time\n\nhh:mm:ss\n\nhh:mm, auto ss=0\n\nhh, auto mm=0, auto ss=0\n\n\n- timezone\n\n+hh:mm or -hh:mm\n\n+hh or -hh\n\nThe full date/time specification is YYYY-MM-DD hh:mm:ss. Users are able to leave\ndate/time parts from right to left. Whenever these parts are left out, a range is\nassumed automatically with second granularity. For example:\n\n\n\"2015-07-07 9:51\" means range of \"2015-07-07 9:51:00\" - \"2015-07-07\n9:51:59\".\n\n\"2015-07\" means range of \"2015-07-01 0:00:00\" - \"2015-07-31 23:59:59\"\n\n\"2015\" means range of \"2015-01-01 0:00:00\" - \"2015-12-31 23:59:59\"\n\n\n\n• Absolute time format\n\nAbsolute time is defined as number of seconds since the Epoch (1970:01:01 00:00\n+00:00).\n\n\n- @seconds\n\n\n• Freeform time format\n\n- weekday names (\"Sunday\" - \"Saturday\" or abbreviated as \"Sun\" - \"Sat\")\n\n- labels for points in time (\"noon\", \"midnight\")\n\n- labels for a day relative to current day (\"today\", \"yesterday\")\n\n- points back in time with relative offset from today (N is a number)\n\n\"N\" \"seconds\" / \"minutes\" / \"hours\" / \"days\" / \"weeks\" / \"years\" \"ago\"\n\n\"N\" \"secs\" / \"mins\" / \"hrs\" ... \"ago\"\n\n\"N\" \"s\" / \"m\" / \"h\" ... \"ago\"\n\n- time specification either in hh:mm:ss format or with AM/PM suffixes\n\n- month names (\"January\" - \"December\" or abbreviated as \"Jan\" - \"Dec\")\n\n", "flag": "-S" }, { "name": "Informal grammar specification", "content": "STATEMENT = column cmpop VALUE | STATEMENT logop STATEMENT | (STATEMENT) |\n!(STATEMENT)\n\nVALUE = [VALUE logop VALUE]\nFor list-based types: string list. Matches strictly. The logop must always be\nof one type within the whole list value.\n\nVALUE = {VALUE logop VALUE}\nFor list-based types: string list. Matches a subset. The logop must always be\nof one type within the whole list value.\n\nVALUE = value\nFor scalar types: number, size, percent, string (or string regex).\n\n" } ] }, "EXAMPLES": { "content": "", "subsections": [ { "name": "Basic usage", "content": "We start our examples with default configuration - lvmconfig(8) is helpful command to display\nconfiguration settings which are currently used, including all configuration related to re‐\nporting. We will use it throughout examples below to display current configuration.\n\n# lvmconfig --type full global/units global/suffix \\\nreport/outputformat report/compactoutput \\\nreport/compactoutputcols report/aligned \\\nreport/headings report/separator \\\nreport/listitemseparator report/prefixes \\\nreport/quoted report/columnsasrows \\\nreport/binaryvaluesasnumeric report/timeformat \\\nreport/markhiddendevices report/twowordunknowndevice \\\nreport/buffered\nunits=\"h\"\nsuffix=1\noutputformat=\"basic\"\ncompactoutput=0\ncompactoutputcols=\"\"\naligned=1\nheadings=1\nseparator=\" \"\nlistitemseparator=\",\"\nprefixes=0\nquoted=1\ncolumnsasrows=0\nbinaryvaluesasnumeric=0\ntimeformat=\"%Y-%m-%d %T %z\"\nmarkhiddendevices=1\ntwowordunknowndevice=0\nbuffered=1\n\nAlso, we start with simple LVM layout with two PVs (/dev/sda, /dev/sdb), VG (vg) and two LVs\n(lvol0 and lvol1) in the VG. We display all possible reports as single commands here, see\nalso pvs(8), vgs(8), lvs(8) man pages for more information. The field set for each report\ntype is configured with configuration settings as we already mentioned in main report\nspecifics section in this man page.\n\n# lvmconfig --type full report/pvscols report/pvssort \\\nreport/pvsegscols report/pvsegssort report/vgscols \\\nreport/vgssort report/lvscols report/lvssort \\\nreport/segscols report/segssort\npvscols=\"pvname,vgname,pvfmt,pvattr,pvsize,pvfree\"\npvssort=\"pvname\"\npvsegscols=\"pvname,vgname,pvfmt,pvattr,pvsize,pvfree,\npvsegstart,pvsegsize\"\npvsegssort=\"pvname,pvsegstart\"\nvgscols=\"vgname,pvcount,lvcount,snapcount,vgattr,vgsize,vgfree\"\nvgssort=\"vgname\"\nlvscols=\"lvname,vgname,lvattr,lvsize,poollv,origin,movepv,\nmirrorlog,copypercent,convertlv\"\nlvssort=\"vgname,lvname\"\nsegscols=\"lvname,vgname,lvattr,stripes,segtype,segsize\"\nsegssort=\"vgname,lvname,segstart\"\n\n# pvs\nPV VG Fmt Attr PSize PFree\n/dev/sda vg lvm2 a-- 100.00m 88.00m\n/dev/sdb vg lvm2 a-- 100.00m 92.00m\n\n# pvs --segments\nPV VG Fmt Attr PSize PFree Start SSize\n/dev/sda vg lvm2 a-- 100.00m 88.00m 0 1\n/dev/sda vg lvm2 a-- 100.00m 88.00m 1 1\n/dev/sda vg lvm2 a-- 100.00m 88.00m 2 1\n/dev/sda vg lvm2 a-- 100.00m 88.00m 3 22\n/dev/sdb vg lvm2 a-- 100.00m 92.00m 0 1\n/dev/sdb vg lvm2 a-- 100.00m 92.00m 1 1\n/dev/sdb vg lvm2 a-- 100.00m 92.00m 2 23\n\n# vgs\nVG #PV #LV #SN Attr VSize VFree\nvg 2 2 0 wz--n- 200.00m 180.00m\n\n# lvs\nLV VG Attr LSize Pool Origin Move Log Cpy%Sync Convert\nlvol0 vg -wi-a----- 4.00m\nlvol1 vg rwi-a-r--- 4.00m 100.00\n\n# lvs --segments\nLV VG Attr #Str Type SSize\nlvol0 vg -wi-a----- 1 linear 4.00m\nlvol1 vg rwi-a-r--- 2 raid1 4.00m\n\nWe will use report/lvscols and report/lvssort configuration settings to define our own list\nof fields to use and to sort by that is different from defaults. You can do this for other\nreports in same manner with report/{pvs,pvseg,vgs,seg}{cols,sort} configuration settings.\nAlso note that in the example below, we don't display the \"lvtime\" field even though we're\nusing it for sorting - this is allowed.\n\n# lvmconfig --type full report/lvscols report/lvssort\nlvscols=\"lvname,lvsize,origin,poollv,copypercent\"\nlvssort=\"-lvtime\"\n\n# lvs\nLV LSize Origin Pool Cpy%Sync\nlvol1 4.00m 100.00\nlvol0 4.00m\n\nYou can use -o--options command line option to override current configuration directly on\ncommand line.\n\n# lvs -o lvname,lvsize\nLV LSize\nlvol1 4.00m\nlvol0 4.00m\n\n# lvs -o+lvlayout\nLV LSize Origin Pool Cpy%Sync Layout\nlvol1 4.00m 100.00 raid,raid1\nlvol0 4.00m linear\n\n# lvs -o-origin\nLV LSize Pool Cpy%Sync\nlvol1 4.00m 100.00\nlvol0 4.00m\n\n# lvs -o lvname,lvsize,origin -o+lvlayout -o-origin -O lvname\nLV LSize Layout\nlvol0 4.00m linear\nlvol1 4.00m raid,raid1\n\nYou can obtain the same information with single command where all the information about PVs,\nPV segments, LVs and LV segments are obtained per VG under a single VG lock for consistency,\nsee also lvm-fullreport(8) man page for more information. The fullreport has its own configu‐\nration settings to define field sets to use, similar to individual reports as displayed\nabove, but configuration settings have \"full\" suffix now. This way, it's possible to con‐\nfigure different sets of fields to display and to sort by for individual reports as well as\nthe full report.\n\n# lvmconfig --type full report/pvscolsfull \\\nreport/pvssortfull report/pvsegscolsfull \\\nreport/pvsegssortfull report/vgscolsfull \\\nreport/vgssortfull report/lvscolsfull \\\nreport/lvssortfull report/segscolsfull \\\nreport/segssortfull\npvscolsfull=\"pvname,vgname\"\npvssortfull=\"pvname\"\npvsegscolsfull=\"pvname,pvsegstart,pvsegsize\"\npvsegssortfull=\"pvuuid,pvsegstart\"\nvgscolsfull=\"vgname\"\nvgssortfull=\"vgname\"\nlvscolsfull=\"lvname,vgname\"\nlvssortfull=\"vgname,lvname\"\nsegscolsfull=\"lvname,segstart,segsize\"\nsegssortfull=\"lvuuid,segstart\"\n\n# lvm fullreport\nVG\nvg\nPV VG\n/dev/sda vg\n/dev/sdb vg\nLV VG\nlvol0 vg\nlvol1 vg\nPV Start SSize\n/dev/sda 0 1\n/dev/sda 1 1\n/dev/sda 2 1\n/dev/sda 3 22\n/dev/sdb 0 1\n/dev/sdb 1 1\n/dev/sdb 2 23\nLV Start SSize\nlvol0 0 4.00m\nlvol1 0 4.00m\n\n" }, { "name": "Automatic output compaction", "content": "If you look at the lvs output above, you can see that the report also contains fields for\nwhich there is no information to display (e.g. the columns under \"Origin\" and \"Pool\" heading\n- the \"origin\" and \"poollv\" fields). LVM can automatically compact report output so such\nfields are not included in final output. To enable this feature and to compact all fields,\nuse report/compactoutput=1 in your configuration.\n\n# lvmconfig --type full report/compactoutput\ncompactoutput=1\n\n# lvs\nLV LSize Cpy%Sync\nlvol1 4.00m 100.00\nlvol0 4.00m\n\n# lvs vg/lvol0\nLV LSize\nlvol0 4.00m\n\nAlternatively, you can define which fields should be compacted by configuring report/com‐‐\npactoutputcols configuration setting (or -o--options # command line option).\n\n# lvmconfig --type full report/compactoutput report/compactoutputcols\ncompactoutput=0\ncompactoutputcols=\"origin\"\n\n# lvs\nLV LSize Pool Cpy%Sync\nlvol1 4.00m 100.00\nlvol0 4.00m\n\n# lvs vg/lvol0\nLV LSize Pool\nlvol0 4.00m\n\n# lvs -o#poollv\nLV LSize Origin Cpy%Sync\nlvol1 4.00m 100.00\nlvol0 4.00m\n\nWe will use report/compactoutput=1 for subsequent examples.\n\n" }, { "name": "Further formatting options", "content": "By default, LVM displays sizes in reports in human-readable form which means that the most\nsuitable unit is used so it's easy to read. You can use report/units configuration setting\n(or --units option directly on command line) and report/suffix configuration setting (or\n--nosuffix command line option) to change this.\n\n# lvs --units b --nosuffix\nLV LSize Cpy%Sync\nlvol1 4194304 100.00\nlvol0 4194304\n\nIf you want to configure whether report headings are displayed or not, use report/headings\nconfiguration settings (or --noheadings command line option).\n\n# lvs --noheadings\nlvol1 4.00m 100.00\nlvol0 4.00m\n\nIn some cases, it may be useful to display report content as key=value pairs where key here\nis actually the field name. Use report/prefixes configuration setting (or --nameprefixes com‐\nmand line option) to switch between standard output and the key=value output. The key=value\npair is the output that is suitable for use in scripts and for other tools to parse easily.\nUsually, you also don't want to display headings with the output that has these key=value\npairs.\n\n# lvs --noheadings --nameprefixes\nLVM2LVNAME='lvol1' LVM2LVSIZE='4.00m' LVM2COPYPERCENT='100.00'\nLVM2LVNAME='lvol0' LVM2LVSIZE='4.00m' LVM2COPYPERCENT=''\n\nTo define whether quotation marks in key=value pairs should be used or not, use report/quoted\nconfiguration setting (or --unquoted command line option).\n\n# lvs --noheadings --nameprefixes --unquoted\nLVM2LVNAME=lvol1 LVM2LVSIZE=4.00m LVM2COPYPERCENT=100.00\nLVM2LVNAME=lvol0 LVM2LVSIZE=4.00m LVM2COPYPERCENT=\n\nFor easier parsing, you can even transpose the report so each column now becomes a row in the\noutput. This is done with report/outputasrows configuration setting (or --rows command line\noption).\n\n# lvs --noheadings --nameprefixes --unquoted --rows\nLVM2LVNAME=lvol1 LVM2LVNAME=lvol0\nLVM2LVSIZE=4.00m LVM2LVSIZE=4.00m\nLVM2COPYPERCENT=100.00 LVM2COPYPERCENT=\n\nUse report/separator configuration setting (or --separator command line option) to define\nyour own field separator to use.\n\n# lvs --noheadings --nameprefixes --unquoted --separator \" | \"\nLVM2LVNAME=lvol1 | LVM2LVSIZE=4.00m | LVM2COPYPERCENT=100.00\nLVM2LVNAME=lvol0 | LVM2LVSIZE=4.00m | LVM2COPYPERCENT=\n\nIf you are using your own separator, the columns in the output are not aligned by default.\nUse report/aligned configuration setting (or --aligned command line option) for LVM to add\nextra spaces in report to align the output properly.\n\n# lvs --separator \" | \"\nLV | LSize | Cpy%Sync\nlvol1 | 4.00m | 100.00\nlvol0 | 4.00m |\n\n# lvs --separator \" | \" --aligned\nLV | LSize | Cpy%Sync\nlvol1 | 4.00m | 100.00\nlvol0 | 4.00m |\n\nLet's display one one more field in addition (\"lvtags\" in this example) for the lvs report\noutput.\n\n# lvs -o+lvtags\nLV LSize Cpy%Sync LV Tags\nlvol1 4.00m 100.00\nlvol0 4.00m tagA,tagB\n\nThe \"LV Tags\" column in the example above displays two list values, separated by \",\" charac‐\nter for LV lvol0. If you need different list item separator, use report/listitemseparator\nconfiguration setting its definition.\n\n# lvmconfig --type full report/listitemseparator\nlistitemseparator=\";\"\n\n# lvs -o+tags\nLV LSize Cpy%Sync LV Tags\nlvol1 4.00m 100.00\nlvol0 4.00m tagA;tagB\n\nBut let's still use the original \",\" character for listitemseparator for subsequent exam‐\nples.\n\nFormat for any of time values displayed in reports can be configured with report/timeformat\nconfiguretion setting. By default complete date and time is displayed, including timezone.\n\n# lvmconfig --type full report/timeformat\ntimeformat=\"%Y-%m-%d %T %z\"\n\n# lvs -o+time\nLV LSize Cpy%Sync CTime\nlvol1 4.00m 100.00 2016-08-29 12:53:36 +0200\nlvol0 4.00m 2016-08-29 10:15:17 +0200\n\nWe can change time format in similar way as we do when using date(1) command or strftime(3)\nfunction (lvmconfig --type default --withcomments report/timeformat will give you complete\nlist of available formatting options). In the example below, we decided to use %s for number\nof seconds since Epoch (1970-01-01 UTC).\n\n# lvmconfig --type full report/timeformat\ntimeformat=\"%s\"\n\n# lvs\nLV Attr LSize Cpy%Sync LV Tags CTime\nlvol1 rwi-a-r--- 4.00m 100.00 1472468016\nlvol0 -wi-a----- 4.00m tagA,tagB 1472458517\n\nThe lvs does not display hidden LVs by default - to include these LVs in the output, you need\nto use -a--all command line option. Names for these hidden LVs are displayed within square\nbrackets.\n\n# lvs -a\nLV LSize Cpy%Sync\nlvol1 4.00m 100.00\n[lvol1rimage0] 4.00m\n[lvol1rmeta0] 4.00m\n[lvol1rimage1] 4.00m\n[lvol1rmeta1] 4.00m\nlvol0 4.00m\n\nYou can configure LVM to display the square brackets for hidden LVs or not with re‐‐\nport/markhiddendevices configuration setting.\n\n# lvmconfig --type full report/markhiddendevices\nmarkhiddendevices=0\n\n# lvs -a\nLV LSize Cpy%Sync\nlvol1 4.00m 100.00\nlvol1rimage0 4.00m\nlvol1rmeta0 4.00m\nlvol1rimage1 4.00m\nlvol1rmeta1 4.00m\nlvol0 4.00m\n\nIt's not recommended to use LV marks for hidden devices to decide whether the LV is the one\nto use by end users or not. Please, use \"lvrole\" field instead which can report whether the\nLV is \"public\" or \"private\". The private LVs are used by LVM only and they should not be ac‐\ncessed directly by end users.\n\n# lvs -a -o+lvrole\nLV LSize Cpy%Sync Role\nlvol1 4.00m 100.00 public\nlvol1rimage0 4.00m private,raid,image\nlvol1rmeta0 4.00m private,raid,metadata\nlvol1rimage1 4.00m private,raid,image\nlvol1rmeta1 4.00m private,raid,metadata\nlvol0 4.00m public\n\nSome of the reporting fields that LVM reports are of binary nature. For such fields, it's ei‐\nther possible to display word representation of the value (this is used by default) or nu‐\nmeric value (0/1 or -1 in case the value is undefined).\n\n# lvs -o+lvactivelocally\nLV LSize Cpy%Sync ActLocal\nlvol1 4.00m 100.00 active locally\nlvol0 4.00m active locally\n\nWe can change the way how these binary values are displayed with report/binaryvaluesasnu‐‐\nmeric configuration setting.\n\n# lvmconfig --type full report/binaryvaluesasnumeric\nbinaryvaluesasnumeric=1\n\n# lvs -o+lvactivelocally\nLV LSize Cpy%Sync ActLocal\nlvol1 4.00m 100.00 1\nlvol0 4.00m 1\n\n" }, { "name": "Changing output format", "content": "LVM can output reports in different formats - use report/outputformat configuration setting\n(or --reportformat command line option) to swith the report output format. Currently, LVM\nsupports \"basic\" (all the examples we used above used this format) and \"JSON\" output format.\n\n# lvs -o lvname,lvsize --reportformat json\n{\n\"report\": [\n{\n\"lv\": [\n{\"lvname\":\"lvol1\", \"lvsize\":\"4.00m\"},\n{\"lvname\":\"lvol0\", \"lvsize\":\"4.00m\"}\n]\n}\n]\n}\n\nNote that some configuration settings and command line options have no effect with certain\nreport formats. For example, with JSON output, it doesn't have any meaning to use re‐‐\nport/aligned (--aligned), report/noheadings (--noheadings), report/columnsasrows (--rows)\nor report/buffered (--unbuffered). All these configuration settings and command line options\nare ignored if using the JSON report output format.\n\n" }, { "name": "Selection", "content": "If you need to select only specific rows from report, you can use LVM's report selection fea‐\nture. If you call -S help, you'll get quick help on selection. The help con‐\ntains list of all fields that LVM can use in reports together with its type enclosed in\nsquare brackets. The example below contains a line from lvs -S help.\n\n# lvs -S help\n...\nlvsize - Size of LV in current units. [size]\n...\n\nThis line tells you you that the \"lvsize\" field is of \"size\" type. If you look at the bottom\nof the help output, you can see section about \"Selection operators\" and its \"Comparison oper‐\nators\".\n\n# lvs -S help\n...\nSelection operators\n-------------------\nComparison operators:\n=~ - Matching regular expression. [regex]\n!~ - Not matching regular expression. [regex]\n= - Equal to. [number, size, percent, string, string list, time]\n!= - Not equal to. [number, size, percent, string, stringlist, time]\n>= - Greater than or equal to. [number, size, percent, time]\n> - Greater than. [number, size, percent, time]\n<= - Less than or equal to. [number, size, percent, time]\n< - Less than. [number, size, percent, time]\nsince - Since specified time (same as '>='). [time]\nafter - After specified time (same as '>'). [time]\nuntil - Until specified time (same as '<='). [time]\nbefore - Before specified time (same as '<'). [time]\n...\n\nHere you can match comparison operators that you may use with the \"lvsize\" field which is of\ntype \"size\" - it's =, !=, >=, >, <= and <. You can find applicable comparison operators for\nother fields and other field types the same way.\n\nTo demostrate selection functionality in LVM, we will create more LVs in addition to lvol0\nand lvol1 we used in our previous examples.\n\n# lvs -o name,size,origin,snappercent,tags,time\nLV LSize Origin Snap% LV Tags CTime\nlvol4 4.00m lvol2 24.61 2016-09-09 16:57:44 +0200\nlvol3 4.00m lvol2 5.08 2016-09-09 16:56:48 +0200\nlvol2 8.00m tagA,tagC,tagD 2016-09-09 16:55:12 +0200\nlvol1 4.00m 2016-08-29 12:53:36 +0200\nlvol0 4.00m tagA,tagB 2016-08-29 10:15:17 +0200\n\nWhen selecting size and percent fields, we don't need to use units. For sizes, default \"m\"\n(for MiB) is used - this is the same behaviour as already used for LVM commands when specify‐\ning sizes (e.g. lvcreate -L). For percent fields, \"%\" is assumed automatically if it's not\nspecified. The example below also demonstrates how several criteria can be combined to‐\ngether.\n\n# lvs -o name,size,snappercent -S 'size=8m'\nLV LSize\nlvol2 8.00m\n\n# lvs -o name,size,snappercent -S 'size=8'\nLV LSize\nlvol2 8.00m\n\n# lvs -o name,size,snappercent -S 'size < 5000k'\nLV LSize Snap%\nlvol4 4.00m 24.61\nlvol3 4.00m 5.08\nlvol1 4.00m\nlvol0 4.00m\n\n# lvs -o name,size,snappercent -S 'size < 5000k && snappercent > 20'\nLV LSize Snap%\nlvol4 4.00m 24.61\n\n# lvs -o name,size,snappercent \\\n-S '(size < 5000k && snappercent > 20%) || name=lvol2'\nLV LSize Snap%\nlvol4 4.00m 24.61\nlvol2 8.00m\n\nYou can also use selection together with processing-oriented commands.\n\n# lvchange --addtag test -S 'size < 5000k'\nLogical volume vg/lvol1 changed.\nLogical volume vg/lvol0 changed.\nLogical volume vg/lvol3 changed.\nLogical volume vg/lvol4 changed.\n\n# lvchange --deltag test -S 'tags = test'\nLogical volume vg/lvol1 changed.\nLogical volume vg/lvol0 changed.\nLogical volume vg/lvol3 changed.\nLogical volume vg/lvol4 changed.\n\nLVM can recognize more complex values used in selection criteria for string list and time\nfield types. For string lists, you can match whole list strictly, its subset or intersection.\nLet's take \"lvtags\" field as an example - we select only rows which contain \"tagA\" within\ntags field. We're using { } to denote that we're interested in subset that matches. If the\nsubset has only one item, we can leave out { }.\n\n# lvs -o name,tags -S 'tags={tagA}'\nLV LV Tags\nlvol2 tagA,tagC,tagD\nlvol0 tagA,tagB\n\n# lvs -o name,tags -S 'tags=tagA'\nLV LV Tags\nlvol2 tagA,tagC,tagD\nlvol0 tagA,tagB\n\nDepending on whether we use \"&&\" (or \",\") or \"||\" ( or \"#\") as delimiter for items in the set\nwe define in selection criterion for string list, we either match subset (\"&&\" or \",\") or\neven intersection (\"||\" or \"#\").\n\n# lvs -o name,tags -S 'tags={tagA,tagC,tagD}'\nLV LV Tags\nlvol2 tagA,tagC,tagD\n\n# lvs -o name,tags -S 'tags={tagA || tagC || tagD}'\nLV LV Tags\nlvol2 tagA,tagC,tagD\nlvol0 tagA,tagB\n\nTo match the complete set, use [ ] with \"&&\" (or \",\") as delimiter for items. Also note that\nthe order in which we define items in the set is not relevant.\n\n# lvs -o name,tags -S 'tags=[tagA]'\n\n# lvs -o name,tags -S 'tags=[tagB,tagA]'\nLV LV Tags\nlvol0 tagA,tagB\n\nIf you use [ ] with \"||\" (or \"#\"), this is exactly the same as using { }.\n\n# lvs -o name,tags -S 'tags=[tagA || tagC || tagD]'\nLV LV Tags\nlvol2 tagA,tagC,tagD\nlvol0 tagA,tagB\n\nTo match a set with no items, use \"\" to denote this (note that we have output compaction en‐\nabled so the \"LV Tags\" column is not displayed in the example below because it's blank and so\nit gets compacted).\n\n# lvs -o name,tags -S 'tags=\"\"'\nLV\nlvol4\nlvol3\nlvol1\n\n# lvs -o name,tags -S 'tags!=\"\"'\nLV LV Tags\nlvol2 tagA,tagC,tagD\nlvol0 tagA,tagB\n\nWhen doing selection based on time fields, we can use either standard, absolute or freeform\ntime expressions in selection criteria. Examples below are using standard forms.\n\n# lvs -o name,time\nLV CTime\nlvol4 2016-09-09 16:57:44 +0200\nlvol3 2016-09-09 16:56:48 +0200\nlvol2 2016-09-09 16:55:12 +0200\nlvol1 2016-08-29 12:53:36 +0200\nlvol0 2016-08-29 10:15:17 +0200\n\n# lvs -o name,time -S 'time since \"2016-09-01\"'\nLV CTime\nlvol4 2016-09-09 16:57:44 +0200\nlvol3 2016-09-09 16:56:48 +0200\nlvol2 2016-09-09 16:55:12 +0200\n\n# lvs -o name,time -S 'time since \"2016-09-09 16:56\"'\nLV CTime\nlvol4 2016-09-09 16:57:44 +0200\nlvol3 2016-09-09 16:56:48 +0200\n\n# lvs -o name,time -S 'time since \"2016-09-09 16:57:30\"'\nLV CTime\nlvol4 2016-09-09 16:57:44 +0200\n\n# lvs -o name,time \\\n-S 'time since \"2016-08-29\" && time until \"2016-09-09 16:55:12\"'\nLV CTime\nlvol2 2016-09-09 16:55:12 +0200\nlvol1 2016-08-29 12:53:36 +0200\nlvol0 2016-08-29 10:15:17 +0200\n\n# lvs -o name,time \\\n-S 'time since \"2016-08-29\" && time before \"2016-09-09 16:55:12\"'\nLV CTime\nlvol1 2016-08-29 12:53:36 +0200\nlvol0 2016-08-29 10:15:17 +0200\n\nTime operators have synonyms: \">=\" for since, \"<=\" for until, \">\" for \"after\" and \"<\" for\n\"before\".\n\n# lvs -o name,time \\\n-S 'time >= \"2016-08-29\" && time <= \"2016-09-09 16:55:30\"'\nLV CTime\nlvol2 2016-09-09 16:55:12 +0200\nlvol1 2016-08-29 12:53:36 +0200\nlvol0 2016-08-29 10:15:17 +0200\n\n# lvs -o name,time \\\n-S 'time since \"2016-08-29\" && time < \"2016-09-09 16:55:12\"'\nLV CTime\nlvol1 2016-08-29 12:53:36 +0200\nlvol0 2016-08-29 10:15:17 +0200\n\nExample below demonstrates using absolute time expression.\n\n# lvs -o name,time --config report/timeformat=\"%s\"\nLV CTime\nlvol4 1473433064\nlvol3 1473433008\nlvol2 1473432912\nlvol1 1472468016\nlvol0 1472458517\n\n# lvs -o name,time -S 'time since @1473433008'\nLV CTime\nlvol4 2016-09-09 16:57:44 +0200\nlvol3 2016-09-09 16:56:48 +0200\n\nExamples below demonstrates using freeform time expressions.\n\n# lvs -o name,time -S 'time since \"2 weeks ago\"'\nLV CTime\nlvol4 2016-09-09 16:57:44 +0200\nlvol3 2016-09-09 16:56:48 +0200\nlvol2 2016-09-09 16:55:12 +0200\nlvol1 2016-08-29 12:53:36 +0200\nlvol0 2016-08-29 10:15:17 +0200\n\n# lvs -o name,time -S 'time since \"1 week ago\"'\nLV CTime\nlvol4 2016-09-09 16:57:44 +0200\nlvol3 2016-09-09 16:56:48 +0200\nlvol2 2016-09-09 16:55:12 +0200\n\n# lvs -o name,time -S 'time since \"2 weeks ago\"'\nLV CTime\nlvol1 2016-08-29 12:53:36 +0200\nlvol0 2016-08-29 10:15:17 +0200\n\n# lvs -o name,time -S 'time before \"1 week ago\"'\nLV CTime\nlvol1 2016-08-29 12:53:36 +0200\nlvol0 2016-08-29 10:15:17 +0200\n\n# lvs -o name,time -S 'time since \"68 hours ago\"'\nLV CTime\nlvol4 2016-09-09 16:57:44 +0200\nlvol3 2016-09-09 16:56:48 +0200\nlvol2 2016-09-09 16:55:12 +0200\n\n# lvs -o name,time -S 'time since \"1 year 3 months ago\"'\nLV CTime\nlvol4 2016-09-09 16:57:44 +0200\nlvol3 2016-09-09 16:56:48 +0200\nlvol2 2016-09-09 16:55:12 +0200\nlvol1 2016-08-29 12:53:36 +0200\nlvol0 2016-08-29 10:15:17 +0200\n\n" }, { "name": "Command log reporting", "content": "As described in categorization based on reporting facility section at the beginning of this\ndocument, both report-oriented and processing-oriented LVM commands can report the command\nlog if this is enabled with log/reportcommandlog configuration setting. Just like any\nother report, we can set the set of fields to display (log/commandlogcols) and to sort by\n(log/commandlogsort) for this report.\n\n# lvmconfig --type full log/reportcommandlog log/commandlogcols \\\nlog/commandlogsort log/commandlogselection\nreportcommandlog=1\ncommandlogcols=\"logseqnum,logtype,logcontext,logobjecttype,\nlogobjectname,logobjectgroup,logmessage,\nlogerrno,logretcode\"\ncommandlogsort=\"logseqnum\"\ncommandlogselection=\"!(logtype=status && message=success)\"\n\n\n# lvs\nLogical Volume\n==============\nLV LSize Cpy%Sync\nlvol1 4.00m 100.00\nlvol0 4.00m\n\nCommand Log\n===========\nSeq LogType Context ObjType ObjName ObjGrp Msg Errno RetCode\n\nAs you can see, the command log is empty (it contains only field names). By default, LVM\nuses selection on the command log report and this case no row matched the selection criteria,\nsee also log report specifics section in this document for more information. We're displaying\ncomplete log report in the example below where we can see that both LVs lvol0 and lvol1 were\nsuccessfully processed as well as the VG vg they are part of.\n\n# lvmconfig --type full log/commandlogselection\ncommandlogselection=\"all\"\n\n# lvs\nLogical Volume\n==============\nLV LSize Cpy%Sync\nlvol1 4.00m 100.00\nlvol0 4.00m\n\nCommand Log\n===========\nSeq LogType Context ObjType ObjName ObjGrp Msg Errno RetCode\n1 status processing lv lvol0 vg success 0 1\n2 status processing lv lvol1 vg success 0 1\n3 status processing vg vg success 0 1\n\n# lvchange -an vg/lvol1\nCommand Log\n===========\nSeq LogType Context ObjType ObjName ObjGrp Msg Errno RetCode\n1 status processing lv lvol1 vg success 0 1\n2 status processing vg vg success 0 1\n\n" }, { "name": "Handling multiple reports per single command", "content": "To configure the log report directly on command line, we need to use --configreport option\nbefore we start any -o--options, -O--sort or -S--select that is targeted for log report.\n\n# lvs -o lvname,lvsize --configreport log -o logobjecttype, \\\nlogobjectname,logmessage,logretcode\nLogical Volume\n==============\nLV LSize\nlvol1 4.00m\nlvol0 4.00m\n\nCommand Log\n===========\nObjType ObjName Msg RetCode\nlv lvol0 success 1\nlv lvol1 success 1\nvg vg success 1\n\nThe lvm fullreport, with or without log report, consists of several reports - the --configre‐‐\nport is also used to target particular subreport here.\n\nBelow is an extended example with lvm fullreport to illustrate combination of various op‐\ntions. The report output is in JSON format. Also, we configure \"vg\", \"pvseg\", \"seg\" and\n\"log\" subreport to contain only specified fields. For the \"pvseg\" subreport, we're intested\nonly in PV names having \"sda\" in their name. For the \"log\" subreport we're intested only in\nlog lines related to either \"lvol0\" object or object having \"sda\" in its name. Also, for the\nlog subreport we define ordering to be based on \"logobjecttype\" field.\n\n# lvm fullreport --reportformat json \\\n--configreport vg -o vgname,vgsize \\\n--configreport pvseg -o pvname,pvsegstart \\\n-S 'pvname=~sda' \\\n--configreport seg -o lvname,segstart \\\n--configreport log -o logobjecttype,logobjectname \\\n-O logobjecttype \\\n-S 'logobjectname=lvol0 || \\\nlogobjectname=~sda'\n{\n\"report\": [\n{\n\"vg\": [\n{\"vgname\":\"vg\", \"vgsize\":\"200.00m\"}\n]\n,\n\"pv\": [\n{\"pvname\":\"/dev/sda\", \"vgname\":\"vg\"},\n{\"pvname\":\"/dev/sdb\", \"vgname\":\"vg\"}\n]\n,\n\"lv\": [\n{\"lvname\":\"lvol0\", \"vgname\":\"vg\"},\n{\"lvname\":\"lvol1\", \"vgname\":\"vg\"}\n]\n,\n\"pvseg\": [\n{\"pvname\":\"/dev/sda\", \"pvsegstart\":\"0\"},\n{\"pvname\":\"/dev/sda\", \"pvsegstart\":\"1\"},\n{\"pvname\":\"/dev/sda\", \"pvsegstart\":\"2\"},\n{\"pvname\":\"/dev/sda\", \"pvsegstart\":\"3\"}\n]\n,\n\"seg\": [\n{\"lvname\":\"lvol0\", \"segstart\":\"0 \"},\n{\"lvname\":\"lvol1\", \"segstart\":\"0 \"}\n]\n}\n]\n,\n\"log\": [\n{\"logobjecttype\":\"lv\", \"logobjectname\":\"lvol0\"},\n{\"logobjecttype\":\"lv\", \"logobjectname\":\"lvol0\"},\n{\"logobjecttype\":\"pv\", \"logobjectname\":\"/dev/sda\"},\n{\"logobjecttype\":\"pv\", \"logobjectname\":\"/dev/sda\"},\n]\n}\n\n" }, { "name": "Report extensions for LVM shell", "content": "As already stated in log report coverage paragraph under log report specifics in this docu‐\nmentation, when using LVM shell the log report coverage is wider. There's also special com‐\nmand designed to query last command's log report in the LVM shell - the lastlog command.\n\nThe example below illustrates a situation where we called lvs command. After that, we in‐\nspected the log report with the lastlog, without any selection so all the log report is dis‐\nplayed on output. Then we called lastlog further, giving various selection criteria. Then we\nran unknown LVM command \"abc\" for which the log report displays appropriate failure state.\n\n# lvm\nlvm> lvs\nLogical Volume\n==============\nLV LSize Cpy%Sync\nlvol1 4.00m 100.00\nlvol0 4.00m\n\nCommand Log\n===========\nSeq LogType Context ObjType ObjName ObjGrp Msg Errno RetCode\n1 status processing lv lvol0 vg success 0 1\n2 status processing lv lvol1 vg success 0 1\n3 status processing vg vg success 0 1\n4 status shell cmd lvs success 0 1\n\nlvm> lastlog\nCommand Log\n===========\nSeq LogType Context ObjType ObjName ObjGrp Msg Errno RetCode\n1 status processing lv lvol0 vg success 0 1\n2 status processing lv lvol1 vg success 0 1\n3 status processing vg vg success 0 1\n4 status shell cmd lvs success 0 1\n\nlvm> lastlog -S logobjecttype=lv\nCommand Log\n===========\nSeq LogType Context ObjType ObjName ObjGrp Msg Errno RetCode\n1 status processing lv lvol0 vg success 0 1\n2 status processing lv lvol1 vg success 0 1\n\nlvm> lastlog -S logcontext=shell\nCommand Log\n===========\nSeq LogType Context ObjType ObjName ObjGrp Msg Errno RetCode\n4 status shell cmd lvs success 0 1\n\nlvm> abc\nCommand Log\n===========\nSeq LogType Context ObjType ObjName ObjGrp Msg Errno RetCode\n1 error shell cmd abc No such command 'abc'. Try 'help'. -1 0\n2 status shell cmd abc failure -1 2\n\n" } ] }, "SEE ALSO": { "content": "lvm (8), lvmconfig (8), lvm fullreport (8)\n\n\n\nRed Hat, Inc LVM TOOLS 2.03.11(2) (2021-01-08) LVMREPORT(7)", "subsections": [] } } } }