lsscsi

package: lsscsi

title: lsscsi(8)

text:
# lsscsi(8)

## NAME
lsscsi - list SCSI devices (or hosts), list NVMe devices

## SYNOPSIS
lsscsi [--brief] [--classic] [--controllers] [--device] [--generic] [--help] [--hosts] [--kname] [--list] [--long] [--long-unit] [--lunhex] [--no-nvme] [--pdt] [--protection] [--protmode] [--scsi_id] [--size] [--sysfsroot=PATH] [--sz-lbs] [--transport] [--unit] [--verbose] [--version] [--wwn] [H:C:T:L]

## DESCRIPTION
Uses information in sysfs (Linux kernel series 2.6 and later) to list SCSI devices (or hosts) currently attached to the system. Many non-SCSI storage devices (but not all) used the SCSI subsystem in Linux. In lsscsi version 0.30 support was added to list NVMe devices.

In single line per device (LU or NVMe namespace) mode, the default, each line starts with a 4 element tuple surrounded by square brackets. For SCSI devices the first element 'H' is the host number, the second element 'C' is the controller number, the third element 'T' is the target number and the final element is the Logical Unit Number (LUN). All four are integers. For NVMe namespaces see two paragraphs down. When the --hosts option is given for SCSI devices the tuple is reduced to one element: the host number.

If a H:C:T:L tuple is given as an argument on the command line then it acts as a filter and only devices that match it are listed. The colons don't have to be present, and '-', '*', '?' or missing components at the end are interpreted as wildcards. The default is '*:*:*:*' which means to match devices (i.e. Logical Units). Any filter string using '*' of '?' should be surrounded by single or double quotes to stop shell expansions. If '-' is used as a wildcard then the whole filter tuple should be prefixed by '-- ' to tell this utility there are no more options on the command line to be interpreted. A leading '[' and trailing ']' are permitted ( e.g. '[1:0:0]' matches all LUNs on 1:0:0). May also be used to filter --hosts in which case only the H is active and may be either a number or in the form "host<n>" where <n> is a host number.

For NVMe devices and controllers almost all of the previous paragraph applies. The main difference is that "N" appears in the 'H' (first) position. The 'C' position for NVMe is the controller's Linux generated "char" device minor number which is the first number that appears in a typical NVMe controller name, for example: "/dev/nvme2". The 'T' position for NVMe is the "CNTLID" value. The final 'L' position is the NVMe namespace identifier which is typically a sequential value starting at 1. The leading explicit "N" for NVMe devices is converted internally into a large value (32,767) that should not interfere with any Linux generated SCSI host number; it also means that the numeric sort used to show hosts (controllers) and devices (LUs or logical units) will always place NVMe devices and controllers after those that use the SCSI subsystem. To filter using a H:C:T:L argument for NVMe controllers, "hostN", "hostN:<num>", "N" or "N:<num>" may be used; when no "<num>" is given, only NVMe controllers will be listed (i.e. it lists no SCSI hosts (HBAs)).

By default in this utility device node names (e.g. "/dev/sda" or "/dev/root_disk") are obtained by noting the major and minor numbers for the listed device obtained from sysfs (e.g. the contents of "/sys/block/sda/dev") and then looking for a match in the "/dev" directory. This "match by major and minor" will allow devices that have been given a different name by udev (for example) to be correctly reported by this utility.

In some situations it may be useful to see the device node name that Linux would produce by default, so the --kname option is provided. An example of where this may be useful is kernel error logs which tend to report disk error messages using the disk's default kernel name.

## OPTIONS
Arguments to long options are mandatory for short options as well. The options are arranged in alphabetical order based on the long option name. Hyphenated long options can also take underscore, and vice versa (e.g. --scsi_id or --scsi-id are acceptable).

-b, --brief

reduces one line per device output to the tuple and the primary device name. This may simplify scripts that process the output of this utility. With the --generic option it will show on each line the tuple (from which the bsg pass-through device name can be deduced), the primary device name (which the block subsystem uses) and the sg device name (also a pass-through).

When the --pdt option is used together with this option the SCSI Peripheral Device Type (PDT) is displayed in hex (with a leading "0x") between the tuple and the primary device name. For NVMe namespaces "0x0" is displayed (for a disk or direct access device).

-c, --classic

The output is similar to that obtained from 'cat /proc/scsi/scsi'

-C, --controllers

Lists NVMe controllers and SCSI hosts. This is a synonym for the --hosts option.

-d, --device

After outputting the (probable) SCSI device name the device node major and minor numbers are shown in brackets (e.g. "/dev/sda[8:0]").

-g, --generic

Output the SCSI generic device file name. Note that if the sg driver is a module it may need to be loaded otherwise '-' may appear.

NVMe does not have generic (char) devices in the same sense as SCSI. Instead NVMe Admin, NVM (i.e. block type commands such as Read and Write) and MI (Management Interface (e.g. to an enclosure)) commands are all sent to the containing controller whose device name is shown when the --hosts option is used.

To unclutter the single line per device mode the --brief option combined with this option should help.

-h, --help

Output the usage message and exit.

-H, --hosts

List the SCSI hosts and NVMe controllers currently attached to the system. If this option is not given (and the --controllers option is not given) then SCSI devices (logical units (LUs)) followed by NVMe devices (namespaces) are listed.

-k, --kname

Use Linux default algorithm for naming devices (e.g. block major 8, minor 0 is "/dev/sda") rather than the "match by major and minor" in the "/dev" directory as discussed above.

-L, --list

Output additional information in <attribute_name>=<value> pairs, one pair per line preceded by two spaces. This option has the same effect as '-lll'.

-l, --long

Output additional information for each SCSI device (host). Can be used multiple times for more output in which case the shorter option form is more convenient (e.g. '-lll'). When used three times (i.e. '-lll') outputs SCSI device (host) attributes one per line; preceded by two spaces; in the form "<attribute_name>=<value>".

-U, --long-unit

Output logical unit name in full, if available. It replaces the normal vendor, product and revision strings given in the single logical unit per line mode. If no logical unit name is found "none" is printed. If the logical unit name is long (e.g. a UUID) then following fields are pushed further to the right as required. This option is functionally equivalent to the '-uuu' option.

If the option is used twice (e.g. '-UU') then EUI, NAA, UUID and T10 vendor ID formats are prefixed by "eui.", "naa.", "uuid." and "t10." respectively. Note that SCSI name format used by iSCSI should already be prefixed by 'iqn.'. Using the '--unit' option 4 or more times (e.g. '-uuuu') will have the same action as '-UU'.

--long_unit is also an acceptable form when invoking this option.

-x, --lunhex

when this option is used once the LUN in the tuple (at the start of each device line) is shown in "T10" format which is up to 16 hexadecimal digits. It is prefixed by "0x" to distinguish the LUN from the decimal value shown in the absence of this option. Also hierarchal LUNs are shown with a "_" character separating the levels. For example the two level LUN: 0x0355006600000000 will appear as 0x0355_0066. If this option is given twice (e.g. using the short form: '-xx') then the full 16 hexadecimal digits are shown for each LUN, prefixed by "0x".

For NVMe, the namespace identifier (nsid) is shown in the "L" position. The nsid is a 32 bit unsigned quantities with 0x0 and 0xffffffff reserved. Without this option, the nsid is shown in decimal. When this option is used once the nsid is output in hex with a lead 0x and with up to 3 leading zeros. When this option is used twice the nsid is output in hex with up to 7 leading zeros.

-N, --no-nvme

this option excludes NVMe devices and controllers for the output. This option may be needed to stop NVMe device output interfering with specific format output like that produced when the --classic option is used.

To only show NVMe devices, use 'lsscsi N', to only show NVMe controllers, use 'lsscsi -H N'.

-D, --pdt

this option displays the SCSI Peripheral Device Type (PDT) in hex preceded by "0x". For NVME namespaces "0x0' is displayed which corresponds to a disk ("Direct Access Device" or SSD). In single line output this hex PDT replaces the device type abbreviation (e.g. "0x0 " replaces "disk ") and appears after the tuple.

-p, --protection

Output target (DIF) and initiator (DIX) protection types.

-P, --protmode

Output effective protection information mode for each disk device.

-i, --scsi_id

outputs the udev derived matching id found in /dev/disk/by-id/scsi* . This is only for disk (and disk like) devices. If no match is found then "dm-uuid-mpath*" and "usb*" are searched in the same directory. If there is still no match then the /sys/class/block/<disk>/holders directory is searched. The matching id is printed following the device name (e.g. /dev/sdc) and if there is no match "-" is output. Note that only disk (like) devices are matched by this option; so, for example, a SCSI enclosure will have an identifier of '-'.

Prior to revision 164 the first match in /dev/disk/by-id/scsi* was printed. A change was added at that point to check for identifiers in a specific order as some are considered "stronger" than others. See the ORDER OF SCSI IDENTIFIERS section below.

-s, --size

Print disk capacity in human readable form. When given once, normal base 10 SI units are used as a prefix for 'B' which is bytes (aka octets). For example MB, GB and TB stand for 10^6, 10^9 and 10^12 bytes respectively. When given twice, IEC 80000-3 prefixes for 'B' are used; for example MiB, GiB and TiB stand for 2^20, 2^30 and 2^40 bytes respectively. The output is rounded to 3 or less significant figures in order to fit on a single line. It will also output the size of RBC devices, CD/DVD media and host managed ZBC disks. Host aware ZBC disks have their "peripheral device type" set to 0 (the same as normal disks) so their size is output.

If given three times (short form is the more convenient: '-sss') then the disk capacity as a logical block count is given. This is an exact figure in decimal reported by the storage device at discovery. Discovery is typically just after boot time, or when it was last attached if the storage device is removable.

To unclutter the single line per device mode the --brief option combined with this option should help.

-y, --sysfsroot=PATH

assumes sysfs is mounted at PATH instead of the default '/sys' . If this option is given PATH should be an absolute path (i.e. start with '/').

-S, --sz-lbs

Print disk capacity as a number of logical blocks (which is the same as '-sss'). When used twice a comma is added followed by the logical block size in bytes. It should be a number like 512 or 4096.

If the logical block size cannot be found (e.g. because the version of Linux predates the /sys/block/<dev_name>/queue directory) then the number of 512 byte blocks followed comma and then '512' is output irrespective of what the true logical block size of the device is. This special case action occurs whether this option is given one or more times.

To unclutter the single line per device mode the --brief option combined with this option should help.

-t, --transport

Output transport information. This will be target related information or, if --hosts is given, initiator related information. When used without --list, a name or identifier (or both) are output on a single line, usually prefixed by the type of transport. For devices this information replaces the normal vendor, product and revision strings. When the --list option is also given then additionally multiple lines of attribute_name=value pairs are output, each indented by two spaces. See the section on transports below.

-u, --unit

Output logical unit name, if available. If this option is given once or twice, then the 30 character field where the vendor, product and revision strings are usually placed is expanded to 32 characters and replaced by the logical unit name. If no logical unit name is found "none" is printed. The first found of the NAA, EUI-64 or SCSI name string is output unless a SCSI name string is found and the associated target port indicates the iSCSI protocol, in which case the SCSI name string is preferred. Finally if there is no match on the above and a T10 Vendor ID descriptor is found then it is used.

If the name cannot fit in the 32 character field then it is truncated to the right and a trailing '_' character is used to alert the reader to the truncation. The 32 character width is chosen since that is large enough to hold 16 byte NAA or EUI-64 identifiers. However SCSI name strings as used by iSCSI can be larger than that.

If this option is used twice then this field is also 32 character wide. If the logical unit name cannot fit then it will be truncated to the left and a leading '_' character is used to alert the reader to the truncation.

If this option is used three times the whole logical unit name is output, followed by several spaces.

In order for this option to work, it needs a Linux kernel from and including 3.15 . It accesses the sysfs vpd_pg83 file for the device in question. Old SCSI and ATA (SATA) equipment may not provide this information. If it is provided by ATA (SATA) then it will be the WWN.

-v, --verbose

outputs directory names where information is found. Use multiple times for more output.

-V, --version

outputs version information then exits. If used once outputs to stderr; if used twice outputs to stdout and shortens the date to yyyymmdd numeric format. The first number in the version string is the release number.

-w, --wwn

outputs the WWN for disks instead of manufacturer, model and revision (or instead of transport information). The World Wide Name (WWN) is typically 64 bits long (16 hex digits) but could be up to 128 bits long. To indicate the WWN is hexadecimal, it is prefixed by "0x". The ATA/SATA WWN is referred to as LU name in SCSI jargon; hence this option is more or less superseded by the --unit and --long-unit options.

## TRANSPORTS
This utility lists SCSI devices which are known as logical units (LU) in the SCSI Architecture Model (ref: SAM-5 at https://www.t10.org) or hosts when the --hosts option is given. A host is called an initiator in SAM-5. A SCSI command travels out via an initiator, across some transport to a target and then onwards to a logical unit. A target device may contain several logical units. A target device has one or more ports that can be viewed as transport end points. Each FC and SAS disk is a single target that has two ports and contains one logical unit. If both target ports on a FC or SAS disk are connected and visible to a machine, then lsscsi will show two entries. Initiators (i.e. hosts) also have one or more ports and some HBAs in Linux have a host entry per initiator port while others have a host entry per initiator device.

When the --transport option is given for devices (i.e. --hosts not given) then most of the information produced by lsscsi is associated with the target, or more precisely: the target port, through which SCSI commands pass that access a logical unit.

Typically this utility provides one line of output per "device" or host. Significantly more information can be obtained by adding the --list option. When used together with the --transport option, after the summary line, multiple lines of transport specific information in the form "<attribute_name>=<value>" are output, each indented by two spaces. Using a filter argument will reduce the volume of output if a lot of devices or hosts are present.

The transports that are currently recognized are: IEEE 1394, ATA, FC, iSCSI, SAS, SATA, SPI, SRP and USB.

For IEEE 1394 (a.k.a. Firewire and "SBP" when storage is involved), the EUI-64 based target port name is output when --transport is given, in the absence of the --hosts option. When the --hosts option is given then the EUI-64 initiator port name is output. Output on the summary line specific to the IEEE 1394 transport is prefixed by "sbp:".

To detect ATA and SATA devices a crude check is performed on the driver name (after the checks for other transports are exhausted). Based on the driver name either the ATA or SATA transport type is chosen. Output on the summary line is either "ata:" or "sata:". A search is made for an associated vpd_pg83 file in sysfs, if found it may contain the device's WWN which is output if present. The WWN will not appear in Linux kernels before 3.15 and with old PATA and SATA devices. Most device and hosts flagged as "ata:" will use the parallel ATA transport (PATA). For SATA devices that are attached via a SAS expander, see the SAS paragraph below.

For Fibre Channel (FC) the port name and port identifier are output when --transport is given. In the absence of the --hosts option these ids will be for the target port associated with the device (logical unit) being listed. When the --hosts option is given then the ids are for the initiator port used by the host. Output on the summary line specific to the FC transport is prefixed by "fc:". If FCoE (over Ethernet) is detected the prefix is changed to "fcoe:".

For iSCSI the target port name is output when --transport is given, in the absence of the --hosts option. This is made up of the iSCSI name and the target portal group tag. Since the iSCSI name starts with "iqn" no further prefix is used. When the --hosts option is given then only "iscsi:" is output on the summary line.

For Serial Attached SCSI the SAS address of the target port (or initiator port if --hosts option is also given) is output. This will be a naa-5 address. For SAS HBAs and SAS targets (such as SAS disks and tape drives) the SAS address will be world wide unique. For SATA disks attached to a SAS expander, the expander provides the SAS address by adding a non zero value to its (i.e. the expander's) SAS address (e.g. expander_sas_address + phy_id + 1). SATA disks directly attached to SAS HBAs seem to have an indeterminate SAS address. Output on the summary line specific to the SAS transport is prefixed by "sas:".

For SATA devices, see the paragraph above on ATA devices. As noted in the previous paragraph, SATA devices attached to SAS expanders will display a manufactured SAS transport address (manufactured by the expander) rather than the SATA device's WWN.

For the SCSI Parallel Interface (SPI) the target port identifier (usually a number between 0 and 15 inclusive) is output when --transport is given, in the absence of the --hosts option. When the --hosts option is given then only "spi:" is output on the summary line.

For the PCIe transport (a.k.a. PCI Express) there at two possible storage types: NVMe and SOP/PQI (SCSI over PCIe). There are very few examples of the latter currently so this utility concentrates on NVMe. NVMe uses its own command set and not SCSI but has many things in common. Rather than re-invent everything currently in use that SCSI has accumulated over nearly 40 years, NVMe is beginning to use some parts of SCSI. A recent example is the SES-3 standard for enclosure management which has been adopted by NVMe. In SCSI a SES device is a logical unit with a peripheral device type (PDT) of 0xd (for enclosure) so it will appear when the lsscsi utility is invoked without any options. In NVMe is seems that an enclosure with appear as attached to the management interface (MI) of a NVMe controller. This means it should appear when "lsscsi --hosts" is invoked. It is unclear whether such a NVMe controller can have any storage namespaces associated with it. The sg_ses utility (in the sg3_utils package) can then be given that NVMe controller's device name (e.g. /dev/nmve1).

When the --transport option is given, after "pcie" the NVMe controller's subsystem vendor id and device id are output, separated by a colon (e.g. "pcie 0x8086:0x390a").

For the SCSI RDMA Protocol (SRP) the IB (InfiniBand) port's GUID is given. As an example, it has a form like this: 0002:c903:00fa:abcd .

When a USB transport is detected, the summary line will contain "usb:" followed by a USB device name. The USB device name has the form "<b>-<p1>[.<p2>[.<p3>]]:<c>.<i>" where <b> is the USB bus number, <p1> is the port on the host. <p2> is a port on a host connected hub, if present. If needed <p3> is a USB hub port closer to the USB storage device. <c> refers to the configuration number while <i> is the interface number. There is a separate SCSI host for each USB (SCSI) target. A USB SCSI target may contain multiple logical units. Thus the same "usb: <device_name>" string appears for a USB SCSI host and all logical units that belong to the USB SCSI target associated with that USB SCSI host.

## LUNS
For historical reasons and as used by several other Unix based Operating Systems, Linux uses a tuple of integers to describe (a path to) a SCSI device (also know as a Logical Unit (LU)). The last element of that tuple is the so-called Logical Unit Number (LUN). And originally in SCSI a LUN was an integer, at first 3 bits long, then 8 then 16 bits. SCSI LUNs today (SAM-5 section 4.7) are 64 bits but SCSI standards now consider a LUN to be an array of 8 bytes.

Up until 2013, Linux mapped SCSI LUNs to a 32 bit integer by taking the first 4 bytes of the SCSI LUN and ignoring the last 4 bytes. Linux treated the first two bytes of the SCSI LUN as a unit (a word) and it became the least significant 16 bits in the Linux LUN integer. The next two bytes of the SCSI LUN became the upper 16 bits in the Linux LUN integer. The rationale for this was to keep commonly used LUNs small Linux LUN integers. The most common LUN (by far) in SCSI LUN (hex) notation is 00 00 00 00 00 00 00 00 and this becomes the Linux LUN integer 0. The next most common LUN is 00 01 00 00 00 00 00 00 and this becomes the Linux LUN integer 1.

In 2013 it is proposed to increase Linux LUNs to a 64 bit integer by extending the mapping outlined above. In this case all information that is possible to represent in a SCSI LUN is mapped a Linux LUN (64 bit) integer. And the mapping can be reversed without losing information.

This version of the utility supports both 32 and 64 bit Linux LUN integers. By default the LUN shown at the end of the tuple commencing each line is a Linux LUN as a decimal integer. When the --lunhex option is given then the LUN is in SCSI LUN format with the 8 bytes run together, with the output in hexadecimal and prefixed by '0x'. The LUN is decoded according to SAM-5's description and trailing zeros (i.e. digits to the right) are not shown. So LUN 0 (i.e. 00 00 00 00 00 00 00 00) is shown as 0x0000 and LUN 65 (i.e. 00 41 00 00 00 00 00 00) is shown as 0x0041. If the --lunhex option is given twice then the full 64 bits (i.e. 16 hexadecimal digits) are shown.

If the --lunhex option is not given on the command line then the environment variable LSSCSI_LUNHEX_OPT is checked. If LSSCSI_LUNHEX_OPT is present then its associated value becomes the number of times the --lunhex is set internally. So, for example, 'LSSCSI_LUNHEX_OPT=2 lsscsi' and 'lsscsi -xx' are equivalent.

## ORDER OF SCSI IDENTIFIERS
This section only applies to the --scsi_id option and only for disk like devices (e.g. not tapes nor enclosures). There are potentially several SCSI identifiers and from revision 164 they are checked in the following order and only the first found is output.

The SCSI identifier preference order is:

3 : NAA based (Network address Authority)

2 : EUI-64 based

8 : SCSI name string (e.g. iSCSI: iqn.1998-01.com.zzware.iscsi:name1)

S : serial number from SCSI VPD page 0x80

1 : T10 Vendor Identifier

0 : Vendor Specific

Those numbers prefixing each entry are the SCSI 'Designator Types' found in the definition of the Device Identification VPD page (0x83) in SPC/-3, SPC/-4 and SPC/-5. The 'S' of course if not a number and it refers to a different VPD page: the Serial Number VPD page (0x80).

There is a more general --wwn option that should apply to almost all devices. The term "WWN" (world-wide name) comes from the ATA and NVMe standards and corresponds to the "Logical Unit (LU) name" in SCSI. The LU name in SCSI tends to change by transport. For SAS the LU name is the LU's NAA identifier.

Plus there the --unit and the --long-unit options that may be helpful in uniquely identifying storage devices.

## EXAMPLES
Information about this utility including examples can also be found at: https://sg.danny.cz/scsi/lsscsi.html .

## NOTES
Information for this command is derived from the sysfs file system, which is assumed to be mounted at /sys unless specified otherwise by the user. SCSI (pseudo) devices that have been detected by the SCSI mid level will be listed even if the required upper level drivers (i.e. sd, sr, st, osst or ch) have not been loaded. If the appropriate upper level driver has not been loaded then the device file name will appear as '-' rather than something like '/dev/st0'. Note that some devices (e.g. scanners and medium changers) do not have a primary upper level driver and can only be accessed via a SCSI generic (sg) device name.

Generic SCSI devices can also be accessed via the bsg driver in Linux. By default, the bsg driver's device node names are of the form '/dev/bsg/H:C:T:L'. So, for example, the SCSI device shown by this utility on a line starting with the tuple '6:0:1:2' could be accessed via the bsg driver with the '/dev/bsg/6:0:1:2' device node name.

lsscsi version 0.21 or later is required to correctly display SCSI devices in Linux kernel 2.6.26 (and possibly later) when the CONFIG_SYSFS_DEPRECATED_V2 kernel option is not defined.

## AUTHOR
Written by Doug Gilbert

## REPORTING BUGS
Report bugs to <dgilbert at interlog dot com>.

## COPYRIGHT
Copyright © 2003-2021 Douglas Gilbert

This software is distributed under the GPL version 2. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

## SEE ALSO
lspci lsusb lsblk


luckybackup

package: luckybackup

title: luckybackup(8)

text:
# luckybackup(8)

## NAME
luckybackup - a powerful, fast and reliable backup & sync tool

## SYNOPSIS
luckybackup [OPTIONS]... [FILE]...

## DESCRIPTION
luckybackup is an application that backs-up and/or synchronizes any directories with the power of rsync

## OPTIONS
--help

displays this help message

--version

displays the current version of the application

--skip-critical

does not execute tasks that appear with a 'CRITICAL' warning message

--dry-run

executes luckybackup in dry-run (simulation) mode

--silent

executes luckybackup in silent mode (just tray notification icon shown)

-c

console mode. Use this, if there is no graphical envrironment available

--no-questions

skips confirmation questions asked to user. Implies -c (console mode)

[FILE]

is the filename of the already created profile that is going to be executed

examples

1. Execute luckybackup gui :

$ luckybackup

2. Execute luckybackup in silent mode for profile '~/.luckyBackup/profiles/BackupHome.profile' :

$ luckybackup --silent ~/.luckyBackup/profiles/BackupHome.profile

3. Execute luckybackup in console mode for profile '~/.luckyBackup/profiles/BackupHome.profile' :

$ luckybackup -c BackupHome.profile

4. Execute luckybackup in console mode for profile '~/.luckyBackup/profiles/BackupHome.profile'

Do not ask any questions and skip all operations that appear CRITICAL after the checks :

$ luckybackup --skip-critical --no-questions ~/.luckyBackup/profiles/BackupHome.profile

## SEE ALSO
For a complete documentation, please have a look at the application manual via the gui main window help menu.

## AUTHOR
luckybackup was written by <Loukas Avgeriou>.

This manual page was written by luckyb <luckyb69@users.sourceforge.net>, for the Debian project (but may be used by others).


luckybackup-pkexec

title: luckybackup-pkexec(8)

text:
# luckybackup-pkexec(8)

## NAME
luckybackup - a powerful, fast and reliable backup & sync tool

## SYNOPSIS
luckybackup-pkexec

## DESCRIPTION
luckybackup is an application that backs-up and/or synchronizes any directories with the power of rsync.

This command is used to run luckybackup's graphical user interface with super-user privileges, using polkit and pkexec.

## OPTIONS
No options are used with this command. eg:

$ luckybackup-pkexec

## SEE ALSO
For a complete documentation, please have a look at the application manual via the gui main window help menu.

## AUTHOR
luckybackup was written by <Loukas Avgeriou>.

This manual page was written by luckyb <luckyb69@users.sourceforge.net>, for the Debian project (but may be used by others).


luksmeta

package: luksmeta

title: luksmeta(8)

text:
# luksmeta(8)

## NAME
luksmeta - Utility for storing metadata in a LUKSv1 header

## SYNOPSIS
luksmeta test -d DEVICE

luksmeta nuke -d DEVICE [-f]

luksmeta init -d DEVICE [-f] [-n]

luksmeta show -d DEVICE [-s SLOT]

luksmeta save -d DEVICE [-s SLOT] -u UUID < DATA

luksmeta load -d DEVICE -s SLOT [-u UUID] > DATA

luksmeta wipe -d DEVICE -s SLOT [-u UUID] [-f]

## OVERVIEW
The luksmeta utility enables an administrator to store metadata in the gap between the end of the LUKSv1 header and the start of the encrypted data. This is useful for storing data that is available before the volume is unlocked, usually for use during the volume unlock process.

The metadata is stored in a series of UUID-typed slots, allowing multiple blocks of metadata. Although the luksmeta slots are inspired by the LUKS slots, they are functionally independent and share only a casual relationship. Slots merely provide a hint that a given chunk of metadata is associated with a specific LUKSv1 password (in a slot with the same number). However, luksmeta itself is indifferent to the relationship between a LUKSv1 slot and the correspondly numbered luksmeta slot, with one exception (detailed below).

After a LUKSv1 volume is initialized using cryptsetup(8), it must also be initialized for metadata storage by luksmeta init. Once this is complete, the device is ready to store medata.

Data can be written to a slot using luksmeta save or read from a slot using luksmeta load. You can also erase the data in an existing slot using luksmeta wipe or query the slots using luksmeta show.

## UUID GENERATION
It is often presumed that saving metadata to a slot requires a specific UUID or that there is an official registry of UUID types. This is incorrect.

UUID stands for Universally Unique IDentifier. UUIDs are a standardized, widely-used data type used for identification without a central registry. For the relevant standards, see ISO 9834-8:2005 and RFC 4122.

UUIDs are large enough that collision is practically impossible. So if your application wants to store data in a luksmeta slot, just generate your own UUID and use it consistently to refer to your type of data. If you have multiple types of data, feel free to generate multiple UUIDs.

The easiest way to generate a UUID is to use uuidgen(1). However, any compliant UUID generator will suffice.

## INITIALIZATION
Before reading or writing metadata, the LUKSv1 block device must be initialized for metadata storage. Three commands help with this process: luksmeta test, luksmeta nuke and luksmeta init.

The luksmeta test command simply checks an existing block device to see if it is initialized for metadata storage. This command does not provide any output, so be sure to check its return code (see below).

The luksmeta nuke command will zero (erase) the entire LUKSv1 header gap. Since this operation is destructive, user confirmation will be required before clearing the gap unless the -f option is supplied.

The luksmeta init command initializes the LUKSv1 block device for metadata storage. This process will wipe out any data in the LUKSv1 header gap. For this reason, this command will require user confirmation before any data is written unless the -f option is supplied. Note that this command succeeds without any modification if the device is already initialized. If you would like to force the creation of clean initialization state, you can specify the -n option to nuke the LUKSv1 header gap before initialization (but after user confirmation).

## METADATA STATE
The luksmeta show command displays the current state of slots on the LUKSv1 block device. If no slot is specified, it prints a table consisting of the slot number, the corresponding LUKSv1 slot state and the UUID of the data stored in the luksmeta slot (or "empty" if no data is stored). If a slot is specified, this command simply prints out the UUID of the data in the slot. If the slot does not contain data, it prints nothing.

## MANAGING METADATA
Managing the metadata in the slots is performed with three commands: luksmeta save, luksmeta load and luksmeta wipe. These commands write metadata to a slot, read metadata from a slot and erase metadata in a slot, respectively.

The luksmeta save command reads metadata on standard input and writes it to the specified slot using the specified UUID. If no slot is specified, luksmeta will search for the first slot number for which the LUKSv1 slot is inactive and the luksmeta slot is empty. This represents the only official correlation between LUKSv1 slots and luksmeta slots. In this case, the metadata is written to the first applicable slot using the specified UUID and the slot number is printed to standard output. In either case, this command will never overwrite existing data. To replace data in a slot you will need to execute luksmeta wipe before luksmeta save.

The luksmeta load command reads data from the specified slot and writes it to standard output. If a UUID is specified, the command will verify that the UUID associated with the metadata in the slot matches the specified UUID. This type check helps to ensure that you always receive the type of data you are expecting as output. If the UUIDs do not match, the command will fail.

The luksmeta wipe command erases the data from the given slot. If a UUID is specified, the command will verify that the UUID associated with the metadata in the slot matches the specified UUID. This type check helps to ensure that you only erase the data you intended to erase. Because this is a destructive operation, this command will require user confirmation before any data is erased, unless the -f option is supplied. Note that this command succeeds if you attempt to wipe a slot that is already empty.

## CAVEATS
The amount of storage in the LUKSv1 header gap is extremely limited. It also varies based upon the configuration used by LUKSv1 at device initialization time. In some LUKSv1 configurations, there is not even enough space for all the metadata slots even at the smallest possible slot size.

During the design of this utility, we considered it likely that users would want to reduce the number of usable slots in exchange for more storage space in the slots used. In order to provide this flexibility, the amount of storage available per-slot is dynamic. Put simply, slots are not a fixed size. This means that it is possible (and even somewhat likely) to encounter an error during luksmeta save indicating that there is insufficient space.

This error is not a programming bug. If you encounter this error it likely means that either all space is being consumed by the already-written slots or that the metadata you are attempting to write simply does not fit.

You can attempt to resolve this problem by calling luksmeta wipe on slots that are no longer in use. This will release the storage space for use by other slots. Note that luksmeta does not, however, currently perform defragmentation since the number of usable blocks is rather limited. You can attempt to manually get around this by extracting all slot data, wiping the slots and reloading them in order. However, this operation is potentially dangerous and should be undertaken with great care.

## OPTIONS
•-d DEVICE, --device=DEVICE : The device on which to perform the operation.

•-s SLOT, --slot=SLOT : The slot number on which to perform the operation.

•-u UUID, --uuid=UUID : The UUID to associate with the operation.

•-f, --force : Forcibly suppress all user prompting.

## RETURN VALUES
This command uses the return values as defined by sysexits.h. The following are general errors (and corresponding numeric exit codes) whose meaning is shared by all luksmeta commands:

•EX_OK (0): The operation was successful.

•EX_USAGE (64): The program was called with invalid parameters.

•EX_DATAERR (65): The specified UUID does not match the slot UUID.

•EX_NOINPUT (66): An error occurred while reading from standard input.

•EX_OSERR (71): An undefined operating system error occurred.

•EX_OSFILE (72): The device is not initialized or is corrupted.

•EX_CANTCREAT (73): There is insufficient space in LUKSv1 header.

•EX_IOERR (74): An IO error occurred when writing to the device.

•EX_NOPERM (77): The user did not grant permission during confirmation.

Additionally, luksmeta save will return EX_UNAVAILABLE when you attempt to save data into a slot that is already used. Likewise, luksmeta load will return EX_UNAVAILABLE when you attempt to read from an empty slot.

## EXAMPLES
Destroy all data (including LUKSMeta data) in the LUKSv1 header gap and initialize the gap for LUKSMeta storage:

```
$ luksmeta init -n -f -d /dev/sdz
```

If already initialized, do nothing. Otherwise, destroy all non-LUKSMeta data in the LUKSv1 header gap and initialize the gap for LUKSMeta storage:

```
$ luksmeta init -f -d /dev/sdz
```

Write some data to a slot:

```
$ UUID=*uuidgen*
$ echo $UUID
31c25e3b-b8e2-4eaa-a427-23aa882feef2
$ echo "Hello, World" | luksmeta save -d /dev/sdz -s 0 -u $UUID
```

Read the data back:

```
$ luksmeta load -d /dev/sdz -s 0 -u $UUID
Hello, World
```

Wipe the data from the slot:

```
$ luksmeta wipe -d /dev/sdz -s 0 -u $UUID
```

Erase all trace of LUKSMeta:

```
$ luksmeta nuke -f -d /dev/sdz
```

## AUTHOR
Nathaniel McCallum <npmccallum@redhat.com>

## SEE ALSO
cryptsetup(8), uuidgen(1)


dmeventd

title: dmeventd(8)

summary: Device-mapper event daemon

text:
# dmeventd(8)

## NAME
dmeventd — Device-mapper event daemon

## SYNOPSIS
dmeventd [-d [-d [-d]]] [-f] [-h] [-l] [-R] [-V] [-?]

## DESCRIPTION
dmeventd is the event monitoring daemon for device-mapper devices. Library plugins can register and carry out actions triggered when particular events occur.

## OPTIONS
-d

Repeat from 1 to 3 times (-d, -dd, -ddd) to increase the detail of debug messages sent to syslog. Each extra d adds more debugging information.

-f

Don't fork, run in the foreground.

-h

Show help information.

-l

Log through stdout and stderr instead of syslog. This option works only with option -f, otherwise it is ignored.

-?

Show help information on stderr.

-R

Replace a running dmeventd instance. The running dmeventd must be version 2.02.77 or newer. The new dmeventd instance will obtain a list of devices and events to monitor from the currently running daemon.

-V

Show version of dmeventd.

## LVM PLUGINS
Mirror

Attempts to handle device failure automatically.

See lvm.conf(5).

Raid

Attempts to handle device failure automatically.

See lvm.conf(5).

Snapshot

Monitors how full a snapshot is becoming and emits a warning to syslog when it exceeds 80% full. The warning is repeated when 85%, 90% and 95% of the snapshot is filled. See lvm.conf(5). Snapshot which runs out of space gets invalid and when it is mounted, it gets umounted if possible.

Thin

Monitors how full a thin pool data and metadata is becoming and emits a warning to syslog when it exceeds 80% full. The warning is repeated when more then 85%, 90% and 95% of the thin pool is filled. See lvm.conf(5). When a thin pool fills over 50% (data or metadata) thin plugin calls configured dmeventd/thin_command with every 5% increase. With default setting it calls internal lvm lvextend --use-policies to resize thin pool when it's been filled above configured threshold activation/thin_pool_autoextend_threshold. If the command fails, dmeventd thin plugin will keep retrying execution with increasing time delay between retries upto 42 minutes. User may also configure external command to support more advanced maintenance operations of a thin pool. Such external command can e.g. remove some unneeded snapshots, use fstrim(8) to free recover space in a thin pool, but also can use lvextend --use-policies if other actions have not released enough space. Command is executed with environmental variable LVM_RUN_BY_DMEVENTD=1 so any lvm2 command executed in this environment will not try to interact with dmeventd. To see the fullness of a thin pool command may check these two environmental variables DMEVENTD_THIN_POOL_DATA and DMEVENTD_THIN_POOL_METADATA. Command can also read status with tools like lvs(8).

Vdo

Monitors how full a VDO pool data is becoming and emits a warning to syslog when it exceeds 80% full. The warning is repeated when more then 85%, 90% and 95% of the VDO pool is filled. See lvm.conf(5). When a VDO pool fills over 50% vdo plugin calls configured dmeventd/vdo_command with every 5% increase. With default setting it calls internal lvm lvextend --use-policies to resize VDO pool when it's been filled above the configured threshold activation/vdo_pool_autoextend_threshold. If the command fails, dmeventd vdo plugin will keep retrying execution with increasing time delay between retries upto 42 minutes. User may also configure external command to support more advanced maintenance operations of a VDO pool. Such external command can e.g. remove some unneeded space with fstrim(8), but also can use lvextend --use-policies if other actions have not released enough space. Command is executed with environmental variable LVM_RUN_BY_DMEVENTD=1 so any lvm2 command executed in this environment will not try to interact with dmeventd. To see the fullness of a VDO pool command may check this environmental variable DMEVENTD_VDO_POOL. Command can also read status with tools like lvs(8).

## ENVIRONMENT VARIABLES
DMEVENTD_THIN_POOL_DATA

Variable is set by thin plugin and is available to executed program. Value present actual usage of thin pool data volume. Variable is not set when error event is processed.

DMEVENTD_THIN_POOL_METADATA

Variable is set by thin plugin and is available to executed program. Value present actual usage of thin pool metadata volume. Variable is not set when error event is processed.

DMEVENTD_VDO_POOL

Variable is set by vdo plugin and is available to executed program. Value present actual usage of VDO pool data volume. Variable is not set when error event is processed.

LVM_RUN_BY_DMEVENTD

Variable is set by thin and vdo plugin to prohibit recursive interation with dmeventd by any executed lvm2 command from a thin_command, vdo_command environment.

## SEE ALSO
lvm(8), lvm.conf(5), lvextend(8),

fstrim(8)


dmfilemapd

title: dmfilemapd(8)

summary: device-mapper filemap monitoring daemon

text:
# dmfilemapd(8)

## NAME
dmfilemapd — device-mapper filemap monitoring daemon

## SYNOPSIS
dmfilemapd file_descriptor group_id abs_path inode|path [foreground [verbose]]

## DESCRIPTION
The dmfilemapd daemon monitors groups of dmstats(8) regions that correspond to the extents of a file, adding and removing regions to reflect the changing state of the file on-disk.

The daemon is normally launched automatically by the dmstats create command, but can be run manually, either to create a new daemon where one did not previously exist, or to change the options previously used, by killing the existing daemon and starting a new one.

## OPTIONS
file_descriptor

Specify the file descriptor number for the file to be monitored. The file descriptor must reference a regular file, open for reading, in a local file system that supports the FIEMAP ioctl, and that returns data describing the physical location of extents. The process that executes dmfilemapd is responsible for opening the file descriptor that is handed to the daemon.

group_id

The dmstats group identifier of the group that dmfilemapd should update. The group must exist and it should correspond to a set of regions created by a previous filemap operation.

abs_path

The absolute path to the file being monitored, at the time that it was opened. The use of abs_path by the daemon differs, depending on the filemap following mode in use; see MODES and the mode option for more information.

inode|path

The filemap monitoring mode the daemon. Use either inode (DM_FILEMAP_FOLLOW_INODE), or path (DM_FILEMAP_FOLLOW_PATH), to enable follow-inode or follow-path mode respectively.

[foreground]

If set to 1, disable forking and allow the daemon to run in the foreground.

[verbose]

Control daemon logging. If set to zero, the daemon will close all stdio streams and run silently. If verbose is a number between 1 and 3, stdio will be retained and the daemon will log messages to stdout and stderr that match the specified verbosity level.

## MODES
The file map monitoring daemon can monitor files in two distinct ways: the mode affects the behaviour of the daemon when a file under monitoring is renamed or unlinked, and the conditions which cause the daemon to terminate.

In both modes, the daemon will always shut down when the group being monitored is deleted.

Follow inode

The daemon follows the inode of the file, as it was at the time the daemon started. The file descriptor referencing the file is kept open at all times, and the daemon will exit when it detects that the file has been unlinked and it is the last holder of a reference to the file.

This mode is useful if the file is expected to be renamed, or moved within the file system, while it is being monitored.

Follow path

The daemon follows the path that was given on the daemon command line. The file descriptor referencing the file is re-opened on each iteration of the daemon, and the daemon will exit if no file exists at this location (a tolerance is allowed so that a brief delay between removal and replacement is permitted).

This mode is useful if the file is updated by unlinking the original and placing a new file at the same path.

## LIMITATIONS
The daemon attempts to maintain good synchronisation between the file extents and the regions contained in the group, however, since the daemon can only react to new allocations once they have been written, there are inevitably some IO events that cannot be counted when a file is growing, particularly if the file is being extended by a single thread writing beyond EOF (for example, the dd program).

There is a further loss of events in that there is currently no way to atomically resize a dmstats region and preserve its current counter values. This affects files when they grow by extending the final extent, rather than allocating a new extent: any events that had accumulated in the region between any prior operation and the resize are lost.

File mapping is currently most effective in cases where the majority of IO does not trigger extent allocation. Future updates may address these limitations when kernel support is available.

## EXAMPLES
Normally the daemon is started automatically by the dmstats create or update_filemap commands but it can be run manually for debugging or testing purposes.

Start the daemon in the background, in follow-path mode

\# dmfilemapd 3 0 /srv/images/vm.img path 0 0 3< /srv/images/vm.img

Start the daemon in follow-inode mode, disable forking and enable verbose logging

\# dmfilemapd 3 0 /var/tmp/data inode 1 3 3< /var/tmp/data

```
Starting dmfilemapd with fd=3, group_id=0 mode=inode, path=/var/tmp/data
dm version   [ opencount flush ]   [16384] (*1)
dm info   (253:0) [ opencount flush ]   [16384] (*1)
dm message   (253:0) [ opencount flush ]  @stats_list dmstats [16384] (*1)
Read alias 'data' from aux_data
Found group_id 0: alias="data"
dm_stats_walk_init: initialised flags to 4000000000000
starting stats walk with   GROUP
exiting _filemap_monitor_get_events() with deleted=0, check=0
Waiting for check interval
```

## AUTHORS
Bryn M. Reeves <bmr@redhat.com>

## SEE ALSO
dmstats(8)

LVM2 resource page: https://www.sourceware.org/lvm2

Device-mapper resource page: http://sources.redhat.com/dm


fsadm

title: fsadm(8)

text:
# fsadm(8)

## NAME
fsadm — utility to resize or check filesystem on a device

## SYNOPSIS
fsadm

[options] check device

fsadm

[options] resize device [new_size]

## DESCRIPTION
fsadm utility checks or resizes the filesystem on a device (can be also dm-crypt encrypted device). It tries to use the same API for ext2, ext3, ext4, ReiserFS and XFS filesystem.

## OPTIONS
-e|--ext-offline

Unmount ext2/ext3/ext4 filesystem before doing resize.

-f|--force

Bypass some sanity checks.

-h|--help

Display the help text.

-l|--lvresize

Resize also given lvm2 logical volume. More volume management functionality is provided with complementary lvresize(8) and the option -r|--resizefs.

-n|--dry-run

Print commands without running them.

-v|--verbose

Be more verbose.

-y|--yes

Answer "yes" at any prompts.

-c|--cryptresize

Resize dm-crypt mapping together with filesystem detected on the device. The dm-crypt device must be recognizable by cryptsetup(8).

new_size[B|K|M|G|T|P|E]

Absolute number of filesystem blocks to be in the filesystem, or an absolute size using a suffix (in powers of 1024). If new_size is not supplied, the whole device is used.

## DIAGNOSTICS
On successful completion, the status code is 0. A status code of 2 indicates the operation was interrupted by the user. A status code of 3 indicates the requested check operation could not be performed because the filesystem is mounted and does not support an online fsck(8). A status code of 1 is used for other failures.

## EXAMPLES
Resize the filesystem on logical volume /dev/vg/test to 1000 megabytes. If /dev/vg/test contains ext2/ext3/ext4 filesystem it will be unmounted prior the resize. All [y/n] questions will be answered 'y'.

\# fsadm -e -y resize /dev/vg/test 1000M

## ENVIRONMENT VARIABLES
TMPDIR

The temporary directory name for mount points. Defaults to "/tmp".

DM_DEV_DIR

The device directory name. Defaults to "/dev" and must be an absolute path.

## SEE ALSO
lvm(8), lvresize(8), lvm.conf(5),

fsck(8), tune2fs(8), resize2fs(8),

reiserfstune(8), resize_reiserfs(8),

xfs_info(8), xfs_growfs(8), xfs_check(8),

cryptsetup(8)


lvchange

title: lvchange(8)

text:
# lvchange(8)

## NAME
lvchange — Change the attributes of logical volume(s)

## SYNOPSIS
lvchange option_args position_args

[ option_args ]

-a|--activate y|n|ay

--activationmode partial|degraded|complete

--addtag Tag

--alloc contiguous|cling|cling_by_tags|normal|anywhere|inherit

-A|--autobackup y|n

--cachemode writethrough|writeback|passthrough

--cachepolicy String

--cachesettings String

--commandprofile String

--compression y|n

--config String

-C|--contiguous y|n

-d|--debug

--deduplication y|n

--deltag Tag

--detachprofile

--devices PV

--devicesfile String

--discards passdown|nopassdown|ignore

--driverloaded y|n

--errorwhenfull y|n

-f|--force

-h|--help

-K|--ignoreactivationskip

--ignorelockingfailure

--ignoremonitoring

--journal String

--lockopt String

--longhelp

-j|--major Number

--[raid]maxrecoveryrate Size[k|UNIT]

--metadataprofile String

--minor Number

--[raid]minrecoveryrate Size[k|UNIT]

--monitor y|n

--nohints

--nolocking

--noudevsync

-P|--partial

-p|--permission rw|r

-M|--persistent y|n

--poll y|n

--profile String

-q|--quiet

-r|--readahead auto|none|Number

--readonly

--rebuild PV

--refresh

--reportformat basic|json

--resync

-S|--select String

-k|--setactivationskip y|n

--setautoactivation y|n

--[raid]syncaction check|repair

--sysinit

-t|--test

--vdosettings String

-v|--verbose

--version

--[raid]writebehind Number

--[raid]writemostly PV[:t|n|y]

-y|--yes

-Z|--zero y|n

## DESCRIPTION
lvchange changes LV attributes in the VG, changes LV activation in the kernel, and includes other utilities for LV maintenance.

## USAGE
Change a general LV attribute.

For options listed in parentheses, any one is

required, after which the others are optional.

lvchange

( -C|--contiguous y|n

-p|--permission rw|r

-r|--readahead auto|none|Number

-k|--setactivationskip y|n

-Z|--zero y|n

-M|--persistent n

--addtag Tag

--deltag Tag

--alloc contiguous|cling|cling_by_tags|normal|anywhere|inherit

--compression y|n

--deduplication y|n

--detachprofile

--metadataprofile String

--profile String

--setautoactivation y|n

--errorwhenfull y|n

--discards passdown|nopassdown|ignore

--cachemode writethrough|writeback|passthrough

--cachepolicy String

--cachesettings String

--[raid]minrecoveryrate Size[k|UNIT]

--[raid]maxrecoveryrate Size[k|UNIT]

--vdosettings String

--[raid]writebehind Number

--[raid]writemostly PV[:t|n|y] )

VG|LV|Tag|Select ...

[ -a|--activate y|n|ay ]

[ --poll y|n ]

[ --monitor y|n ]

[ COMMON_OPTIONS ]

—

Resyncronize a mirror or raid LV.

Use to reset 'R' attribute on a not initially synchronized LV.

lvchange --resync VG|LV1|Tag|Select ...

[ -a|--activate y|n|ay ]

[ COMMON_OPTIONS ]

LV1 types: mirror raid

—

Resynchronize or check a raid LV.

lvchange --syncaction check|repair VG|LV1|Tag|Select ...

[ COMMON_OPTIONS ]

LV1 types: raid

—

Reconstruct data on specific PVs of a raid LV.

lvchange --rebuild PV VG|LV1|Tag|Select ...

[ COMMON_OPTIONS ]

LV1 types: raid

—

Activate or deactivate an LV.

lvchange -a|--activate y|n|ay VG|LV|Tag|Select ...

[ -P|--partial ]

[ -K|--ignoreactivationskip ]

[ --activationmode partial|degraded|complete ]

[ --poll y|n ]

[ --monitor y|n ]

[ --ignorelockingfailure ]

[ --sysinit ]

[ --readonly ]

[ COMMON_OPTIONS ]

—

Reactivate an LV using the latest metadata.

lvchange --refresh VG|LV|Tag|Select ...

[ -P|--partial ]

[ --activationmode partial|degraded|complete ]

[ --poll y|n ]

[ --monitor y|n ]

[ COMMON_OPTIONS ]

—

Start or stop monitoring an LV from dmeventd.

lvchange --monitor y|n VG|LV|Tag|Select ...

[ COMMON_OPTIONS ]

—

Start or stop processing an LV conversion.

lvchange --poll y|n VG|LV|Tag|Select ...

[ --monitor y|n ]

[ COMMON_OPTIONS ]

—

Make the minor device number persistent for an LV.

lvchange -M|--persistent y --minor Number LV

[ -j|--major Number ]

[ -a|--activate y|n|ay ]

[ --poll y|n ]

[ --monitor y|n ]

[ COMMON_OPTIONS ]

—

Common options for command:

[ -A|--autobackup y|n ]

[ -f|--force ]

[ -S|--select String ]

[ --ignoremonitoring ]

[ --noudevsync ]

[ --reportformat basic|json ]

Common options for lvm:

[ -d|--debug ]

[ -h|--help ]

[ -q|--quiet ]

[ -t|--test ]

[ -v|--verbose ]

[ -y|--yes ]

[ --commandprofile String ]

[ --config String ]

[ --devices PV ]

[ --devicesfile String ]

[ --driverloaded y|n ]

[ --journal String ]

[ --lockopt String ]

[ --longhelp ]

[ --nohints ]

[ --nolocking ]

[ --profile String ]

[ --version ]

## OPTIONS
-a|--activate y|n|ay

Change the active state of LVs. An active LV can be used through a block device, allowing data on the LV to be accessed. y makes LVs active, or available. n makes LVs inactive, or unavailable. The block device for the LV is added or removed from the system using device-mapper in the kernel. A symbolic link /dev/VGName/LVName pointing to the device node is also added/removed. All software and scripts should access the device through the symbolic link and present this as the name of the device. The location and name of the underlying device node may depend on the distribution, configuration (e.g. udev), or release version. ay specifies autoactivation, which is used by system-generated activation commands. By default, LVs are autoactivated. An autoactivation property can be set on a VG or LV to disable autoactivation, see --setautoactivation y|n in vgchange, lvchange, vgcreate, and lvcreate. Display the property with vgs or lvs "-o autoactivation". The lvm.conf(5) auto_activation_volume_list includes names of VGs or LVs that should be autoactivated, and anything not listed is not autoactivated. When auto_activation_volume_list is undefined (the default), it has no effect. If auto_activation_volume_list is defined and empty, no LVs are autoactivated. Items included by auto_activation_volume_list will not be autoactivated if the autoactivation property has been disabled. See lvmlockd(8) for more information about activation options ey and sy for shared VGs.

--activationmode partial|degraded|complete

Determines if LV activation is allowed when PVs are missing, e.g. because of a device failure. complete only allows LVs with no missing PVs to be activated, and is the most restrictive mode. degraded allows RAID LVs with missing PVs to be activated. (This does not include the "mirror" type, see "raid1" instead.) partial allows any LV with missing PVs to be activated, and should only be used for recovery or repair. For default, see lvm.conf(5) activation_mode. See lvmraid(7) for more information.

--addtag Tag

Adds a tag to a PV, VG or LV. This option can be repeated to add multiple tags at once. See lvm(8) for information about tags.

--alloc contiguous|cling|cling_by_tags|normal|anywhere|inherit

Determines the allocation policy when a command needs to allocate Physical Extents (PEs) from the VG. Each VG and LV has an allocation policy which can be changed with vgchange/lvchange, or overridden on the command line. normal applies common sense rules such as not placing parallel stripes on the same PV. inherit applies the VG policy to an LV. contiguous requires new PEs be placed adjacent to existing PEs. cling places new PEs on the same PV as existing PEs in the same stripe of the LV. If there are sufficient PEs for an allocation, but normal does not use them, anywhere will use them even if it reduces performance, e.g. by placing two stripes on the same PV. Optional positional PV args on the command line can also be used to limit which PVs the command will use for allocation. See lvm(8) for more information about allocation.

-A|--autobackup y|n

Specifies if metadata should be backed up automatically after a change. Enabling this is strongly advised! See vgcfgbackup(8) for more information.

--cachemode writethrough|writeback|passthrough

Specifies when writes to a cache LV should be considered complete. writeback considers a write complete as soon as it is stored in the cache pool. writethough considers a write complete only when it has been stored in both the cache pool and on the origin LV. While writethrough may be slower for writes, it is more resilient if something should happen to a device associated with the cache pool LV. With passthrough, all reads are served from the origin LV (all reads miss the cache) and all writes are forwarded to the origin LV; additionally, write hits cause cache block invalidates. See lvmcache(7) for more information.

--cachepolicy String

Specifies the cache policy for a cache LV. See lvmcache(7) for more information.

--cachesettings String

Specifies tunable kernel options for dm-cache or dm-writecache LVs. Use the form 'option=value' or 'option1=value option2=value', or repeat --cachesettings for each option being set. These settings override the default kernel behaviors which are usually adequate. To remove cachesettings and revert to the default kernel behaviors, use --cachesettings 'default' for dm-cache or an empty string --cachesettings '' for dm-writecache. See lvmcache(7) for more information.

--commandprofile String

The command profile to use for command configuration. See lvm.conf(5) for more information about profiles.

--compression y|n

Controls whether compression is enabled or disable for VDO volume. See lvmvdo(7) for more information about VDO usage.

--config String

Config settings for the command. These override lvm.conf(5) settings. The String arg uses the same format as lvm.conf(5), or may use section/field syntax. See lvm.conf(5) for more information about config.

-C|--contiguous y|n

Sets or resets the contiguous allocation policy for LVs. Default is no contiguous allocation based on a next free principle. It is only possible to change a non-contiguous allocation policy to contiguous if all of the allocated physical extents in the LV are already contiguous.

-d|--debug ...

Set debug level. Repeat from 1 to 6 times to increase the detail of messages sent to the log file and/or syslog (if configured).

--deduplication y|n

Controls whether deduplication is enabled or disable for VDO volume. See lvmvdo(7) for more information about VDO usage.

--deltag Tag

Deletes a tag from a PV, VG or LV. This option can be repeated to delete multiple tags at once. See lvm(8) for information about tags.

--detachprofile

Detaches a metadata profile from a VG or LV. See lvm.conf(5) for more information about profiles.

--devices PV

Restricts the devices that are visible and accessible to the command. Devices not listed will appear to be missing. This option can be repeated, or accepts a comma separated list of devices. This overrides the devices file.

--devicesfile String

A file listing devices that LVM should use. The file must exist in /etc/lvm/devices/ and is managed with the lvmdevices(8) command. This overrides the lvm.conf(5) devices/devicesfile and devices/use_devicesfile settings.

--discards passdown|nopassdown|ignore

Specifies how the device-mapper thin pool layer in the kernel should handle discards. ignore causes the thin pool to ignore discards. nopassdown causes the thin pool to process discards itself to allow reuse of unneeded extents in the thin pool. passdown causes the thin pool to process discards itself (like nopassdown) and pass the discards to the underlying device. See lvmthin(7) for more information.

--driverloaded y|n

If set to no, the command will not attempt to use device-mapper. For testing and debugging.

--errorwhenfull y|n

Specifies thin pool behavior when data space is exhausted. When yes, device-mapper will immediately return an error when a thin pool is full and an I/O request requires space. When no, device-mapper will queue these I/O requests for a period of time to allow the thin pool to be extended. Errors are returned if no space is available after the timeout. (Also see dm-thin-pool kernel module option no_space_timeout.) See lvmthin(7) for more information.

-f|--force ...

Override various checks, confirmations and protections. Use with extreme caution.

-h|--help

Display help text.

-K|--ignoreactivationskip

Ignore the "activation skip" LV flag during activation to allow LVs with the flag set to be activated.

--ignorelockingfailure

Allows a command to continue with read-only metadata operations after locking failures.

--ignoremonitoring

Do not interact with dmeventd unless --monitor is specified. Do not use this if dmeventd is already monitoring a device.

--journal String

Record information in the systemd journal. This information is in addition to information enabled by the lvm.conf log/journal setting. command: record information about the command. output: record the default command output. debug: record full command debugging.

--lockopt String

Used to pass options for special cases to lvmlockd. See lvmlockd(8) for more information.

--longhelp

Display long help text.

-j|--major Number

Sets the major number of an LV block device.

--[raid]maxrecoveryrate Size[k|UNIT]

Sets the maximum recovery rate for a RAID LV. The rate value is an amount of data per second for each device in the array. Setting the rate to 0 means it will be unbounded. See lvmraid(7) for more information.

--metadataprofile String

The metadata profile to use for command configuration. See lvm.conf(5) for more information about profiles.

--minor Number

Sets the minor number of an LV block device.

--[raid]minrecoveryrate Size[k|UNIT]

Sets the minimum recovery rate for a RAID LV. The rate value is an amount of data per second for each device in the array. Setting the rate to 0 means it will be unbounded. See lvmraid(7) for more information.

--monitor y|n

Start (yes) or stop (no) monitoring an LV with dmeventd. dmeventd monitors kernel events for an LV, and performs automated maintenance for the LV in reponse to specific events. See dmeventd(8) for more information.

--nohints

Do not use the hints file to locate devices for PVs. A command may read more devices to find PVs when hints are not used. The command will still perform standard hint file invalidation where appropriate.

--nolocking

Disable locking. Use with caution, concurrent commands may produce incorrect results.

--noudevsync

Disables udev synchronisation. The process will not wait for notification from udev. It will continue irrespective of any possible udev processing in the background. Only use this if udev is not running or has rules that ignore the devices LVM creates.

-P|--partial

Commands will do their best to activate LVs with missing PV extents. Missing extents may be replaced with error or zero segments according to the missing_stripe_filler setting. Metadata may not be changed with this option.

-p|--permission rw|r

Set access permission to read only r or read and write rw.

-M|--persistent y|n

When yes, makes the specified minor number persistent.

--poll y|n

When yes, start the background transformation of an LV. An incomplete transformation, e.g. pvmove or lvconvert interrupted by reboot or crash, can be restarted from the last checkpoint with --poll y. When no, background transformation of an LV will not occur, and the transformation will not complete. It may not be appropriate to immediately poll an LV after activation, in which case --poll n can be used to defer polling until a later --poll y command.

--profile String

An alias for --commandprofile or --metadataprofile, depending on the command.

-q|--quiet ...

Suppress output and log messages. Overrides --debug and --verbose. Repeat once to also suppress any prompts with answer 'no'.

-r|--readahead auto|none|Number

Sets read ahead sector count of an LV. auto is the default which allows the kernel to choose a suitable value automatically. none is equivalent to zero.

--readonly

Run the command in a special read-only mode which will read on-disk metadata without needing to take any locks. This can be used to peek inside metadata used by a virtual machine image while the virtual machine is running. No attempt will be made to communicate with the device-mapper kernel driver, so this option is unable to report whether or not LVs are actually in use.

--rebuild PV

Selects a PV to rebuild in a raid LV. Multiple PVs can be rebuilt by repeating this option. Use this option in place of --resync or --syncaction repair when the PVs with corrupted data are known, and their data should be reconstructed rather than reconstructing default (rotating) data. See lvmraid(7) for more information.

--refresh

If the LV is active, reload its metadata. This is not necessary in normal operation, but may be useful if something has gone wrong, or if some form of manual LV sharing is being used.

--reportformat basic|json

Overrides current output format for reports which is defined globally by the report/output_format setting in lvm.conf(5). basic is the original format with columns and rows. If there is more than one report per command, each report is prefixed with the report name for identification. json produces report output in JSON format. See lvmreport(7) for more information.

--resync

Initiates mirror synchronization. Synchronization generally happens automatically, but this option forces it to run. Also see --rebuild to synchronize a specific PV. During synchronization, data is read from the primary mirror device and copied to the others. This can take considerable time, during which the LV is without a complete redundant copy of the data. See lvmraid(7) for more information.

-S|--select String

Select objects for processing and reporting based on specified criteria. The criteria syntax is described by --select help and lvmreport(7). For reporting commands, one row is displayed for each object matching the criteria. See --options help for selectable object fields. Rows can be displayed with an additional "selected" field (-o selected) showing 1 if the row matches the selection and 0 otherwise. For non-reporting commands which process LVM entities, the selection is used to choose items to process.

-k|--setactivationskip y|n

Persistently sets (yes) or clears (no) the "activation skip" flag on an LV. An LV with this flag set is not activated unless the --ignoreactivationskip option is used by the activation command. This flag is set by default on new thin snapshot LVs. The flag is not applied to deactivation. The current value of the flag is indicated in the lvs lv_attr bits.

--setautoactivation y|n

Set the autoactivation property on a VG or LV. Display the property with vgs or lvs "-o autoactivation". When the autoactivation property is disabled, the VG or LV will not be activated by a command doing autoactivation (vgchange, lvchange, or pvscan using -aay.) If autoactivation is disabled on a VG, no LVs will be autoactivated in that VG, and the LV autoactivation property has no effect. If autoactivation is enabled on a VG, autoactivation can be disabled for individual LVs.

--[raid]syncaction check|repair

Initiate different types of RAID synchronization. This causes the RAID LV to read all data and parity blocks in the array and check for discrepancies (mismatches between mirrors or incorrect parity values). check will count but not correct discrepancies. repair will correct discrepancies. See lvs(8) for reporting discrepancies found or repaired.

--sysinit

Indicates that vgchange/lvchange is being invoked from early system initialisation scripts (e.g. rc.sysinit or an initrd), before writable filesystems are available. As such, some functionality needs to be disabled and this option acts as a shortcut which selects an appropriate set of options. Currently, this is equivalent to using --ignorelockingfailure, --ignoremonitoring, --poll n, and setting env var LVM_SUPPRESS_LOCKING_FAILURE_MESSAGES. vgchange/lvchange skip autoactivation, and defer to pvscan autoactivation.

-t|--test

Run in test mode. Commands will not update metadata. This is implemented by disabling all metadata writing but nevertheless returning success to the calling function. This may lead to unusual error messages in multi-stage operations if a tool relies on reading back metadata it believes has changed but hasn't.

--vdosettings String

Specifies tunable VDO options for VDO LVs. Use the form 'option=value' or 'option1=value option2=value', or repeat --vdosettings for each option being set. These settings override the default VDO behaviors. To remove vdosettings and revert to the default VDO behaviors, use --vdosettings 'default'. See lvmvdo(7) for more information.

-v|--verbose ...

Set verbose level. Repeat from 1 to 4 times to increase the detail of messages sent to stdout and stderr.

--version

Display version information.

--[raid]writebehind Number

The maximum number of outstanding writes that are allowed to devices in a RAID1 LV that is marked write-mostly. Once this value is exceeded, writes become synchronous (i.e. all writes to the constituent devices must complete before the array signals the write has completed). Setting the value to zero clears the preference and allows the system to choose the value arbitrarily.

--[raid]writemostly PV[:t|n|y]

Mark a device in a RAID1 LV as write-mostly. All reads to these drives will be avoided unless absolutely necessary. This keeps the number of I/Os to the drive to a minimum. The default behavior is to set the write-mostly attribute for the specified PV. It is also possible to remove the write-mostly flag by adding the suffix :n at the end of the PV name, or to toggle the value with the suffix :t. Repeat this option to change the attribute on multiple PVs.

-y|--yes

Do not prompt for confirmation interactively but always assume the answer yes. Use with extreme caution. (For automatic no, see -qq.)

-Z|--zero y|n

Set zeroing mode for thin pool. Note: already provisioned blocks from pool in non-zero mode are not cleared in unwritten parts when setting --zero y.

## VARIABLES
VG

Volume Group name. See lvm(8) for valid names.

LV

Logical Volume name. See lvm(8) for valid names. An LV positional arg generally includes the VG name and LV name, e.g. VG/LV. LV1 indicates the LV must have a specific type, where the accepted LV types are listed. (raid represents raid<N> type).

Tag

Tag name. See lvm(8) for information about tag names and using tags in place of a VG, LV or PV.

Select

Select indicates that a required positional parameter can be omitted if the --select option is used. No arg appears in this position.

String

See the option description for information about the string content.

Size[UNIT]

Size is an input number that accepts an optional unit. Input units are always treated as base two values, regardless of capitalization, e.g. 'k' and 'K' both refer to 1024. The default input unit is specified by letter, followed by |UNIT. UNIT represents other possible input units: b|B is bytes, s|S is sectors of 512 bytes, k|K is KiB, m|M is MiB, g|G is GiB, t|T is TiB, p|P is PiB, e|E is EiB. (This should not be confused with the output control --units, where capital letters mean multiple of 1000.)

## ENVIRONMENT VARIABLES
See lvm(8) for information about environment variables used by lvm. For example, LVM_VG_NAME can generally be substituted for a required VG parameter.

## EXAMPLES
Change LV permission to read-only:

lvchange -pr vg00/lvol1

## SEE ALSO
lvm(8), lvm.conf(5), lvmconfig(8), lvmdevices(8),

pvchange(8), pvck(8), pvcreate(8), pvdisplay(8), pvmove(8), pvremove(8), pvresize(8), pvs(8), pvscan(8),

vgcfgbackup(8), vgcfgrestore(8), vgchange(8), vgck(8), vgcreate(8), vgconvert(8), vgdisplay(8), vgexport(8), vgextend(8), vgimport(8), vgimportclone(8), vgimportdevices(8), vgmerge(8), vgmknodes(8), vgreduce(8), vgremove(8), vgrename(8), vgs(8), vgscan(8), vgsplit(8),

lvcreate(8), lvchange(8), lvconvert(8), lvdisplay(8), lvextend(8), lvreduce(8), lvremove(8), lvrename(8), lvresize(8), lvs(8), lvscan(8),

lvm-fullreport(8), lvm-lvpoll(8), blkdeactivate(8), lvmdump(8),

dmeventd(8), lvmpolld(8), lvmlockd(8), lvmlockctl(8), cmirrord(8), lvmdbusd(8), fsadm(8),

lvmsystemid(7), lvmreport(7), lvmraid(7), lvmthin(7), lvmcache(7)