Categorization based on reporting facility
Based on functionality, commands which make use of the reporting
infrastructure are divided in two groups:
Report-oriented commands
These commands inform about current LVM state and their
primary role is to display this information in compendious
way. To make a distinction, we will name this report as
main report. The set of report-only commands include: pvs,
vgs, lvs, pvdisplay, vgdisplay, lvdisplay, lvm devtypes,
lvm fullreport. For further information about main
report, see Main report specifics.
Processing-oriented commands
These commands are responsible for changing LVM state and
they do not contain any main report as identified for
report-oriented commands, they only perform some kind of
processing. The set of processing-oriented commands
includes: pvcreate, vgcreate, lvcreate, pvchange,
vgchange, lvchange, pvremove, vgremove, lvremove,
pvresize, vgextend, vgreduce, lvextend, lvreduce,
lvresize, lvrename, pvscan, vgscan, lvscan, pvmove,
vgcfgbackup, vgck, vgconvert, vgexport, vgimport,
vgmknodes.
If enabled, so called log report is either displayed solely (for
processing-oriented commands) or in addition to main report (for
report-oriented commands). The log report contains a log of
operations, messages and per-object status with complete object
identification collected during LVM command execution. See Log
report specifics for more information about this report type.
Terms
When describing reporting functionality and features in this
text, we will use terms row and column. By row we mean series of
values reported for single entity (for example single PV, VG or
LV). Each value from the row then belongs to a column of certain
type. The columns have column headings which are short
descriptions for the columns. The columns are referenced by
column names. Please note that this text is also using term field
interchangeably with the term column. Most of the time the term
columns is abbreviated as col in configuration.
Common report configuration settings and command line options
There are common configuration settings and command line options
which apply to both main report and log report. Following lists
contain all of them, separated into groups based on their use.
Common configuration settings
Changing report output format, composition and other output
modifiers:
- global/suffix
- global/units
- report/aligned
- report/binary_values_as_numeric
- report/columns_as_rows
- report/compact_output
- report/compact_output_cols
- report/headings
- report/list_item_separator
- report/mark_hidden_devices
- report/output_format
- report/prefixes
- report/quoted
- report/separator
- report/time_format
- report/two_word_unknown_device
Special settings
- report/buffered
This document does not describe these settings in more detail -
if you need detailed information, including values which are
accepted for the settings, please run lvmconfig --type default
--withcomments <setting>. There are more configuration settings
in addition to the common set listed above, but they are specific
to either main report or log report, see main report specifics
and log report specifics for these settings. Besides configuring
reports globally by using configuration settings, there are also
command line options you can use to extend, override or further
specify the report configuration.
Common command line options
Definition of the set of fields to use
-o|--options FieldSet
Field set to use. See main report specifics and log
report specifics for information about field sets
configured with global configuration settings that
this option overrides.
-o|--options +FieldSet
Fields to include to current field set. See main
report specifics and log report specifics for
information about field sets configured with global
configuration settings that this option extends.
-o|--options -FieldSet
Fields to exclude from current field set. See main
report specifics and log report specifics for
information about field sets configured with global
configuration settings that this option reduces.
-o|--options #FieldSet
Compaction of unused fields. Overrides
report/compact_output_cols configuration setting.
Sorting
-O|--sort +FieldSet
Fields to sort by in ascending order. See main
report specifics and log report specifics for
information about field sets configured with global
configuration settings that this option overrides.
-O|--sort -FieldSet
Fields to sort by in descending order. See main
report specifics and log report specifics for
information about fields sets configured with
global configuration settings that this options
overrides.
Selection
-S|--select Selection
Define selection criteria for report output. For
log report, this also overrides
log/command_log_selection configuration setting,
see also log report specifics.
Changing output format and composition
--reportformat
Overrides report/output_format configuration
setting.
--aligned
Overrides report/aligned configuration setting.
--binary
Overrides report/binary_values_as_numeric
configuration setting.
--nameprefixes
Overrides report/prefixes configuration setting.
--noheadings
Overrides report/noheadings configuration setting.
--nosuffix
Overrides global/suffix configuration setting.
--rows Overrides report/columns_as_rows configuration
setting.
--separator
Overrides report/separator configuration setting.
--units
Overrides global/units configuration setting.
--unquoted
Overrides report/quoted configuration setting.
Special options
--configreport ReportName
This defines the ReportName for which any
subsequent -o|--columns, -O|--sort or -S|--select
applies to. See also Main report specifics and Log
report specifics for possible ReportName values.
--logonly
When an LVM command contains both main report and
log report, this option suppresses the main report
output and it causes the log report output to be
displayed only.
--unbuffered
Overrides report/buffered configuration setting.
The FieldSet mentioned in the lists above is a set of field names
where each field name is delimited by "," character. Field set
definition, sorting and selection may be repeated on command line
(-o+/-o- includes/excludes fields to/from current list, for all
the other repeatable options, the last value typed for the option
on the command line is used). The Selection is a string with
selection criteria, see also Selection paragraph below for more
information about constructing these criteria.
Main report specifics
The main report currently encompasses these distinct subtypes,
referenced by their name - ReportName as listed below. The
command in parenthesis is representative command that uses the
main report subtype by default. Each subtype has its own
configuration setting for global field set definition as well as
sort field definition (listed below each individual ReportName):
pv representing report about Physical Volumes (pvs)
- report/pvs_cols
- report/pvs_sort
pvseg representing report about Physical Volume Segments
(pvs --segments)
- report/pvseg_cols
- report/pvseg_sort
vg representing report about Volume Groups (vgs)
- report/vgs_cols
- report/vgs_sort
lv representing report about Logical Volumes (lvs)
- report/lvs_cols
- report/lvs_sort
seg representing report about Logical Volume Segments
(lvs --segments)
- report/segs_cols
- report/segs_sort
full representing report combining all of the above as a
whole (lvm fullreport)
- report/pvs_cols_full
- report/pvs_sort_full
- report/pvsegs_cols_full
- report/pvseg_sort_full
- report/vgs_cols_full
- report/vgs_sort_full
- report/lvs_cols_full
- report/lvs_sort_full
- report/segs_cols_full
- report/segs_sort_full
devtype
representing report about device types
(lvm devtypes)
- report/devtypes_cols
- report/devtypes_sort
Use pvs, vgs, lvs -o help or lvm devtypes -o help to get complete
list of fields that you can use for main report. The list of
fields in the help output is separated in groups based on which
report type they belong to. Note that LVM can change final
report type used if fields from different groups are combined
together. Some of these combinations are not allowed in which
case LVM will issue an error.
For all main report subtypes except full, it's not necessary to
use --configreport ReportName to denote which report any
subsequent -o, -O or -S option applies to as they always apply to
the single main report type. Currently, lvm fullreport is the
only command that includes more than one main report subtype.
Therefore, the --configreport is particularly suitable for the
full report if you need to configure each of its subreports in a
different way.
Log report specifics
You can enable log report with log/report_command_log
configuration setting - this functionality is disabled by
default. The log report contains a log collected during LVM
command execution and then the log is displayed just like any
other report known from main report. There is only one log report
subtype as shown below together with related configuration
settings for fields, sorting and selection:
log representing log report
- log/command_log_cols
- log/command_log_sort
- log/command_log_selection
You always need to use --configreport log together with
-o|--options, -O|--sort or -S|--selection to override
configuration settings directly on command line for log report.
When compared to main report, in addition to usual configuration
settings for report fields and sorting, the log report has also
configuration option for selection -
report/command_log_selection. This configuration setting is
provided for convenience so it's not necessary to use -S|--select
on command line each time an LVM command is executed and we need
the same selection criteria to be applied for log report. Default
selection criteria used for log report are
log/command_log_selection="!(log_type=status &&
message=success)". This means that, by default, log report
doesn't display status messages about successful operation and it
displays only rows with error, warning, print-type messages and
messages about failure states (for more information, see log
report content below).
Log report coverage
Currently, when running LVM commands directly (not in LVM shell),
the log report covers command's processing stage which is the
moment when LVM entities are iterated and processed one by one.
It does not cover any command initialization nor command
finalization stage. If there is any message issued out of log
report's coverage range, such message goes directly to output,
bypassing the log report. By default, that is standard error
output for error and warning messages and standard output for
common print-like messages.
When running LVM commands in LVM shell, the log report covers the
whole LVM command's execution, including command's processing as
well as initialization and finalization stage. So from this point
of view, the log report coverage is complete for executed LVM
commands. Note that there are still a few moments when LVM shell
needs to initialize itself before it even enters the main loop in
which it executes LVM commands. Also, there is a moment when LVM
shell needs to prepare log report properly for next command
executed in the shell and then, after the command's run, the
shell needs to display the log report for that recently executed
command. If there is a failure or any other message issued during
this time, the LVM will bypass log report and display messages on
output directly.
For these reasons and for completeness, it's not possible to rely
fully on log report as the only indicator of LVM command's status
and the only place where all messages issued during LVM command
execution are collected. You always need to check whether the
command has not failed out of log report's range by checking the
non-report output too.
To help with this, LVM can separate output which you can then
redirect to any custom file descriptor that you prepare before
running an LVM command or LVM shell and then you make LVM to use
these file descriptors for different kinds of output by defining
environment variables with file descriptor numbers. See also
LVM_OUT_FD, LVM_ERR_FD and LVM_REPORT_FD environment variable
description in lvm(8) man page.
Also note that, by default, reports use the same file descriptor
as common print-like messages, which is standard output. If you
plan to use log report in your scripts or any external tool, you
should use LVM_OUT_FD, LVM_ERR_FD and LVM_REPORT_FD to separate
all output types to different file descriptors. For example, with
bash, that would be:
LVM_OUT_FD=3 LVM_ERR_FD=4 LVM_REPORT_FD=5 <lvm command>
3>out_file 4>err_file 5>report_file
Where the <lvm_command> is either direct LVM command or LVM
shell. You can collect all three types of output in particular
files then.
Log report content
Each item in the log report consists of these set of fields
providing various information:
Basic information (mandatory):
log_seq_num
Item sequence number. The sequence number is unique
for each log item and it increases in the order of
the log items as they appeared during LVM command
execution.
log_type
Type of log for the item. Currently, these types
are used:
status for any status information that is logged
print for any common message printed while the log
is collected
error for any error message printed while the log
is collected
warn for any warning message printed while the
log is collected
log_context
Context of the log for the item. Currently, two
contexts are identified:
shell for the log collected in the outermost code
before and after executing concrete LVM
commands
processing
for the log collected while processing LVM
entities during LVM command execution
Message (mandatory):
log_message
Any message associated with current item. For
status log type, the message contains either
success or failure denoting current state. For
print, error and warn log types, the message
contains the exact message of that type that got
issued.
Object information (used only if applicable):
log_object_type field
Type of the object processed. Currently, these
object types are recognized:
cmd for command as a whole
orphan for processing group of PVs not in any VG
yet
pv for PV processing
label for direct PV label processing (without VG
metadata)
vg for VG processing
lv for LV processing
log_object_name
Name of the object processed.
log_object_id
ID of the object processed.
log_object_group
A group where the processed object belongs to.
log_object_group_id
An ID of a group where the processed object belongs
to.
Numeric status (used only if applicable):
log_errno
Error number associated with current item.
log_ret_code
Return code associated with current item.
You can also run lvm --configreport log -o help to to display
complete list of fields that you may use for the log report.
Selection
Selection is used for a report to display only rows that match
selection criteria. All rows are displayed with the additional
selected field (-o selected) displaying 1 if the row matches the
Selection and 0 otherwise. The selection criteria are a set of
statements combined by logical and grouping operators. The
statement consists of a field name for which a set of valid
values is defined using comparison operators. For complete list
of fields names that you can use in selection, see the output of
lvm -S help. The help output also contains type of values that
each field displays enclosed in brackets.
List of operators recognized in selection criteria
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.
< less than.
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
] list end
{ list subset start
} list subset end
Field types and selection operands
Field type restricts the set of operators and values that you may
use with the field when defining selection criteria. You can see
field type for each field if you run lvm -S help where you can
find the type name enclosed in square brackets. Currently, LVM
recognizes 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 lvcreate(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 separator 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")
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. Matches strictly. The
log_op must always be of one type within the whole list value.
- VALUE = {VALUE log_op VALUE}
For list-based types: string list. Matches a subset. The
log_op must always be of one type within the whole list value.
- VALUE = value
For scalar types: number, size, percent, string (or string
regex).
